Events¶

Doriax events use FunctionSubscribe<Ret(Args...)>, a multicast delegate that stores callbacks with string tags. Adding a callback with an existing tag replaces the previous one, which prevents duplicate subscriptions from the same source.

Events work identically in C++ and Lua. C++ uses macros from FunctionSubscribe.h. Lua uses RegisterEvent and RegisterEngineEvent globals registered by LuaBinding.

How dispatch works¶

flowchart LR
    Platform[Platform input / frame tick]
    Engine[Engine.systemTouchStart / systemUpdate]
    FS[FunctionSubscribe.call]
    CPP[C++ callback]
    Lua[Lua closure]
    Platform --> Engine --> FS
    FS --> CPP
    FS --> Lua

1. The platform layer calls Engine::systemUpdate(), systemTouchStart(), etc.
2. Engine forwards to static FunctionSubscribe members (onUpdate.call(), etc.).
3. Subsystems and components fire their own events during simulation (physics contacts, UI pointer events, action start/stop).
4. Each subscriber runs in registration order unless disabled or removed.

FunctionSubscribe API¶

Defined in engine/core/util/FunctionSubscribe.h.

With DORIAX_CRASH_GUARD enabled, failing subscribers are removed automatically and optionally reported through a global crash handler.

Engine events¶

Engine exposes frame, lifecycle, input, and pointer events.

Input routing options¶

Configure how events reach gameplay vs. UI:

C++ registration macros¶

All macros live in FunctionSubscribe.h and generate a unique tag: typeid(ClassName)_objectAddress_methodName.

Engine events¶

REGISTER_ENGINE_EVENT(onUpdate);
UNREGISTER_ENGINE_EVENT(onUpdate);

Any FunctionSubscribe member¶

auto* physics = scene->getPhysicsSystem();
REGISTER_EVENT(physics->beginContact2D, onBeginContact);
UNREGISTER_EVENT(physics->beginContact2D, onBeginContact);

Component events on the same entity¶

REGISTER_COMPONENT_EVENT(UIComponent, onClick, onClick);
REGISTER_UI_EVENT(onClick, onClick);           // shorthand for UIComponent
REGISTER_BUTTON_EVENT(onPress, onPress);       // ButtonComponent
REGISTER_SCROLLBAR_EVENT(onChange, onChange);  // ScrollbarComponent
REGISTER_PANEL_EVENT(onMove, onMove);          // PanelComponent

Matching UNREGISTER_* macros remove subscriptions in destructors.

Example: full C++ script¶

class DoorTrigger : public doriax::ScriptBase {
public:
    DoorTrigger(doriax::Scene* scene, doriax::Entity entity);
    ~DoorTrigger();

    void onUpdate();
    void onClick(float x, float y);
    void onBeginContact(doriax::Body2D bodyA, int shapeA, doriax::Body2D bodyB, int shapeB);

private:
    doriax::PhysicsSystem* physics = nullptr;
};

DoorTrigger::DoorTrigger(Scene* scene, Entity entity) : ScriptBase(scene, entity) {
    physics = scene->getPhysicsSystem();
    REGISTER_ENGINE_EVENT(onUpdate);
    REGISTER_UI_EVENT(onClick, onClick);
    if (physics) {
        REGISTER_EVENT(physics->beginContact2D, onBeginContact);
    }
}

DoorTrigger::~DoorTrigger() {
    UNREGISTER_ENGINE_EVENT(onUpdate);
    UNREGISTER_UI_EVENT(onClick, onClick);
    if (physics) {
        UNREGISTER_EVENT(physics->beginContact2D, onBeginContact);
    }
}

Lua event registration¶

LuaBinding::registerHelpersFunctions exposes two globals:

If tag is omitted, Doriax builds: ClassName_instancePointer_methodName

Engine event (Lua)¶

function Player:init()
    RegisterEngineEvent(self, "onUpdate")
end

function Player:onUpdate()
    -- called every frame
end

Component event (Lua)¶

function Trigger:init()
    local ui = self.scene:findComponent(UIComponent, self.entity)
    RegisterEvent(self, ui.onClick, "onClick")
end

function Trigger:onClick(x, y)
    print("clicked", x, y)
end

Physics event (Lua)¶

function Trap:init()
    local physics = self.scene:getPhysicsSystem()
    RegisterEvent(self, physics.beginContact2D, "onBeginContact")
end

function Trap:onBeginContact(bodyA, shapeA, bodyB, shapeB)
    print("2D contact")
end

Custom tag¶

RegisterEngineEvent(self, "onUpdate", "player1_update")

Use custom tags when you need to replace or manually remove a specific subscription.

Physics events¶

PhysicsSystem exposes 2D (Box2D) and 3D (Jolt) collision events.

2D events¶

3D events¶

UI component events¶

UIComponent events (also available through REGISTER_UI_EVENT):

Widget-specific events¶

Action and sound events¶

Use these to chain gameplay reactions to tweens, timelines, or audio playback.

Easing as an event¶

Ease extends FunctionSubscribe<float(float)>. Timed actions can use custom easing curves by subscribing to an Ease instance.

Cleanup¶

Always unregister in C++ destructors when the object can outlive a scene reload.

Best practices¶

• Register in a constructor or Lua init(). Never register in hot per-frame code.
• Unregister in destructors (C++) or rely on Lua cleanup for script components.
• Use onFixedUpdate for physics-sensitive simulation, not onUpdate.
• Enable setIgnoreEventsHandledByUI(true) when UI and gameplay share screen space.
• Return false from preSolve2D or shouldCollide* filters to implement one-way platforms, team filters, or trigger volumes.

Reference¶

• Engine — engine events (onUpdate, input, lifecycle)
• PhysicsSystem — collision and contact events
• Script workflow: Creating Scripts