Ubiquitousse

• Index

Contents

• Functions
• Entity table
• System objects

Modules

• ubiquitousse
• ldtk
• ecs
• asset

Topics

• README
• LICENSE

Module ecs

ECS (entity compenent system) library

Entity Component System library, inspired by the excellent tiny-ecs.

Main differences include:

• ability to nest systems;
• instanciation of systems for each world (no shared state);
• adding and removing entities is done instantaneously
• ability to add and remove components from entities after they were added to the world.

No mandatory dependency. Optional dependency: ubiquitousse.scene, to allow quick creation of ECS-based scenes.

The module returns a table that contains several functions, world or scene are starting points to create your world.

Usage:

TODO

Functions

world (...)	Create and returns a world system based on a list of systems.
all (...)	Returns a filter that returns true if, for every argument, a field with the same name exists in the entity.
any (...)	Returns a filter that returns true if one of the arguments if the name of a field in the entity.
scene (name[, systems={}[, entities={}]])	If uqt.scene is available, returns a new scene that will consist of a ECS world with the specified systems and entities.

Entity table

Entity system table.

entity

System objects

Modifiable fields

System.name	Name of the system.
System.systems	List of subsystems.
System.interval	If not false, the system will only update every interval seconds.
System.active	The system and its susbsystems will only update if this is true.
System.visible	The system and its subsystems will only draw if this is true.
System.default	Defaults value to put into the entities’s system table when they are added.
System.methods	Defaults methods to assign to the entities’s system table when they are added.

Callbacks.

System:filter (e) [callback]	Called when checking if an entity should be added to this system.
System:compare (e1, e2) [callback]	Called when adding an entity to this system determining its order.
System:onAdd (s) [callback]	Called when adding an entity to the system.
System:onRemove (s) [callback]	Called when removing an entity from the system.
System:onInstance () [callback]	Called when the system is instancied, before any call to System:onAddToWorld (including other systems in the world).
System:onAddToWorld (world) [callback]	Called when the system is added to a world.
System:onRemoveFromWorld (world) [callback]	Called when the system is removed from a world (i.e., the world is destroyed).
System:onDestroy () [callback]	Called when the world is destroyed, after every call to System:onRemoveFromWorld (including other systems in the world).
System:onUpdate (dt) [callback]	Called when updating the system.
System:onDraw () [callback]	Called when drawing the system.
System:process (s, dt) [callback]	Called when updating the system, for every entity the system contains.
System:render (s) [callback]	Called when drawing the system, for every entity the system contains.

Read-only fields

System.world [read-only]	The world the system belongs to.
System.entityCount [read-only]	Number of entities in the system.
System.s [read-only]	Map of all named systems in the world (not only subsystems).

Methods.

System:add (e, ...)	Add entities to the system and its subsystems.
System:refresh (e, ...)	Refresh an entity’s systems.
System:remove (e, ...)	Remove entities to the system and its subsystems.
System:has (e, ...)	Returns true if every entity is in the system.
System:iter ()	Returns an iterator that iterate through the entties in this system.
System:clear ()	Remove every entity from the system and its subsystems.
System:update (dt)	Try to update the system and its subsystems.
System:draw ()	Try to draw the system and its subsystems.
System:destroy ()	Remove all the entities and subsystems in this system.

Functions

world (...)

Create and returns a world system based on a list of systems. The systems will be instancied for this world.

Parameters:

• ... table,... list of (uninstancied) system tables

Returns:

System the world system

all (...)

Returns a filter that returns true if, for every argument, a field with the same name exists in the entity.

Parameters:

• ... string,... list of field names that must be in entity

Returns:

function(e) that returns true if e has all the fields

any (...)

Returns a filter that returns true if one of the arguments if the name of a field in the entity.

Parameters:

• ... string,... list of field names that may be in entity

Returns:

function(e) that returns true if e has at leats one of the fields

scene (name[, systems={}[, entities={}]])

If uqt.scene is available, returns a new scene that will consist of a ECS world with the specified systems and entities.

Requires:

ubiquitousse.scene

Parameters:

• name string the name of the new scene
• systems table list of systems to add to the world (default {})
• entities table list of entities to add to the world (default {})

Returns:

scene the new scene

Entity table

Entity system table.

entity

System objects

Modifiable fields

System.name

Name of the system. Used to create a field with the system’s name in world.s and into each entity (the “entity’s system table”) that’s in this system. If not set, the entity will not have a system table.

Do not change after system instanciation.

Type:

• string
• nil if no name

System.systems

List of subsystems. On a instancied system, this is a list of the same subsystems, but instancied for this world.

Do not change after system instanciation.

Type:

• table
• nil if no subsystem

System.interval

If not false, the system will only update every interval seconds. false by default.

Type:

• number interval of time between each update
• false to disable

System.active

The system and its susbsystems will only update if this is true. true by default.

Type:

boolean

System.visible

The system and its subsystems will only draw if this is true. true by default.

Type:

boolean

System.default

Defaults value to put into the entities’s system table when they are added. Will recursively fill missing values.

