Skip to content

Commit

Permalink
move config reference to its own page
Browse files Browse the repository at this point in the history
  • Loading branch information
@holic
holic committed Jul 31, 2024
1 parent 5561ea1 commit 67abe67
Show file tree
Hide file tree
Showing 4 changed files with 265 additions and 201 deletions.
49 changes: 49 additions & 0 deletions docs/components/Params.module.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
.list {
display: grid;
grid-template-columns: 12rem auto;
}
.list > :nth-child(n + 3) {
border-top: 1px solid rgba(255, 255, 255, 0.1);
}
.title:not(:first-child),
.list:not(:first-child):not(.title + .list) {
margin-top: 1rem;
}
.list:not(:last-child) {
margin-bottom: 1rem;
}

.title {
font-size: 0.75rem;
text-transform: uppercase;
font-weight: bold;
text-align: center;
color: rgba(255, 255, 255, 0.5);
}

.title,
.term,
.definition {
padding-left: 0.5rem;
padding-right: 0.5rem;
}
.term,
.definition {
padding-top: 0.375rem;
padding-bottom: 0.375rem;
}
.term {
font-family: monospace;
font-weight: bold;
background: rgba(255, 255, 255, 0.1);
white-space: nowrap;
text-overflow: ellipsis;
overflow: hidden;
}
.term:hover {
overflow: visible;
position: relative;
}
.definition {
padding-left: 0.5rem;
}
30 changes: 30 additions & 0 deletions docs/components/Params.tsx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import React, { ReactNode } from "react";
import styles from "./Params.module.css";

type ParamsProps = {
title?: string;
children: ReactNode;
};

export function Params({ title, children }: ParamsProps) {
return (
<>
{title ? <div className={styles.title}>{title}</div> : null}
<dl className={styles.list}>{children}</dl>
</>
);
}

type ParamProps = {
name: string;
children: ReactNode;
};

export function Param({ name, children }: ParamProps) {
return (
<>
<dt className={styles.term}>{name}</dt>
<dd className={styles.definition}>{children}</dd>
</>
);
}
241 changes: 40 additions & 201 deletions docs/pages/config.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,47 @@
# MUD config

