dojoengine/book
Overview
This skill manages Dojo world migrations, upgrades, and breaking-change workflows when updating deployed Dojo worlds. It helps you inspect diffs, plan safe strategies, and execute migrations while preserving data integrity and minimizing downtime.
How this skill works
The skill inspects current world state and code changes (sozo inspect), builds and tests locally (sozo build, sozo test), and runs migrations (sozo migrate) using profiles. It classifies changes as additive or breaking, recommends strategies (new world, parallel models, or data-migration systems), and provides a checklist and troubleshooting guidance for successful upgrades.
When to use it
- Deploy changes to an existing Dojo world
- Upgrade your project to a new Dojo version
- Handle schema or model breaking changes
- Migrate data between model versions
- Validate migration on testnet before production
Best practices
- Run sozo inspect to understand new, modified, and removed resources before migrating
- Prefer additive changes where possible; treat key, type, or removed-field changes as breaking
- For breaking changes, choose between new world, parallel models, or an explicit data migration system
- Build and run full test suites (sozo build; sozo test) and test migrations on Katana or testnet first
- Keep a migration checklist: inspect, plan, build, test, migrate, verify, and monitor
Example use cases
- Add a new model and migrate safely with default profile
- Upgrade project dependencies to Dojo v1.8.0, run tests, then migrate
- Handle a changed model key by deploying parallel model versions and writing a migrator to copy data
- Deploy a new world seed to avoid irreversible breaking changes and migrate clients to the new address
- Debug migration failures by rebuilding, checking Scarb.toml compatibility, and verifying account gas profiles
FAQ
Safest options are deploy a new world (different seed) or keep versioned models and write a migration system to transform data; both avoid in-place destructive changes.
What commands should I run before migrating?
Run sozo inspect to review diffs, then sozo build and sozo test to ensure the code compiles and passes tests before sozo migrate.
How do I upgrade the Dojo version?
Update dojo versions in Scarb.toml, review the changelog for breaking changes, rebuild and test, then run sozo migrate.
8 skills
This skill helps manage world migrations, upgrades, and breaking changes in Dojo deployments, ensuring smooth version updates and data integrity.
This skill helps you connect and bind your game clients to a Dojo world, generating bindings and enabling real-time queries.
This skill helps you configure Dojo projects by managing Scarb.toml, profiles, world settings, and dependencies across environments.
This skill helps you generate comprehensive Dojo tests for models and systems using spawn_test_world and cheat codes to verify state and behavior.
This skill helps you configure and use the Torii indexer for GraphQL queries, real-time subscriptions, and SQL access to your world state.
This skill helps you implement ERC20 and ERC721 token standards in Dojo using Origami, enabling game currencies, items, and token-based mechanics.
This skill helps you generate Cairo Dojo system contracts that implement game logic, modify models, and emit events.
This skill helps you configure world permissions, manage namespaces and resource ownership to enforce access control in your Dojo world.
