Practical guide

Listen for a post-commit event

Register a generation-scoped handler for an immutable owner fact without placing gameplay control flow inside the event chain.

Procedure

1. Choose a registered event ID and confirm its payload fields in the API Reference.
2. Register one bounded callback with events.listen during package initialization.
3. Treat the detached event table as read-only application data. It contains no engine references, and edits cannot change the source event or another callback's copy.
4. If the handler requests follow-up behavior, submit a typed command; it cannot execute before a later fixed tick.
5. Remove an optional listener with events.ignore, or let reload and shutdown destroy the complete Lua generation.

Example

local completion_subscription = nil

function initialize_package()
    completion_subscription = events.listen(
        "events.command.completed",
        function(event)
            feedback = event.payload.command_id .. " completed"
        end
    )
end

function shutdown_package()
    if completion_subscription ~= nil then
        events.ignore(completion_subscription)
        completion_subscription = nil
    end
end

Constraints and recovery

• Events report immutable facts after mutation; handlers cannot cancel, replace, or intercept owner control flow.
• Delivery is ordered by event sequence, package dependency order, and subscription creation order.
• Every handler runs under Lua protected-call, instruction, memory, query, command, and event budgets. Repeated faults disable only the offending package.
• events.after remains available for bounded catch-up and diagnostics when active delivery was missed.

Related symbols

• events.listen
• events.ignore
• events.after
• events.command.completed
• command.submit

Project references

• Game Development Phase 14
• Engine extension contract