Modules

Modules are onchain installation scripts that create resources and their associated configuration when called by a World. This is somewhat similar to one of the use cases for foundry scripts (opens in a new tab), except that modules are deployed onchain and can be used by any World on the same chain.

Module installation

The easiest way to install modules is to edit the config file. At the top level you specify modules, a list of modules to install. Every module is a struct with three parameters:

• 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 the module is to be installed with root namespace privileges. The default is false.
• args - a list of arguments to give the module's install function. Each argument is a structure with two fields:
  • type - the 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).

You can see an example of this method on the ERC-721 module page.

Installation by transaction

Modules can be installed using World.installModule(address moduleAddress, bytes memory initData) (opens in a new tab). When you do this, the World calls the module's install function with initData as the argument(s). Because this is a call, the module does not have any administrative permissions on the World.

Alternatively, the owner of the root namespace can install modules using World.installRootModule(address moduleAddress, bytes memory initData) (opens in a new tab). In this case, the World uses delegatecall and module has all the permissions of a System in the root namespace.

Writing modules

The common use for a module is to add functionality to a World. In most cases we expect that a module would:

1. Create a namespace for the new functionality.
2. Create the tables and Systems for the new functionality.
3. Create any access permissions required (beyond the default, which is that a System has access to its own namespace).
4. Either assign the ownership of the new namespace to an entity that would administer it (a user, a multisig, etc.) or burn it by assigning the namespace ownership to address(0).

Root modules run with the same permission as Systems in the root namespace, so they do not need to create a namespace for themselves. They can just create their own tables and Systems as needed.

For more information about writing modules see the detailed guide.

Sample modules

MUD comes with several modules you can use or inspect to help you write your own:

• KeysInTable (opens in a new tab) - automatically tracks the keys in a table to make them enumerable.
• KeysWithValue (opens in a new tab) - automatically tracks a reverse mapping for a table that maps a value hash to a list of keys with this value.
• Puppet (opens in a new tab) - installs the PuppetDelegationControl to allow creating Puppet contracts, eg used by the ERC20 and ERC721 modules.
• ERC20 (opens in a new tab) - installs an ERC20 token into a namespace in a World.
• ERC721 (opens in a new tab) - installs an ERC721 token into a namespace in a World.
• UniqueEntity (opens in a new tab) - add methods to get a unique entity ID.
• Standard Delegations (opens in a new tab) - add delegations limited by time or number of calls.