重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
npx skills add https://github.com/dojoengine/book --skill dojo-system创建实现游戏逻辑并修改模型状态的 Dojo 系统(智能合约)。
为任何 Dojo 系统复制这些导入项:
// 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};
self.world_default() 从何而来?self.world_default() 由 #[dojo::contract] 自动提供 - 无需导入!
#[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) {
// world_default() 可用是因为 #[dojo::contract]
let mut world = self.world_default();
// 现在使用 world 进行所有操作...
}
}
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
需要: use dojo::event::EventStorage;
// 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,
});
}
| 你想使用 | 导入这个 |
|---|---|
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; |
生成包含以下内容的 Cairo 系统合约:
#[dojo::contract] 属性#[starknet::interface] 的接口定义world.read_model(), world.write_model())#[dojo::event] 的事件触发交互模式:
"Create a system for player movement"
我将询问:
直接模式:
"Create a move system that updates Position based on Direction"
一个 Dojo 合约包含一个接口特征和一个合约模块:
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();
// 读取当前位置(如果未设置则默认为零)
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
}
使用你的命名空间获取世界存储:
let mut world = self.world(@"my_namespace");
创建一个辅助函数以避免重复命名空间:
#[generate_trait]
impl InternalImpl of InternalTrait {
fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
self.world(@"my_namespace")
}
}
let position: Position = world.read_model(player);
world.write_model(@Position { player, vec: Vec2 { x: 10, y: 20 } });
使用 #[dojo::event] 定义事件:
#[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 });
use starknet::get_caller_address;
let player = get_caller_address();
let entity_id = world.uuid();
每个系统应有一个明确的目的:
MovementSystem:处理玩家/实体移动CombatSystem:管理战斗和伤害InventorySystem:管理物品系统应是无状态的,从模型读取状态:
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);
}
在修改状态之前验证输入:
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');
// 继续移动
}
系统需要写入权限来修改模型。在 dojo_dev.toml 中配置:
[writers]
"my_namespace" = ["my_namespace-actions"]
或授予特定模型访问权限:
[writers]
"my_namespace-Position" = ["my_namespace-actions"]
"my_namespace-Moves" = ["my_namespace-actions"]
创建系统后:
dojo-test 技能测试系统逻辑dojo-review 技能检查问题dojo-deploy 技能部署你的世界dojo-client 技能从前端调用系统每周安装次数
61
代码库
GitHub 星标数
53
首次出现
2026年1月30日
安全审计
安装于
codex57
opencode57
kimi-cli55
gemini-cli55
cursor55
github-copilot54
Create Dojo systems (smart contracts) that implement your game's logic and modify model state.
Copy these imports for any Dojo system:
// 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};
self.world_default() come from?self.world_default() is provided automatically by #[dojo::contract] - no import needed!
#[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...
}
}
}
Requires: use dojo::event::EventStorage;
// 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,
});
}
| 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 |
Generates Cairo system contracts with:
#[dojo::contract] attribute#[starknet::interface]world.read_model(), world.write_model())#[dojo::event]Interactive mode:
"Create a system for player movement"
I'll ask about:
Direct mode:
"Create a move system that updates Position based on Direction"
A Dojo contract consists of an interface trait and a contract module:
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
}
Get the world storage using your namespace:
let mut world = self.world(@"my_namespace");
Create a helper function to avoid repeating the namespace:
#[generate_trait]
impl InternalImpl of InternalTrait {
fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
self.world(@"my_namespace")
}
}
let position: Position = world.read_model(player);
world.write_model(@Position { player, vec: Vec2 { x: 10, y: 20 } });
Define events with #[dojo::event]:
#[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 });
use starknet::get_caller_address;
let player = get_caller_address();
let entity_id = world.uuid();
Each system should have one clear purpose:
MovementSystem: Handles player/entity movementCombatSystem: Manages battles and damageInventorySystem: Manages itemsSystems should be stateless, reading state from models:
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);
}
Validate inputs before modifying state:
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
}
Systems need writer permission to modify models. Configure in dojo_dev.toml:
[writers]
"my_namespace" = ["my_namespace-actions"]
Or grant specific model access:
[writers]
"my_namespace-Position" = ["my_namespace-actions"]
"my_namespace-Moves" = ["my_namespace-actions"]
After creating systems:
dojo-test skill to test system logicdojo-review skill to check for issuesdojo-deploy skill to deploy your worlddojo-client skill to call systems from frontendWeekly Installs
61
Repository
GitHub Stars
53
First Seen
Jan 30, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex57
opencode57
kimi-cli55
gemini-cli55
cursor55
github-copilot54
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
123,700 周安装
#[dojo::contract]get_caller_address() | use starknet::get_caller_address; |