Module ecs
[hook-sys] Provides a Lua-side ECS.
Required hooks: update.
To interact with comps defined by a library, see comps.
To define your own comps, see Comp and System.
Entity
| entity:comps() | [ECS] Get the comps associated with this entity. |
| comps(e) | Get the comps associated with an entity. |
| EntityComps | Holds the comp instances associated with the entity it was accessed from. |
Comp
| Comp(key) | Create a new Comp. |
| comp:setSchema(schema) | Set the schema for a comp. |
| comp:destroy() | Destroy this comp, removing it from all entities. |
System
| System(name) | Create a new System. |
| system:addRequiredComponents(...) | [ECS] Add EE ECS components that are required on each entity this system processes. |
| system:addRequiredComps(...) | Add Lua ECS comps that are required on each entity this system processes. |
| system:onUpdateGlobal(fn) | Add a callback to call once per update call for this system. |
| system:onUpdateEntity(fn) | Add a callback to call once per entity per update call for this system. |
| system:runBefore(name) | Enforce that this system must run before another in each update. |
| system:runAfter(name) | Enforce that this system must run after another in each update. |
| system:destroy() | Destroy this system, stopping it from processing. |
| system:query() | Query all entities that this system should process. |
| System.queryEntitiesWithComp(comp) | Efficiently query entities that have a specified comp. |
Entity
An entity is a thing that exists in the world of EmptyEpsilon. On non-
ECS, this is a SpaceObject; on ECS, an Entity.
- entity:comps()
-
[
ECS] Get the comps associated with this entity.Returns:
-
The EntityComps for the entity.
- comps(e)
-
Get the comps associated with an entity.
Parameters:
- e the entity to get comps for
Returns:
-
The EntityComps for the entity.
- EntityComps
-
Holds the comp instances associated with the entity it was accessed from.
- To set a comp, set
comps[name] = {...}. - To read a comp, read
comps[name]. - To edit a comp in-place, set the desired fields on
comps[name].
For example, with a hypothetical "position" comp defined as having fields "x" and "y":
- To set the position:
comps.position = {x = 1, y = 2} - To read the x coordinate:
local x = comps.position.x - To set only the y coordinate:
comps.position.y = 42
For details of what fields are available on each comp, refer to the documentation for the specific comp.
- To set a comp, set
Comp
A Comp defines a collection of data that can be attached to an entity.
- Comp(key)
-
Create a new Comp.
Parameters:
- key The key of the new Comp.
Returns:
-
The new Comp instance.
- comp:setSchema(schema)
-
Set the schema for a comp. If this method is not called, the comp will not permit any fields.
For details on the schema format, see
schema.tableSchema.Parameters:
- schema
Returns:
-
self
- comp:destroy()
- Destroy this comp, removing it from all entities.
System
A System processes a set of entities, typically which share some set of comps and/or components in common.
- System(name)
-
Create a new System.
Parameters:
- name The name of the new System.
Returns:
-
The new System instance.
- system:addRequiredComponents(...)
-
[
ECS] Add EE ECS components that are required on each entity this system processes.Parameters:
- ... The component names that are required.
Returns:
-
self
- system:addRequiredComps(...)
-
Add Lua ECS comps that are required on each entity this system processes.
If possible, the first such comp should be the least likely to appear, as it will be used to pre-filter the entity set.
Parameters:
- ... The comp names that are required.
Returns:
-
self
- system:onUpdateGlobal(fn)
-
Add a callback to call once per update call for this system.
Parameters:
- fn The callback to use, which will be called with (delta, ents).
Returns:
-
self
- system:onUpdateEntity(fn)
-
Add a callback to call once per entity per update call for this system.
Parameters:
- fn The callback to use, which will be called with (delta, ent, comps).
Returns:
-
self
- system:runBefore(name)
-
Enforce that this system must run before another in each update.
Parameters:
- name The name of the other system.
Returns:
-
self
- system:runAfter(name)
-
Enforce that this system must run after another in each update.
Parameters:
- name The name of the other system.
Returns:
-
self
- system:destroy()
- Destroy this system, stopping it from processing.
- system:query()
-
Query all entities that this system should process.
Returns:
-
A table which when iterated over with
pairs()will yieldent, compspairs. - System.queryEntitiesWithComp(comp)
-
Efficiently query entities that have a specified comp.
Parameters:
- comp The comp to query for.
Returns:
-
A table which when iterated over with
pairs()will yieldent, compspairs.