Manage world migrations, handle breaking changes, and upgrade Dojo versions. Use when updating deployed worlds, migrating to new versions, or handling schema changes.
Handles Dojo world migrations, version upgrades, and breaking changes. Triggers when you need to update deployed worlds, migrate to new Dojo versions, or manage schema changes.
/plugin marketplace add dojoengine/book/plugin install book@dojoengineThis skill is limited to using the following tools:
Handle world migrations, upgrades, and breaking changes when updating deployed Dojo worlds.
Manages migration workflows:
Update existing world:
"Migrate my changes to the deployed world"
Version upgrade:
"Upgrade my project to Dojo v1.1.0"
Breaking changes:
"Help me handle breaking changes in my models"
Check diff:
sozo migrate --diff
Shows:
Review changes:
Strategy:
Apply changes:
sozo migrate --world WORLD_ADDRESS
With specific profile:
sozo migrate --world WORLD_ADDRESS --profile sepolia
Adding new model:
// New model - safe to add
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct NewFeature {
#[key]
pub player: ContractAddress,
pub data: u32,
}
Adding new system:
// New system - safe to add
#[dojo::contract]
pub mod new_system {
// Implementation
}
Adding model field:
// Old
struct Position {
#[key] player: ContractAddress,
x: u32,
y: u32,
}
// New - adding field (careful!)
struct Position {
#[key] player: ContractAddress,
x: u32,
y: u32,
z: u32, // New field - existing data needs handling
}
Changing key fields:
// Old
struct Position {
#[key] player: ContractAddress,
x: u32, y: u32,
}
// New - BREAKING! Cannot migrate
struct Position {
#[key] entity_id: u32, // Different key type
x: u32, y: u32,
}
Removing fields:
// Old
struct Stats {
#[key] player: ContractAddress,
health: u8,
mana: u8,
}
// New - BREAKING! Data loss
struct Stats {
#[key] player: ContractAddress,
health: u8,
// mana removed
}
Changing field types:
// Old
struct Position {
#[key] player: ContractAddress,
x: u32,
y: u32,
}
// New - BREAKING! Type incompatible
struct Position {
#[key] player: ContractAddress,
x: u128, // Changed type
y: u128,
}
Deploy fresh world with new schema:
# Deploy new world with different name
sozo migrate --name my_game_v2
Pros:
Cons:
Migrate data from old to new:
// Migration system
#[dojo::contract]
pub mod migrator {
fn migrate_positions(ref self: ContractState) {
// Read old format
let old_pos = world.read_model_old(player);
// Transform to new format
let new_pos = transform(old_pos);
// Write new format
world.write_model(@new_pos);
}
}
Keep both old and new:
// Keep old model
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct PositionV1 {
#[key] player: ContractAddress,
x: u32, y: u32,
}
// Add new model
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct PositionV2 {
#[key] entity_id: u32,
x: u32, y: u32, z: u32,
}
Usually safe:
[dependencies]
dojo = { git = "https://github.com/dojoengine/dojo", tag = "v1.0.1" }
scarb update
sozo build
sozo test
sozo migrate --world WORLD_ADDRESS
Check changelog for:
# Update dependency
# Update Scarb.toml
# Rebuild
sozo build
# Test thoroughly
sozo test
# Migrate
sozo migrate --world WORLD_ADDRESS
Breaking changes likely:
# Read CHANGELOG.md and migration guide
# Update code for breaking changes
# Update Scarb.toml
# Build and test
sozo build
sozo test
# Deploy new world or migrate carefully
sozo migrate --name my_game_v2
sozo migrate --diff)sozo build)sozo test)sozo migrate --world ADDR)# 1. Add model to code
# 2. Build
sozo build
# 3. Migrate
sozo migrate --world WORLD_ADDRESS
# 4. Verify
sozo model get NewModel KEY
# 1. Update system code
# 2. Build and test
sozo build
sozo test
# 3. Migrate (redeploys system)
sozo migrate --world WORLD_ADDRESS
# 4. Test updated system
sozo execute actions updated_function
# 1. Add field to model
# 2. Handle existing data:
# - New field will be zero/default for existing entities
# - May need migration system to populate
# 3. Build and migrate
sozo build
sozo migrate --world WORLD_ADDRESS
# Revert to previous commit
git revert HEAD
# Rebuild and migrate
sozo build
sozo migrate --world WORLD_ADDRESS
# Switch to previous tag
git checkout v1.0.0
# Redeploy
sozo build
sozo migrate --world WORLD_ADDRESS
# Deploy new world with new name
sozo migrate --name my_game_legacy # Old version
sozo migrate --name my_game_v2 # New version
# Run both in parallel during transition
sozo build firstAfter migration:
dojo-client skill)dojo-indexer skill)This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.