MUD for Solidity Programmers

To properly use MUD you need to do some things differently than the way you do them normally in Solidity.

State variables

A System contract should not store any internal state, but only interact with World state via Tables.

• By concentrating all the state information in a single contract (the World) we make it easier to apply access control, execute hooks when data changes, etc.
• It is a lot easier to upgrade functionality when you do not need to deal with storage because the contract does not have a state.
• The same System can be used by multiple Worlds.

Instead of using state variables (opens in a new tab) you can achieve the same functionality with tables.

Value-type (string, uint, etc.)

Value-type (opens in a new tab) state variables such as bool, uint256, and string are represented by a singleton table, a table with no key that only contains a single record.

contract Example {
  string name;
}

import { defineWorld } from "@latticexyz/world";
 
export default defineWorld({
  namespace: "app",
  tables: {
    Name: {
      schema: {
        name: "string",
      },
      key: [],
    },
  },
});

Structures

A struct (opens in a new tab) state variable wraps multiple variables together. You can create a singleton table with multiple value fields.

contract Example {
  struct Person {
    string name;
    address personalWallet;
    uint balance;
  }
  Person deployer;
}

import { defineWorld } from "@latticexyz/world";
 
export default defineWorld({
  namespace: "app",
  tables: {
    Deployer: {
      schema: {
        personalWallet: "address",
        balance: "uint256",
        name: "string",
      },
      key: [],
    },
  },
});

Mappings

A mapping type (opens in a new tab) maps between a key type and a value type, which is pretty much the same as what MUD tables do.

contract Example {
  mapping(address => uint) public balances;
}

import { defineWorld } from "@latticexyz/world";
 
export default defineWorld({
  namespace: "app",
  tables: {
    Balances: {
      schema: {
        owner: "address",
        balance: "uint256",
      },
      key: ["owner"],
    },
  },
});

contract Example {
  mapping(address => mapping(address => uint256)) public allowances;
}

import { defineWorld } from "@latticexyz/world";
 
export default defineWorld({
  namespace: "app",
  tables: {
    Allowances: {
      schema: {
        owner: "address",
        spender: "address",
        balance: "uint256",
      },
      key: ["owner", "spender"],
    },
  },
});

Arrays

There are two ways in which MUD supports arrays.

1. Arrays of fixed-length value types, such as uint24[] or address[], are supported as table fields (opens in a new tab).

   Example

   Solidity

   contract Example {
     bool[] listOfBooleans;
   }

   MUD

   import { defineWorld } from "@latticexyz/world";
    
   export default defineWorld({
     namespace: "app",
     tables: {
       ListOfBooleans: {
         schema: {
           values: "bool[]",
         },
         key: [],
       },
     },
   });

2. An array is a mapping between an unsigned integer and the value type of the array. We can use a table with index as the key. That way, we can get around the limitation that arrays of variable-length types such as string or bytes are not supported.

   Example

   Solidity

   contract Example {
     string[] listOfNames;
   }

   MUD

   import { defineWorld } from "@latticexyz/world";
    
   export default defineWorld({
     namespace: "app",
     tables: {
       ListOfNames: {
         schema: {
           index: "uint256",
           name: "string",
         },
         key: ["index"],
       },
     },
   });