dojo-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dojo System Generation

Dojo 系统生成

Create Dojo systems (smart contracts) that implement your game's logic and modify model state.

创建可实现游戏逻辑并修改模型状态的Dojo系统（智能合约）。

Essential Imports (Dojo 1.0+)

必要导入（Dojo 1.0+）

Copy these imports for any Dojo system:

cairo

// Core Dojo imports - ALWAYS needed for systems
use dojo::model::{ModelStorage, ModelValueStorage};
use dojo::event::EventStorage;

// Starknet essentials
use starknet::{ContractAddress, get_caller_address, get_block_timestamp};

所有Dojo系统都需复制以下导入代码：

cairo

// Core Dojo imports - ALWAYS needed for systems
use dojo::model::{ModelStorage, ModelValueStorage};
use dojo::event::EventStorage;

// Starknet essentials
use starknet::{ContractAddress, get_caller_address, get_block_timestamp};

Where does

self.world_default()

come from?

self.world_default()

来自哪里？

self.world_default()
is provided automatically by
#[dojo::contract]
- no import needed!

cairo

#[dojo::contract]  // <-- This macro provides world_default()
mod my_system {
    use dojo::model::{ModelStorage, ModelValueStorage};
    use dojo::event::EventStorage;

    #[abi(embed_v0)]
    impl MyImpl of IMySystem<ContractState> {
        fn my_function(ref self: ContractState) {
            // world_default() is available because of #[dojo::contract]
            let mut world = self.world_default();
            
            // Now use world for all operations...
        }
    }
}

self.world_default()
由
#[dojo::contract]
自动提供——无需导入！

cairo

#[dojo::contract]  // <-- 该宏提供world_default()
mod my_system {
    use dojo::model::{ModelStorage, ModelValueStorage};
    use dojo::event::EventStorage;

    #[abi(embed_v0)]
    impl MyImpl of IMySystem<ContractState> {
        fn my_function(ref self: ContractState) {
            // 因#[dojo::contract]，world_default()可直接使用
            let mut world = self.world_default();
            
            // 后续所有操作都通过world进行...
        }
    }
}

How to emit events

如何触发事件

Requires:

use dojo::event::EventStorage;

cairo

// 1. Define the event (outside impl block)
#[derive(Copy, Drop, Serde)]
#[dojo::event]
struct PlayerMoved {
    #[key]
    player: ContractAddress,
    from_x: u32,
    from_y: u32,
    to_x: u32,
    to_y: u32,
}

// 2. Emit it (inside a function)
fn move_player(ref self: ContractState, direction: u8) {
    let mut world = self.world_default();
    
    // ... game logic ...
    
    // Emit event - note the @ for snapshot
    world.emit_event(@PlayerMoved {
        player: get_caller_address(),
        from_x: 0,
        from_y: 0, 
        to_x: 1,
        to_y: 1,
    });
}

依赖：

use dojo::event::EventStorage;

cairo

// 1. 定义事件（在impl块外部）
#[derive(Copy, Drop, Serde)]
#[dojo::event]
struct PlayerMoved {
    #[key]
    player: ContractAddress,
    from_x: u32,
    from_y: u32,
    to_x: u32,
    to_y: u32,
}

// 2. 触发事件（在函数内部）
fn move_player(ref self: ContractState, direction: u8) {
    let mut world = self.world_default();
    
    // ... 游戏逻辑 ...
    
    // 触发事件 - 注意使用@进行快照
    world.emit_event(@PlayerMoved {
        player: get_caller_address(),
        from_x: 0,
        from_y: 0, 
        to_x: 1,
        to_y: 1,
    });
}

Quick reference: What imports what

快速参考：功能与对应导入

You want to use	Import this
`world.read_model()`	`use dojo::model::ModelStorage;`
`world.write_model()`	`use dojo::model::ModelStorage;`
`world.emit_event()`	`use dojo::event::EventStorage;`
`self.world_default()`	Nothing! Provided by `#[dojo::contract]`
`get_caller_address()`	`use starknet::get_caller_address;`

想要使用的功能	需导入的内容
`world.read_model()`	`use dojo::model::ModelStorage;`
`world.write_model()`	`use dojo::model::ModelStorage;`
`world.emit_event()`	`use dojo::event::EventStorage;`
`self.world_default()`	无需导入！由 `#[dojo::contract]` 自动提供
`get_caller_address()`	`use starknet::get_caller_address;`

