Back to Details

dojo-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dojo Configuration Management

Dojo配置管理

Manage Dojo project configuration including Scarb.toml, deployment profiles, and world settings.
管理Dojo项目配置，包括Scarb.toml、部署配置文件和世界设置。

When to Use This Skill

使用场景

  • "Configure Dojo for my project"
  • "Update Scarb.toml dependencies"
  • "Set up deployment profiles"
  • "Configure world settings"
  • "为我的项目配置Dojo"
  • "更新Scarb.toml依赖项"
  • "设置部署配置文件"
  • "配置世界设置"

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
管理以下配置文件：
  • Scarb.toml
    - 包清单与依赖项
  • dojo_dev.toml
    - 本地开发配置文件
  • dojo_<profile>.toml
    - 其他环境配置文件
  • 世界配置、命名空间与权限

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"
交互式模式：
"更新我的Dojo配置"
我会询问以下信息：
  • 要配置的内容（依赖项、配置文件、世界设置）
  • 环境（开发、测试网、主网）
  • 具体设置项
直接模式：
"将Origami库添加到我的依赖项中"
"为Sepolia配置生产部署"

Configuration Files

配置文件

Dojo projects use two types of configuration files:
Dojo项目使用两类配置文件：

Scarb.toml
- Project Manifest

Scarb.toml
- 项目清单

Defines project dependencies and build settings:
toml
[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"]
定义项目依赖项与构建设置：
toml
[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

dojo_<profile>.toml
- 配置文件配置

Profile-specific deployment settings. Dojo looks for 
dojo_dev.toml
by default.
toml
[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"]
特定环境的部署设置。Dojo默认会查找
dojo_dev.toml
。
toml
[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:
bash
undefined
Dojo使用配置文件管理不同环境：
bash
undefined

Use default 'dev' profile (dojo_dev.toml)

使用默认的'dev'配置文件（dojo_dev.toml）

sozo build sozo migrate
sozo build sozo migrate

Use specific profile (dojo_mainnet.toml)

使用特定配置文件（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
sozo build --profile mainnet sozo migrate --profile mainnet

**配置文件命名规则：** `dojo_<profile>.toml`
- `dojo_dev.toml` - 开发环境（默认）
- `dojo_staging.toml` - 预发布环境
- `dojo_mainnet.toml` - 生产环境

World Configuration

世界配置

toml
[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"
toml
[world]
name = "My Game"                    # 人类可读名称
description = "A provable game"     # 描述
seed = "my-unique-seed"             # 地址生成的唯一种子
cover_uri = "ipfs://Qm..."          # 封面图（ipfs:// 或 file:// 格式）
icon_uri = "ipfs://Qm..."           # 图标

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

Environment Settings

环境设置

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

Or use keystore for production:

生产环境可使用密钥库：

keystore_path = "/path/to/keystore"

keystore_path = "/path/to/keystore"

world_address = "0x077c0..." # Set after first deployment
undefined
world_address = "0x077c0..." # 首次部署后设置
undefined

Namespace Configuration

命名空间配置

Namespaces organize your resources:
toml
[namespace]
default = "my_game"                 # Default namespace for all resources
命名空间用于组织资源：
toml
[namespace]
default = "my_game"                 # 所有资源的默认命名空间

Optional: Map specific resources to namespaces

可选：将特定资源映射到命名空间

mappings = { "weapons" = ["Sword", "Bow"], "characters" = ["Player", "Enemy"] }

Resources get tagged as `<namespace>-<resource_name>`.
mappings = { "weapons" = ["Sword", "Bow"], "characters" = ["Player", "Enemy"] }

资源会被标记为`<namespace>-<resource_name>`格式。

Permission Configuration

权限配置

Set up initial permissions at deployment time:
toml
[writers]
在部署时设置初始权限：
toml
[writers]

Namespace-level: actions can write to all resources in my_game

命名空间级别：actions可写入my_game下的所有资源

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

Resource-specific: movement can only write to Position

资源特定：movement仅能写入Position

"my_game-Position" = ["my_game-movement"]
[owners]
"my_game-Position" = ["my_game-movement"]
[owners]

Namespace ownership

命名空间所有权

"my_game" = ["my_game-admin"]
undefined
"my_game" = ["my_game-admin"]
undefined

Dependencies

依赖项

Add Dojo Dependencies

添加Dojo依赖

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

[dev-dependencies]
cairo_test = "2.12.2"
dojo_cairo_test = "1.7.1"
toml
[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):
toml
[dependencies]
origami_token = { git = "https://github.com/dojoengine/origami", tag = "v1.0.0" }
Alexandria (math utilities):
toml
[dependencies]
alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria" }
Origami（游戏工具库）：
toml
[dependencies]
origami_token = { git = "https://github.com/dojoengine/origami", tag = "v1.0.0" }
Alexandria（数学工具库）：
toml
[dependencies]
alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria" }

External Contracts

外部合约

When using external libraries with models:
toml
[[target.starknet-contract]]
build-external-contracts = [
    "dojo::world::world_contract::world",
    "armory::models::m_Flatbow",        # Format: <crate>::<path>::m_<ModelName>
]
当使用包含模型的外部库时：
toml
[[target.starknet-contract]]
build-external-contracts = [
    "dojo::world::world_contract::world",
    "armory::models::m_Flatbow",        # 格式：<crate>::<path>::m_<ModelName>
]

Environment Examples

环境示例

Development (dojo_dev.toml)

开发环境（dojo_dev.toml）

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"]
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)

生产环境（dojo_mainnet.toml）

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"]
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
:
undefined
绝对不要提交私钥到版本库。 在
.gitignore
中添加以下内容：
undefined

Ignore sensitive configs

忽略敏感配置

dojo_mainnet.toml dojo_*_secrets.toml
dojo_mainnet.toml dojo_*_secrets.toml

Keep development config

保留开发环境配置

!dojo_dev.toml

**Use keystore for production:**
```toml
[env]
keystore_path = "~/.starknet_accounts/mainnet.json"
!dojo_dev.toml

**生产环境使用密钥库：**
```toml
[env]
keystore_path = "~/.starknet_accounts/mainnet.json"

Instead of: private_key = "0x..."

替代：private_key = "0x..."

undefined
undefined

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)
"配置文件未找到"：
  • 确保
    dojo_<profile>.toml
    存在于项目根目录
  • 检查配置文件名与
    --profile
    参数的拼写是否一致
"世界未找到"：
  • 首次部署后，在
    [env]
    中设置
    world_address
  • 验证RPC URL是否正确
"账户未找到"：
  • 确保账户已部署到目标网络
  • 检查account_address格式（需以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
完成配置后：
  1. 使用
    dojo-deploy
    技能根据配置部署项目
  2. 更新部署时使用
    dojo-migrate
    技能
  3. 使用
    dojo-world
    技能管理运行时权限

Related Skills

相关技能

  • dojo-init: Initialize new project with config
  • dojo-deploy: Deploy using configuration
  • dojo-migrate: Update deployed worlds
  • dojo-world: Manage world permissions
  • dojo-init：初始化带有配置的新项目
  • dojo-deploy：使用配置部署项目
  • dojo-migrate：更新已部署的世界
  • dojo-world：管理世界权限