Reference

MUD config reference

The MUD config has two modes: single namespace and multiple namespaces. By default, the config will assume a single namespace unless you start using the namespaces config option.

Single namespace

namespace

The namespace used for this project's resources and access control. The namespace must fit into a bytes14. Leaving this blank will use the root namespace, which is not recommended for most use cases.

tables

A mapping of table labels to their table config. Unless disabled, this will codegen a corresponding table library for better UX when reading/writing records.

Table options
name

The bytes14 name used in the resource ID. Defaults to the first 14 characters of the table label.

type

Table type, either "table" or "offchainTable". Defaults to "table".

schema

An ordered mapping of field names to their schema type, enums label, or userTypes label. Static-length field types (e.g. uint256) must come before dynamic-length field types (e.g. string or uint8[]).

key

A tuple of field names in the schema to be used as the primary key of table records. Only static-length fields are supported as keys.

codegen

Customize how codegen should behave when generating this table's corresponding Solidity library.

outputDirectory
Output directory of codegen table library relative to top-level codegen.outputDirectory. Defaults to "tables".
dataStruct
Whether or not to use a struct for table data. Defaults to true.
deploy

Customize how to deploy this table.

disabled
Disable deployment of this table. Defaults to false.

Tables can also be defined using shorthands. For multi-field tables, the value in the mapping can be just the table schema, but must include a static-length id field to be used as the key. For single-field tables, the value in the mapping can be just the field type, which assumes a schema of { id: "bytes32", value: … } where value is the provided field type.

systems

A mapping of system labels to their system config. All systems must be named using a System suffix. Systems only need to be included here if they are deviating from system config defaults.

System options
name

The bytes14 name used in the resource ID. Defaults to the first 14 characters of the system label.

openAccess
Whether or not any address can call this system. Defaults to true.
accessList
A list of contract addresses or system labels that can call this system, used with openAccess: false.
deploy

Customize how to deploy this system.

disabled
Disable deployment of this system. Defaults to false.
registerWorldFunctions
Whether this system's functions should be registered on the world, prefixed with the system namespace. Defaults to true.

Multiple namespaces

namespaces

A mapping of namespace labels to their namespace config. Using this config option expects your project's source directory to use a similar structure of namespace directories like src/namespaces/[namespaceLabel].

Namespace options
namespace

The bytes14 namespace used in the resource ID. Defaults to the first 14 characters of the namespace label.

tables

Tables in this namespace. Same shape as tables in single namespace mode.

systems

Systems in this namespace. Same shape as systems in single namespace mode.

Additional options

The following options are available in both single- and multiple-namespace modes.

enums

A mapping of enum labels to an array of string values. Enum labels can be used as schema types within tables.

userTypes

A mapping of user type labels to their user type config. User type labels can be used as schema types within tables.

User type options
type
Solidity-native schema type.
filePath

Path to source file relative to project root (must start with ./) or import path from a package (must have proper remappings set up).

modules

A list of modules to install into the world during the deploy step.

Module config options
artifactPath
Relative path to the module's compiled JSON artifact (usually in out) or an import path if using a module from an npm package. This path is resolved using Node's module require API (opens in a new tab).
root
Whether or not to install this as a root module. Defaults to false.
args

A list of arguments used to call the module's install function. Each argument is a structure with two fields:

excludeSystems
A list of system labels to exclude from codegen and deploy.
sourceDirectory
Path to this project's Solidity source files, relative to the project root. Defaults to "src". This should be kept in alignment with foundry.toml.
codegen

Customize how codegen should behave when generating this table's corresponding Solidity library.

outputDirectory
Output directory of codegen relative to sourceDirectory. Defaults to "codegen". When using multiple namespaces, this will be prefixed with namespaces/[namespaceLabel].
userTypesFilename
Filename relative to outputDirectory to codegen enums into. Defaults to "common.sol".
worldgenDirectory
Output directory of world interfaces relative to outputDirectory. Defaults to "world".
deploy

Customize how to deploy this table.

deploysDirectory
Directory, relative to project root, to write the deployment artifacts to. Defaults to "deploys".
postDeployScript
Script name to execute after the deployment is complete. Defaults to "PostDeploy".
worldsFile
JSON filename, relative to project root, to write per-chain world deployment addresses. Defaults to "worlds.json".
upgradeableWorldImplementation
Wheter or not to deploy the world with an upgradeable proxy, allowing for the core implementation to be upgraded. Defaults to false, but we recommend true.