Tables

World uses the store tables, but adds access control. For onchain tables, the data is stored by the World contract, which is also a StoreData (opens in a new tab).

When a System reads or writes storage via table libraries, the request goes into StoreSwitch (opens in a new tab). This library decides which approach to use:

• If the System is in the root namespace, then it was called with delegatecall (opens in a new tab). This means it inherits the World storage and can write directly to storage using StoreCore (opens in a new tab). These calls bypass access control.

• If the System is in any other namespace, then it was called with call (opens in a new tab) and has to call back into the World using IStore (opens in a new tab). These calls go through access control. They are only permitted if the System has access to the table in question. By default a System has access to its own namespace and therefore to all the tables inside it. Additional access can be granted by the namespace owner.

1. An account calls a function called game__myFunc on the World. This function was registered by the owner of the game namespace and points to the myFunc function in one of the Systems in the namespace namespace.

2. The World verifies that access is permitted (for example, because game:System is publicly accessible) and if so calls myFunc on the game:System contract with the provided parameters.

3. At some point in its execution myFunc decides to update the data in the table game:Items. As with all other tables, this table is stored in the World's storage. To modify it, function calls a function on the World contract.

4. The World verifies that access is permitted (by default it would be, because game:System has access to the game namespace). If so, it modifies the data in the game:Items table.

Code samples

Reading from a table

Anybody connected to the blockchain can run the view functions that read table content, provided they know which key to use (by default MUD does not keep a list of keys written to a table onchain, to save on storage operations).

All the functions to read from a MUD store are available. In this example we use the Counter table in the vanilla template, which is a singleton so there is no key to worry about.

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;
 
import { Script } from "forge-std/Script.sol";
import { console } from "forge-std/console.sol";
import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";
import { Counter } from "../src/codegen/index.sol";
 
contract ReadCounter is Script {
  function run() external {
    address worldAddress = 0xC14fBdb7808D9e2a37c1a45b635C8C3fF64a1cc1;
    StoreSwitch.setStoreAddress(worldAddress);
    console.log("Counter value:", Counter.get());
  }
}

import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";

import { Counter } from "../src/codegen/index.sol";

    address worldAddress = 0xC14fBdb7808D9e2a37c1a45b635C8C3fF64a1cc1;
    StoreSwitch.setStoreAddress(worldAddress);

    console.log("Counter value:", Counter.get());

Writing to table

All the functions to write to a MUD store are available. In this example we reset Counter to zero. Note that only authorized addresses are allowed to write directly to a table.

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;
 
import { Script } from "forge-std/Script.sol";
import { console } from "forge-std/console.sol";
import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";
import { Counter } from "../src/codegen/index.sol";
 
contract ResetCounter is Script {
  function run() external {
    // Specify a store so that you can use tables directly
    address worldAddress = 0xC14fBdb7808D9e2a37c1a45b635C8C3fF64a1cc1;
    StoreSwitch.setStoreAddress(worldAddress);
 
    // Load the private key from the `PRIVATE_KEY` environment variable (in .env)
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
 
    // Start broadcasting transactions from the deployer account
    vm.startBroadcast(deployerPrivateKey);
    Counter.set(0);
    vm.stopBroadcast();
 
    console.log("Counter value:", Counter.get());
  }
}

    Counter.set(0);