# MUD in minutes

By [HOL](https://paragraph.com/@tractorprincess) · 2023-06-24

---

MUD: a new blockchain paradigm
------------------------------

MUD is set of libraries and tools that work well together to build scalable onchain applications, which can be deployed to any EVM-based network.

I highly recommend watching Lattice's [D.E.F.CON keynote](https://www.youtube.com/watch?v=P9UTCLCz-iA) on the principles behind MUD. It provides a new way to code, but it's not just any smart contract template… 

> _MUD is a framework for ambitious Ethereum applications (mud.dev)_

MUD uses Entity - Component - System (ECS) architecture, with tables used in place of components in the [codebase](https://github.com/latticexyz/mud).  

ECS creates separation between application state and code that operates on that state; where entities are the basic units of a game, and they can have any number of components. Components are small pieces of data that define an entity's behavior. The code that operates on the components is written in one or more system files.

> _As you may be able to tell already, writing systems and their methods in MUD is similar to writing regular smart contracts. The key difference is that their state is defined and stored in tables rather than in the system contract itself. (mud.dev)_

Indeed, game engine Unity says ECS enables creators to build more **ambitious** games.

![https://mud.dev/](https://storage.googleapis.com/papyrus_images/d9f0850ccbf6925e4b3128893dcd339491f4cae8be99caadcd0ec1c2bddb00fb.png)

https://mud.dev/

### Why use MUD?

*   Scalable
    
*   Flexible
    
*   Fast (no indexers or sub-graphs needed)
    
*   Hot reload for dev
    
*   Huge potential for autonomous applications (just look at the range of projects spawned at the [autonomous worlds hackathon](https://twitter.com/latticexyz/status/1672187756619988993))
    

The MUD stack brings together all the following in an efficient way using [pnpm](https://pnpm.io/), reducing code bloat:

> _Store: An onchain database._
> 
> _World: An entry-point framework that brings standardized access-control, upgrades, and modules._
> 
> _Blazing fast development tools based on Foundry (opens in a new tab)_
> 
> _Client-side data-stores that magically reflect onchain state._
> 
> _MODE: A Postgres database you can query with SQL that reflects your onchain state 1 to 1._

MODE is an off-chain indexer for on-chain applications built with MUD, and it’s able to “track” the state of any MUD-built application on any network that MODE is running on.

The MUD store is used instead of Solidity compiler-driven data storage, making querying data **cheaper** and more **flexible**. 

![https://mud.dev/mode](https://storage.googleapis.com/papyrus_images/dafb4cb1d84ad6882f3bd0f1bdd40a6b36c7d1214de7311995d600a61cf75d81.webp)

https://mud.dev/mode

Dev intro
---------

The MUD [docs](https://mud.dev/quick-start) are pretty great, actually, and it’s easy to grab their template.

The repo is effectively a monorepo containing two packages: **client** and **contracts**. 

Root level dependencies are minimal and they include `@latticexyz`. The packages each contain their own `node_modules`.

### Adding features

Broadly speaking, features can be added iteratively to a project by looping through A, B and C in turn. 

**A. in contracts package**

1.  components are defined as **tables** (examples: Player, Position, Movable, Encounter), together with their types in `mud.config.ts`
    
2.  **methods** that can act on the components are added to the system(s) (_spawn_ player, _move_ position, _block_ movement…) - in the [Emojimon tutorial](https://mud.dev/tutorials/emojimon) you'll see the map system `MapSystem.sol` and the encounter system `EncounterSystem.sol`
    

**B. in client package**

1.  update the **client backend** in `createSystemCalls.ts` to reflect the methods you added to the system. This is also where validation checks can happen, along the lines of 'is valid player', 'is valid move', etc
    
2.  hook up to your **frontend**. `@latticexyz` helpfully provides hooks for reading component values and querying entity states (such as `useComponentValue` and `useEntityQuery` for react)
    
3.  add **optimistic rendering** if you want (recommended). Adding optimistic rendering in MUD is as straightforward as importing `import { overridableComponent } from "@latticexyz/recs";` in `createClientComponents` and then including it wherever you want to optimize in `createSystemCalls`
    

**C. return to contracts package to initialize**

1.  update the post deploy script `PostDeploy.s.sol` to set any **initial configuration** options, such as initializing your map with terrain and enabling encounters
    

### Takeaways

The number of systems doesn't need to match the number of entities, and as already mentioned there can be any number of components.  Taking the time to define how to properly apply the ECS model to the features you want to add to your project is worthwhile, and MUD provides a sub-system pattern for reusable logic.

Time spent in properly designing the project's logic should pay off overall, with a flexible and scalable app at the end.

Frankly, I'm excited to see where MUD takes us.

---

*Originally published on [HOL](https://paragraph.com/@tractorprincess/mud-in-minutes)*