When to Use This Skill

何时使用该技能

"Create a spawn system"
"Add a move system that updates position"
"Implement combat logic"
"Generate a system for [game action]"

"创建一个生成系统"
"添加一个更新位置的移动系统"
"实现战斗逻辑"
"为[游戏操作]生成系统"

What This Skill Does

该技能能做什么

Generates Cairo system contracts with:

```
#[dojo::contract]
```
attribute
Interface definition with
```
#[starknet::interface]
```
System implementation
World access (
```
world.read_model()
```
,
```
world.write_model()
```
)
Event emissions with
```
#[dojo::event]
```

生成包含以下内容的Cairo系统合约：

```
#[dojo::contract]
```
属性
使用
```
#[starknet::interface]
```
定义的接口
系统实现代码
World访问（
```
world.read_model()
```
、
```
world.write_model()
```
）
使用
```
#[dojo::event]
```
触发事件

Quick Start

快速开始

Interactive mode:

"Create a system for player movement"

I'll ask about:

System name
Functions and their parameters
Models used
Authorization requirements

Direct mode:

"Create a move system that updates Position based on Direction"

交互模式：

"创建一个玩家移动系统"

我会询问以下信息：

系统名称
函数及其参数
使用的模型
授权要求

直接模式：

"创建一个根据Direction更新Position的移动系统"

System Structure

系统结构

A Dojo contract consists of an interface trait and a contract module:

cairo

use dojo_starter::models::{Direction, Position};

// Define the interface
#[starknet::interface]
trait IActions<T> {
    fn spawn(ref self: T);
    fn move(ref self: T, direction: Direction);
}

// Dojo contract
#[dojo::contract]
pub mod actions {
    use super::{IActions, Direction, Position};
    use starknet::{ContractAddress, get_caller_address};
    use dojo_starter::models::{Vec2, Moves};

    use dojo::model::{ModelStorage, ModelValueStorage};
    use dojo::event::EventStorage;

    // Define a custom event
    #[derive(Copy, Drop, Serde)]
    #[dojo::event]
    pub struct Moved {
        #[key]
        pub player: ContractAddress,
        pub direction: Direction,
    }

    #[abi(embed_v0)]
    impl ActionsImpl of IActions<ContractState> {
        fn spawn(ref self: ContractState) {
            let mut world = self.world_default();
            let player = get_caller_address();

            // Read current position (defaults to zero if not set)
            let position: Position = world.read_model(player);

            // Set initial position
            let new_position = Position {
                player,
                vec: Vec2 { x: position.vec.x + 10, y: position.vec.y + 10 }
            };
            world.write_model(@new_position);

            // Set initial moves
            let moves = Moves {
                player,
                remaining: 100,
                last_direction: Direction::None(()),
                can_move: true
            };
            world.write_model(@moves);
        }

        fn move(ref self: ContractState, direction: Direction) {
            let mut world = self.world_default();
            let player = get_caller_address();

            // Read current state
            let position: Position = world.read_model(player);
            let mut moves: Moves = world.read_model(player);

            // Update moves
            moves.remaining -= 1;
            moves.last_direction = direction;

            // Calculate next position
            let next = next_position(position, direction);

            // Write updated state
            world.write_model(@next);
            world.write_model(@moves);

            // Emit event
            world.emit_event(@Moved { player, direction });
        }
    }

    // Internal helper to get world with namespace
    #[generate_trait]
    impl InternalImpl of InternalTrait {
        fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
            self.world(@"dojo_starter")
        }
    }
}

// Helper function outside the contract
fn next_position(mut position: Position, direction: Direction) -> Position {
    match direction {
        Direction::None => { return position; },
        Direction::Left => { position.vec.x -= 1; },
        Direction::Right => { position.vec.x += 1; },
        Direction::Up => { position.vec.y -= 1; },
        Direction::Down => { position.vec.y += 1; },
    };
    position
}

Dojo合约由接口 trait 和合约模块组成：

cairo

use dojo_starter::models::{Direction, Position};

// 定义接口
#[starknet::interface]
trait IActions<T> {
    fn spawn(ref self: T);
    fn move(ref self: T, direction: Direction);
}

