How to Build Fully On-Chain Games with MUD and Dojo: A Practical Guide for Web3 Developers

Building fully on-chain games is no longer a theoretical exercise reserved for blockchain maximalists. Thanks to the rapid evolution of open-source frameworks like MUD and Dojo, Web3 developers now have the tools to create complex, persistent game worlds governed entirely by smart contracts. In 2025, these frameworks stand at the heart of a new wave of transparent, player-owned gaming ecosystems that are pushing the boundaries of what’s possible on Ethereum and StarkNet.

The Core Architecture: Why ECS Matters for On-Chain Games

At the foundation of both MUD and Dojo lies the Entity-Component-System (ECS) pattern. This architectural approach separates data (components) from behavior (systems), allowing for modular, scalable design that is especially well-suited to decentralized environments. In practical terms, ECS means you can build games where every property and rule is stored and enforced directly on-chain, ensuring transparency and composability.

MUD employs ECS to structure its core components:

Store: An on-chain database for managing persistent game state.
World: A standardized gateway for access control, upgrades, and modular extensions.
MODE: A robust query engine using SQL-like syntax to reflect live chain state.

Dojo, meanwhile, brings ECS natively to StarkNet through Cairo contracts. Its ecosystem includes:

Katana: Local sequencer for rapid development iteration.
Sozo: CLI toolset for project management and contract deployment.
Torii: Indexing engine enabling efficient off-chain queries.

This shared architecture is not just a technical curiosity – it’s a direct response to the challenges of scaling complex game logic in trustless environments. By making state transitions explicit and modular, developers can iterate faster while maintaining security guarantees that are essential in Web3 gaming.

[tweet]

MUD vs Dojo: Choosing Your Framework

The decision between MUD and Dojo is not simply about chain preference – it’s about aligning your project’s needs with each framework’s strengths. If you’re targeting Ethereum mainnet or L2s compatible with Solidity, MUD offers mature tooling and a growing library of modules designed for composability. Its SQL-inspired MODE system provides powerful ways to query game state directly from the chain – a boon for analytics-heavy or social games.

If your ambitions lean toward provable computation or leveraging Cairo’s performance optimizations on StarkNet, Dojo is purpose-built for you. With its native support for zero-knowledge proofs and high-throughput execution via Katana, Dojo enables games with richer mechanics while keeping all logic verifiable on-chain. The result? Worlds where players can trust not only ownership but also every outcome generated by code. For a deeper dive into how these engines are shaping next-generation titles, see this analysis.

Your First Steps: Setting Up an On-Chain Game Project

The practical journey begins with understanding your chosen framework’s development environment. Here’s how most teams get started today:

Initialize Your Fully On-Chain Game Project with MUD or Dojo

a diagram illustrating the Entity-Component-System (ECS) architecture with labeled boxes for Entities, Components, and Systems, connected by arrows, in a modern, minimalist style

Understand the ECS Architecture

Begin by familiarizing yourself with the Entity-Component-System (ECS) architecture. This modular approach separates game state (Components) from logic (Systems), enabling scalable, flexible, and reusable code—a foundational principle for both MUD and Dojo frameworks.

a thoughtful developer at a crossroads, signposts labeled 'MUD (Ethereum)' and 'Dojo (StarkNet)', futuristic style

Choose Your Framework: MUD or Dojo

Select the framework that aligns with your target blockchain: use MUD for Ethereum-based games or Dojo for StarkNet projects, especially if you require provable on-chain logic. Assess your project’s needs and the ecosystem you wish to build within.

a developer's desk with a laptop, terminal windows showing installation commands for MUD and Dojo tools, clean and organized workspace

Set Up Your Development Environment

Prepare your local environment. For MUD, install the framework and its dependencies via npm or yarn. For Dojo, follow the official guide to install Katana, Sozo, and Torii. Ensure your tools are up-to-date to leverage the latest features and security patches.

a whiteboard filled with diagrams of game entities and components, sticky notes representing systems, creative brainstorming session

Develop Game Components and Systems

Define your game’s entities and their components (e.g., health, position, inventory). Implement systems to handle game logic, such as movement or combat. This modularity allows for easy iteration and expansion as your game evolves.

a futuristic control room with screens showing contract deployment progress and test results, sense of anticipation

Deploy and Test Your Contracts

Deploy your smart contracts using the framework’s tools—Sozo for Dojo or MUD’s deployment scripts. Test your game thoroughly in a local or testnet environment to ensure all logic and interactions function as intended before going live.

a vibrant online forum with avatars of developers discussing, exchanging ideas, and sharing code snippets, digital community vibe

Engage with the On-Chain Game Dev Community

