Dojo Configuration Management

Manage Dojo project configuration including Scarb.toml, deployment profiles, and world settings.

When to Use This Skill

• "Configure Dojo for my project"
• "Update Scarb.toml dependencies"
• "Set up deployment profiles"
• "Configure world settings"

What This Skill Does

Manages configuration files:

• Scarb.toml - Package manifest and dependencies
• dojo_dev.toml - Local development profile
• dojo_<profile>.toml - Other environment profiles
• World configuration, namespaces, and permissions

Quick Start

Interactive mode:

"Update my Dojo configuration"

I'll ask about:

• What to configure (dependencies, profiles, world)
• Environment (dev, testnet, mainnet)
• Specific settings

Direct mode:

"Add the Origami library to my dependencies"
"Configure production deployment for Sepolia"

Configuration Files

Dojo projects use two types of configuration files:

Scarb.toml - Project Manifest

Defines project dependencies and build settings:

[package]
cairo-version = "2.12.2"
name = "my-dojo-game"
version = "1.0.0"
edition = "2024_07"

[[target.starknet-contract]]
sierra = true
build-external-contracts = ["dojo::world::world_contract::world"]

[dependencies]
starknet = "2.12.2"
dojo = "1.7.1"

[dev-dependencies]
cairo_test = "2.12.2"
dojo_cairo_test = "1.7.1"

[tool.scarb]
allow-prebuilt-plugins = ["dojo_cairo_macros"]

dojo_<profile>.toml - Profile Configuration

Profile-specific deployment settings. Dojo looks for dojo_dev.toml by default.

[world]
name = "My Game"
description = "An awesome on-chain game"
seed = "my-unique-seed"
cover_uri = "file://assets/cover.png"
icon_uri = "file://assets/icon.png"

[env]
rpc_url = "http://localhost:5050/"
account_address = "0x127fd..."
private_key = "0xc5b2f..."

[namespace]
default = "my_game"

[writers]
"my_game" = ["my_game-actions"]

[owners]
"my_game" = ["my_game-admin"]

Profile System

Dojo uses profiles to manage different environments:

# Use default 'dev' profile (dojo_dev.toml)
sozo build
sozo migrate

# Use specific profile (dojo_mainnet.toml)
sozo build --profile mainnet
sozo migrate --profile mainnet

Profile file naming: dojo_<profile>.toml

• dojo_dev.toml - Development (default)
• dojo_staging.toml - Staging
• dojo_mainnet.toml - Production

World Configuration

[world]
name = "My Game"                    # Human-readable name
description = "A provable game"     # Description
seed = "my-unique-seed"             # Unique seed for address generation
cover_uri = "ipfs://Qm..."          # Cover image (ipfs:// or file://)
icon_uri = "ipfs://Qm..."           # Icon image

[world.socials]
x = "https://x.com/mygame"
discord = "https://discord.gg/mygame"

Environment Settings

[env]
rpc_url = "http://localhost:5050/"
account_address = "0x127fd..."
private_key = "0xc5b2f..."
# Or use keystore for production:
# keystore_path = "/path/to/keystore"
world_address = "0x077c0..."        # Set after first deployment

Namespace Configuration

Namespaces organize your resources:

[namespace]
default = "my_game"                 # Default namespace for all resources

# Optional: Map specific resources to namespaces
mappings = { "weapons" = ["Sword", "Bow"], "characters" = ["Player", "Enemy"] }

Resources get tagged as <namespace>-<resource_name>.

Permission Configuration

Set up initial permissions at deployment time:

[writers]
# Namespace-level: actions can write to all resources in my_game
"my_game" = ["my_game-actions"]
# Resource-specific: movement can only write to Position
"my_game-Position" = ["my_game-movement"]

[owners]
# Namespace ownership
"my_game" = ["my_game-admin"]

Dependencies

Add Dojo Dependencies

[dependencies]
starknet = "2.12.2"
dojo = "1.7.1"

[dev-dependencies]
cairo_test = "2.12.2"
dojo_cairo_test = "1.7.1"

Add External Libraries

Origami (game utilities):

[dependencies]
origami_token = { git = "https://github.com/dojoengine/origami", tag = "v1.0.0" }

Alexandria (math utilities):

[dependencies]
alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria" }

External Contracts

When using external libraries with models:

[[target.starknet-contract]]
build-external-contracts = [
    "dojo::world::world_contract::world",
    "armory::models::m_Flatbow",        # Format: <crate>::<path>::m_<ModelName>
]

Environment Examples

Development (dojo_dev.toml)

[world]
name = "My Game (Dev)"
seed = "dev-my-game"

[env]
rpc_url = "http://localhost:5050/"
account_address = "0x127fd..."
private_key = "0xc5b2f..."

[namespace]
default = "dev"

[writers]
"dev" = ["dev-actions"]

Production (dojo_mainnet.toml)

[world]
name = "My Game"
seed = "prod-my-game"
description = "Production deployment"
cover_uri = "ipfs://YourCoverHash"
icon_uri = "ipfs://YourIconHash"

[env]
rpc_url = "https://api.cartridge.gg/x/starknet/mainnet"
account_address = "0x..."
keystore_path = "~/.starknet_accounts/mainnet.json"

[namespace]
default = "game"

[writers]
"game" = ["game-actions"]

[owners]
"game" = ["game-admin"]

Security

Protecting Secrets

Never commit private keys. Use .gitignore:

# Ignore sensitive configs
dojo_mainnet.toml
dojo_*_secrets.toml

# Keep development config
!dojo_dev.toml

Use keystore for production:

[env]
keystore_path = "~/.starknet_accounts/mainnet.json"
# Instead of: private_key = "0x..."

Troubleshooting

"Profile not found":

• Ensure dojo_<profile>.toml exists in project root
• Check spelling matches the --profile flag

"World not found":

• Set world_address in [env] after first deployment
• Verify RPC URL is correct

"Account not found":

• Ensure account is deployed on target network
• Check account_address format (should start with 0x)

Next Steps

After configuration:

1. Use dojo-deploy skill to deploy with your config
2. Use dojo-migrate skill when updating deployments
3. Use dojo-world skill to manage runtime permissions

Related Skills

• dojo-init: Initialize new project with config
• dojo-deploy: Deploy using configuration
• dojo-migrate: Update deployed worlds
• dojo-world: Manage world permissions