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, oruserTypes
label. Static-length field types (e.g.uint256
) must come before dynamic-length field types (e.g.string
oruint8[]
).- 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 thekey
. For single-field tables, the value in the mapping can be just the field type, which assumes a schema of{ id: "bytes32", value: … }
wherevalue
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 modulerequire
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:
Structure in each argument- type
- Solidity data type.
- value
The value. To encode a complex data type, such as a structure or an array, you can use Viem's
encodeAbiParameters
(opens in a new tab).
- 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 withfoundry.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 withnamespaces/[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 recommendtrue
.