Module nata

Entity management for Lua.

Functions

oop ([options]) Creates a new OOP system definition.
new ([options[, ...]]) Creates a new Pool.

SystemDefinition

SystemDefinition:init (...) Called when the pool is first created.
SystemDefinition:add (e) Called when an entity is added to the pool.
SystemDefinition:remove (e) Called when an entity is removed from the pool.
SystemDefinition:addToGroup (groupName, e) Called when an entity is added to a group.
SystemDefinition:removeFromGroup (groupName, e) Called when an entity is removed from a group.

System

System.pool The Pool that this system is running on.

Group

Group.filter The filter that defines which entities are added to this group.
Group.sort A function that specifies how the entities in this group should be sorted.
Group.entities A list of all the entities in the group.
Group.hasEntity A set of all the entities in the group.

Pool

Pool.entities A list of all the entities in the pool.
Pool.hasEntity A set of all the entities in the pool.
Pool.groups A dictionary of the Groups in the pool.
Pool.data A field containing any data you want.
Pool:queue (entity) Queues an entity to be added to the pool.
Pool:flush () Adds the queued entities to the pool.
Pool:remove (f) Removes entities from the pool.
Pool:on (event, f) Registers a function to be called when an event is emitted.
Pool:off (event, f) Unregisters a function from an event.
Pool:emit (event, ...) Emits an event.
Pool:getSystem (systemDefinition) Gets this pool's instance of a system.

OopOptions

OopOptions.include A list of events to forward to entities.
OopOptions.exclude A list of events not to forward to entities.
OopOptions.group The name of the group of entities to forward events to.

GroupOptions

GroupOptions.filter The filter that defines which entities are added to this group.
GroupOptions.sort A function that specifies how the entities in this group should be sorted.

PoolOptions

PoolOptions.groups A dictionary of groups for the pool to have.
PoolOptions.systems A list of SystemDefinitions for the pool to use.
PoolOptions.data An initial value to set Pool.data to.


Functions

oop ([options])
Creates a new OOP system definition. An OOP system, upon receiving an event, will call the function of the same name on each entity it monitors (if it exists). This facilitates a more traditional, OOP-style entity management, where you loop over a table of entities and call update and draw functions on them.

Parameters:

  • options OopOptions how to set up the OOP system (optional)

Returns:

    SystemDefinition the new OOP system definition
new ([options[, ...]])
Creates a new Pool.

Parameters:

  • options PoolOptions how to set up the pool (optional)
  • ... additional arguments to pass to the pool's init event (optional)

Returns:

    Pool the new pool

SystemDefinition

Defines the behaviors of a system.

There's no constructor for SystemDefinitions. Rather, you simply define a table with functions that correspond to events. These events can be named anything you like. Below are the built-in events that the pool will automatically call.

SystemDefinition:init (...)
Called when the pool is first created.

Parameters:

  • ... additional arguments that were passed to nata.new.
SystemDefinition:add (e)
Called when an entity is added to the pool.

Parameters:

  • e table the entity that was added
SystemDefinition:remove (e)
Called when an entity is removed from the pool.

Parameters:

  • e table the entity that was removed
SystemDefinition:addToGroup (groupName, e)
Called when an entity is added to a group.

Parameters:

  • groupName string the name of the group that the entity was added to
  • e table the entity that was added
SystemDefinition:removeFromGroup (groupName, e)
Called when an entity is removed from a group.

Parameters:

  • groupName string the name of the group that the entity was removed from
  • e table the entity that was removed

System

Responds to events in a pool.

Systems are not created directly. They're created by the Pool according to the SystemDefinitions passed to nata.new. Each system instance inherits all of the functions of its SystemDefinition.

System.pool
The Pool that this system is running on.

Group

Manages a subset of entities.
Group.filter

The filter that defines which entities are added to this group. Can be either:

  • A list of required keys
  • A function that takes the entity as the first argument and returns true if the entity should be added to the group
  • filter table or function (optional)
Group.sort
A function that specifies how the entities in this group should be sorted. Has the same requirements as the function argument to Lua's built-in table.sort.
  • sort function (optional)
Group.entities
A list of all the entities in the group.
Group.hasEntity
A set of all the entities in the group.

Usage:

    print(pool.groups.physical.hasEntity[e]) -- prints "true" if the entity is in the "physical" group, or "nil" if not

Pool

Manages entities in a game world.
Pool.entities
A list of all the entities in the pool.
Pool.hasEntity
A set of all the entities in the pool.

Usage:

    print(pool.hasEntity[e]) -- prints "true" if the entity is in the pool, or "nil" if not
Pool.groups
A dictionary of the Groups in the pool.
Pool.data
A field containing any data you want.
  • data
Pool:queue (entity)
Queues an entity to be added to the pool.

Parameters:

  • entity table the entity to add

Returns:

    table the queued entity
Pool:flush ()
Adds the queued entities to the pool. Entities are added in the order they were queued.
Pool:remove (f)
Removes entities from the pool.

Parameters:

  • f function the condition upon which an entity should be removed. The function should take an entity as the first argument and return true if the entity should be removed.
Pool:on (event, f)
Registers a function to be called when an event is emitted.

Parameters:

  • event string the event to listen for
  • f function the function to call

Returns:

    function the function that was registered
Pool:off (event, f)
Unregisters a function from an event.

Parameters:

  • event string the event to unregister the function from
  • f function the function to unregister
Pool:emit (event, ...)
Emits an event. The system[event] function will be called for each system that has it, and functions registered to the event will be called as well.

Parameters:

  • event string the event to emit
  • ... additional arguments to pass to the functions that are called
Pool:getSystem (systemDefinition)
Gets this pool's instance of a system.

Parameters:

Returns:

    System the instance of the system running in this pool

OopOptions

Defines the behavior of an OOP system.
OopOptions.include
A list of events to forward to entities. If not defined, the system will forward all events to entities (except for the ones in the exclude list).
OopOptions.exclude
A list of events not to forward to entities.
OopOptions.group
The name of the group of entities to forward events to. If not defined, the system will forward events to all entities.

GroupOptions

Defines the filter and sort function for a Group.
GroupOptions.filter

The filter that defines which entities are added to this group. Can be either:

  • A list of required keys
  • A function that takes the entity as the first argument and returns true if the entity should be added to the group
  • filter table or function (optional)
GroupOptions.sort
A function that specifies how the entities in this group should be sorted. Has the same requirements as the function argument to Lua's built-in table.sort.
  • sort function (optional)

PoolOptions

Defines the groups and systems for a Pool.
PoolOptions.groups
A dictionary of groups for the pool to have. Each key is the name of the group, and each value should be a GroupOptions table.
  • groups table (default {})
PoolOptions.systems
A list of SystemDefinitions for the pool to use.
  • systems table (default {nata.oop()})
PoolOptions.data
An initial value to set Pool.data to.
  • data (default {})
generated by LDoc 1.4.6 Last updated 2020-04-24 01:19:49