@skewedaspect/sage 0.3.0

package/dist/classes/input/gamepad.d.ts

@@ -0,0 +1,94 @@
+import type { GamepadDevice, GamepadInputState } from '../../interfaces/input.ts';
+/**
+ * Callback type for gamepad device connection events
+ */
+export type GamepadDeviceCallback = (device: GamepadDevice) => void;
+/**
+ * Callback type for gamepad input events
+ */
+export type GamepadInputCallback = (device: GamepadDevice, state: GamepadInputState) => void;
+/**
+ * Responsible for tracking gamepad state and notifying subscribers of changes.
+ */
+export declare class GamepadInputPlugin {
+    private _gamepadDevices;
+    private _buttonStates;
+    private _axesStates;
+    private _onDeviceConnected?;
+    private _onDeviceDisconnected?;
+    private _onInputChanged?;
+    /**
+     * Create a new GamepadResourceAccess
+     */
+    constructor();
+    /**
+     * Register a callback for device connected events
+     *
+     * @param callback - The callback to register
+     */
+    onDeviceConnected(callback: GamepadDeviceCallback): void;
+    /**
+     * Register a callback for device disconnected events
+     *
+     * @param callback - The callback to register
+     */
+    onDeviceDisconnected(callback: GamepadDeviceCallback): void;
+    /**
+     * Register a callback for input changed events
+     *
+     * @param callback - The callback to register
+     */
+    onInputChanged(callback: GamepadInputCallback): void;
+    /**
+     * Get all connected gamepad devices
+     */
+    getDevices(): GamepadDevice[];
+    /**
+     * Get all connected gamepad states
+     */
+    getStates(): Record<number, GamepadInputState>;
+    /**
+     * Get a specific gamepad device by index
+     *
+     * @param index - The index of the gamepad to get
+     */
+    getDevice(index: number): GamepadDevice | null;
+    /**
+     * Get a specific gamepad state by index
+     *
+     * @param index - The index of the gamepad state to get
+     */
+    getState(index: number): GamepadInputState | null;
+    /**
+     * Poll for gamepad state updates - call this in your game loop
+     */
+    pollGamepads(): void;
+    /**
+     * Destroy the gamepad resource access and clean up event listeners
+     */
+    destroy(): void;
+    /**
+     * Set up gamepad event listeners
+     */
+    private _setupGamepadEvents;
+    /**
+     * Handle gamepad connected event
+     */
+    private _handleGamepadConnected;
+    /**
+     * Handle gamepad disconnected event
+     */
+    private _handleGamepadDisconnected;
+    /**
+     * Notify subscribers of device connected event
+     */
+    private _notifyDeviceConnected;
+    /**
+     * Notify subscribers of device disconnected event
+     */
+    private _notifyDeviceDisconnected;
+    /**
+     * Notify subscribers of input changed event
+     */
+    private _notifyInputChanged;
+}

package/dist/classes/input/keyboard.d.ts

@@ -0,0 +1,66 @@
+import type { KeyboardDevice, KeyboardInputState } from '../../interfaces/input.ts';
+/**
+ * Callback type for keyboard device connection events
+ */
+export type KeyboardDeviceCallback = (device: KeyboardDevice) => void;
+/**
+ * Callback type for keyboard input events
+ */
+export type KeyboardInputCallback = (device: KeyboardDevice, state: KeyboardInputState) => void;
+/**
+ * Responsible for tracking keyboard state and notifying subscribers of changes.
+ */
+export declare class KeyboardInputPlugin {
+    private _keyboardDevice;
+    private _keysState;
+    private _onDeviceConnected?;
+    private _onInputChanged?;
+    /**
+     * Create a new KeyboardResourceAccess
+     */
+    constructor();
+    /**
+     * Register a callback for device connected events
+     *
+     * @param callback - The callback to register
+     */
+    onDeviceConnected(callback: KeyboardDeviceCallback): void;
+    /**
+     * Register a callback for input changed events
+     *
+     * @param callback - The callback to register
+     */
+    onInputChanged(callback: KeyboardInputCallback): void;
+    /**
+     * Get the current keyboard state
+     */
+    getState(): KeyboardInputState;
+    /**
+     * Get the keyboard device
+     */
+    getDevice(): KeyboardDevice;
+    /**
+     * Destroy the keyboard resource access and clean up event listeners
+     */
+    destroy(): void;
+    /**
+     * Set up keyboard event listeners
+     */
+    private _setupKeyboardEvents;
+    /**
+     * Handle keyboard key down events
+     */
+    private _handleKeyDown;
+    /**
+     * Handle keyboard key up events
+     */
+    private _handleKeyUp;
+    /**
+     * Notify subscribers of device connected event
+     */
+    private _notifyDeviceConnected;
+    /**
+     * Notify subscribers of input changed event
+     */
+    private _notifyInputChanged;
+}

