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
function createEntity() external returns (uint256);: Creates a new entity, assigns it a unique Id, and returns it.function entityExists(uint256 _entityId) external view returns (bool);: Reports whether the given entity exists in the world.function getEntityCount() external view returns (uint256);: Returns the total number of entities in the world.function setEntityState(uint256 _entityId, bool _entityState) external;: Switches an entity's state to enabled (true) or disabled (false).function getEntityState(uint256 _entityId) external view returns (bool);: Returns the current state of the entity.function registerComponent(address _componentAddress) external;: Registers a component contract to the world. The same component cannot be registered more than once.function componentExists(address _componentAddress) external view returns (bool);: Reports whether the given component is registered in the world.function getComponents() external view returns (address[] memory);: Returns an array of contract addresses for every component registered in the world.function setComponentState(address _componentAddress, bool _componentState) external;: Changes a component's state. If false, it cannot be attached to an entity.function getComponentState(address _componentAddress) external view returns (bool);: Returns a component's state.function addComponent(uint256 _entityId, address _componentAddress) external;: Attaches a component to an entity. Both the entity and the component must be in the enabled state.function hasComponent(uint256 _entityId, address _componentAddress) external view returns (bool);: Reports whether the given component is attached to the entity.function removeComponent(uint256 _entityId, address _componentAddress) external;: Detaches a previously attached component from the entity.function getEntityComponents(uint256 _entityId) external view returns (address[] memory);: Returns an array of contract addresses for all components attached to the entity.function registerSystem(address _systemAddress) external;: Registers a system contract to the world. The same system cannot be registered more than once.function systemExists(address _systemAddress) external view returns (bool);: Reports whether the given system is registered in the world.function getSystems() external view returns (address[] memory);: Returns an array of contract addresses for every system registered in the world.function setSystemState(address _systemAddress, bool _systemState) external;: Changes a system's state.function getSystemState(address _systemAddress) external view returns (bool);: Returns a system's state.function world() external view returns (address);: Returns the address of the world contract this component is registered to.function types() external view returns (Types.Type[] memory, Types.Type[] memory);: Returns the array of types for the data the component stores and the array of types for the get() parameters.function set(uint256 _entityId, bytes memory _data) external;: Stores data for an entity. Both the entity and the system operating on it must be in the enabled state.function get(uint256 _entityId) external view returns (bytes memory);: Retrieves an entity's data by its entity Id.function get(uint256 _entityId, bytes memory _params) external view returns (bytes memory);: Retrieves data matching given conditions by adding extra parameters to the entity Id.
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
- Do not expose management functions to regular users: Unless implementing a special feature, createEntity(), setEntityState(), addComponent(), removeComponent(), registerComponent(), setComponentState(), registerSystem(), and setSystemState() should not be provided directly to regular users, and should instead be configured by the contract owner.
- Component data should only be modified via set(): A component contract should not provide any function other than set() that modifies an entity. set() should also include checks for whether the entity is enabled and whether the system operating on it is enabled.
- Code audit before registering a system: Once a system is registered to the world, it can manipulate the component data of every entity in the world. The security of every system contract's code must be checked and audited before registration.
- Disable deprecated elements immediately: If a new version deprecates certain entities, component contracts, or system contracts, they must be disabled promptly via setEntityState(), setComponentState(), and setSystemState().