Module tiny-ecs

Info:

  • Copyright: 2015
  • License: MIT
  • Author: Calvin Rose

Filter functions

tiny.requireAll (...) Makes a Filter that selects Entities with all specified Components and Filters.
tiny.requireAny (...) Makes a Filter that selects Entities with at least one of the specified Components and Filters.
tiny.rejectAll (...) Makes a Filter that rejects Entities with all specified Components and Filters, and selects all other Entities.
tiny.rejectAny (...) Makes a Filter that rejects Entities with at least one of the specified Components and Filters, and selects all other Entities.

System functions

tiny.system (table, attributes) Creates a new System or System class.
tiny.processingSystem (table) Creates a new Processing System or Processing System class.
tiny.getSystemEntityCount (system) Get number of Entities in the System.

World functions

tiny.world (...) Creates a new World.
tiny.addEntity (world, entity) Adds an Entity to the world.
tiny.addSystem (world, system) Adds a System to the world.
tiny.add (world, ...) Shortcut for adding multiple Entities and Systems to the World.
tiny.removeEntity (world, entity) Removes an Entity to the World.
tiny.removeSystem (world, system) Removes a System from the world.
tiny.remove (world, ...) Shortcut for removing multiple Entities and Systems from the World.
tiny.update (world, dt, filter) Updates the World by dt (delta time).
tiny.clearEntities (world) Removes all Entities from the World.
tiny.clearSystems (world) Removes all Systems from the World.
tiny.getEntityCount (world) Gets number of Entities in the World.
tiny.getSystemCount (world) Gets number of Systems in World.
tiny.getSystemIndex (world, system) Gets the index of a System in the World.
tiny.setSystemIndex (world, system, index) Sets the index of a System in the World, and returns the old index.


Filter functions

A Filter is a function that selects which Entities apply to a System. Filters take two parameters, the System and the Entity, and return a boolean value indicating if the Entity should be processed by the System.

Filters must be added to Systems by setting the filter field of the System. Filter's returned by tiny.requireAll and tiny.requireAny are immutable and can be used by multiple Systems.

local f1 = tiny.requireAll("position", "velocity", "size")
local f2 = tiny.requireAny("position", "velocity", "size")

local e1 = {
    position = {2, 3},
    velocity = {3, 3},
    size = {4, 4}
}

local entity2 = {
    position = {4, 5},
    size = {4, 4}
}

local e3 = {
    position = {2, 3},
    velocity = {3, 3}
}

print(f1(nil, e1), f1(nil, e2), f1(nil, e3)) -- prints true, false, false
print(f2(nil, e1), f2(nil, e2), f2(nil, e3)) -- prints true, true, true

Filters can also be passed as arguments to other Filter constructors. This is a powerful way to create complex, custom Filters that select a very specific set of Entities.

-- Selects Entities with an "image" Component, but not Entities with a
-- "Player" or "Enemy" Component.
filter = tiny.requireAll("image", tiny.rejectAny("Player", "Enemy"))
tiny.requireAll (...)
Makes a Filter that selects Entities with all specified Components and Filters.
tiny.requireAny (...)
Makes a Filter that selects Entities with at least one of the specified Components and Filters.
tiny.rejectAll (...)
Makes a Filter that rejects Entities with all specified Components and Filters, and selects all other Entities.
tiny.rejectAny (...)
Makes a Filter that rejects Entities with at least one of the specified Components and Filters, and selects all other Entities.

System functions

A System is a wrapper around function callbacks for manipulating Entities. Systems are implemented as tables that contain at least one method; an update function that takes parameters like so:

  • function system:update(dt).

There are also a few other optional callbacks:

  • function system:filter(entity) - Returns true if this System should include this Entity, otherwise should return false. If this isn't specified, no Entities are included in the System.
  • function system:onAdd(entity) - Called when an Entity is added to the System.
  • function system:onRemove(entity) - Called when an Entity is removed from the System.
  • function system:onModify(dt) - Called when the System is modified by adding or removing Entities from the System.