When an entity is added to a system, a .entity field is always set in the system table, referring to the full entity table.

Changing this will not affect entities already in the system.

Type:

• table
• nil if no default

System.methods

Defaults methods to assign to the entities’s system table when they are added.

When calling the methods with entity.systemName:method(…), the method will actually receive the arguments method(system, system table, …). Methamethods are accepted. New methods can be created anytime.

Type:

• table
• nil if no methods

Callbacks.

System:filter (e) ^[callback]

Called when checking if an entity should be added to this system. Returns true if the entity should be added to this system (and therefore its subsystems).

If this is a string or a table, it will be converted to a filter function on instanciation using ecs.any.

If this true, will accept every entity; if false, reject every entity.

Will only test entities when they are added; changing this after system creation will not affect entities already in the system.

By default, rejects everything.

Parameters:

• e table entity table to check

Returns:

boolean true if entity should be added

System:compare (e1, e2) ^[callback]

Called when adding an entity to this system determining its order. Returns true if e1 <= e2. e1 and e2 are two entities.

Used to place the entity in the sorted entity list when it is added; changing this after system creation will not change the order of entities already in the system.

By default, entities are in the same order they were inserted.

Parameters:

• e1 table entity table to check for inferiority
• e2 table entity table to check for superiority

Returns:

boolean true if e1 <= e2

System:onAdd (s) ^[callback]

Called when adding an entity to the system.

Parameters:

• s table the entity’s system table

System:onRemove (s) ^[callback]

Called when removing an entity from the system.

Parameters:

• s table the entity’s system table

System:onInstance () ^[callback]

Called when the system is instancied, before any call to System:onAddToWorld (including other systems in the world).

System:onAddToWorld (world) ^[callback]

Called when the system is added to a world.

Parameters:

• world System world system

System:onRemoveFromWorld (world) ^[callback]

Called when the system is removed from a world (i.e., the world is destroyed).

Parameters:

• world System world system

System:onDestroy () ^[callback]

Called when the world is destroyed, after every call to System:onRemoveFromWorld (including other systems in the world).

System:onUpdate (dt) ^[callback]

Called when updating the system.

Parameters:

• dt number delta-time since last update

System:onDraw () ^[callback]

Called when drawing the system.

System:process (s, dt) ^[callback]

Called when updating the system, for every entity the system contains. Called after System:onUpdate was called on the system.

Parameters:

• s table the entity’s system table
• dt number delta-time since last update

System:render (s) ^[callback]

Called when drawing the system, for every entity the system contains. Called after System:onDraw was called on the system.

Parameters:

• s table the entity’s system table

Read-only fields

System.world ^[read-only]

The world the system belongs to.

Type:

System world

System.entityCount ^[read-only]

Number of entities in the system.

Type:

integer

System.s ^[read-only]

Map of all named systems in the world (not only subsystems). Same for every system from the same world.

Type:

table {[system.name]=instanciedSystem, ...}

Methods.

System:add (e, ...)

Add entities to the system and its subsystems.

Will skip entities that are already in the system.

Entities are added to subsystems after they were succesfully added to their parent system.

If this is called on a subsystem instead of the world, be warned that this will bypass all the parent’s systems filters.

Since System:remove will not search for entities in systems where they should have been filtered out, the added entities will not be removed when calling :remove on a parent system or the world. The entity can be removed by calling System:remove on the system System:add was called on.

Complexity: O(1) per unordered system, O(entityCount) per ordered system.

Parameters:

• e table entity to add
• ... table... other entities to add

Returns:

e,... the function arguments

System:refresh (e, ...)

Refresh an entity’s systems.

Behave similarly to System:add, but if the entity is already in the system, instead of skipping it, it will check for new and removed components and add and remove from (sub)systems accordingly.

Complexity: O(1) per system + add/remove complexity.

Parameters:

• e table entity to refresh
• ... table... other entities to refresh

Returns:

e,... the function arguments

System:remove (e, ...)

Remove entities to the system and its subsystems.

Will skip entities that are not in the system.

Entities are removed from subsystems before they are removed from their parent system.

If you intend to call this on a subsystem instead of the world, please read the warning in System:add.

Returns all removed entities.

Complexity: O(1) per system.

Parameters:

• e table entity to remove
• ... table... other entities to remove

Returns:

e,... the function arguments

System:has (e, ...)

Returns true if every entity is in the system.

Complexity: O(1).

Parameters:

• e table entity that may be in the system
• ... table... other entities that may be in the system

Returns:

boolean true if every entity is in the system

System:iter ()

Returns an iterator that iterate through the entties in this system.

Returns:

iterator iterator over the entities in this system, in order

System:clear ()

Remove every entity from the system and its subsystems.

System:update (dt)

Try to update the system and its subsystems. Should be called on every game update.

Subsystems are updated after their parent system.

Parameters:

• dt number delta-time since last update

System:draw ()

Try to draw the system and its subsystems. Should be called on every game draw.

Subsystems are drawn after their parent system.

System:destroy ()

Remove all the entities and subsystems in this system.