Skip to main content
The Signals namespace is how you broadcast messages between entities in the level. A signal carries an identifier string and optional data payload; any entity that listens for that identifier will receive the signal and can act on it. You choose the delivery scope — all entities, a single target, a tag group, a type group, or entities that pass a custom filter function.

​
Functions

​
emit

Dispatches a pre-built Signal object, or constructs one inline from a property table. 
--- @param signal Signal
--- @return any
function Signals.emit(signal)

--- @param signalProperties table
--- @return any
function Signals.emit(signalProperties)
The table form lets you build and emit in a single expression: 
Signals.emit{ id = "OnActivate", data = { power = 2 } }

​
emitToAll

Broadcasts a signal to every entity in the level, optionally with a data payload. 
--- @param signalId string
--- @return any
function Signals.emitToAll(signalId)

--- @param signalId string
--- @param data any
--- @return any
function Signals.emitToAll(signalId, data)

​
emitTo

Sends a signal to a single specific entity. 
--- @param signalId string
--- @param target Element
--- @return any
function Signals.emitTo(signalId, target)

--- @param signalId string
--- @param target Element
--- @param data any
--- @return any
function Signals.emitTo(signalId, target, data)

​
emitToTag

Sends a signal to every entity that carries the given tag string. 
--- @param signalId string
--- @param tag string
--- @return any
function Signals.emitToTag(signalId, tag)

--- @param signalId string
--- @param tag string
--- @param data any
--- @return any
function Signals.emitToTag(signalId, tag, data)

​
emitToType

Sends a signal to every entity of a given EntityType. 
--- @param signalId string
--- @param type EntityType
--- @return any
function Signals.emitToType(signalId, type)

--- @param signalId string
--- @param type EntityType
--- @param data any
--- @return any
function Signals.emitToType(signalId, type, data)

​
emitToTypeAndTag

Sends a signal to every entity that matches both the given type and tag. 
--- @param signalId string
--- @param type EntityType
--- @param tag string
--- @return any
function Signals.emitToTypeAndTag(signalId, type, tag)

--- @param signalId string
--- @param type EntityType
--- @param tag string
--- @param data any
--- @return any
function Signals.emitToTypeAndTag(signalId, type, tag, data)

​
emitToCustom

Sends a signal to every entity for which customFilter(entity, signal) returns true. 
--- @param signalId string
--- @param customFilter function
--- @return any
function Signals.emitToCustom(signalId, customFilter)

--- @param signalId string
--- @param customFilter function
--- @param data any
--- @return any
function Signals.emitToCustom(signalId, customFilter, data)

​
Signal Class

You can construct a Signal object manually when you need full control over all delivery options. Pass it to Signals.emit().

​
Properties

PropertyTypeDescription
signal.idstringThe signal identifier string (required).
signal.dataanyOptional payload delivered alongside the signal.
signal.targetElementIf set, only this entity receives the signal.
signal.tagFilterstringIf set, only entities with this tag receive the signal.
signal.typeFilterEntityTypeOnly entities of this type receive the signal. Defaults to EntityType.Any.
signal.customFilterfunctionIf set, called for each candidate entity; return true to include it.

​
Signal.new

--- @param id string
--- @param data any
--- @param target Element
--- @param tagFilter string
--- @param typeFilter EntityType
--- @param customFilter function
--- @return Signal
function Signal.new(id, data, target, tagFilter, typeFilter, customFilter)

--- @param properties table
--- @return Signal
function Signal.new(properties)
The table-constructor form is the most common approach. All fields except id are optional: 
local sig = Signal.new{
    id         = "OnDoorOpen",
    tagFilter  = "wooden-door",
    typeFilter = EntityType.Block,
    data       = { silent = true },
}
Signals.emit(sig)

​
Usage Examples

​
Broadcast to all entities

function OnStart()
    Signals.emitToAll("OnLevelBegin")
end

​
Target a specific entity

function OnKeyCollected()
    local exit = Elements.tagged["exit-block"]
    Signals.emitTo("OnUnlock", exit, { source = "key" })
end

​
Notify all entities sharing a tag

-- Wake up every enemy tagged "sleeping-guard"
Signals.emitToTag("OnWakeUp", "sleeping-guard")

​
Filter by type and tag together

-- Tell every Side entity tagged "pressure-plate" that the ball rolled over one
Signals.emitToTypeAndTag("OnPressed", EntityType.Side, "pressure-plate")

​
Custom filter

-- Only send the signal to blocks that are in the main section
Signals.emitToCustom("OnFlash", function(entity, signal)
    return entity.sectionId == "main"
end)