Hecs
A high performance lightweight ECS with a plugin ecosystem.
See TECHNICAL.md for details on performance and the internals of this library.
Install
Install via npm/yarn:
yarn add hecs
Quickstart
static props = type: TypesText static props = value: Object3D static queries = added: Model modified: Mesh removed: Mesh { thisqueriesadded thisqueriesmodified thisqueriesremoved } const world = systems: ModelSystem components: Model Mesh worldentities { world }
Worlds
Creating a world
const world = plugins: CorePlugin systems: MySystem components: MyComponent
Updating the world
world
Entities
Creating an entity
const basketball = worldentities
Entity Hierarchy
const parent = worldentitiesconst child = worldentities child // use `null` to unsetparentchildparent // [child]child // parent
Adding components
basketball
Retrieving components
const model = basketball
Marking a component as modified
If you use queries that need to know when components are modified you will need to mark them as modified.
const model = basketballmodelpath = 'basketball-2.glb'model
Removing components
basketball
Activating an entity
Entities are inactive by default and are not simulated in world queries until they are activated:
basketball
Deactivating an entity
If you want to remove an entity from the world but still keep it around, use deactivate. When deactivated, all Components are temporarily removed except StateComponents, so that System queries can still process and deallocate any resources. Once all StateComponents are removed the enitity is completely removed from all queries.
basketball
Destroying an entity
If you want to completely remove an entity, use destroy. All Components are removed except StateComponents so that System queries can still process and deallocate resources. Once all StateComponents are removed the entity is completely destroyed.
basketball
Components
Defining components
static props = path: TypesText
LocalComponents
LocalComponents work exactly the same as Components except they are ignored when calling
world.toJSON()
or entity.toJSON()
. LocalComponents should be used in a network
environment when the data doesn't need to be synced between other servers or clients.
static props = axis: TypesAxis2D
StateComponents
StateComponents work the same as regular Components but are kept around after an entity is deactivated or destroyed, so that Systems can process or deallocate resources.
static props = value: TypesObject3D
Systems
Creating systems
static queries = added: Model modified: Mesh removed: Mesh { thisqueriesadded thisqueriesmodified thisqueriesremoved }
Plugins
Creating a plugin
Plugins are a collection of things such as Systems and Components that you can use in your world, or compose with other plugins.
The Plugin options are exactly the same as when instantiating a new World:
name: 'my-plugin' plugins: systems: components: {}
name: The name of your plugin, used for debugging purposes.
plugins: A plugin can depend on other plugins. If two plugins depend on the same plugin it will only be registered once.
systems: An array of Systems to add to the world.
components: An array of Components to register.
decorate: A function that provides the world instance. Useful for constructing shared services, eg scenes.