ECS (Entity Component System) Documentation
The Entity Component System (ECS) is a design pattern used in game development to manage the complexity of game objects and their behaviors. It separates data (components) from behavior (systems), allowing for more flexible and efficient game architecture.
Ecs Methods
b8.ECS.addComponent(id, name [,data])
Attach or overwrite a component on an entity.
Parameters
- id (number): Entity ID
- name (string): Component name
- [data] (Object): Component data (stored by reference) (default: {})
b8.ECS.addSystem(fn, name)
Register a system that runs every frame.
Parameters
- fn (Function): System function (dt)=>void
- name (string): Unique system name
b8.ECS.addSystemOnce(fn, name)
Add a system a single time. Don’t overwite existing systems or add multiple copies.
Parameters
- fn (Function): System function (dt)=>void
- name (string): Unique system name
b8.ECS.countByType(typeName)
Count entities by type.
Parameters
- typeName (string): Type name
b8.ECS.create(bundle)
Create an entity from a bundle of components.
Parameters
- bundle (Object.<string, Object>): Keys = component names
Returns
- (number): The new entity ID
b8.ECS.entitiesAt(col, row)
Get all entities at a specific grid location.
Parameters
- col (number): Column coordinate
- row (number): Row coordinate
Returns
- (number[]): Array of entity IDs at that location
b8.ECS.getAllEntities()
Get all entity IDs.
b8.ECS.getComponent(id, name)
Get one specific component for an entity.
Parameters
- id (number): Entity ID
- name (string): Component name
b8.ECS.getComponents(name)
Get the component map for a given component name.
Parameters
- name (string): Component name
Returns
- (Map<number,Object>): Map<entityId,data>
b8.ECS.getEntity(id)
Return all components for a given entity.
Parameters
- id (number): Entity ID
Returns
- (Map<string, Object>): Map of name → data
b8.ECS.hasComponent(id, name)
Check if an entity owns a component.
Parameters
- id (number): Entity ID
- name (string): Component name
b8.ECS.query(names)
Query for entities that own all given components.
Parameters
- names (…string): List of component names
Returns
- (number[]): Array of entity IDs
b8.ECS.removeComponent(id, name)
Remove a single component from an entity.
Parameters
- id (number): Entity ID
- name (string): Component name
b8.ECS.removeEntity(id)
Remove an entity entirely (all its components).
Parameters
- id (number): Entity ID
b8.ECS.removeSystem()
Remove a previously-registered system.
b8.ECS.reset()
Reset the ECS (clears all entities & components).
b8.ECS.run(dt)
Run every system in order. Optionally pass a filter: (name)=>boolean
Parameters
- dt (number): Delta-time in seconds
b8.ECS.setComponent(id, name, data)
Set a component on an entity, overwriting any existing data. This is a convenience method for add().
Parameters
- id (number): Entity ID
- name (string): Component name
- data (Object): Component data (stored by reference)
b8.ECS.setLoc(id, col, row)
Set the location of an entity.
Parameters
- id (number): Entity ID
- col (number): X tile coordinate
- row (number): Y tile coordinate
