@dojoengine/recs

recs - Reactive Entity Component System

recs is built with reactivity in mind. Components and Queries expose an update$ stream, that Systems can react to.

To build some fundamental intuition about ECS, have a look at our MUD ECS introduction.

recs is seamlessly integrated with the other MUD libraries, but can be used independently.

For detailed documentation, check out mud.dev/recs.

Features

• Reactive components, queries, and systems
• Powerful queries, including advanced indirect relationship queries
• Seamless integration with other MUD libraries and services
• Simple, declarative API
• Ultra high performance
• TypeScript support

Example

import {
  createWorld,
  defineComponent,
  createEntity,
  withValue,
  defineSystem,
  Has,
  getComponentValue,
  setComponent,
} from "@latticexyz/recs";

// Create a new World
const World = createWorld();

// Define a couple components
const Position = defineComponent(world, { x: Type.Number, y: Type.Number });
const Movable = defineComponent(world, { speed: Type.Number });

// Create a new entity
const entity1 = createEntity(world, [withValue(Position, { x: 0, y: 0 }), withValue(Movable, { speed: 10 })]);

// Define a system that reacts to updates of movable entities with a position
defineSystem(world, [Has(Position), Has(Movable)], (update) => {
  console.log("Entity", update.entity, "moved to", update.value);
  // ... do stuff, like rendering the entity on the screen, etc
});

// Move the entity around
setInterval(() => {
  const currentPosition = getComponentValue(Position, entity1);
  const newPosition = { x: position.x + 1, y: position.y + 1 };
  setComponent(Position, entity1, newPosition);
}, 1000);

Acknowledgements

• Syntax originally inspired by bitECS

Changelog

Version 2.0.12

Release date: Fri May 31 2024

Patch changes

feat(store,world): add option to codegen tables into namespace dirs (#2840) (@latticexyz/store)

Internal tablegen function (exported from @latticexyz/store/codegen) now expects an object of options with a configPath to use as a base path to resolve other relative paths from.

feat(store,world): add option to codegen tables into namespace dirs (#2840) (@latticexyz/store, @latticexyz/world)

Added sourceDirectory as a top-level config option for specifying contracts source (i.e. Solidity) directory relative to the MUD config. This is used to resolve other paths in the config, like codegen and user types. Like foundry.toml, this defaults to src and should be kept in sync with foundry.toml.

Also added a codegen.namespaceDirectories option to organize codegen output (table libraries, etc.) into directories by namespace. For example, a Counter table in the app namespace will have codegen at codegen/app/tables/Counter.sol. If not set, defaults to true when using top-level namespaces key, false otherwise.

fix(cli,world): resolve table by just name (#2850) (@latticexyz/cli, @latticexyz/world)

Fixed resolveTableId usage within config's module args to allow referencing both namespaced tables (e.g. resolveTableId("app_Tasks")) as well as tables by just their name (e.g. resolveTableId("Tasks")). Note that using just the table name requires it to be unique among all tables within the config.

This helper is now exported from @latticexyz/world package as intended. The previous, deprecated export has been removed.

-import { resolveTableId } from "@latticexyz/config/library";
+import { resolveTableId } from "@latticexyz/world/internal";

fix(world-modules): register total supply table in erc20 module (#2877) (@latticexyz/world-modules)

Fixed ERC20Module to register the TotalSupply table when creating a new token.

If you've deployed a world with the ERC20Module, we recommend patching your world to register this table so that indexers can properly decode its record. You can do so with a simple Forge script:

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

import { Script } from "forge-std/Script.sol";
import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";
import { TotalSupply } from "@latticexyz/world-modules/src/modules/erc20-puppet/tables/TotalSupply.sol";
import { _totalSupplyTableId } from "@latticexyz/world-modules/src/modules/erc20-puppet/utils.sol";

contract RegisterTotalSupply is Script {
  function run(address worldAddress, string memory namespaceString) external {
    bytes14 namespace = bytes14(bytes(namespaceString));

    StoreSwitch.setStoreAddress(worldAddress);

    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
    vm.startBroadcast(deployerPrivateKey);

    TotalSupply.register(_totalSupplyTableId(namespace));

    vm.stopBroadcast();
  }
}

Then execute the transactions by running the following forge script command:

forge script ./script/RegisterTotalSupply.s.sol --sig "run(address,string)" $WORLD_ADDRESS $NAMESPACE_STRING

feat(common): export base tsconfig (#2873) (@latticexyz/abi-ts, @latticexyz/block-logs-stream, @latticexyz/cli, @latticexyz/common, @latticexyz/config, @latticexyz/dev-tools, @latticexyz/faucet, @latticexyz/gas-report, @latticexyz/protocol-parser, @latticexyz/query, @latticexyz/react, @latticexyz/recs, @latticexyz/schema-type, @latticexyz/store-indexer, @latticexyz/store-sync, @latticexyz/store, @latticexyz/utils, @latticexyz/world-modules, @latticexyz/world, create-mud, solhint-config-mud, solhint-plugin-mud)

TS source has been removed from published packages in favor of DTS in an effort to improve TS performance. All packages now inherit from a base TS config in @latticexyz/common to allow us to continue iterating on TS performance without requiring changes in your project code.

If you have a MUD project that you're upgrading, we suggest adding a tsconfig.json file to your project workspace that extends this base config.

pnpm add -D @latticexyz/common
echo "{\n  \"extends\": \"@latticexyz/common/tsconfig.base.json\"\n}" > tsconfig.json

Then in each package of your project, inherit from your workspace root's config.

For example, your TS config in packages/contracts/tsconfig.json might look like:

{
  "extends": "../../tsconfig.json"
}

And your TS config in packages/client/tsconfig.json might look like:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "types": ["vite/client"],
    "target": "ESNext",
    "lib": ["ESNext", "DOM"],
    "jsx": "react-jsx",
    "jsxImportSource": "react"
  },
  "include": ["src"]
}

You may need to adjust the above configs to include any additional TS options you've set. This config pattern may also reveal new TS errors that need to be fixed or rules disabled.

If you want to keep your existing TS configs, we recommend at least updating your moduleResolution setting.

-"moduleResolution": "node"
+"moduleResolution": "Bundler"

feat(create-mud): clean up template scripts, add garnet/redstone (#2839) (create-mud)

Removed unnecessary build step in scripts and added deploy scripts for Redstone and Garnet chains.

---