Certain CLI commands, such as [`mud tablegen`](/cli/tablegen) and [`mud worldgen`](/cli/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 `mud.config.ts` file is where a MUD project begins. It defines the resources ([namespaces](/world/namespaces-access-control), [tables](/store/tables), [systems](/world/systems), and [modules](/world/modules)) used by your app and how MUD should codegen and deploy them. Its output is strongly typed for better type safety and developer experience in the form of hinting, inference, and autocomplete.

The config is used to define:
By default, the MUD config assumes your project is using only a [single namespace](#single-namespace). This is a great starting place for simple apps and worlds, where you're not yet thinking about extendability.

- The tables in your project.
- The [namespace(s)](/world/namespaces-access-control) that [systems](/world/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 systems.
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](/world/modules) that will be installed in the `World`.
- The enumerations in your `World`.
- Deployment and code generation options.
Once you're building a more complex app or on top of an existing world, you may want to take advantage of [multiple namespaces](#multiple-namespaces). This enables more complex and composable behavior, including access control around data and functionality. Even MUD itself takes advantage of several namespaces for its core resources.

## Single namespace

```tsx
import { defineWorld } from "@latticexyz/world";

export default defineWorld({
namespace: "mud",
enums: {
TerrainType: ["None", "TallGrass", "Boulder"],
},
tables: {
Counter: {
schema: {
value: "uint32",
},
key: [],
},
Tasks: {
schema: {
id: "bytes32",
createdAt: "uint256",
completedAt: "uint256",
description: "string",
},
key: ["id"],
},
},
systems: {
IncrementSystem: {
name: "increment",
openAccess: true,
},
},
excludeSystems: ["System3", "System2"],
});
```

## Multiple namespaces

Expand Down Expand Up @@ -213,193 +242,3 @@ Note that this is a convention, _any_ `*System.sol` under `src/namespaces/<names
- `src/codegn/common.sol` - the enumerations in the config file.
- `src/codegen/world/I*.sol` - interfaces for all the systems.
- `src/codegen/world/IWorld.sol` - the `IWorld` interface that inherits from all the `I*System.sol` files.

### Fields within a namespace

- **`tables`**: a record of tables. The keys in the record are table names.
The value is a record of [table properties](https://github.com/latticexyz/mud/blob/main/packages/store/ts/config/storeConfig.ts#L110-L135).

- **`schema`** (record):
The keys of this record are the field names in the data, which includes both the key fields and the value fields.
By convention, these keys 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.

- **`key`** (list):
A list of the `schema` fields that are the key for that table.
If you want a singleton table, use an empty list (as in `Counter` table above).

- **`type`** (either `table` or `offchainTable`): [The table type](/store/tables#types-of-tables).
The default is `table`, which is a table stored onchain.
If you specify `offchainTable`, the table's data is only available offchain through events.

- **`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:

- `registerFunctionSelectors` (optional, default `true`): a `bool`.
Whether we want to automatically register the `public` functions of the system as
[function selectors](/world/function-selectors)
- `openAccess` (optional, default `true`): a `bool`.
If set to `false`, access is limited to:
- systems in the same namespace
- Addresses listed in `accessList`
- systems listed in `accessList`
- [Addresses added to the access list after deployment](/world/namespaces-access-control#modifying-access-control).
- `accessList`: an array of `string`. Each address in the array will be granted access to this system, allowing them to call it.

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

### Global configuration keys (for multi-namespace config files)

In addition to `namespaces`, these fields are also supported.

- **`enums`**: a record of [enumerations](https://solidity-by-example.org/enum/).
The keys are the names of the enumerations.
The values are arrays of the strings for the values the enumeration can take.

- **`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.

- **`codegen`**: a record of code generation options.

- **`worldInterfaceName`** a `string`: The name of the interface for the `World`.
The default value is `IWorld`.
- **`worldgenDirectory`** a `string`: The directory for system and world interfaces.
The default value is `world`.

- **`deploy`**: a record of deployment options.

- **`postDeployScript`** a `string`: Script to execute after the deployment is complete.
This script must be placed in the forge scripts directory (see `foundry.toml`) and have a `.s.sol` extension.
The default is `PostDeploy`.

- **`deploysDirectory`** a `string`: Which folder to put the deployment artifacts into after deployment.
The default is `./deploys`.

- **`worldsFile`** a `string`: JSON file for the chain to `World` deploy address mapping.
The default is `./worlds.json`.

- **`upgradeableWorldImplementation`** a `bool`: Whether the `World` is to be deployed behind a proxy to [enable upgrades
of the core World implementation](/world/upgrades). The default is `false`.

## Single namespace

This is an older config file format which is still supported.

```tsx
import { defineWorld } from "@latticexyz/world";

export default defineWorld({
enums: {
TerrainType: ["None", "TallGrass", "Boulder"],
},
excludeSystems: ["System3", "System2"],
worldContractName: "CustomWorld",
namespace: "mud",
systems: {
IncrementSystem: {
name: "increment",
openAccess: true,
},
},
tables: {
Counter: {
schema: {
value: "uint32",
},
key: [],
},
Tasks: {
schema: {
id: "bytes32",
createdAt: "uint256",
completedAt: "uint256",
description: "string",
},
key: ["id"],
},
},
});
```

### Global configuration keys (for single namespace config files)

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, which is [highly discouraged](/guides/best-practices/system-best-practices#avoid-the-root-namespace-if-possible).

- **`tables`**: a record of tables. The keys in the record are table names.
The value is a record of [table properties](https://github.com/latticexyz/mud/blob/main/packages/store/ts/config/storeConfig.ts#L110-L135).

- **`schema`** (record):
The keys of this record are the field names in the data, which includes both the key fields and the value fields.
By convention, these keys 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.

- **`key`** (list):
A list of the `schema` fields that are the key for that table.
If you want a singleton table, use an empty list (as in `Counter` table above).

- **`type`** (either `table` or `offchainTable`): [The table type](/store/tables#types-of-tables).
The default is `table`, which is a table stored onchain.
If you specify `offchainTable`, the table's data is only available offchain through events.

- **`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:

- `registerFunctionSelectors` (optional, default `true`): a `bool`.
Whether we want to automatically register the `public` functions of the system as
[function selectors](/world/function-selectors)
- `openAccess` (optional, default `true`): a `bool`.
If set to `false`, access is limited to:
- Systems in the same namespace
- Addresses listed in `accessList`
- Systems listed in `accessList`
- [Addresses added to the access list after deployment](/world/namespaces-access-control#modifying-access-control).
- `accessList`: an array of `string`. Each address in the array will be granted access to this system, allowing them to call it.

- **`enums`**: a record of [enumerations](https://solidity-by-example.org/enum/).
The keys are the names of the enumerations.
The values are arrays of the strings for the values the enumeration can take.

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

- **`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.

- **`codegen`**: a record of code generation options.

- **`worldInterfaceName`** a `string`: The name of the interface for the `World`.
The default value is `IWorld`.
- **`worldgenDirectory`** a `string`: The directory for system and world interfaces.
The default value is `world`.

- **`deploy`**: a record of deployment options.

- **`postDeployScript`** a `string`: Script to execute after the deployment is complete.
This script must be placed in the forge scripts directory (see `foundry.toml`) and have a `.s.sol` extension.
The default is `PostDeploy`.

- **`deploysDirectory`** a `string`: Which folder to put the deployment artifacts into after deployment.
The default is `./deploys`.

- **`worldsFile`** a `string`: JSON file for the chain to `World` deploy address mapping.
The default is `./worlds.json`.

- <a id="upgradeableWorldImplementation" />
**`upgradeableWorldImplementation`** a `bool`: Whether the `World` is to be deployed behind a proxy to [enable upgrades
of the core World implementation](/world/upgrades). The default is `false`.
Loading

0 comments on commit 67abe67

Please sign in to comment.