Join the MUD and Dojo developer communities to exchange knowledge, solve challenges, and stay informed about best practices. Collaboration accelerates learning and helps you keep pace with the rapidly evolving on-chain gaming landscape.

MUD Setup Highlights:

Install Node. js dependencies via npm or yarn
Create your project scaffold using mud-cli tools
Define components (e. g. , PlayerStats, Inventory) as Solidity contracts extending MUD interfaces
Add systems (e. g. , CombatSystem) to handle interactions between entities/components

Dojo Setup Highlights:

Install Cairo toolchain; initialize project via Sozo CLI
Create component schemas in Cairo files (e. g. , Position. cairo)
Add system logic as separate contract modules; wire up access control via World configuration

This early phase is critical – it lays down the rules that will govern your world autonomously once deployed. Both frameworks emphasize modularity from day one so that you can upgrade systems or add new features without risking legacy code integrity.

With your project scaffolded and the ECS foundation in place, the next step is to bring your game logic and persistent state to life. This phase is where the unique strengths of fully on-chain games become apparent: every move, asset, and outcome is not just recorded but enforced by smart contracts, eliminating ambiguity and empowering true player ownership.

From Components to Gameplay: Implementing Game Logic On-Chain

The heart of any on-chain game lies in its systems, the smart contract modules that define how entities interact, evolve, or compete. In MUD, systems are typically Solidity contracts that reference component data stored in the Store. For instance, a CombatSystem might check player stats before resolving an attack, then update health or inventory components based on results. Dojo follows a similar approach using Cairo for StarkNet-native logic, leveraging its composability for more complex or zero-knowledge-driven mechanics.

Testing is non-negotiable at this stage. Both frameworks offer robust local environments, MUD’s testnet deployments and Dojo’s Katana sequencer, so you can simulate transactions and edge cases without incurring real gas costs. This iterative process ensures your game remains secure and bug-free before going live.

Persistent Game State: Why It Matters for Players

What sets fully on-chain games apart from traditional Web2 or even hybrid blockchain games is the guarantee of persistent state. Player progress, assets, world changes, all are immutably recorded on-chain and accessible via public queries. This persistence isn’t just technical; it enables new economic models (like interoperable NFTs) and social dynamics (such as DAOs governing world rules) that were previously impossible.

The MODE query engine in MUD serves as a prime example, developers and community members alike can craft custom SQL-like queries to surface real-time insights about the world state. In Dojo, Torii provides similar capabilities adapted for StarkNet’s architecture.

Scaling Your World: Upgrades and Community-Driven Development

A key advantage of ECS-based frameworks is upgradeability. As your game grows, from a simple prototype to a living world, you can deploy new systems or extend components without rewriting core contracts. Both MUD’s World module and Dojo’s modular design support hot-swapping features while preserving legacy data, a paradigm shift from monolithic smart contract design.

This flexibility fosters vibrant community involvement. Open-source modules can be shared across projects; player-created content becomes part of the canonical world; DAOs may even vote on upgrades or rule changes, ensuring that governance remains transparent and participatory at every level.

Innovative On-Chain Games Built with MUD and Dojo

PopCraft – A fully on-chain, casual click-based game built with MUD, demonstrating real-time gameplay and persistent world state managed entirely on Ethereum. PopCraft showcases the potential for non-financial, interactive experiences in the on-chain ecosystem.
Realms: Eternum – A strategy game leveraging Dojo on StarkNet, where players build, trade, and conquer in a provable, autonomous world. Realms: Eternum exemplifies how Dojo enables complex, scalable on-chain mechanics and player-owned assets.
Bibliotheca DAO’s Autonomous Worlds – An initiative using Dojo to create open, persistent worlds on StarkNet, where the game logic and state are fully transparent and governed by the community. This project highlights the collaborative and composable nature of on-chain game development.
Mammothon – A fully on-chain game integrating MUD with HappyChain, designed for experimentation with autonomous world-building and user-driven economies. Mammothon demonstrates the flexibility of MUD for rapid prototyping and modular game logic.
Loot Realms – An open-source, on-chain metaverse built with Dojo, where NFTs and game assets are managed as composable components. Loot Realms illustrates the synergy between NFT collections and on-chain game frameworks for creating dynamic, player-owned universes.

Next Steps: From MVP to Autonomous Worlds

After initial deployment comes iteration, listening to players, analyzing on-chain data, refining systems for balance or scalability. The open nature of fully on-chain games means analytics aren’t proprietary; anyone can build dashboards or bots using MODE (MUD) or Torii (Dojo), fostering transparency across the ecosystem.

If you’re ready to deepen your technical understanding or explore case studies from leading projects, don’t miss our deep dives into technical challenges faced by pioneering teams. For inspiration on what’s already possible with these frameworks, see our curated list of top strategy games built with MUD and Dojo.