@skewedaspect/sage 0.3.0

package/src/classes/bindings/toggle.ts

@@ -0,0 +1,261 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Toggle Binding
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { GameEventBus } from '../eventBus.ts';
+
+// Interfaces
+import type { Action } from '../../interfaces/action.ts';
+import type { Binding, ToggleBindingDefinition } from '../../interfaces/binding.ts';
+import type { DeviceValueReader, InputState } from '../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Options for configuring a toggle binding
+ */
+export interface ToggleBindingOptions
+{
+    /**
+     * If true, toggle on falling edge (true -> false) instead of rising edge (false -> true)
+     */
+    invert ?: boolean;
+
+    /**
+     * Initial toggle state (defaults to false - off)
+     */
+    initialState ?: boolean;
+
+    /**
+     * Threshold for analog inputs (0.0 to 1.0)
+     * When input value is >= threshold, it's considered "active" (true)
+     * When input value is < threshold, it's considered "inactive" (false)
+     * Defaults to 0.5 for analog inputs
+     */
+    threshold ?: number;
+
+    /**
+     * Value to emit when the toggle is in the "on" state for digital actions
+     * If undefined, will emit boolean true
+     * Ignored for analog actions
+     */
+    onValue ?: boolean | number;
+
+    /**
+     * Value to emit when the toggle is in the "off" state for digital actions
+     * If undefined, will emit boolean false
+     * Ignored for analog actions
+     */
+    offValue ?: boolean | number;
+
+    /**
+     * Optional context name this binding belongs to
+     */
+    context ?: string;
+}
+
+/**
+ * Implementation of a toggle binding, which maintains and toggles state between true/false
+ * when a button/key is pressed or released, remaining in that state until toggled again.
+ * Can handle both digital and analog inputs with configurable threshold.
+ * Can output either digital or analog values based on the action type.
+ */
+export class ToggleBinding implements Binding
+{
+    public readonly type = 'toggle' as const;
+    public readonly action : Action;
+    public readonly context ?: string;
+    public readonly deviceID : string;
+    public readonly reader : DeviceValueReader;
+
+    // Toggle-specific options
+    private readonly _invert : boolean;
+    private readonly _threshold : number;
+    private readonly _initialState : boolean;
+    private readonly _onValue : boolean | number;
+    private readonly _offValue : boolean | number;
+
+    // State tracking
+    private _lastDigitalState = false;
+    private _toggleState : boolean;
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public Getters
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Get the current toggle state
+     *
+     * @returns Current toggle state (true = on, false = off)
+     */
+    public get state() : boolean
+    {
+        return this._toggleState;
+    }
+
+    /**
+     * Set the toggle state directly (useful for programmatic control)
+     *
+     * @param value - New toggle state
+     */
+    public set state(value : boolean)
+    {
+        this._toggleState = value;
+    }
+
+    /**
+     * Get the value emitted when toggle is in the "on" state
+     *
+     * @returns The value for the "on" state
+     */
+    public get onValue() : boolean | number
+    {
+        return this._onValue;
+    }
+
+    /**
+     * Get the value emitted when toggle is in the "off" state
+     *
+     * @returns The value for the "off" state
+     */
+    public get offValue() : boolean | number
+    {
+        return this._offValue;
+    }
+
+    /**
+     * Get the current value based on toggle state
+     *
+     * @returns The current value (boolean or number)
+     */
+    public get value() : boolean | number
+    {
+        if(this.action.type === 'analog')
+        {
+            return this._toggleState
+                ? (this.action.maxValue ?? 1)
+                : (this.action.minValue ?? 0);
+        }
+        else
+        {
+            return this._toggleState ? this._onValue : this._offValue;
+        }
+    }
+
+    /**
+     * Get the current options for this toggle binding.
+     *
+     * @returns The current options for this toggle binding
+     */
+    public get options() : ToggleBindingOptions
+    {
+        return {
+            invert: this._invert,
+            threshold: this._threshold,
+            initialState: this._initialState,
+            onValue: this._onValue,
+            offValue: this._offValue,
+        };
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Create a new toggle binding
+     *
+     * @param action - Action to toggle
+     * @param deviceID - Device ID this binding is for
+     * @param reader - Input reader to read values from
+     * @param options - Binding configuration options
+     */
+    constructor(
+        action : Action,
+        deviceID : string,
+        reader : DeviceValueReader,
+        options : ToggleBindingOptions = {}
+    )
+    {
+        this.action = action;
+        this.deviceID = deviceID;
+        this.reader = reader;
+        this.context = options.context;
+
+        // Set options with defaults
+        this._invert = options.invert ?? false;
+        this._threshold = options.threshold ?? 0.5;
+        this._initialState = options.initialState ?? false;
+        this._toggleState = this._initialState;
+
+        // For digital actions, these control the output value
+        // For analog actions, these are not used (we use action properties instead)
+        this._onValue = options.onValue ?? true;
+        this._offValue = options.offValue ?? false;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Process input state and emit a digital action if toggled
+     *
+     * @param state - Current input state
+     * @param eventBus - Event bus to emit action events to
+     */
+    public process(state : InputState, eventBus : GameEventBus) : void
+    {
+        const rawValue = this.reader.getValue(state) ?? false;
+        const digitalState = typeof rawValue === 'boolean'
+            ? rawValue
+            : rawValue >= this._threshold;
+
+        const shouldToggle = this._invert
+            ? !digitalState && this._lastDigitalState
+            : digitalState && !this._lastDigitalState;
+
+        this._lastDigitalState = digitalState;
+
+        if(!shouldToggle) { return; }
+
+        this._toggleState = !this._toggleState;
+
+        eventBus.publish({
+            type: `action:${ this.action.name }`,
+            payload: {
+                value: this.value,
+                deviceId: this.deviceID,
+                context: this.context,
+            },
+        });
+    }
+
+    /**
+     * Reset toggle to its initial state
+     */
+    public reset() : void
+    {
+        this._toggleState = this._initialState;
+    }
+
+    /**
+     * Returns a JSON-serializable representation of this toggle binding
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    public toJSON() : ToggleBindingDefinition
+    {
+        return {
+            type: this.type,
+            action: this.action.name,
+            input: {
+                deviceID: this.deviceID,
+                ...this.reader.toJSON(),
+            },
+            state: this._toggleState,
+            context: this.context,
+            options: this.options,
+        };
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/classes/bindings/trigger.ts

@@ -0,0 +1,211 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Trigger Binding
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { GameEventBus } from '../eventBus.ts';
+
+// Interfaces
+import type { Action } from '../../interfaces/action.ts';
+import type { Binding, TriggerBindingDefinition } from '../../interfaces/binding.ts';
+import type { DeviceValueReader, InputState } from '../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * All supported edge modes for validation
+ */
+export const edgeModes = [ 'rising', 'falling', 'both' ] as const;
+
+/**
+ * Defines when a trigger binding will fire based on input state changes
+ */
+export type EdgeMode = typeof edgeModes[number];
+
+/**
+ * Options for configuring a trigger binding
+ */
+export interface TriggerBindingOptions
+{
+    /**
+     * Which edge(s) should cause the trigger to fire
+     * - 'rising': Only trigger on false -> true transitions
+     * - 'falling': Only trigger on true -> false transitions
+     * - 'both': Trigger on any state change
+     */
+    edgeMode ?: EdgeMode;
+
+    /**
+     * Threshold for analog inputs (0.0 to 1.0)
+     * When input value is >= threshold, it's considered "active" (true)
+     * When input value is < threshold, it's considered "inactive" (false)
+     * Defaults to 0.5 for analog inputs
+     */
+    threshold ?: number;
+
+    /**
+     * Optional context name this binding belongs to
+     */
+    context ?: string;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Implementation of a trigger binding, which emits an action when a button/key is pressed or released.
+ * Can handle both digital and analog inputs with configurable threshold.
+ * Can output either digital or analog values based on the action type.
+ */
+export class TriggerBinding implements Binding
+{
+    public readonly type = 'trigger' as const;
+    public readonly action : Action;
+    public readonly context ?: string;
+    public readonly deviceID : string;
+    public readonly reader : DeviceValueReader;
+
+    // Trigger-specific options
+    private readonly _edgeMode : EdgeMode;
+    private readonly _threshold : number;
+
+    // State tracking
+    private _lastDigitalState = false;
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public Getters
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Get the current options for this trigger binding.
+     *
+     * @returns The current options for this trigger binding
+     */
+    get options() : TriggerBindingOptions
+    {
+        return {
+            edgeMode: this._edgeMode,
+            threshold: this._threshold,
+        };
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Create a new trigger binding
+     *
+     * @param action - Action to trigger
+     * @param deviceID - Device ID this binding is for
+     * @param reader - Input reader to read values from
+     * @param options - Binding configuration options
+     */
+    constructor(
+        action : Action,
+        deviceID : string,
+        reader : DeviceValueReader,
+        options : TriggerBindingOptions = {}
+    )
+    {
+        this.action = action;
+        this.deviceID = deviceID;
+        this.reader = reader;
+        this.context = options.context;
+
+        // Set options with defaults
+        this._edgeMode = options.edgeMode ?? 'rising';
+        this._threshold = options.threshold ?? 0.5;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Process input state and emit an action if triggered
+     *
+     * @param state - Current input state
+     * @param eventBus - Event bus to emit action events to
+     * @returns True if an action was triggered, false otherwise
+     */
+    public process(state : InputState, eventBus : GameEventBus) : void
+    {
+        // Extract the raw value using our source
+        const rawValue = this.reader.getValue(state) ?? false;
+
+        // Determine the digital state based on the threshold
+        const digitalState = typeof rawValue === 'boolean'
+            ? rawValue
+            : rawValue >= this._threshold;
+
+        // Determine if we should trigger based on the configured edge mode
+        let shouldTrigger = false;
+
+        switch (this._edgeMode)
+        {
+            case 'rising':
+                shouldTrigger = digitalState && !this._lastDigitalState;
+                break;
+            case 'falling':
+                shouldTrigger = !digitalState && this._lastDigitalState;
+                break;
+            case 'both':
+                shouldTrigger = digitalState !== this._lastDigitalState;
+                break;
+        }
+
+        // Update last known state for next time
+        this._lastDigitalState = digitalState;
+
+        // If triggered, emit the action event
+        if(shouldTrigger)
+        {
+            let outputValue : boolean | number;
+            if(this.action.type === 'analog')
+            {
+                // Use raw value and convert to a number if needed
+                let finalValue = typeof rawValue === 'number' ? rawValue : (rawValue ? 1.0 : 0.0);
+
+                // Apply scaling if action parameters exist
+                if(this.action.minValue !== undefined || this.action.maxValue !== undefined)
+                {
+                    const min = this.action.minValue ?? 0;
+                    const max = this.action.maxValue ?? 1;
+                    finalValue = min + (finalValue * (max - min));
+                }
+                outputValue = finalValue;
+            }
+            else
+            {
+                outputValue = true;
+            }
+            const actionEvent = {
+                type: `action:${ this.action.name }`,
+                payload: {
+                    value: outputValue,
+                    deviceId: this.deviceID,
+                    context: this.context,
+                },
+            };
+            eventBus.publish(actionEvent);
+        }
+    }
+
+    /**
+     * Returns a JSON-serializable representation of this trigger binding
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    public toJSON() : TriggerBindingDefinition
+    {
+        return {
+            type: this.type,
+            action: this.action.name,
+            input: {
+                deviceID: this.deviceID,
+                ...this.reader.toJSON(),
+            },
+            context: this.context,
+            options: this.options,
+        };
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/classes/bindings/value.ts

@@ -0,0 +1,227 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Value Binding
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { GameEventBus } from '../eventBus.ts';
+
+// Interfaces
+import type { Action } from '../../interfaces/action.ts';
+import type { Binding, ValueBindingDefinition } from '../../interfaces/binding.ts';
+import type { DeviceValueReader, InputState } from '../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Options for configuring a value binding
+ */
+export interface ValueBindingOptions
+{
+    /**
+     * Factor to scale the input value by (1.0 = no scaling)
+     */
+    scale ?: number;
+
+    /**
+     * Value to add to the input value after scaling
+     */
+    offset ?: number;
+
+    /**
+     * Whether to invert the input value (multiply by -1)
+     */
+    invert ?: boolean;
+
+    /**
+     * Optional context name this binding belongs to
+     */
+    context ?: string;
+
+    /**
+     * If true, only emit values when they change
+     * If false, always emit values on each process call
+     */
+    emitOnChange ?: boolean;
+
+    /**
+     * Deadzone threshold (0.0 to 1.0)
+     * Input values below this threshold will be treated as 0
+     */
+    deadzone ?: number;
+
+    /**
+     * Value to emit when the input is digital and true
+     * Only used when action is digital
+     */
+    onValue ?: boolean | number;
+
+    /**
+     * Value to emit when the input is digital and false
+     * Only used when action is digital
+     */
+    offValue ?: boolean | number;
+
+    /**
+     * Minimum value to clamp output to
+     */
+    min ?: number;
+
+    /**
+     * Maximum value to clamp output to
+     */
+    max ?: number;
+}
+
+/**
+ * Implementation of a value binding, which directly converts an analog input
+ * to an analog output with optional scaling, offset, and clamping.
+ * Can handle both digital and analog inputs/outputs based on action type.
+ */
+export class ValueBinding implements Binding
+{
+    public readonly type = 'value' as const;
+    public readonly action : Action;
+    public readonly context ?: string;
+    public readonly deviceID : string;
+    public readonly reader : DeviceValueReader;
+
+    // Value-specific options
+    private readonly _scale : number;
+    private readonly _offset : number;
+    private readonly _invert : boolean;
+    private readonly _emitOnChange : boolean;
+    private readonly _deadzone : number;
+    private readonly _onValue : boolean | number;
+    private readonly _offValue : boolean | number;
+    private readonly _min : number;
+    private readonly _max : number;
+
+    // State tracking
+    private _lastValue : number | boolean | undefined;
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Get the current options for this value binding.
+     *
+     * @returns The current options for this value binding
+     */
+    get options() : ValueBindingOptions
+    {
+        return {
+            scale: this._scale,
+            offset: this._offset,
+            invert: this._invert,
+            emitOnChange: this._emitOnChange,
+            deadzone: this._deadzone,
+            onValue: this._onValue,
+            offValue: this._offValue,
+            min: this._min,
+            max: this._max,
+        };
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Create a new value binding
+     *
+     * @param action - Action to emit values for
+     * @param deviceID - Device ID this binding is for
+     * @param reader - Input reader to read values from
+     * @param options - Binding configuration options
+     */
+    constructor(
+        action : Action,
+        deviceID : string,
+        reader : DeviceValueReader,
+        options : ValueBindingOptions = {}
+    )
+    {
+        this.action = action;
+        this.deviceID = deviceID;
+        this.reader = reader;
+        this.context = options.context;
+
+        // Common options that apply to both analog and digital
+        this._scale = options.scale ?? 1.0;
+        this._offset = options.offset ?? 0.0;
+        this._invert = options.invert ?? false;
+        this._emitOnChange = options.emitOnChange ?? true;
+        this._deadzone = options.deadzone ?? 0.0;
+
+        // For digital actions, these control the output value
+        // For analog actions, these are not used
+        this._onValue = options.onValue ?? true;
+        this._offValue = options.offValue ?? false;
+
+        // Store min/max values explicitly
+        const defaultMin = this.action.type === 'analog'
+            ? this.action.minValue ?? Number.NEGATIVE_INFINITY
+            : Number.NEGATIVE_INFINITY;
+        this._min = options.min ?? defaultMin;
+
+        const defaultMax = this.action.type === 'analog'
+            ? this.action.maxValue ?? Number.POSITIVE_INFINITY
+            : Number.POSITIVE_INFINITY;
+        this._max = options.max ?? defaultMax;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Process input state and emit an action value
+     *
+     * @param state - Current input state
+     * @param eventBus - Event bus to emit action events to
+     * @returns True if a value was emitted, false otherwise
+     */
+    public process(state : InputState, eventBus : GameEventBus) : void
+    {
+        const rawValue = this.reader.getValue(state);
+        if(rawValue === undefined) { return; }
+
+        const numericValue = typeof rawValue === 'boolean' ? (rawValue ? 1.0 : 0.0) : rawValue;
+        if(numericValue === undefined) { return; }
+
+        let value = this._deadzone > 0 && Math.abs(numericValue) < this._deadzone ? 0 : numericValue;
+        value = ((this._invert ? -value : value) * this._scale) + this._offset;
+
+        // Apply min/max clamping
+        value = Math.max(this._min, Math.min(this._max, value));
+
+        if(this._emitOnChange && this._lastValue === value) { return; }
+        this._lastValue = value;
+
+        eventBus.publish({
+            type: `action:${ this.action.name }`,
+            payload: {
+                value,
+                deviceId: this.deviceID,
+                context: this.context,
+            },
+        });
+    }
+
+    /**
+     * Returns a JSON-serializable representation of this value binding
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    public toJSON() : ValueBindingDefinition
+    {
+        return {
+            type: this.type,
+            action: this.action.name,
+            input: {
+                deviceID: this.deviceID,
+                ...this.reader.toJSON(),
+            },
+            context: this.context,
+            options: this.options,
+        };
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------