@skewedaspect/sage 0.3.0

package/src/interfaces/action.ts

@@ -0,0 +1,30 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Action Interfaces
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * 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/src/interfaces/binding.ts

@@ -0,0 +1,191 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Binding Interfaces
+//----------------------------------------------------------------------------------------------------------------------
+
+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 const bindingTypes : BindingType[] = [
+    'trigger',
+    'toggle',
+    'value',
+];
+
+/**
+ * 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/src/interfaces/entity.ts

@@ -0,0 +1,21 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Game Entity and Behavior Interfaces
+//----------------------------------------------------------------------------------------------------------------------
+
+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[]; // Actions that this entity requires
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/interfaces/game.ts

@@ -0,0 +1,44 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Game Engine Related Interfaces
+//----------------------------------------------------------------------------------------------------------------------
+
+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;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/interfaces/input.ts

@@ -0,0 +1,221 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Input Device Interfaces
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Valid input device types
+ */
+export const validDeviceTypes = [ 'keyboard', 'mouse', 'gamepad' ] as const;
+export type DeviceType = typeof validDeviceTypes[number];
+
+/**
+ * Base input device interface
+ */
+export interface InputDevice
+{
+    id : string;
+    name : string;
+    type : DeviceType;
+    connected : boolean;
+}
+
+/**
+ * Keyboard device information
+ */
+export interface KeyboardDevice extends InputDevice
+{
+    type : 'keyboard';
+}
+
+/**
+ * Mouse device information
+ */
+export interface MouseDevice extends InputDevice
+{
+    type : 'mouse';
+}
+
+/**
+ * Gamepad device information
+ */
+export interface GamepadDevice extends InputDevice
+{
+    type : 'gamepad';
+    index : number;
+    mapping : string;
+    axes : number[];
+    buttons : GamepadButton[];
+}
+
+/**
+ * Base interface for all input device states
+ */
+export interface BaseInputState
+{
+    event ?: Event;
+}
+
+/**
+ * Button state interface (for both mouse and gamepad)
+ */
+export interface ButtonState
+{
+    pressed : boolean;
+    touched ?: boolean;
+    value ?: number;
+}
+
+/**
+ * Mouse position interface
+ */
+export interface Position
+{
+    absolute : { x : number, y : number };
+    relative : { x : number, y : number };
+}
+
+/**
+ * Unified keyboard input state with object literals instead of Maps
+ */
+export interface KeyboardInputState extends BaseInputState
+{
+    type : 'keyboard';
+    keys : Record<string, boolean>;
+    delta : Record<string, boolean>;
+    event ?: KeyboardEvent;
+}
+
+/**
+ * Unified mouse input state with object literals instead of Maps
+ */
+export interface MouseInputState extends BaseInputState
+{
+    type : 'mouse';
+    buttons : Record<string, ButtonState>;
+    axes : Record<string, number>;
+    position : Position;
+    wheel ?: {
+        deltaX : number;
+        deltaY : number;
+        deltaZ : number;
+        deltaMode : number;
+    };
+    event ?: MouseEvent | WheelEvent;
+}
+
+/**
+ * Unified gamepad input state with object literals instead of Maps
+ */
+export interface GamepadInputState extends BaseInputState
+{
+    type : 'gamepad';
+    buttons : Record<string, ButtonState>;
+    axes : Record<string, number>;
+    event ?: GamepadEvent;
+}
+
+/**
+ * Unified input state interface that can represent any input device
+ */
+export type InputState = KeyboardInputState | MouseInputState | GamepadInputState;
+
+/**
+ * Base interface for serialized device value readers
+ */
+export interface DeviceValueReaderDefinitionBase
+{
+    /**
+     * The device type of input source
+     */
+    type : DeviceType;
+
+    /**
+     * The input source type (e.g., 'key', 'button', 'axis')
+     */
+    sourceType : string;
+
+    /**
+     * The specific identifier for this input source (e.g., 'KeyA', '0', 'absolute:x')
+     */
+    sourceKey : string;
+}
+
+/**
+ * Keyboard value reader definition
+ */
+export interface KeyboardValueReaderDefinition extends DeviceValueReaderDefinitionBase
+{
+    type : 'keyboard';
+    sourceType : 'key';
+    sourceKey : string;
+    options ?: {
+        useDelta ?: boolean;
+    };
+}
+
+/**
+ * Mouse value reader definition
+ */
+export interface MouseValueReaderDefinition extends DeviceValueReaderDefinitionBase
+{
+    type : 'mouse';
+    sourceType : string;
+    sourceKey : string;
+}
+
+/**
+ * Gamepad value reader definition
+ */
+export interface GamepadValueReaderDefinition extends DeviceValueReaderDefinitionBase
+{
+    type : 'gamepad';
+    sourceType : string;
+    sourceKey : string;
+    options ?: {
+        useAnalogValue ?: boolean;
+        deadzone ?: number;
+        invert ?: boolean;
+    };
+}
+
+/**
+ * Union type of all device value reader definitions
+ */
+export type DeviceValueReaderDefinition =
+    | KeyboardValueReaderDefinition
+    | MouseValueReaderDefinition
+    | GamepadValueReaderDefinition;
+
+/**
+ * Interface for all device value readers
+ * Unified interface for all types of input sources that can extract values from device states
+ */
+export interface DeviceValueReader
+{
+    /**
+     * The type of input source (e.g., 'key', 'button', 'axis')
+     */
+    readonly sourceType : string;
+
+    /**
+     * The specific identifier for this input source (e.g., 'KeyA', '0', 'absolute:x')
+     */
+    readonly sourceKey : string;
+
+    /**
+     * Gets the value from an input state
+     *
+     * @param state - The current input state
+     * @returns The value from the input (boolean or number) or undefined if not applicable to this state
+     */
+    getValue(state : InputState) : boolean | number | undefined;
+
+    /**
+     * Convert the reader to a JSON-serializable object
+     *
+     * @returns A JSON-serializable representation of the reader
+     */
+    toJSON() : DeviceValueReaderDefinition;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/interfaces/logger.ts

@@ -0,0 +1,118 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Logger Interfaces
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Defines the available logging levels as string literals.
+ */
+export const LogLevels = [
+    'trace',
+    'debug',
+    'info',
+    'warn',
+    'error',
+    'none',
+] as const;
+
+/**
+ * Type for LogLevel values
+ */
+export type LogLevel = typeof LogLevels[number];
+
+/**
+ * Interface for a logging backend implementation.
+ * Backends handle the actual output of log messages.
+ */
+export interface LoggingBackend
+{
+    /**
+     * Log a message at TRACE level
+     *
+     * @param category - The category for this message (typically class/module name)
+     * @param message - The message text to log
+     * @param args - Optional additional arguments to include
+     */
+    trace(category : string, message : string, ...args : any[]) : void;
+
+    /**
+     * Log a message at DEBUG level
+     *
+     * @param category - The category for this message (typically class/module name)
+     * @param message - The message text to log
+     * @param args - Optional additional arguments to include
+     */
+    debug(category : string, message : string, ...args : any[]) : void;
+
+    /**
+     * Log a message at INFO level
+     *
+     * @param category - The category for this message (typically class/module name)
+     * @param message - The message text to log
+     * @param args - Optional additional arguments to include
+     */
+    info(category : string, message : string, ...args : any[]) : void;
+
+    /**
+     * Log a message at WARN level
+     *
+     * @param category - The category for this message (typically class/module name)
+     * @param message - The message text to log
+     * @param args - Optional additional arguments to include
+     */
+    warn(category : string, message : string, ...args : any[]) : void;
+
+    /**
+     * Log a message at ERROR level
+     *
+     * @param category - The category for this message (typically class/module name)
+     * @param message - The message text to log
+     * @param args - Optional additional arguments to include
+     */
+    error(category : string, message : string, ...args : any[]) : void;
+
+    /**
+     * Start a timer with the specified label.
+     *
+     * @param category - The category for this timer (typically class/module name)
+     * @param label - A unique label to identify the timer
+     */
+    time(category : string, label : string) : void;
+
+    /**
+     * End a timer with the specified label and log the time elapsed.
+     *
+     * @param category - The category for this timer (typically class/module name)
+     * @param label - The label identifying the timer to end
+     */
+    timeEnd(category : string, label : string) : void;
+}
+
+/**
+ * Interface for a logger instance.
+ * Each instance is typically associated with a specific category/component.
+ */
+export interface LoggerInterface
+{
+    /** Log a message at TRACE level */
+    trace(message : string, ...args : any[]) : void;
+
+    /** Log a message at DEBUG level */
+    debug(message : string, ...args : any[]) : void;
+
+    /** Log a message at INFO level */
+    info(message : string, ...args : any[]) : void;
+
+    /** Log a message at WARN level */
+    warn(message : string, ...args : any[]) : void;
+
+    /** Log a message at ERROR level */
+    error(message : string, ...args : any[]) : void;
+
+    /** Start a timer with the given label */
+    time(label : string) : void;
+
+    /** End a timer and log the elapsed time */
+    timeEnd(label : string) : void;
+}
+
+//----------------------------------------------------------------------------------------------------------------------