@skewedaspect/sage 0.3.0

package/src/classes/input/mouse.ts

@@ -0,0 +1,276 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Mouse Input Resource Access
+//----------------------------------------------------------------------------------------------------------------------
+
+// Interfaces
+import type { ButtonState, MouseDevice, MouseInputState, Position } from '../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Callback type for mouse device connection events
+ */
+export type MouseDeviceCallback = (device : MouseDevice) => void;
+
+/**
+ * Callback type for mouse input events
+ */
+export type MouseInputCallback = (device : MouseDevice, state : MouseInputState) => void;
+
+/**
+ * Responsible for tracking mouse state and notifying subscribers of changes.
+ */
+export class MouseInputPlugin
+{
+    private _targetElement : HTMLElement;
+    private _mouseDevice : MouseDevice;
+    private _buttonState : Record<string, ButtonState> = {};
+    private _axesState : Record<string, number> = {};
+    private _position : Position = {
+        absolute: { x: 0, y: 0 },
+        relative: { x: 0, y: 0 },
+    };
+
+    private _wheelState = {
+        deltaX: 0,
+        deltaY: 0,
+        deltaZ: 0,
+        deltaMode: 0,
+    };
+
+    // Callbacks
+    private _onDeviceConnected ?: MouseDeviceCallback;
+    private _onInputChanged ?: MouseInputCallback;
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Create a new MouseResourceAccess
+     *
+     * @param targetElement - The DOM element to attach mouse listeners to (defaults to document.body)
+     */
+    constructor(targetElement : HTMLElement = document.body)
+    {
+        this._targetElement = targetElement;
+
+        // Initialize mouse device
+        this._mouseDevice = {
+            id: 'mouse-0',
+            name: 'Mouse',
+            type: 'mouse',
+            connected: true,
+        };
+
+        // Set up event listeners
+        this._setupMouseEvents();
+
+        // Initialize axes to zero
+        this._axesState['axis-x'] = 0;
+        this._axesState['axis-y'] = 0;
+
+        // Notify that device is connected (on next tick to allow callback registration)
+        setTimeout(() => this._notifyDeviceConnected(), 0);
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Register a callback for device connected events
+     *
+     * @param callback - The callback to register
+     */
+    public onDeviceConnected(callback : MouseDeviceCallback) : void
+    {
+        this._onDeviceConnected = callback;
+    }
+
+    /**
+     * Register a callback for input changed events
+     *
+     * @param callback - The callback to register
+     */
+    public onInputChanged(callback : MouseInputCallback) : void
+    {
+        this._onInputChanged = callback;
+    }
+
+    /**
+     * Get the current mouse state
+     */
+    public getState() : MouseInputState
+    {
+        return {
+            type: 'mouse',
+            buttons: { ...this._buttonState },
+            axes: { ...this._axesState },
+            position: {
+                absolute: { ...this._position.absolute },
+                relative: { ...this._position.relative },
+            },
+            wheel: { ...this._wheelState },
+        };
+    }
+
+    /**
+     * Get the mouse device
+     */
+    public getDevice() : MouseDevice
+    {
+        return { ...this._mouseDevice };
+    }
+
+    /**
+     * Destroy the mouse resource access and clean up event listeners
+     */
+    public destroy() : void
+    {
+        // Remove mouse event listeners
+        this._targetElement.removeEventListener('mousedown', this._handleMouseDown);
+        this._targetElement.removeEventListener('mouseup', this._handleMouseUp);
+        this._targetElement.removeEventListener('mousemove', this._handleMouseMove);
+        this._targetElement.removeEventListener('wheel', this._handleMouseWheel);
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Private Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Set up mouse event listeners
+     */
+    private _setupMouseEvents() : void
+    {
+        // Bind handlers to this instance
+        this._handleMouseDown = this._handleMouseDown.bind(this);
+        this._handleMouseUp = this._handleMouseUp.bind(this);
+        this._handleMouseMove = this._handleMouseMove.bind(this);
+        this._handleMouseWheel = this._handleMouseWheel.bind(this);
+
+        // Add event listeners
+        this._targetElement.addEventListener('mousedown', this._handleMouseDown);
+        this._targetElement.addEventListener('mouseup', this._handleMouseUp);
+        this._targetElement.addEventListener('mousemove', this._handleMouseMove);
+        this._targetElement.addEventListener('wheel', this._handleMouseWheel);
+    }
+
+    /**
+     * Handle mouse button down events
+     */
+    private _handleMouseDown(event : MouseEvent) : void
+    {
+        const buttonKey = `button-${ event.button }`;
+        const buttonState : ButtonState = {
+            pressed: true,
+        };
+
+        this._buttonState[buttonKey] = buttonState;
+
+        this._notifyInputChanged({
+            type: 'mouse',
+            event,
+            buttons: { ...this._buttonState },
+            axes: { ...this._axesState },
+            position: { ...this._position },
+        });
+    }
+
+    /**
+     * Handle mouse button up events
+     */
+    private _handleMouseUp(event : MouseEvent) : void
+    {
+        const buttonKey = `button-${ event.button }`;
+        const buttonState : ButtonState = {
+            pressed: false,
+        };
+
+        this._buttonState[buttonKey] = buttonState;
+
+        this._notifyInputChanged({
+            type: 'mouse',
+            event,
+            buttons: { ...this._buttonState },
+            axes: { ...this._axesState },
+            position: { ...this._position },
+        });
+    }
+
+    /**
+     * Handle mouse move events
+     */
+    private _handleMouseMove(event : MouseEvent) : void
+    {
+        // Update position
+        this._position = {
+            absolute: {
+                x: event.clientX,
+                y: event.clientY,
+            },
+            relative: {
+                x: event.movementX,
+                y: event.movementY,
+            },
+        };
+
+        // Update axis values
+        this._axesState['axis-x'] = event.clientX;
+        this._axesState['axis-y'] = event.clientY;
+
+        this._notifyInputChanged({
+            type: 'mouse',
+            event,
+            buttons: { ...this._buttonState },
+            axes: { ...this._axesState },
+            position: { ...this._position },
+        });
+    }
+
+    /**
+     * Handle mouse wheel events
+     */
+    private _handleMouseWheel(event : WheelEvent) : void
+    {
+        // Update wheel state
+        this._wheelState = {
+            deltaX: event.deltaX,
+            deltaY: event.deltaY,
+            deltaZ: event.deltaZ,
+            deltaMode: event.deltaMode,
+        };
+
+        this._notifyInputChanged({
+            type: 'mouse',
+            event,
+            buttons: { ...this._buttonState },
+            axes: { ...this._axesState },
+            position: { ...this._position },
+            wheel: { ...this._wheelState },
+        });
+    }
+
+    /**
+     * Notify subscribers of device connected event
+     */
+    private _notifyDeviceConnected() : void
+    {
+        if(this._onDeviceConnected)
+        {
+            this._onDeviceConnected(this._mouseDevice);
+        }
+    }
+
+    /**
+     * Notify subscribers of input changed event
+     */
+    private _notifyInputChanged(state : MouseInputState) : void
+    {
+        if(this._onInputChanged)
+        {
+            this._onInputChanged(this._mouseDevice, state);
+        }
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/classes/input/readers/gamepad.ts

@@ -0,0 +1,179 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Gamepad Value Reader
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { DeviceValueReader, GamepadValueReaderDefinition, InputState } from '../../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Types of gamepad input sources
+ */
+export type GamepadSourceType = 'button' | 'axis';
+
+/**
+ * Options for configuring a gamepad value reader
+ */
+export interface GamepadReaderOptions
+{
+    /**
+     * Whether to use the analog value instead of boolean pressed state for buttons
+     */
+    useAnalogValue ?: boolean;
+
+    /**
+     * Deadzone value (0.0 - 1.0) for analog axes
+     * Input values below this threshold will be treated as 0
+     */
+    deadzone ?: number;
+
+    /**
+     * Whether to invert the axis values
+     */
+    invert ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Reads values from gamepad input states
+ */
+export class GamepadValueReader implements DeviceValueReader
+{
+    /**
+     * The type of gamepad input
+     */
+    readonly sourceType : GamepadSourceType;
+
+    /**
+     * The specific key for this input
+     */
+    readonly sourceKey : string;
+
+    /**
+     * Whether to use analog value for buttons
+     */
+    private readonly useAnalogValue : boolean;
+
+    /**
+     * Deadzone value for axes
+     */
+    private readonly deadzone : number;
+
+    /**
+     * Whether to invert axis values
+     */
+    private readonly invert : boolean;
+
+    /**
+     * Creates a new GamepadValueReader
+     *
+     * @param sourceType - Type of gamepad input to monitor (button or axis)
+     * @param sourceKey - The specific key for this input type
+     * @param options - Configuration options
+     */
+    constructor(sourceType : GamepadSourceType, sourceKey : string, options : GamepadReaderOptions = {})
+    {
+        this.sourceType = sourceType;
+        this.sourceKey = sourceKey;
+        this.useAnalogValue = options.useAnalogValue || false;
+        this.deadzone = options.deadzone || 0.1; // Default 10% deadzone
+        this.invert = options.invert || false;
+    }
+
+    /**
+     * Gets the value of the input source based on the current state
+     *
+     * @param state - The current input state
+     * @returns The value of the input source
+     */
+    public getValue(state : InputState) : boolean | number | undefined
+    {
+        // Check if the state is from the correct device type
+        if(state.type !== 'gamepad')
+        {
+            return undefined;
+        }
+
+        switch (this.sourceType)
+        {
+            case 'button':
+            {
+                const buttonState = state.buttons[this.sourceKey];
+
+                if(!buttonState)
+                {
+                    return undefined;
+                }
+
+                return this.useAnalogValue ? buttonState.value : buttonState.pressed;
+            }
+
+            case 'axis':
+            {
+                let value = state.axes[this.sourceKey];
+
+                if(value === undefined)
+                {
+                    return undefined;
+                }
+
+                // Apply deadzone
+                if(Math.abs(value) < this.deadzone)
+                {
+                    value = 0;
+                }
+
+                // Apply inversion if needed
+                return this.invert ? -value : value;
+            }
+
+            default:
+                return undefined;
+        }
+    }
+
+    /**
+     * Creates a GamepadValueReader from a string representation
+     *
+     * @param sourceTypeString - String in format "sourceType:sourceKey" (e.g., "button:0", "axis:1")
+     * @param options - Optional configuration options
+     * @returns A new GamepadValueReader instance
+     */
+    public static fromString(sourceTypeString : string, options : GamepadReaderOptions = {}) : GamepadValueReader
+    {
+        const [ sourceType, sourceKey ] = sourceTypeString.split(':');
+
+        if(!sourceType || !sourceKey)
+        {
+            throw new Error(`Invalid gamepad source format: ${ sourceTypeString }`);
+        }
+
+        return new GamepadValueReader(
+            sourceType as GamepadSourceType,
+            sourceKey,
+            options
+        );
+    }
+
+    /**
+     * Returns a JSON-serializable representation of this gamepad value reader
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    public toJSON() : GamepadValueReaderDefinition
+    {
+        return {
+            type: 'gamepad',
+            sourceType: this.sourceType,
+            sourceKey: this.sourceKey,
+            options: {
+                useAnalogValue: this.useAnalogValue,
+                deadzone: this.deadzone,
+                invert: this.invert,
+            },
+        };
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/classes/input/readers/keyboard.ts

@@ -0,0 +1,123 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Keyboard Value Reader
+//----------------------------------------------------------------------------------------------------------------------
+
+import type {
+    DeviceValueReader,
+    InputState,
+    KeyboardInputState,
+    KeyboardValueReaderDefinition,
+} from '../../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Types of keyboard input sources
+ */
+export type KeyboardSourceType = 'key';
+
+/**
+ * Options for configuring a keyboard value reader
+ */
+export interface KeyboardReaderOptions
+{
+    /**
+     * Whether to use delta state instead of current state
+     * When true, the source will only return true on the initial key press
+     */
+    useDelta ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Reads values from keyboard input states
+ */
+export class KeyboardValueReader implements DeviceValueReader
+{
+    /**
+     * The type of keyboard input (always 'key')
+     */
+    public readonly sourceType : KeyboardSourceType = 'key';
+
+    /**
+     * The key code to monitor (e.g., "KeyA", "Space")
+     */
+    public readonly sourceKey : string;
+
+    /**
+     * Whether to use delta state instead of current state
+     */
+    private readonly useDelta : boolean;
+
+    /**
+     * Creates a new KeyboardValueReader
+     *
+     * @param keyCode - The key code to monitor (e.g., "KeyA", "Space")
+     * @param options - Configuration options
+     */
+    constructor(keyCode : string, options : KeyboardReaderOptions = {})
+    {
+        this.sourceKey = keyCode;
+        this.useDelta = options.useDelta || false;
+    }
+
+    /**
+     * Gets the value of the key state
+     *
+     * @param state - The input state
+     * @returns The key state value or undefined if the state type is not keyboard
+     */
+    public getValue(state : InputState) : boolean | undefined
+    {
+        // Check if the state is from the correct device type
+        if(state.type !== 'keyboard')
+        {
+            return undefined;
+        }
+
+        const keyboardState = state as KeyboardInputState;
+
+        // Get value from either the current state or delta state based on configuration
+        if(this.useDelta)
+        {
+            return keyboardState.delta[this.sourceKey];
+        }
+        else
+        {
+            return keyboardState.keys[this.sourceKey];
+        }
+    }
+
+    /**
+     * Creates a KeyboardValueReader from a string representation
+     *
+     * @param sourceKey - The key code (e.g., "KeyA", "Space")
+     * @param options - Optional configuration
+     * @returns A new KeyboardValueReader instance
+     */
+    public static fromString(sourceKey : string, options : KeyboardReaderOptions = {}) : KeyboardValueReader
+    {
+        return new KeyboardValueReader(sourceKey, options);
+    }
+
+    /**
+     * Returns a JSON-serializable representation of this keyboard value reader
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    public toJSON() : KeyboardValueReaderDefinition
+    {
+        return {
+
+            type: 'keyboard',
+            sourceType: this.sourceType,
+            sourceKey: this.sourceKey,
+            options: {
+                useDelta: this.useDelta,
+            },
+        };
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/classes/input/readers/mouse.ts

@@ -0,0 +1,133 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Mouse Value Reader
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { DeviceValueReader, InputState, MouseValueReaderDefinition } from '../../../interfaces/input.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Types of mouse input sources
+ */
+export type MouseSourceType = 'button' | 'position' | 'wheel';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Reads values from mouse input states
+ */
+export class MouseValueReader implements DeviceValueReader
+{
+    /**
+     * The type of mouse input
+     */
+    readonly sourceType : MouseSourceType;
+
+    /**
+     * The specific key for this input
+     */
+    readonly sourceKey : string;
+
+    /**
+     * Creates a new MouseValueReader
+     *
+     * @param sourceType - Type of mouse input to monitor (button, position, wheel)
+     * @param sourceKey - The specific key for this input type
+     */
+    constructor(sourceType : MouseSourceType, sourceKey : string)
+    {
+        this.sourceType = sourceType;
+        this.sourceKey = sourceKey;
+    }
+
+    /**
+     * Gets the value of the mouse input source
+     *
+     * @param state - The current input state
+     * @returns The value of the input source
+     */
+    public getValue(state : InputState) : boolean | number | undefined
+    {
+        // Check if the state is from the correct device type
+        if(state.type !== 'mouse')
+        {
+            return undefined;
+        }
+
+        switch (this.sourceType)
+        {
+            case 'button':
+            {
+                const buttonState = state.buttons[this.sourceKey];
+                return buttonState ? buttonState.pressed : undefined;
+            }
+
+            case 'position':
+            {
+                // Position keys are in format "positionType:axis" (e.g., "absolute:x")
+                const [ posType, axis ] = this.sourceKey.split(':');
+
+                if(!posType || !axis || (posType !== 'absolute' && posType !== 'relative')
+                    || (axis !== 'x' && axis !== 'y'))
+                {
+                    return undefined;
+                }
+
+                return state.position[posType][axis];
+            }
+
+            case 'wheel':
+            {
+                const isValidWheelKey = this.sourceKey === 'deltaX' || this.sourceKey === 'deltaY'
+                    || this.sourceKey === 'deltaZ';
+                if(state.wheel && isValidWheelKey)
+                {
+                    return state.wheel[this.sourceKey];
+                }
+                return undefined;
+            }
+
+            default:
+                return undefined;
+        }
+    }
+
+    /**
+     * Creates a MouseValueReader from a string representation
+     *
+     * @param sourceTypeString - String in format "sourceType:sourceKey" (e.g., "button:0", "position:absolute:x")
+     * @returns A new MouseValueReader instance
+     */
+    public static fromString(sourceTypeString : string) : MouseValueReader
+    {
+        const [ sourceType, ...keyParts ] = sourceTypeString.split(':');
+        const sourceKey = keyParts.join(':');
+
+        if(!sourceType || !sourceKey)
+        {
+            throw new Error(`Invalid mouse source format: ${ sourceTypeString }`);
+        }
+
+        return new MouseValueReader(
+            sourceType as MouseSourceType,
+            sourceKey
+        );
+    }
+
+    /**
+     * Returns a JSON-serializable representation of this mouse value reader
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    public toJSON() : MouseValueReaderDefinition
+    {
+        // Always return consistent 'mouse' type with sourceType and sourceKey
+        return {
+            type: 'mouse',
+            sourceType: this.sourceType,
+            sourceKey: this.sourceKey,
+        };
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------