For Filters, it is convenient to use tiny.requireAll or tiny.requireAny, but one can write their own filters as well. Set the Filter of a System like so:

system.filter = tiny.requireAll("a", "b", "c")

or

function system:filter(entity)
    return entity.myRequiredComponentName ~= nil
end

All Systems also have a few important fields that are initialized when the system is added to the World. A few are important, and few should be less commonly used.

  • The active flag is whether or not the System is updated automatically. Inactive Systems should be updated manually or not at all via system:update(dt). Defaults to true.
  • The 'entities' field is an ordered list of Entities in the System. This list can be used to quickly iterate through all Entities in a System.
  • The indices field is a table of Entity keys to their indices in the entities list. Most Systems can ignore this.
  • The modified flag is an indicator if the System has been modified in the last update. If so, the onModify callback will be called on the System in the next update, if it has one. This is usually managed by tiny-ecs, so users should mostly ignore this, too.
tiny.system (table, attributes)
Creates a new System or System class. An optinal list of attributes may be passed to specify the behavior of the System. Currently, the three supported attributes are "process", "sorted", and "interval".

  • "process" marks the new System as a Processing System. Processing Systems process each entity individual, and are usually what is needed. Processing Systems have three extra callbacks compared to a vanilla System.
    • function system:preProcess(entities, dt) - Called before iterating over each Entity.
    • function system:postProcess(entities, dt) - Called for each Entity in the System.
    • function system:process(entity, dt) - Called after iteration. Processing Systems have their own update method, so don't implement a a custom update callback for Processing Systems.
  • "sorted" marks the new System as a Sorted System. Sorted Systems sort their Entities according to a user-defined method, system:compare(e1, e2), which should return true if e1 should come before e2 and false otherwise.
  • "interval" marks the new System as an Interval System. Interval Systems are updated regulary according to an interval rather than every time the world is update. This is useful for Systems that don't need to be updated often or need be deterministic. Interval Systems have a user-defined field interval that is the time interval between updates. If no interval is specified, a default of 1 is used.

If table is nil, this function uses an empty table.

tiny.processingSystem (table)
Creates a new Processing System or Processing System class. Shortcut for tiny.system(table, { "process" }).

See also:

tiny.getSystemEntityCount (system)
Get number of Entities in the System.

World functions

A World is a container that manages Entities and Systems. Typically, a program uses one World at a time.

For all World functions except tiny.world(...), object-oriented syntax can be used instead of the documented syntax. For example, tiny.add(world, e1, e2, e3) is the same as world:add(e1, e2, e3).

tiny.world (...)
Creates a new World. Can optionally add default Systems and Entities.
tiny.addEntity (world, entity)
Adds an Entity to the world. Also call this on Entities that have changed Components such that they match different Filters.
tiny.addSystem (world, system)
Adds a System to the world.
tiny.add (world, ...)
Shortcut for adding multiple Entities and Systems to the World.
tiny.removeEntity (world, entity)
Removes an Entity to the World.
tiny.removeSystem (world, system)
Removes a System from the world.
tiny.remove (world, ...)
Shortcut for removing multiple Entities and Systems from the World.
tiny.update (world, dt, filter)
Updates the World by dt (delta time). Takes an optional parameter, filter, which is a Filter that selects Systems from the World. Only selected Systems are updated. Put this function in your main loop.
tiny.clearEntities (world)
Removes all Entities from the World.
tiny.clearSystems (world)
Removes all Systems from the World.
tiny.getEntityCount (world)
Gets number of Entities in the World.
tiny.getSystemCount (world)
Gets number of Systems in World.
tiny.getSystemIndex (world, system)
Gets the index of a System in the World. Lower indexed Systems are processed before higher indexed systems.
tiny.setSystemIndex (world, system, index)
Sets the index of a System in the World, and returns the old index. Changes the order in which they Systems processed, because lower indexed Systems are processed first.
generated by LDoc 1.4.3 Last updated 2015-06-16 23:50:18