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.requireOne (...) Makes a Filter that selects Entities with at least one of the specified Components and Filters.

System functions

tiny.system (table) Creates a 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 count of Entities in World.
tiny.getSystemCount (world) Gets count 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.requireOne are immutable and can be used by multiple Systems.

local f1 = tiny.requireAll("position", "velocity", "size")
local f2 = tiny.requireOne("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
tiny.requireAll (...)
Makes a Filter that selects Entities with all specified Components and Filters.

Parameters:

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

Parameters:

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

System functions

A System is a wrapper around function callbacks for manipulating Entities.
tiny.system (table)

Creates a System. Systems are 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 conveient to use tiny.requireAll or tiny.requireOne, but one can write their own filters as well. Set the Filter of your System like so:

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

or

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

Parameters:

  • table A table to be used as a System, or nil to create a new System.
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

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

See also:

World functions

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

The tiny-ecs module is set to be the __index of all World tables, so the often clearer syntax of world:method() can be used for any function in the library. 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 count of Entities in World.

Parameters:

  • world
tiny.getSystemCount (world)
Gets count of Systems in World.

Parameters:

  • world
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
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
generated by LDoc 1.4.3 Last updated 2015-05-04 20:16:58