[Feature] Bitmask-Based Component Event Filtering with Granular Handlers

[vmarcella]

Overview

Refactor the Component trait's event handling system to replace the monolithic
on_event method with granular, opt-in event handlers and a bitmask-based
filtering system. This change eliminates boilerplate pattern matching in
components, improves runtime performance by skipping uninterested components,
and provides a more ergonomic API for component authors.

Current State

The current Component trait requires all components to implement on_event,
which receives every event and forces exhaustive pattern matching:

// crates/lambda-rs/src/component.rs:30-33
fn on_event(&mut self, event: Events) -> Result<R, E>;

Components must match against all event variants even when they only care about
a subset:

// Example from crates/lambda-rs/examples/textured_cube.rs:370-385
fn on_event(&mut self, event: Events) -> Result<ComponentResult, String> {
 match event {
 Events::Window { event, .. } => match event {
 WindowEvent::Resize { width, height } => {
 self.width = width;
 self.height = height;
 }
 _ => {}
 },
 _ => {} // Must handle all other variants
 }
 return Ok(ComponentResult::Success);
}

This approach has several limitations:

• Boilerplate: Every component must write _ => {} arms for unused events
• Poor branch prediction: Runtime iterates all components for every event
• No filtering: Components receive events they never handle

Scope

Goals:

• Introduce EventMask bitmask type for O(1) event category filtering
• Add granular on_*_event methods with default no-op implementations
• Update ApplicationRuntime to skip components based on their event mask
• Remove the on_event method from the Component trait
• Update all examples to use the new event handling API

Non-Goals:

• Generic Handles<E> trait system (adds complexity without runtime benefit
  when using trait objects)
• Dynamic event subscription/unsubscription at runtime
• Event prioritization or ordering guarantees beyond current behavior

Proposed API

EventMask (events.rs)

/// Bitmask for O(1) event category filtering.
#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
pub struct EventMask(u8);

impl EventMask {
 pub const NONE: Self = Self(0);
 pub const WINDOW: Self = Self(1 << 0);
 pub const KEYBOARD: Self = Self(1 << 1);
 pub const MOUSE: Self = Self(1 << 2);
 pub const RUNTIME: Self = Self(1 << 3);
 pub const COMPONENT: Self = Self(1 << 4);

 /// Check if this mask contains the given event category.
 #[inline(always)]
 pub const fn contains(self, other: Self) -> bool {
 (self.0 & other.0) != 0
 }

 /// Combine two masks.
 #[inline(always)]
 pub const fn union(self, other: Self) -> Self {
 Self(self.0 | other.0)
 }
}

impl Events {
 /// Return the mask for this event's category.
 pub const fn mask(&self) -> EventMask {
 match self {
 Events::Window { .. } => EventMask::WINDOW,
 Events::Keyboard { .. } => EventMask::KEYBOARD,
 Events::Mouse { .. } => EventMask::MOUSE,
 Events::Runtime { .. } => EventMask::RUNTIME,
 Events::Component { .. } => EventMask::COMPONENT,
 }
 }
}

Updated Component Trait (component.rs)

pub trait Component<R, E>
where
 R: Sized + Debug,
 E: Sized + Debug,
{
 /// Return which event categories this component handles.
 /// The runtime skips dispatch for events not in this mask.
 fn event_mask(&self) -> EventMask {
 EventMask::NONE
 }

 /// Called when a window event occurs. Override to handle.
 fn on_window_event(&mut self, _event: &WindowEvent) {}

 /// Called when a keyboard event occurs. Override to handle.
 fn on_keyboard_event(&mut self, _event: &Key) {}

 /// Called when a mouse event occurs. Override to handle.
 fn on_mouse_event(&mut self, _event: &Mouse) {}

 /// Called when a runtime event occurs. Override to handle.
 fn on_runtime_event(&mut self, _event: &RuntimeEvent) {}

 /// Called when a component event occurs. Override to handle.
 fn on_component_event(&mut self, _event: &ComponentEvent) {}

 // Existing lifecycle methods remain unchanged
 fn on_attach(&mut self, render_context: &mut RenderContext) -> Result<R, E>;
 fn on_detach(&mut self, render_context: &mut RenderContext) -> Result<R, E>;
 fn on_update(&mut self, last_frame: &Duration) -> Result<R, E>;
 fn on_render(&mut self, render_context: &mut RenderContext) -> Vec<RenderCommand>;
}

Example Usage

impl Component<ComponentResult, String> for PlayerController {
 fn event_mask(&self) -> EventMask {
 EventMask::WINDOW
 .union(EventMask::KEYBOARD)
 .union(EventMask::MOUSE)
 }

 fn on_window_event(&mut self, event: &WindowEvent) {
 if let WindowEvent::Resize { width, height } = event {
 self.width = *width;
 self.height = *height;
 }
 }

 fn on_keyboard_event(&mut self, event: &Key) {
 if let Key::Pressed { virtual_key: Some(VirtualKey::Escape), .. } = event {
 self.paused = true;
 }
 }

 fn on_mouse_event(&mut self, event: &Mouse) {
 if let Mouse::Moved { x, y, .. } = event {
 self.cursor_position = (*x, *y);
 }
 }

 // on_runtime_event and on_component_event use default no-op

 fn on_attach(&mut self, _ctx: &mut RenderContext) -> Result<ComponentResult, String> {
 return Ok(ComponentResult::Success);
 }

 // ... other lifecycle methods
}

Acceptance Criteria

• EventMask type added to events.rs with NONE, WINDOW, KEYBOARD,
  MOUSE, RUNTIME, COMPONENT constants
• Events::mask() method returns the appropriate EventMask for each variant
• Component trait updated with event_mask() and on_*_event() methods
• on_event method removed from Component trait
• ApplicationRuntime updated to filter components by mask before dispatch
• All examples updated to use new event handling API
• Unit tests added for EventMask operations
• Documentation updated for Component trait and event handling

Affected Crates

lambda-rs

Notes

• This change is breaking and requires updates to all existing components
• The bitmask approach allows future extension (up to 8 event categories with
  u8, expandable to u16 or u32 if needed)

[vmarcella]

This has been resolved by #94