EntityModifier

local EntityModifier = require('encompass').EntityModifier

An EntityModifier is an Engine which is responsible for consuming EntityMessages and manipulating Entities in response, for example, adding a component to an entity or deactivating an entity.

EntityModifiers are defined by the EntityMessage prototype they track and the modify function they implement.

It is an anti-pattern to read Entities or Components inside an EntityModifier. Do not do this.

Function Reference

EntityModifier.define(name, message_type, state_message_types)
Arguments:
  • name (string) – The name of the EntityModifier.
  • message_type (prototype) – An EntityMessage prototype that should be tracked by the EntityModifier.
  • state_message_types (table) – An array-style table of StateMessage types that should be tracked by the EntityModifier. Optional

Defines an EntityModifier that will track the given EntityMessage prototype, and optionally track the given StateMessage types.

EntityModifier:get_state_message(state_message_type)
Arguments:
  • state_message_type (StateMessage) – A StateMessage prototype that has been tracked by the EntityModifier.
Returns:

StateMessage or nil An instantiated StateMessage of the given typrototypepe, or nil if none has been produced this frame.
EntityModifier:modify(entity, messages, dt)
Arguments:
  • entity (Entity) – A reference to an entity referenced by the tracked Message.
  • messages (table) – An array-style table containing references to multiple messages that have been tracked by the EntityModifier and all reference the same component.
  • dt – The delta time given by the World’s current frame update.

This callback is triggered when one or more EntityMessages of the specified prototype is produced by a Detecter. The programmer must override this callback or an error will be thrown.

Example

local AddComponentMessage = require('game.messages.add_component')

local EntityModifier = require('encompass').EntityModifier
local AddComponentModifier = EntityModifier.define('AddComponentModifier', AddComponentMessage)

function AddComponentModifier:modify(entity, messages, dt)
    for _, message in pairs(messages) do
        entity:add_component(message.component_to_add, message.component_args)
    end
end

return AddComponentModifier