Configuration
Dojo uses a profile-based configuration system that allows you to manage different settings for development, testing, and production environments. Every Dojo command operates within a specific profile context, giving you fine-grained control over how your project builds, deploys, and runs.
Understanding Profiles
Profiles separate your project configuration into distinct environments. This allows you to use different settings for local development versus production deployment without manually changing configuration files.
# Use the default 'dev' profile
sozo build
# Use a specific profile
sozo build --profile mainnet
sozo migrate --profile staging
- Specified profile: If you provide
--profile <name>
, Dojo looks fordojo_<name>.toml
- Default fallback: If no profile is specified, Dojo uses the
dev
profile (dojo_dev.toml
) - Configuration loading: Each profile file contains deployment and environment settings for that specific context
Configuration Files
Dojo projects use two main configuration files:
Scarb.toml
- Cairo Project Manifest
The Scarb manifest defines your project's dependencies, build settings, and Cairo compilation options. This file is required for all Cairo projects and controls how your code compiles.
dojo_<profile>.toml
- Dojo Profile Configuration
Profile-specific files contain deployment settings, world metadata, and environment variables. These files control how your world deploys and behaves in different environments.
my-dojo-project/
├── Scarb.toml # Project manifest & dependencies
├── dojo_dev.toml # Development profile
├── dojo_staging.toml # Staging profile
└── dojo_mainnet.toml # Production profile
Project Manifest (Scarb.toml
)
Your Scarb.toml
file defines the core project structure and dependencies.
Here's the minimum configuration needed for a Dojo project:
[package]
cairo-version = "=2.10.1"
name = "my-dojo-game"
version = "1.5.0"
edition = "2024_07"
[[target.starknet-contract]]
sierra = true
build-external-contracts = ["dojo::world::world_contract::world"]
[dependencies]
starknet = "2.8.4"
dojo = { git = "https://github.com/dojoengine/dojo.git", tag = "v1.5.0" }
[dev-dependencies]
cairo_test = "=2.10.1"
dojo_cairo_test = { git = "https://github.com/dojoengine/dojo.git", tag = "v1.5.0" }
[features]
default = []
You can refer to the Scarb documentation for more information.
Custom Profiles in Scarb
Add custom profiles to control build settings for different environments:
# Development profile (default)
[profile.dev]
# Fast builds, debug symbols enabled
[profile.staging]
# Settings specific to staging
[profile.mainnet]
# Optimized builds for production
External Contract Dependencies
When using external libraries with models, you must explicitly build their contracts:
[[target.starknet-contract]]
build-external-contracts = [
"dojo::world::world_contract::world", # Used by Sozo to check the world version
"armory::models::m_Flatbow", # External model contract
"tokens::models::m_ERC20Token" # Another external model
]
- Format:
<crate>::<path>::m_<ModelName>
- Example: If
armory
crate hasmodels::Flatbow
model, include"armory::models::m_Flatbow"
Profile Configuration (dojo_<profile>.toml
)
Profile configuration files contain all deployment and runtime settings for specific environments. Each section controls a different aspect of your Dojo world.
Basic World Configuration
[world]
name = "My Dojo Game"
description = "An awesome on-chain game built with Dojo"
seed = "my-unique-seed"
cover_uri = "file://assets/cover.png"
icon_uri = "file://assets/icon.png"
website = "https://mydojogame.com"
[world.socials]
x = "https://x.com/mydojogame"
discord = "https://discord.gg/mydojogame"
github = "https://github.com/mydojogame/contracts"
name
- Human-readable world nameseed
- Unique identifier for deterministic world address generation
description
- World description for metadatacover_uri
/icon_uri
- Visual assets (supportsfile://
andipfs://
)website
- Project website URLsocials
- Social media links
See more information about world metadata here.
Environment Settings
[env]
rpc_url = "http://localhost:5050/"
account_address = "0x127fd..."
private_key = "0xc5b2f..."
keystore_path = "/path/to/keystore"
world_address = "0x077c0..."
rpc_url
- Starknet RPC endpointaccount_address
- Deployer account addressprivate_key
- Deployer private key (usekeystore_path
in production)keystore_path
- The path to the file containing the deployer's private key.world_address
- Deployed world address (set after first deployment)
Namespace Management
[namespace]
default = "game"
mappings = {
"weapons" = ["Sword", "Bow", "Shield"],
"characters" = ["Player", "Enemy", "NPC"]
}
- Default namespace: All resources not explicitly mapped use this namespace
- Explicit mappings: Map specific models/contracts to custom namespaces
- Resource tags: Final resource tags become
<namespace>-<resource_name>
Player
model →characters-Player
tagGameState
model →game-GameState
tag (uses default namespace)
Permission Configuration
# Format: "<TARGET_TAG>" = ["<GRANTEE_TAG>"]
[writers]
# Namespace-level permissions
"game" = ["game-actions", "game-admin"]
# Resource-specific permissions
"game-Position" = ["game-movement"]
"weapons-Sword" = ["weapons-combat", "game-actions"]
[owners]
# Namespace ownership
"game" = ["game-admin"]
# Resource ownership
"weapons" = ["weapons-manager"]
- Namespace permissions - Control access to all resources in a namespace
- Resource permissions - Control access to specific models/contracts
- Writers - Can modify data in models
- Owners - Can modify data AND manage permissions
Contract Initialization
By default, Dojo contracts don't have initialization arguments.
However, you can pass init arguments to Dojo contracts using a dojo_init
function:
#[dojo::contract]
mod my_system {
fn dojo_init(ref self: ContractState, arg1: felt252, arg2: u256) {
// ...
}
}
[init_call_args]
"game-my_system" = ["0x123", "u256:0x456"]
External Contract Deployment
Deploy and manage external (non-Dojo) contracts alongside your world:
[[external_contracts]]
contract_name = "ERC20Token"
instance_name = "GoldToken" # If deploying multiple instances
salt = "1" # Hashed with contract_name/instance_name to generate contract address
constructor_data = [
"str:Gold Coin", # Token name
"sstr:GOLD", # Symbol
"u256:1000000000000000000", # Total supply
"0x1234567890abcdef..." # Owner address
]
contract_name
- Cairo contract name to deployinstance_name
- Unique instance identifier (for multiple deployments)salt
- Deterministic address generation saltconstructor_data
- Arguments for contract constructor
Migration Control
[migration]
order_inits = ["game-registry", "game-actions", "token-manager"]
skip_contracts = ["game-debug_tools", "test-helpers"]
disable_multicall = false
order_inits
- Specific order for contract initialization callsskip_contracts
- Don't deploy these contracts (but still build them)disable_multicall
- Force individual transactions instead of batching
Resource Metadata
Add descriptive metadata for your models, contracts, and events:
[[models]]
tag = "game-Position"
description = "Player position in the game world"
icon_uri = "file://icons/position.png"
[[contracts]]
tag = "game-actions"
description = "Core gameplay actions and mechanics"
icon_uri = "file://icons/actions.png"
[[events]]
tag = "game-PlayerMoved"
description = "Emitted when a player changes position"
See more information about resource metadata here.
Configuration Examples
Development Profile (dojo_dev.toml
)
[world]
name = "My Game (Development)"
seed = "dev-my-game"
[env]
rpc_url = "http://localhost:5050/"
account_address = "0x127fd..."
private_key = "0xc5b2f..."
[namespace]
default = "dev"
[writers]
"dev" = ["dev-actions"]
[migration]
disable_multicall = true # Easier debugging
Production Profile (dojo_mainnet.toml
)
[world]
name = "My Game"
seed = "prod-my-game"
description = "Production deployment of My Game"
cover_uri = "ipfs://YourCoverHash"
icon_uri = "ipfs://YourIconHash"
website = "https://mygame.com"
[env]
rpc_url = "https://api.cartridge.gg/x/prod-my-game/katana"
account_address = "0x127fd..."
keystore_path = "~/.starknet_accounts/mainnet.json"
[env.ipfs_config]
url = "https://ipfs.infura.io:5001"
username = "prod_username"
password = "prod_password"
[namespace]
default = "game"
mappings = { "items" = ["Sword", "Shield", "Potion"] }
[writers]
"game" = ["game-actions"]
"items" = ["game-actions", "item-manager"]
[owners]
"game" = ["game-admin"]
See Also
- World Permissions - Runtime permission management
- Sozo Reference - Command-line tool documentation
- Calldata Format - Constructor argument formatting
- World Metadata - World and resource metadata