ERC-7509 Entity Component System

Draft · Other · created 2023-09-05

A minimal interface for implementing the Entity Component System (ECS), a design pattern used in game development, as a smart contract. It separates data (components) from logic (systems), allowing an application made of multiple contracts to be freely composed and managed.

Why it is needed

When data and behavior are mixed together inside a single contract for a game or app, the structure becomes hard to change. Adding new features or upgrading affects existing data, and it is hard to reuse code elsewhere. If an app consists of multiple contracts, there is no good way to manage each contract's state in one place. And when different games or apps try to interoperate by exchanging data, there is no common framework for it. This proposal simplifies the ECS pattern, widely used in game development to increase code reuse, for contracts, defining a common interface in which a component (a data container) is attached to an entity (a unique identifier) and manipulated by logic called a system.

What to implement

In depth

World-centered structure and workflow

A world contract is a container that holds entities, component contracts, and system contracts. The core principle is establishing relationships between entities and component contracts, and using system contracts to dynamically change entity data stored inside components. The workflow laid out in the original text has eight steps: create a world by implementing IWorld, create an entity via createEntity(), create a component by implementing IComponent, register it via registerComponent(), attach it to an entity via addComponent(), create a system contract, register it via registerSystem(), and run the system. A system contract has no interface restrictions, so it can define any function.

Why entity existence and state are distinguished

An entity is created via createEntity(), and it MUST be assigned a unique Id. A state of true means usable, and false means unusable; a component cannot be added to or removed from an entity whose state is false. The original text distinguishes an entity that does not exist from an entity whose state is false, because state alone cannot determine whether an entity actually exists. When an external contributor builds a component based on an entity, that component is meaningless if the entity does not exist at all. But if the entity exists and is simply in a false state, it still has meaning, since the contributor can wait for the state to become true and then attach it.

Rules for registering and attaching components

A component MUST be registered to the world before it can be attached to an entity, and the same component MUST NOT be registered more than once. When registering, it is RECOMMENDED (SHOULD) to verify that the address returned by the component's world() matches the current world contract. If a component's state is false, it cannot be attached to an entity. addComponent() can only be used with an enabled entity and component, and the same component cannot be attached twice; removeComponent() can only detach a component that was previously attached. getEntityComponents() returns an array of addresses directly rather than component ids, because returning ids would force the caller to look up the address for each id separately, generating multiple requests.

IComponent and type information

A component contract implements world(), types(), set(), and two variants of get(). types() returns the array of types for entity data and the array of types for get() parameters, and it is RECOMMENDED (SHOULD) to use Types.sol, an enum library covering all data types. The reason for holding type information instead of a plain byte array is to guarantee type correctness when using the component, avoiding potential errors and mismatches, and to let external developers store and retrieve data clearly according to type. set() stores data when both the entity and the system operating on it are enabled and the component is attached to the entity.

The purpose of get() with extra parameters

A component provides two forms of get(). One takes only the entity id, and the other takes an additional parameter called _params, used as a condition when retrieving data. In the original text's example, if a component storing HP corresponding to an entity's level is defined, calling get() with the entity's level passed as _params retrieves the HP matching that specific level. Whether extra parameters are needed is left to the purpose of the implemented component (SHOULD).

External developer participation in registration

Whether registerComponent() and registerSystem() are opened up externally depends on how open the app or game is. If developer participation is encouraged, components and systems registered externally should initially have their state set to false, and should only be activated via setComponentState() and setSystemState() after confirming no malicious code was submitted.

A proposal still in Draft stage

This proposal is in Draft status. Since it is at a draft stage where content may change, the latest specification should be checked before implementation.

Things to watch out for

Original ERC · ← ERCs