package/dist/classes/input/mouse.d.ts

@@ -0,0 +1,80 @@
+import type { MouseDevice, MouseInputState } 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 declare class MouseInputPlugin {
+    private _targetElement;
+    private _mouseDevice;
+    private _buttonState;
+    private _axesState;
+    private _position;
+    private _wheelState;
+    private _onDeviceConnected?;
+    private _onInputChanged?;
+    /**
+     * Create a new MouseResourceAccess
+     *
+     * @param targetElement - The DOM element to attach mouse listeners to (defaults to document.body)
+     */
+    constructor(targetElement?: HTMLElement);
+    /**
+     * Register a callback for device connected events
+     *
+     * @param callback - The callback to register
+     */
+    onDeviceConnected(callback: MouseDeviceCallback): void;
+    /**
+     * Register a callback for input changed events
+     *
+     * @param callback - The callback to register
+     */
+    onInputChanged(callback: MouseInputCallback): void;
+    /**
+     * Get the current mouse state
+     */
+    getState(): MouseInputState;
+    /**
+     * Get the mouse device
+     */
+    getDevice(): MouseDevice;
+    /**
+     * Destroy the mouse resource access and clean up event listeners
+     */
+    destroy(): void;
+    /**
+     * Set up mouse event listeners
+     */
+    private _setupMouseEvents;
+    /**
+     * Handle mouse button down events
+     */
+    private _handleMouseDown;
+    /**
+     * Handle mouse button up events
+     */
+    private _handleMouseUp;
+    /**
+     * Handle mouse move events
+     */
+    private _handleMouseMove;
+    /**
+     * Handle mouse wheel events
+     */
+    private _handleMouseWheel;
+    /**
+     * Notify subscribers of device connected event
+     */
+    private _notifyDeviceConnected;
+    /**
+     * Notify subscribers of input changed event
+     */
+    private _notifyInputChanged;
+}

package/dist/classes/input/readers/gamepad.d.ts

@@ -0,0 +1,77 @@
+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 declare 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;
+    /**
+     * Deadzone value for axes
+     */
+    private readonly deadzone;
+    /**
+     * Whether to invert axis values
+     */
+    private readonly invert;
+    /**
+     * 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);
+    /**
+     * 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
+     */
+    getValue(state: InputState): boolean | number | 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
+     */
+    static fromString(sourceTypeString: string, options?: GamepadReaderOptions): GamepadValueReader;
+    /**
+     * Returns a JSON-serializable representation of this gamepad value reader
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    toJSON(): GamepadValueReaderDefinition;
+}

package/dist/classes/input/readers/keyboard.d.ts

@@ -0,0 +1,60 @@
+import type { DeviceValueReader, InputState, 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 declare class KeyboardValueReader implements DeviceValueReader {
+    /**
+     * The type of keyboard input (always 'key')
+     */
+    readonly sourceType: KeyboardSourceType;
+    /**
+     * The key code to monitor (e.g., "KeyA", "Space")
+     */
+    readonly sourceKey: string;
+    /**
+     * Whether to use delta state instead of current state
+     */
+    private readonly useDelta;
+    /**
+     * Creates a new KeyboardValueReader
+     *
+     * @param keyCode - The key code to monitor (e.g., "KeyA", "Space")
+     * @param options - Configuration options
+     */
+    constructor(keyCode: string, options?: KeyboardReaderOptions);
+    /**
+     * 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
+     */
+    getValue(state: InputState): boolean | undefined;
+    /**
+     * 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
+     */
+    static fromString(sourceKey: string, options?: KeyboardReaderOptions): KeyboardValueReader;
+    /**
+     * Returns a JSON-serializable representation of this keyboard value reader
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    toJSON(): KeyboardValueReaderDefinition;
+}

package/dist/classes/input/readers/mouse.d.ts

@@ -0,0 +1,45 @@
+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 declare 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);
+    /**
+     * Gets the value of the mouse input source
+     *
+     * @param state - The current input state
+     * @returns The value of the input source
+     */
+    getValue(state: InputState): boolean | number | 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
+     */
+    static fromString(sourceTypeString: string): MouseValueReader;
+    /**
+     * Returns a JSON-serializable representation of this mouse value reader
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    toJSON(): MouseValueReaderDefinition;
+}

package/dist/classes/loggers/consoleBackend.d.ts

@@ -0,0 +1,29 @@
+import type { LoggingBackend } from '../../interfaces/logger.ts';
+/**
+ * A logging backend that logs to the console.
+ */
+export declare class ConsoleBackend implements LoggingBackend {
+    private timers;
+    constructor();
+    /**
+     * Get the CSS style for a specific log level
+     */
+    private getStyleForLevel;
+    /**
+     * Format a log message with category, timestamp and log level
+     */
+    private formatMessage;
+    trace(category: string, message: string, ...args: any[]): void;
+    debug(category: string, message: string, ...args: any[]): void;
+    info(category: string, message: string, ...args: any[]): void;
+    warn(category: string, message: string, ...args: any[]): void;
+    error(category: string, message: string, ...args: any[]): void;
+    /**
+     * Start a timer with the specified label.
+     */
+    time(category: string, label: string): void;
+    /**
+     * End a timer and log the elapsed time.
+     */
+    timeEnd(category: string, label: string): void;
+}