// Dojo合约
#[dojo::contract]
pub mod actions {
    use super::{IActions, Direction, Position};
    use starknet::{ContractAddress, get_caller_address};
    use dojo_starter::models::{Vec2, Moves};

    use dojo::model::{ModelStorage, ModelValueStorage};
    use dojo::event::EventStorage;

    // 定义自定义事件
    #[derive(Copy, Drop, Serde)]
    #[dojo::event]
    pub struct Moved {
        #[key]
        pub player: ContractAddress,
        pub direction: Direction,
    }

    #[abi(embed_v0)]
    impl ActionsImpl of IActions<ContractState> {
        fn spawn(ref self: ContractState) {
            let mut world = self.world_default();
            let player = get_caller_address();

            // 读取当前位置（未设置则默认值为0）
            let position: Position = world.read_model(player);

            // 设置初始位置
            let new_position = Position {
                player,
                vec: Vec2 { x: position.vec.x + 10, y: position.vec.y + 10 }
            };
            world.write_model(@new_position);

            // 设置初始移动次数
            let moves = Moves {
                player,
                remaining: 100,
                last_direction: Direction::None(()),
                can_move: true
            };
            world.write_model(@moves);
        }

        fn move(ref self: ContractState, direction: Direction) {
            let mut world = self.world_default();
            let player = get_caller_address();

            // 读取当前状态
            let position: Position = world.read_model(player);
            let mut moves: Moves = world.read_model(player);

            // 更新移动次数
            moves.remaining -= 1;
            moves.last_direction = direction;

            // 计算下一个位置
            let next = next_position(position, direction);

            // 写入更新后的状态
            world.write_model(@next);
            world.write_model(@moves);

            // 触发事件
            world.emit_event(@Moved { player, direction });
        }
    }

    // 获取带命名空间的world的内部辅助函数
    #[generate_trait]
    impl InternalImpl of InternalTrait {
        fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
            self.world(@"dojo_starter")
        }
    }
}

// 合约外部的辅助函数
fn next_position(mut position: Position, direction: Direction) -> Position {
    match direction {
        Direction::None => { return position; },
        Direction::Left => { position.vec.x -= 1; },
        Direction::Right => { position.vec.x += 1; },
        Direction::Up => { position.vec.y -= 1; },
        Direction::Down => { position.vec.y += 1; },
    };
    position
}

Key Concepts

核心概念

World Access

World访问

Get the world storage using your namespace:

cairo

let mut world = self.world(@"my_namespace");

Create a helper function to avoid repeating the namespace:

cairo

#[generate_trait]
impl InternalImpl of InternalTrait {
    fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
        self.world(@"my_namespace")
    }
}

使用命名空间获取world存储：

cairo

let mut world = self.world(@"my_namespace");

创建辅助函数避免重复输入命名空间：

cairo

#[generate_trait]
impl InternalImpl of InternalTrait {
    fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
        self.world(@"my_namespace")
    }
}

Reading Models

读取模型

cairo

let position: Position = world.read_model(player);

cairo

let position: Position = world.read_model(player);

Writing Models

写入模型

cairo

world.write_model(@Position { player, vec: Vec2 { x: 10, y: 20 } });

cairo

world.write_model(@Position { player, vec: Vec2 { x: 10, y: 20 } });

Emitting Events

触发事件

Define events with

#[dojo::event]

cairo

#[derive(Copy, Drop, Serde)]
#[dojo::event]
pub struct PlayerMoved {
    #[key]
    pub player: ContractAddress,
    pub from: Vec2,
    pub to: Vec2,
}

// Emit in your function
world.emit_event(@PlayerMoved { player, from: old_pos, to: new_pos });

使用

#[dojo::event]

定义事件：

cairo

#[derive(Copy, Drop, Serde)]
#[dojo::event]
pub struct PlayerMoved {
    #[key]
    pub player: ContractAddress,
    pub from: Vec2,
    pub to: Vec2,
}

// 在函数中触发
world.emit_event(@PlayerMoved { player, from: old_pos, to: new_pos });

Getting Caller

获取调用者

cairo

use starknet::get_caller_address;

let player = get_caller_address();

cairo

use starknet::get_caller_address;

let player = get_caller_address();

Generating Unique IDs

生成唯一ID

cairo

let entity_id = world.uuid();

cairo

