@skewedaspect/sage 0.9.0-beta.6 → 0.9.0-beta.8

package/dist/classes/bindings/toggle.d.ts

@@ -1,7 +1,7 @@
 import { GameEventBus } from "../eventBus.d.ts";
 import { Action } from "../../interfaces/action.d.ts";
 import { Binding, ToggleBindingDefinition } from "../../interfaces/binding.d.ts";
-import { DeviceValueReader, InputState } from "../../interfaces/input.d.ts";
+import { DeviceType, DeviceValueReader, InputState } from "../../interfaces/input.d.ts";
 /**
  * Options for configuring a toggle binding
  */
@@ -49,6 +49,7 @@ export declare class ToggleBinding implements Binding {
     readonly action: Action;
     readonly context?: string;
     readonly deviceID: string;
+    readonly deviceType: DeviceType;
     readonly reader: DeviceValueReader;
     private readonly _invert;
     private readonly _threshold;
@@ -87,10 +88,11 @@ export declare class ToggleBinding implements Binding {
      *
      * @param action
      * @param deviceID
+     * @param deviceType
      * @param reader
      * @param options
      */
-    constructor(action: Action, deviceID: string, reader: DeviceValueReader, options?: ToggleBindingOptions);
+    constructor(action: Action, deviceID: string, deviceType: DeviceType, reader: DeviceValueReader, options?: ToggleBindingOptions);
     /**
      * Process input state and emit an action event if the toggle flipped.
      *

package/dist/classes/bindings/trigger.d.ts

@@ -1,7 +1,7 @@
 import { GameEventBus } from "../eventBus.d.ts";
 import { Action } from "../../interfaces/action.d.ts";
 import { Binding, TriggerBindingDefinition } from "../../interfaces/binding.d.ts";
-import { DeviceValueReader, InputState } from "../../interfaces/input.d.ts";
+import { DeviceType, DeviceValueReader, InputState } from "../../interfaces/input.d.ts";
 /**
  * All supported edge modes for validation
  */
@@ -43,6 +43,7 @@ export declare class TriggerBinding implements Binding {
     readonly action: Action;
     readonly context?: string;
     readonly deviceID: string;
+    readonly deviceType: DeviceType;
     readonly reader: DeviceValueReader;
     private readonly _edgeMode;
     private readonly _threshold;
@@ -56,10 +57,11 @@ export declare class TriggerBinding implements Binding {
      *
      * @param action
      * @param deviceID
+     * @param deviceType
      * @param reader
      * @param options
      */
-    constructor(action: Action, deviceID: string, reader: DeviceValueReader, options?: TriggerBindingOptions);
+    constructor(action: Action, deviceID: string, deviceType: DeviceType, reader: DeviceValueReader, options?: TriggerBindingOptions);
     /**
      * Process input state and emit an action event on the configured edge transition(s).
      *

package/dist/classes/bindings/value.d.ts

@@ -1,7 +1,7 @@
 import { GameEventBus } from "../eventBus.d.ts";
 import { Action } from "../../interfaces/action.d.ts";
 import { Binding, ValueBindingDefinition } from "../../interfaces/binding.d.ts";
-import { DeviceValueReader, InputState } from "../../interfaces/input.d.ts";
+import { DeviceType, DeviceValueReader, InputState } from "../../interfaces/input.d.ts";
 /**
  * Options for configuring a value binding
  */
@@ -61,6 +61,7 @@ export declare class ValueBinding implements Binding {
     readonly action: Action;
     readonly context?: string;
     readonly deviceID: string;
+    readonly deviceType: DeviceType;
     readonly reader: DeviceValueReader;
     private readonly _scale;
     private readonly _offset;
@@ -84,7 +85,7 @@ export declare class ValueBinding implements Binding {
      * @param reader
      * @param options
      */
-    constructor(action: Action, deviceID: string, reader: DeviceValueReader, options?: ValueBindingOptions);
+    constructor(action: Action, deviceID: string, deviceType: DeviceType, reader: DeviceValueReader, options?: ValueBindingOptions);
     /**
      * Process input state, apply scaling/deadzone/clamping, and emit an action event if the value changed.
      *

package/dist/classes/entity.d.ts

@@ -3,6 +3,26 @@ import { GameEntityBehaviorConstructor } from "../interfaces/entity.d.ts";
 import { Destroyable } from "../interfaces/lifecycle.d.ts";
 import { GameEvent, GameEventBus } from "./eventBus.d.ts";
 import { GameEngine } from "./gameEngine.d.ts";
+/**
+ * Result of a request sent to an entity's behaviors.
+ * `success: true` means a behavior handled the request and returned a value.
+ * `success: false` means no behavior handled it, or a behavior threw an error.
+ */
+export type RequestResult<T> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Narrow interface for entity-to-manager messaging delegation.
+ * Avoids a circular import between entity.ts and managers/entity.ts.
+ */
+interface EntityMessenger {
+    send(target: string, type: string, payload?: unknown, senderID?: string): Promise<void>;
+    request<T>(target: string, type: string, payload?: unknown, senderID?: string): Promise<RequestResult<T>>;
+}
 /**
  * Options for attaching a behavior at a specific position.
  * Only one positioning option should be specified.
@@ -27,6 +47,8 @@ interface SimpleGameEntity<EntityState extends object = object> {
     state: EntityState;
     eventBus: GameEventBus;
     tags: ReadonlySet<string>;
+    send(target: string, type: string, payload?: unknown): Promise<void>;
+    request<T>(target: string, type: string, payload?: unknown): Promise<RequestResult<T>>;
 }
 /**
  * Base class for game entity behaviors. Subclass this to define how an entity reacts to events
@@ -52,6 +74,14 @@ export declare abstract class GameEntityBehavior<RequiredState extends object =
      */
     $setEntity(entity: SimpleGameEntity<RequiredState> | null): void;
     abstract processEvent(event: GameEvent, state: RequiredState): Promise<boolean> | boolean;
+    /**
+     * Handles a direct request sent to this entity. Return a value to respond,
+     * or `undefined` to pass the request to the next behavior.
+     *
+     * @param event - The request event (type, payload, senderID, targetID)
+     * @param state - Current entity state
+     */
+    processRequest?(event: GameEvent, state: RequiredState): Promise<unknown> | unknown | undefined;
     update?(dt: number, state: RequiredState): void;
     destroy?(): Promise<void>;
     /**
@@ -103,6 +133,7 @@ export declare class GameEntity<EntityState extends object = object> implements
     behaviors: GameEntityBehavior[];
     eventBus: GameEventBus;
     private _gameEngine;
+    private _entityManager;
     private _tags;
     private subscriptions;
     /**
@@ -169,6 +200,47 @@ export declare class GameEntity<EntityState extends object = object> implements
      * @param child
      */
     $removeChild(child: GameEntity): void;
+    /**
+     * Sets the entity manager reference for cross-entity messaging.
+     * Called by the EntityManager after entity creation.
+     * @param manager
+     * @internal
+     */
+    $setEntityManager(manager: EntityMessenger): void;
+    /**
+     * Sends a fire-and-forget event directly to a specific entity's behaviors, bypassing the event bus.
+     * If the target matches this entity's own ID, dispatches locally.
+     *
+     * @param target - Entity ID or name
+     * @param type - Event type string
+     * @param payload - Optional event payload
+     */
+    send(target: string, type: string, payload?: unknown): Promise<void>;
+    /**
+     * Sends a request to a specific entity's behaviors and returns the first response.
+     * If the target matches this entity's own ID, dispatches locally.
+     *
+     * @param target - Entity ID or name
+     * @param type - Request type string
+     * @param payload - Optional request payload
+     */
+    request<T>(target: string, type: string, payload?: unknown): Promise<RequestResult<T>>;
+    /**
+     * Sends a fire-and-forget event directly to this entity's own behaviors.
+     *
+     * @param type - Event type string
+     * @param payload - Optional event payload
+     * @internal
+     */
+    $send(type: string, payload?: unknown, senderID?: string): Promise<void>;
+    /**
+     * Sends a request to this entity's own behaviors and returns the first response.
+     *
+     * @param type - Request type string
+     * @param payload - Optional request payload
+     * @internal
+     */
+    $request<T>(type: string, payload?: unknown, senderID?: string): Promise<RequestResult<T>>;
     /**
      * Resets the entity for object pool recycling.
      * Restores state and tags to defaults, detaches from node, notifies behaviors, and resets children.

package/dist/events/payloads.d.ts

@@ -1,5 +1,5 @@
 import { AbstractMesh } from '@babylonjs/core';
-import { InputDevice, InputState } from "../interfaces/input.d.ts";
+import { DeviceType, InputDevice, InputState } from "../interfaces/input.d.ts";
 /** Payload for input:device:connected events */
 export interface DeviceConnectedPayload {
     device: InputDevice;
@@ -14,6 +14,11 @@ export interface InputChangedPayload {
     device: InputDevice;
     state: InputState;
 }
+/** Payload for input:device-type:changed events */
+export interface DeviceTypeChangedPayload {
+    deviceType: DeviceType;
+    previousDeviceType: DeviceType | null;
+}
 /** Payload for level:progress events */
 export interface LevelProgressPayload {
     levelName: string;
@@ -111,6 +116,7 @@ export interface LibraryEventPayloadMap {
     'input:device:connected': DeviceConnectedPayload;
     'input:device:disconnected': DeviceDisconnectedPayload;
     'input:changed': InputChangedPayload;
+    'input:device-type:changed': DeviceTypeChangedPayload;
     'level:progress': LevelProgressPayload;
     'level:complete': LevelCompletePayload;
     'level:error': LevelErrorPayload;

package/dist/interfaces/action.d.ts

@@ -4,6 +4,7 @@
 export interface DigitalAction {
     type: 'digital';
     name: string;
+    label?: string;
 }
 /**
  * Analog action (numeric)
@@ -11,6 +12,7 @@ export interface DigitalAction {
 export interface AnalogAction {
     type: 'analog';
     name: string;
+    label?: string;
     minValue?: number;
     maxValue?: number;
 }

package/dist/interfaces/binding.d.ts

@@ -1,5 +1,5 @@
 import { GameEventBus } from "../classes/eventBus.d.ts";
-import { DeviceValueReader, DeviceValueReaderDefinition, InputState } from "./input.d.ts";
+import { DeviceType, DeviceValueReader, DeviceValueReaderDefinition, InputState } from "./input.d.ts";
 import { Action } from "./action.d.ts";
 /**
  * Types of bindings supported by the system
@@ -25,6 +25,17 @@ export interface Context {
 export type InputDefinition = DeviceValueReaderDefinition & {
     deviceID: string;
 };
+/**
+ * Options for captureInput() — waits for the next intentional input and returns its descriptor.
+ */
+export interface CaptureInputOptions {
+    /** Device types to listen for */
+    deviceTypes: DeviceType[];
+    /** Optional filter for source types (e.g. ['key', 'button', 'axis']) */
+    sourceTypes?: ('key' | 'button' | 'axis' | 'position' | 'wheel')[];
+    /** Optional AbortSignal for cancellation or timeout */
+    signal?: AbortSignal;
+}
 /**
  * Base interface for binding definitions with object-based sources
  */
@@ -88,6 +99,7 @@ export interface Binding {
     readonly action: Action;
     readonly context?: string;
     readonly deviceID: string;
+    readonly deviceType: DeviceType;
     readonly reader: DeviceValueReader;
     /**
      * Process input state and potentially emit an action event

package/dist/managers/binding.d.ts

@@ -1,7 +1,7 @@
 import { GameEventBus } from "../classes/eventBus.d.ts";
-import { Binding, BindingDefinition, Context } from "../interfaces/binding.d.ts";
+import { Binding, BindingDefinition, CaptureInputOptions, Context, InputDefinition } from "../interfaces/binding.d.ts";
 import { Disposable } from "../interfaces/lifecycle.d.ts";
-import { InputDevice, InputState } from "../interfaces/input.d.ts";
+import { DeviceType, InputDevice, InputState } from "../interfaces/input.d.ts";
 import { Action } from "../interfaces/action.d.ts";
 import { LoggingUtility } from "../utils/logger.d.ts";
 /**
@@ -33,6 +33,10 @@ export declare class BindingManager implements Disposable {
      * Set of all active contexts (both exclusive and non-exclusive)
      */
     private _activeContexts;
+    /** The most recent device type that produced intentional input */
+    private _lastActiveDeviceType;
+    /** Active captureInput() state, or null when not capturing */
+    private _captureState;
     /** Event bus for handling game events */
     private _eventBus;
     /** Unsubscribe function for input events */
@@ -68,6 +72,13 @@ export declare class BindingManager implements Disposable {
      * @param exceptContextName
      */
     private _deactivateExclusiveContexts;
+    /**
+     * Determines whether an input event represents intentional activity that should
+     * update the last-active device type. Filters out noise like idle mousemove.
+     *
+     * @param state
+     */
+    private _shouldUpdateActiveDevice;
     /**
      * Create a binding from a binding definition.
      *
@@ -82,6 +93,19 @@ export declare class BindingManager implements Disposable {
      * @throws Error if the reader type is not supported
      */
     private _createInputSourceFromDefinition;
+    /**
+     * Evaluates an input event during capture mode. If the event matches the capture criteria,
+     * resolves the capture promise and cleans up. Otherwise does nothing and waits for the next event.
+     *
+     * @param device
+     * @param state
+     */
+    private _processCaptureInput;
+    /**
+     * Tears down capture state, deactivates the temporary context, and restores the
+     * snapshotted contexts. Does not resolve or reject — the caller handles that.
+     */
+    private _cleanupCapture;
     /**
      * Handle input from a device and process all relevant bindings.
      *
@@ -108,6 +132,20 @@ export declare class BindingManager implements Disposable {
      * @param actionName
      */
     getAction(actionName: string): Action | null;
+    /**
+     * Returns the device type that most recently produced intentional input,
+     * or `null` if no input has been received yet.
+     */
+    get lastActiveDeviceType(): DeviceType | null;
+    /**
+     * Waits for the next intentional input event and returns a descriptor suitable for constructing
+     * a binding. While capturing, all normal bindings are suppressed via a temporary exclusive context.
+     * Previous context state is restored when the capture completes or is cancelled.
+     *
+     * @param options
+     * @throws Error if a capture is already in progress
+     */
+    captureInput(options: CaptureInputOptions): Promise<InputDefinition>;
     /**
      * Registers a context with specific options.
      * Updates exclusivity if the context already exists.
@@ -168,12 +206,13 @@ export declare class BindingManager implements Disposable {
      */
     unregisterBindings(actionName: string, context?: string | null): void;
     /**
-     * Gets all bindings for a specific action.
+     * Gets all bindings for a specific action, optionally filtered by device type and/or context.
      *
      * @param actionName
+     * @param deviceType - If provided, filters to only bindings for that device type
      * @param context - If provided, filters to only bindings in that context
      */
-    getBindingsForAction(actionName: string, context?: string | null): Binding[];
+    getBindingsForAction(actionName: string, deviceType?: DeviceType, context?: string | null): Binding[];
     /**
      * Exports the current configuration to a serializable object.
      * Includes all actions, bindings, contexts, and their active states.

package/dist/managers/entity.d.ts

@@ -1,5 +1,5 @@
 import { TransformNode } from '@babylonjs/core';
-import { GameEntity } from "../classes/entity.d.ts";
+import { GameEntity, RequestResult } from "../classes/entity.d.ts";
 import { GameEventBus } from "../classes/eventBus.d.ts";
 import { GameEngine } from "../classes/gameEngine.d.ts";
 import { GameEntityDefinition } from "../interfaces/entity.d.ts";
@@ -174,6 +174,25 @@ export declare class GameEntityManager implements Disposable {
      * Gets the total number of entities.
      */
     get entityCount(): number;
+    /**
+     * Sends a fire-and-forget event directly to a specific entity's behaviors, bypassing the event bus.
+     * Resolves the target by entity ID first (O(1)), then falls back to name lookup (O(1)).
+     *
+     * @param target - Entity ID or name
+     * @param type - Event type string
+     * @param payload - Optional event payload
+     */
+    send(target: string, type: string, payload?: unknown, senderID?: string): Promise<void>;
+    /**
+     * Sends a request to a specific entity's behaviors and returns the first response.
+     * Resolves the target by entity ID first (O(1)), then falls back to name lookup (O(1)).
+     *
+     * @param target - Entity ID or name
+     * @param type - Request type string
+     * @param payload - Optional request payload
+     * @param senderID - Optional sender entity ID (stamped on the event)
+     */
+    request<T>(target: string, type: string, payload?: unknown, senderID?: string): Promise<RequestResult<T>>;
     /**
      * Adds a tag to an entity and updates the tag index.
      * @param entity - Entity instance or entity ID