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) Creates a default System.
tiny.processingSystem (table) Creates a Processing System.
tiny.sortedSystem (table) Creates a Sorted Processing 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) Updates the World.
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.


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.

Parameters:

  • ... List of required Components and other Filters.
tiny.requireAny (...)
Makes a Filter that selects Entities with at least one of the specified Components and Filters.

Parameters:

  • ... List of required Components and other Filters.
tiny.rejectAll (...)
Makes a Filter that rejects Entities with all specified Components and Filters, and selects all other Entities.

Parameters:

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

Parameters:

  • ... List of required Components and other Filters.

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)
  • function system:onAdd(entity)
  • function system:onRemove(entity)
  • function system:onModify(dt)

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)
Creates a default System.

Parameters:

  • table A table to be used as a System, or nil to create a new System.

Returns:

    A new System or System class
tiny.processingSystem (table)
Creates a Processing System.

A Processing System iterates through its Entities in no particluar order, and updates them individually. It has two important fields:

  • function system:process(entity, dt)
  • function system:filter(entity)

There are also a few other optional callbacks, including the optional callbacks in tiny.system:

  • function system:preProcess(entities, dt)
  • function system:postProcess(entities, dt)

Processing System.

Parameters:

  • table A table to be used as a System, or nil to create a new

Returns:

    A new Processing System or Processing System class

See also:

tiny.sortedSystem (table)
Creates a Sorted Processing System. A Sorted System iterates through its Entities in a specific order, and updates them individually. It has three important methods:

  • function system:process(entity, dt)
  • function system:compare(entity1, entity2)
  • function system:filter(entity)

Sorted Systems have the same optitonal callbacks as ProcessingSystems. Sorted System.

Parameters:

  • table A table to be used as a System, or nil to create a new

Returns:

    A new Sorted System or Sorted System class

See also:

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.

Parameters:

  • ... Systems and Entities to add to the World

Returns:

    A new World
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.

Parameters:

  • world
  • entity
tiny.addSystem (world, system)
Adds a System to the world.

Parameters:

  • world
  • system
tiny.add (world, ...)
Shortcut for adding multiple Entities and Systems to the World.

Parameters:

  • world
  • ... Systems and Entities

See also:

tiny.removeEntity (world, entity)
Removes an Entity to the World.

Parameters:

  • world
  • entity
tiny.removeSystem (world, system)
Removes a System from the world.

Parameters:

  • world
  • system
tiny.remove (world, ...)
Shortcut for removing multiple Entities and Systems from the World.

Parameters:

  • world
  • ... Systems and Entities

See also:

tiny.update (world, dt)
Updates the World. Put this in your main loop.

Parameters:

  • world
  • dt Delta time
tiny.clearEntities (world)
Removes all Entities from the World.

Parameters:

  • world
tiny.clearSystems (world)
Removes all Systems from the World.

Parameters:

  • world
tiny.getEntityCount (world)
Gets number of Entities in the World.

Parameters:

  • world

Returns:

    An integer
tiny.getSystemCount (world)
Gets number of Systems in World.

Parameters:

  • world

Returns:

    An integer
tiny.getSystemIndex (world, system)
Gets the index of a System in the World. Lower indexed Systems are processed before higher indexed systems.

Parameters:

  • world
  • system

Returns:

    An integer between 1 and world:getSystemCount() inclusive
tiny.setSystemIndex (world, system, index)
Sets the index of a System in the World. Changes the order in which they Systems processed, because lower indexed Systems are processed first.

Parameters:

  • world
  • system
  • index

Returns:

    Old index
generated by LDoc 1.4.3 Last updated 2015-05-07 19:57:49