let entity_id = world.uuid();

System Design

系统设计

Single Responsibility

单一职责

Each system should have one clear purpose:

```
MovementSystem
```
: Handles player/entity movement
```
CombatSystem
```
: Manages battles and damage
```
InventorySystem
```
: Manages items

每个系统应只有一个明确的用途：

```
MovementSystem
```
：处理玩家/实体移动
```
CombatSystem
```
：管理战斗与伤害
```
InventorySystem
```
：管理物品

Stateless Design

无状态设计

Systems should be stateless, reading state from models:

cairo

fn attack(ref self: ContractState, target: ContractAddress) {
    let mut world = self.world_default();
    let attacker = get_caller_address();

    // Read current state
    let attacker_stats: Combat = world.read_model(attacker);
    let mut target_stats: Combat = world.read_model(target);

    // Apply logic
    target_stats.health -= attacker_stats.damage;

    // Write updated state
    world.write_model(@target_stats);
}

系统应保持无状态，从模型中读取状态：

cairo

fn attack(ref self: ContractState, target: ContractAddress) {
    let mut world = self.world_default();
    let attacker = get_caller_address();

    // 读取当前状态
    let attacker_stats: Combat = world.read_model(attacker);
    let mut target_stats: Combat = world.read_model(target);

    // 应用逻辑
    target_stats.health -= attacker_stats.damage;

    // 写入更新后的状态
    world.write_model(@target_stats);
}

Input Validation

输入验证

Validate inputs before modifying state:

cairo

fn move(ref self: ContractState, direction: Direction) {
    let mut world = self.world_default();
    let player = get_caller_address();

    let moves: Moves = world.read_model(player);
    assert(moves.remaining > 0, 'No moves remaining');
    assert(moves.can_move, 'Movement disabled');

    // Proceed with movement
}

修改状态前需验证输入：

cairo

fn move(ref self: ContractState, direction: Direction) {
    let mut world = self.world_default();
    let player = get_caller_address();

    let moves: Moves = world.read_model(player);
    assert(moves.remaining > 0, 'No moves remaining');
    assert(moves.can_move, 'Movement disabled');

    // 继续执行移动逻辑
}

Permissions

权限设置

Systems need writer permission to modify models. Configure in

dojo_dev.toml

toml

[writers]
"my_namespace" = ["my_namespace-actions"]

Or grant specific model access:

toml

[writers]
"my_namespace-Position" = ["my_namespace-actions"]
"my_namespace-Moves" = ["my_namespace-actions"]

系统需要写入权限才能修改模型。在

dojo_dev.toml

中配置：

toml

[writers]
"my_namespace" = ["my_namespace-actions"]

或授予特定模型的访问权限：

toml

[writers]
"my_namespace-Position" = ["my_namespace-actions"]
"my_namespace-Moves" = ["my_namespace-actions"]

Next Steps

后续步骤

After creating systems:

Use
```
dojo-test
```
skill to test system logic
Use
```
dojo-review
```
skill to check for issues
Use
```
dojo-deploy
```
skill to deploy your world
Use
```
dojo-client
```
skill to call systems from frontend

创建系统后：

使用
```
dojo-test
```
技能测试系统逻辑
使用
```
dojo-review
```
技能检查问题
使用
```
dojo-deploy
```
技能部署你的world
使用
```
dojo-client
```
技能从前端调用系统

dojo-system

Original

Translation

Dojo System Generation

Dojo 系统生成

Essential Imports (Dojo 1.0+)

必要导入（Dojo 1.0+）

Where does self.world_default() come from?

self.world_default() 来自哪里？

How to emit events

如何触发事件

Quick reference: What imports what

快速参考：功能与对应导入

When to Use This Skill

何时使用该技能

What This Skill Does

该技能能做什么

Quick Start

快速开始

System Structure

系统结构

Key Concepts

核心概念

World Access

World访问

Reading Models

读取模型

Writing Models

写入模型

Emitting Events

触发事件

Getting Caller

获取调用者

Generating Unique IDs

生成唯一ID

System Design

系统设计

Single Responsibility

单一职责

Stateless Design

无状态设计

Input Validation

输入验证

Permissions

权限设置

Next Steps

后续步骤

Related Skills

相关技能

Where does
`self.world_default()`
come from?

`self.world_default()`
来自哪里？