package/dist/classes/loggers/nullBackend.d.ts

@@ -0,0 +1,14 @@
+import type { LoggingBackend } from '../../interfaces/logger.ts';
+/**
+ * A logging backend that does nothing (discards all logs).
+ * Useful for production environments or when you want to completely disable logging.
+ */
+export declare class NullBackend implements LoggingBackend {
+    trace(_category: string, _message: string, ..._args: any[]): void;
+    debug(_category: string, _message: string, ..._args: any[]): void;
+    info(_category: string, _message: string, ..._args: any[]): void;
+    warn(_category: string, _message: string, ..._args: any[]): void;
+    error(_category: string, _message: string, ..._args: any[]): void;
+    time(_category: string, _label: string): void;
+    timeEnd(_category: string, _label: string): void;
+}

package/dist/engines/scene.d.ts

@@ -0,0 +1,11 @@
+import { AbstractEngine, HavokPlugin, Scene } from '@babylonjs/core';
+import type { GameCanvas } from '../interfaces/game.ts';
+import { type LoggingUtility } from '../utils/logger.ts';
+export declare class SceneEngine {
+    private _engine;
+    private _physics;
+    private _log;
+    constructor(engine: AbstractEngine, physics: HavokPlugin, logger?: LoggingUtility);
+    private _buildDemoScene;
+    loadScene(canvas: GameCanvas): Promise<Scene>;
+}

package/dist/interfaces/action.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Digital action (boolean)
+ */
+export interface DigitalAction {
+    type: 'digital';
+    name: string;
+}
+/**
+ * Analog action (numeric)
+ */
+export interface AnalogAction {
+    type: 'analog';
+    name: string;
+    minValue?: number;
+    maxValue?: number;
+}
+/**
+ * Action types
+ */
+export type Action = DigitalAction | AnalogAction;

package/dist/interfaces/binding.d.ts

