tecs.events#

Typed events and address-based message buses.

Define a record, initialize it in place, and register it once:

local record Damaged is tecs.events.Event
    amount: number

    metamethod __call: function(self, amount: number): Damaged
end

Damaged.init = function(event: Damaged, amount: number)
    event.amount = amount
end

tecs.events.newEvent(Damaged)

Worlds use the same event definitions and address routing as a standalone MessageBus. Address 0 conventionally names a whole world, while entity IDs address individual entities.

Event delivery is synchronous. The emitter owns an event instance during dispatch, so observers treat its fields as read-only and copy values they need to retain. A table event constructed directly, such as Damaged(10), is an independent value the caller may keep.

Module contents#

Constructors#

Types#

Constructors#

tecs.events.newEvent Static#

Configures a table event with a callable constructor.

Registration mutates the supplied definition by assigning its event ID and constructor metatable. Register each definition once.

function tecs.events.newEvent<E is Event>(event: E)

Type Parameters#

Arguments#

Returns#

None.

tecs.events.newFFIEvent Static#

Configures an FFI event with a callable constructor.

Registration mutates the supplied definition. Field names must be unique C identifiers. eventId and typeId are reserved. Use double for entity IDs so their packed slot and generation remain exact.

function tecs.events.newFFIEvent<E is Event>(
    event: E, fields: {{string, string}}, structName: string
)

Type Parameters#

Arguments#

Returns#

None.

tecs.events.newMessageBus Static#

Creates an independent address-based event message bus.

function tecs.events.newMessageBus(): MessageBus

Arguments#

None.

Returns#

Types#

tecs.events.Event interface#

Event names a registered event definition or one of its instances.

interface tecs.events.Event
    eventId: integer
end

tecs.events.Event.eventId field#

Read-only. The unique ID of the event.

tecs.events.Event.eventId: integer

tecs.events.EventInit type#

EventInit initializes an event instance from constructor arguments.

type tecs.events.EventInit = function<E is Event>(E, ...: any)

tecs.events.EventListener type#

EventListener synchronously receives an event of its declared type.

type tecs.events.EventListener = function<E is Event>(E)

tecs.events.MessageBus interface#

MessageBus routes typed events by integer address.

interface tecs.events.MessageBus
    emit: function<E is Event>(MessageBus, integer, E)
    hasObservers: function<E is Event>(MessageBus, integer, E): boolean
    observeOnce: function<E is Event>(
        MessageBus, integer, E, function(E)
    )
    stopObserving: function<E is Event>(
        MessageBus, integer, E, function(E) | string
    )
    clearAddress: function(self, integer)
    clearEntityObservers: function(self)
    observe: function<E is Event>(
        self,
        address: integer,
        eventType: E,
        observer: function(E),
        id: string
    )
    reset: function(self)
end

tecs.events.MessageBus.emit Static#

Emit an event to all observers at the specified address.

function tecs.events.MessageBus.emit<E is Event>(MessageBus, integer, E)

Type Parameters

Arguments

Returns

None.

tecs.events.MessageBus.hasObservers Static#

Check if any observers exist for an event type at an address.

function tecs.events.MessageBus.hasObservers<E is Event>(
    MessageBus, integer, E
): boolean

Type Parameters

Arguments

Returns

tecs.events.MessageBus.observeOnce Static#

Observe an event type at a specific address, at most once.

function tecs.events.MessageBus.observeOnce<E is Event>(
    MessageBus, integer, E, function(E)
)

Type Parameters

Arguments

Returns

None.

tecs.events.MessageBus.stopObserving Static#

Stop observing an event type at a specific address.

function tecs.events.MessageBus.stopObserving<E is Event>(
    MessageBus, integer, E, function(E) | string
)

Type Parameters

Arguments

Returns

None.

tecs.events.MessageBus:clearAddress Instance#

Clear all observers for an address (used on entity despawn).

function tecs.events.MessageBus.clearAddress(self, integer)

Arguments

Returns

None.

tecs.events.MessageBus:clearEntityObservers Instance#

Clear per-entity observers (every address except the global address 0), preserving global subscriptions. Used by world:clearEntities so query infrastructure stays subscribed.

function tecs.events.MessageBus.clearEntityObservers(self)

Arguments

Returns

None.

tecs.events.MessageBus:observe Instance#

Observe an event type at a specific address. Address 0 is for world-level events, entity IDs for entity events.

function tecs.events.MessageBus.observe<E is Event>(
    self,
    address: integer,
    eventType: E,
    observer: function(E),
    id: string
)

Type Parameters

Arguments

Returns

None.

tecs.events.MessageBus:reset Instance#

Reset the entire message bus.

function tecs.events.MessageBus.reset(self)

Arguments

Returns