dojo-model
Create Dojo models for storing game state with proper key definitions, trait derivations, and ECS patterns. Use when defining game entities, components, or state structures.
When & Why to Use This Skill
This Claude skill streamlines on-chain game development by automating the creation of Dojo models in Cairo. It ensures that game state structures follow Entity Component System (ECS) patterns, automatically handling boilerplate tasks such as trait derivations (Drop, Serde, Copy), key field configurations, and optimized data typing for the Starknet ecosystem.
Use Cases
- Defining game entities and components like Player stats, NPC attributes, or Item properties with proper ECS architecture.
- Creating spatial and map systems using composite keys to define coordinates, tiles, and environmental data.
- Implementing player-owned state models, such as inventories or quest progress, keyed by contract addresses.
- Generating global singleton models for game-wide configurations and state constants.
| name | dojo-model |
|---|---|
| description | Create Dojo models for storing game state with proper key definitions, trait derivations, and ECS patterns. Use when defining game entities, components, or state structures. |
| allowed-tools | Read, Write, Edit, Glob, Grep |
Dojo Model Generation
Create Dojo models that define your game's state using Entity Component System (ECS) patterns.
When to Use This Skill
- "Add a Position model"
- "Create a Player entity with health and level"
- "Generate an Inventory model"
- "Define a model for [game concept]"
What This Skill Does
Generates Cairo model structs with:
#[dojo::model]attribute- Proper trait derivations (Drop, Serde, Copy)
- Key field configuration (#[key])
- Field types appropriate to your data
- Optional: Model tests
Quick Start
Interactive mode:
"Add a model for player positions"
I'll ask about:
- Model name
- Key fields (what makes it unique)
- Data fields and their types
- Whether to generate tests
Direct mode:
"Create a Position model with player as key and x, y coordinates"
Model Patterns
Entity Component
Small, focused models for specific aspects:
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Position {
#[key]
pub entity_id: u32,
pub x: u32,
pub y: u32,
}
Player-Owned
Models keyed by player address:
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Inventory {
#[key]
pub player: ContractAddress,
pub gold: u32,
pub items: u8,
}
Composite Keys
Multiple keys for relationships:
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Tile {
#[key]
pub x: u32,
#[key]
pub y: u32,
pub terrain_type: u8,
}
Global Singleton
Constant key for global state:
const GAME_CONFIG: u128 = 999999;
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Config {
#[key]
pub config_id: u128,
pub max_players: u8,
}
Key Concepts
#[key] Attribute:
- Defines how models are indexed
- At least one key required
- Keys must come before data fields
- Keys not stored, used for lookup only
Required Traits:
Drop- Cairo ownershipSerde- SerializationCopy- For copyable types (optional)
Field Types:
u8,u32,u128- Unsigned integersfelt252- Field elementsbool- BooleansContractAddress- Addresses- Custom enums (with Introspect)
Model API
Write a Model
world.write_model(@Position { entity_id: 1, x: 10, y: 20 });
Read a Model
let position: Position = world.read_model(entity_id);
Update a Model
let mut position: Position = world.read_model(entity_id);
position.x += 1;
world.write_model(@position);
Best Practices
- Keep models small and focused (one concern per model)
- Use appropriate key patterns (single, composite, constant)
- Choose smallest sufficient type (u8 vs u32 vs u128)
- Name fields clearly
- Add doc comments for complex models
Next Steps
After creating models:
- Use
dojo-systemskill to create systems that use your models - Use
dojo-testskill to test model read/write operations - Use
dojo-configskill to ensure models are registered
Related Skills
- dojo-system: Create systems that use these models
- dojo-test: Test your models
- dojo-init: Initialize project first
- dojo-review: Review model design