@@ -0,0 +1,144 @@
+import type { GameEventBus } from '../classes/eventBus.ts';
+import type { DeviceValueReader, DeviceValueReaderDefinition, InputState } from './input.ts';
+import type { Action } from './action.ts';
+/**
+ * Types of bindings supported by the system
+ */
+export type BindingType = 'trigger' | 'toggle' | 'value';
+/**
+ * Array of all supported binding types for validation
+ */
+export declare const bindingTypes: BindingType[];
+/**
+ * Context for organizing bindings into groups that can be activated/deactivated together
+ */
+export interface Context {
+    /**
+     * Name of the context for identification
+     */
+    name: string;
+    /**
+     * Whether this context is exclusive (only one exclusive context can be active at a time)
+     */
+    exclusive: boolean;
+}
+/**
+ * Input definition that combines device ID and reader configuration into a single object
+ */
+export type InputDefinition = DeviceValueReaderDefinition & {
+    deviceID: string;
+};
+/**
+ * Base interface for binding definitions with object-based sources
+ */
+export interface BindingDefinitionBase {
+    /**
+     * Type of binding
+     */
+    type: BindingType;
+    /**
+     * Name of the (already registered) action this binding triggers
+     */
+    action: string;
+    /**
+     * Input definition combining device ID and reader configuration
+     */
+    input: InputDefinition;
+    /**
+     * Optional context name this binding belongs to
+     */
+    context?: string;
+    /**
+     * Optional options for the binding
+     */
+    options?: Record<string, any>;
+}
+/**
+ * Trigger binding definition
+ */
+export interface TriggerBindingDefinition extends BindingDefinitionBase {
+    type: 'trigger';
+    options?: {
+        edgeMode?: 'rising' | 'falling' | 'both';
+        threshold?: number;
+        passthrough?: boolean;
+    };
+}
+/**
+ * Toggle binding definition
+ */
+export interface ToggleBindingDefinition extends BindingDefinitionBase {
+    type: 'toggle';
+    state?: boolean;
+    options?: {
+        invert?: boolean;
+        initialState?: boolean;
+        threshold?: number;
+        onValue?: boolean | number;
+        offValue?: boolean | number;
+    };
+}
+/**
+ * Value binding definition
+ */
+export interface ValueBindingDefinition extends BindingDefinitionBase {
+    type: 'value';
+    options?: {
+        scale?: number;
+        offset?: number;
+        min?: number;
+        max?: number;
+        invert?: boolean;
+        emitOnChange?: boolean;
+        deadzone?: number;
+    };
+}
+/**
+ * Generic binding definition (for any other binding types)
+ */
+export interface GenericBindingDefinition extends BindingDefinitionBase {
+    type: Exclude<BindingType, 'trigger' | 'toggle' | 'value'>;
+    options?: Record<string, any>;
+}
+/**
+ * Union type of all binding definitions
+ */
+export type BindingDefinition = TriggerBindingDefinition | ToggleBindingDefinition | ValueBindingDefinition | GenericBindingDefinition;
+/**
+ * Base interface for all input bindings
+ */
+export interface Binding {
+    /**
+     * Type of binding
+     */
+    readonly type: BindingType;
+    /**
+     * Action object this binding triggers
+     */
+    readonly action: Action;
+    /**
+     * Optional context name this binding belongs to
+     */
+    readonly context?: string;
+    /**
+     * Device ID this binding is associated with
+     */
+    readonly deviceID: string;
+    /**
+     * Input source that provides values for this binding
+     */
+    readonly reader: DeviceValueReader;
+    /**
+     * Process input state and potentially emit an action event
+     *
+     * @param state - Current input state for the device
+     * @param eventBus - Event bus to emit action events to
+     */
+    process(state: InputState, eventBus: GameEventBus): void;
+    /**
+     * Convert the binding to a JSON-serializable object
+     *
+     * @returns A JSON-serializable representation of the binding
+     */
+    toJSON(): BindingDefinition;
+}

package/dist/interfaces/entity.d.ts

@@ -0,0 +1,9 @@
+import { GameEntityBehavior } from '../classes/entity.ts';
+import { Action } from './action.ts';
+export type GameEntityBehaviorConstructor<RequiredState extends object = object> = new () => GameEntityBehavior<RequiredState>;
+export interface GameEntityDefinition {
+    type: string;
+    defaultState: Record<string, any>;
+    behaviors: GameEntityBehaviorConstructor[];
+    actions?: Action[];
+}

package/dist/interfaces/game.d.ts

@@ -0,0 +1,26 @@
+import { EngineOptions, NullEngineOptions, WebGPUEngineOptions } from '@babylonjs/core';
+import type { LogLevel } from './logger.ts';
+import { BindingDefinition } from './binding.ts';
+export type GameCanvas = HTMLCanvasElement | OffscreenCanvas | null;
+/** Specifies which rendering engine to force using */
+export type EngineType = 'webgl' | 'webgpu' | 'auto';
+export interface BabylonEngineOptions {
+    antialias?: boolean;
+    adaptToDeviceRatio?: boolean;
+    options?: EngineOptions;
+}
+export type RenderEngineOptions = (BabylonEngineOptions | NullEngineOptions | WebGPUEngineOptions) & {
+    /** Force a specific engine type, overriding automatic detection */
+    forceEngine?: EngineType;
+};
+/**
+ * SAGE Engine options for configuring the game engine
+ */
+export interface SageOptions {
+    /** Render engine options for BabylonJS */
+    renderOptions?: RenderEngineOptions;
+    /** Input bindings to be registered at startup */
+    bindings?: BindingDefinition[];
+    /** Logging level for the engine */
+    logLevel?: LogLevel;
+}