MUD config

Certain CLI commands, such as mud tablegen and mud worldgen require the MUD configuration file. This file needs to be named mud.config.ts and be in the same folder as your foundry.toml file.

The config is used to define:

  • The tables in your project in the tables object of your configuration.
  • The namespace that systems and tables will be deployed in.
  • The Systems in your project. By default, the deployer will find all Solidity matching *System.sol (so any file ending in System.sol, in any folder) and deploy them as public System. If you want greater control over your systems (to change their public access or their name), you can use the systems object in the config.
  • The modules that will be installed in the World.

The is an example of a World config:

import { mudConfig } from "@latticexyz/world/register";
import { resolveTableId } from "@latticexyz/config";
export default mudConfig({
  excludeSystems: ["System3", "System2"],
  worldContractName: "CustomWorld",
  namespace: "mud",
  systems: {
    IncrementSystem: {
      name: "increment",
      openAccess: true,
  tables: {
    CounterTable: {
      valueSchema: {
        value: "uint32",
  deploysDirectory: "./mud-deploys",
  modules: [
      name: "KeysWithValueModule",
      root: true,
      args: [resolveTableId("CounterTable")],

Global configuration keys

The global configuration keys are all optional.

  • namespace: a string: which namespace to deploy the resources defined in the config into. The default value is the ROOT namespace.

  • excludeSystems: an array of string: which systems to not deploy, even if their name ends with “System”.

  • worldContractName: a string: the name of a contract in your project implementing the IWorld interface. Useful if you want to modify the default World implementation, but potentially dangerous.

  • deploysDirectory a string: which folder to put the deployment artifacts into after deployment.

  • modules an array of module definitions: each module definition has a name, root (optional), and args key.

    • name: Name of the module to install. The same module can be installed multiple times. This should be the name of the contract file without .sol (eg: if the file is named DopeModule.sol, the name of the module is DopeModule)

    • root: whether to create a root module or not. root modules have access to all tables and are not bound to namespace restrictions.

    • args: a list of arguments to be sent to the install function of the module. In this array, you can use the function resolveTableId. This function will turn a table name from your config into its low-level ID in the World. It is useful to pass references of a table to a module.

  • systems: a record of system definitions. The keys in the record are file names without the .sol extension. For example, if your system is named TestSystem.sol, use TestSystem as the key.

    The value is a record of system configuration properties:

    • fileSelector (optional): a string: the file selector for the system.

    • openAccess (optional, default true): a bool: if set to false, only the systems in the same namespace and the addresses or systems listed in the the accessList array have access.

    • accessList (required if openAccess is false): an array of string. Each address in the array will be granted access to this system, allowing them to call it.

  • tables: a record of tables. The keys in the record are table names. The value is a record of table properties (opens in a new tab).

    • valueSchema (record): The keys of this record are the field names of the value (which should start with a lowercase letter). The values are strings that contain the data types of the fields. Note that this is the sole required field, all the others are optional.

    • keySchema (record): The keys of this record are the field names of the key (which should start with a lowercase letter). The values are strings that contain the data types of the fields.

      The default value is:

      { "key": "bytes32" }

      For a singleton table (one that contains a single row), use {} as the key schema.

    • directory (string): Directory in which to create the table. The default is tables, so by default tables are created in src/codegen/tables.

    • tableIdArgument (bool): Make methods accept tableId argument instead of it being a hardcoded constant. The default is false because you can achieve the same result using StoreSwitch.

    • storeArgument (bool): Include methods that accept a manual IStore argument. The default is true.

    • offchainOnly: (bool): Table's information is available offchain (using events (opens in a new tab)), but don't store in onchain. These tables require a lot less gas.

    • dataStruct: (bool): Include a data struct (opens in a new tab) and methods for it. Default is false for 1-column tables; true for multi-column tables.

      Sample code for using a table library with dataStruct:

      // no data struct
      MyTable.set(keccak256("some.key"), 1, 12, "foo");
      // data struct
      MyTable.set(keccak256("some.key"), { field1: 1, field2: 12, stringField: "foo" });