Proposal: Create a Generalized Event System

[miogds]

I propose the creation of a generalized event system for the engine. While this work was initially motivated by the need to redesign the InputSystem to better support binding OS input events (keyboard, mouse, etc.) to engine logic (e.g., moveForward), further exploration suggests that a dedicated EventSystem and EventManager would provide a more powerful and extensible foundation for the entire engine.

This system would allow any component—InputSystem, AnimationSystem, PhysicsSystem, RenderSystem, etc.—to communicate through a unified event mechanism, improving decoupling, extensibility, and clarity.

---

Motivation

The current design limits event handling primarily to input-related actions. This creates friction when attempting to extend the engine to support more complex interactions such as:

• Physics triggers passing messages to animations.
• Entities forwarding unknown events to child entities (e.g., a car object forwarding a dismountEvent to its passengers).
• Rendering or system-wide signals that should not be tightly coupled to specific systems.

By introducing a generalized event framework, we can:

1. Unify communication between engine subsystems.
2. Decouple systems so they only depend on event definitions, not direct references to each other.
3. Enable event chaining/propagation, allowing objects/entities to handle, pass along, or block events as needed.

---

Proposal Details

1. Core Components

• EventSystem: A high-level manager responsible for lifecycle, subscriptions, and system-wide dispatch.
• EventManager: Manages the queue of events, dispatch timing, and delivery semantics.

2. Event Structure

• Core event type contains:

  • type: integer identifier (extensible, allows new event types).
  • args: core argument values (standardized).

• Extensions:

  • Can provide helper initializers, accessors, or processors.
  • Cannot add new value types—ensures the event payload remains minimal and avoids unnecessary dependencies.

3. Event Flow

• Events can be:

  • Signaled by any system or entity.
  • Queued by the EventManager for deferred processing.
  • Dispatched to interested listeners.

• Entities and objects may:

  • Handle events directly.
  • Pass events along the chain (hierarchy or ownership).
  • Block events if required.

4. Input System Integration

The redesigned InputSystem will:

• Translate OS-level events (keyboard, mouse, controller, etc.) into engine events.
• Use the EventManager to enqueue events.
• Bind events to gameplay or logic functions (e.g., moveForward).

This ensures input handling is no longer a special case—it is simply one producer of events.

---

Example Use Case

Imagine a car object with a player entity inside:

1. A dismountEvent is triggered.
2. The car object receives it. The car doesn’t handle it but forwards it.
3. The player object interprets it and triggers the open door + exit animation sequence.

This shows the flexibility of a system where objects don’t need to “understand” all events—they can simply route them until the right handler acts.

---

Benefits

• Extensible and future-proof communication system.
• Reduces tight coupling between subsystems.
• Supports event propagation, filtering, and blocking.
• Provides a foundation for more advanced features (animation triggers, physics callbacks, networking events, etc.).

---

Next Steps

1. Finalize event struct design.
2. Implement EventManager with queue and dispatch logic.
3. Update InputSystem to integrate with the new system.
4. Gradually migrate other subsystems (e.g., Physics, Animation) to adopt event-driven communication.

---

👉 Note: Work on the InputSystem redesign will be on hold until this event system is implemented.

---

@untoldengine What do you think?

[untoldengine]

I’m on board with this proposal. A generalized event system will help us decouple subsystems and make future features easier to plug in. Let’s proceed.

How about if we also include:

• Phase + priority lanes
  Classify events into PreUpdate, PostPhysics, PreRender, etc., with optional priority. Each lane uses a bounded ring buffer → determinism + no runaway memory and predictable perf.

• Dual path delivery
  Support both:

  • post(event, phase:) — queued delivery for that phase
  • emitNow(event) — immediate delivery within the current phase (for input/critical cases)

• Explicit propagation API (forwarding is opt-in; no automatic tree walks)

    enum EventResult {
      case handled
      case `continue`
      case forward(to: EntityID)
      case bubbleUp
    }

Thoughts?

[miogds]

I agree. I like your idea. We can also have channels, like physics, animation, etc. It’s not only registering for an event, but also for a channel, for a phase. I think we could extend that behavior in so many ways. I'll work on a branch to add the event system, at least a first draft so we can try it and see how it can work with all these ideas.

[untoldengine]

I like that.

[miogds]

I was thinking that I don't really like that an event can follow the whole scene tree. For example, if you have a terrain, only made of rocks and a car, you only need to send animation events to the car. The whole rest of the entities that are the terrain, that could be huge, don't have to listen to that particular animation event. I like the approach that the channels or domains ( I like more the last name ) register for a particular event if, for example, you add an animation event or any other event. So the tree graph of all entities that have a list to the event is smaller instead of the whole scene. So the idea is that every domain has his own graph tree to listen for a particular event...