@skewedaspect/sage 0.3.0

package/dist/interfaces/input.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Valid input device types
+ */
+export declare const validDeviceTypes: readonly ["keyboard", "mouse", "gamepad"];
+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/dist/interfaces/logger.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Defines the available logging levels as string literals.
+ */
+export declare const LogLevels: readonly ["trace", "debug", "info", "warn", "error", "none"];
+/**
+ * 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;
+}

package/dist/managers/binding.d.ts

@@ -0,0 +1,185 @@
+import { GameEventBus } from '../classes/eventBus.ts';
+import { type Binding, type BindingDefinition, type Context } from '../interfaces/binding.ts';
+import type { InputDevice, InputState } from '../interfaces/input.ts';
+import type { Action } from '../interfaces/action.ts';
+import { LoggingUtility } from '../utils/logger.ts';
+/**
+ * Configuration object structure for binding manager
+ */
+export interface BindingConfiguration {
+    /** All registered actions */
+    actions: Action[];
+    /** All registered bindings */
+    bindings: BindingDefinition[];
+    /** All registered contexts */
+    contexts: {
+        name: string;
+        exclusive: boolean;
+        active: boolean;
+    }[];
+}
+/**
+ * Manages input bindings and actions for the game
+ */
+export declare class BindingManager {
+    /** Map of device IDs to their bindings */
+    private _bindings;
+    /** Map of action names to their action definitions */
+    private _actions;
+    /** Map of all registered contexts by name for O(1) lookup */
+    private _contexts;
+    /**
+     * Set of all active contexts (both exclusive and non-exclusive)
+     */
+    private _activeContexts;
+    /** Event bus for handling game events */
+    private _eventBus;
+    /** Logger instance */
+    private _log;
+    /**
+     * Creates an instance of BindingManager.
+     *
+     * @param eventBus - The game event bus to publish events to
+     * @param logger - The logging utility to use
+     */
+    constructor(eventBus: GameEventBus, logger?: LoggingUtility);
+    /**
+     * Checks if a binding's context is currently active
+     *
+     * @param binding - The binding to check
+     * @returns True if binding's context is active or has no context
+     */
+    private _isBindingContextActive;
+    /**
+     * Get a context by name, creating it if it doesn't exist
+     *
+     * @param contextName - The name of the context to get or create
+     * @param exclusive - Whether the context is exclusive (only used if creating)
+     * @returns The context object
+     */
+    private _getOrCreateContext;
+    /**
+     * Deactivate all exclusive contexts except the specified one
+     *
+     * @param exceptContextName - Name of context to not deactivate
+     * @returns Array of deactivated context names
+     */
+    private _deactivateExclusiveContexts;
+    /**
+     * Create a binding from a binding definition
+     *
+     * @param definition - The binding definition to create a binding from
+     * @returns A new binding instance or null if the type is not supported
+     */
+    private _createBindingFromDefinition;
+    /**
+     * Create a device value reader from a definition object
+     *
+     * @param definition - The device value reader definition
+     * @returns A new device value reader instance
+     * @throws Error if the reader type is not supported
+     */
+    private _createInputSourceFromDefinition;
+    /**
+     * Handle input from a device and process all relevant bindings
+     *
+     * @param device - The input device
+     * @param state - Current input state
+     */
+    $handleInput(device: InputDevice, state: InputState): void;
+    /**
+     * Registers an action
+     *
+     * @param action - The action to register
+     * @throws Error if action is already registered
+     */
+    registerAction(action: Action): void;
+    /**
+     * Gets an action by name
+     *
+     * @param actionName - The name of the action to get
+     * @returns The action or null if not found
+     */
+    getAction(actionName: string): Action | null;
+    /**
+     * Registers a context with specific options
+     *
+     * @param contextName - The name of the context to register
+     * @param exclusive - Whether the context is exclusive (default: true)
+     * @returns The registered context
+     */
+    registerContext(contextName: string, exclusive?: boolean): Context;
+    /**
+     * Activates a context, enabling all bindings associated with it.
+     * If the context is exclusive, all other exclusive contexts will be deactivated.
+     *
+     * @param contextName - The name of the context to activate
+     */
+    activateContext(contextName: string): void;
+    /**
+     * Deactivates a context, disabling all bindings associated with it
+     *
+     * @param contextName - The name of the context to deactivate
+     */
+    deactivateContext(contextName: string): void;
+    /**
+     * Returns a list of all active contexts
+     *
+     * @returns Array of active context names
+     */
+    getActiveContexts(): string[];
+    /**
+     * Returns whether a context is active
+     *
+     * @param contextName - The context to check
+     * @returns True if the context is active
+     */
+    isContextActive(contextName: string): boolean;
+    /**
+     * Gets a context by name
+     *
+     * @param contextName - The context name to get
+     * @returns The context or null if not found
+     */
+    getContext(contextName: string): Context | null;
+    /**
+     * Register a binding for an input device
+     *
+     * @param binding - The binding to register
+     * @throws Error if binding type is invalid
+     */
+    $registerBinding(binding: Binding): void;
+    /**
+     * Register a binding using a binding definition object
+     *
+     * @param definition - The binding definition to register
+     */
+    registerBinding(definition: BindingDefinition): void;
+    /**
+     * Unregister all bindings for an action within a context
+     *
+     * @param actionName - The name of the action
+     * @param context - The context to unregister from (defaults to null)
+     */
+    unregisterBindings(actionName: string, context?: string | null): void;
+    /**
+     * Gets all bindings for a specific action
+     *
+     * @param actionName - The name of the action
+     * @param context - The context to get bindings from (optional)
+     * @returns Array of bindings that match the criteria
+     */
+    getBindingsForAction(actionName: string, context?: string | null): Binding[];
+    /**
+     * Exports the current configuration to a serializable object
+     *
+     * @returns A BindingConfiguration object representing the current state
+     */
+    exportConfiguration(): BindingConfiguration;
+    /**
+     * Imports a configuration from an object
+     *
+     * @param config - The configuration to import
+     */
+    importConfiguration(config: BindingConfiguration): void;
+}

package/dist/managers/entity.d.ts

@@ -0,0 +1,70 @@
+import { GameEntity } from '../classes/entity.ts';
+import { GameEventBus } from '../classes/eventBus.ts';
+import type { GameEntityDefinition } from '../interfaces/entity.ts';
+import type { BindingManager } from '../managers/binding.ts';
+import { LoggingUtility } from '../utils/logger.ts';
+export declare class GameEntityManager {
+    /** The event bus for the entity manager. */
+    private eventBus;
+    /** A map of entities managed by the entity manager. */
+    private entities;
+    /** A map of entity definitions registered with the entity manager. */
+    private entityDefinitions;
+    /** Reference to the binding manager for registering actions */
+    private bindingManager;
+    /** Logger instance */
+    private _log;
+    /**
+     * Creates an instance of EntityManager.
+     * @param eventBus - The event bus for the entity manager.
+     * @param logger - The logging utility to use
+     * @param bindingManager - The binding manager for registering actions
+     */
+    constructor(eventBus: GameEventBus, logger: LoggingUtility | undefined, bindingManager: BindingManager);
+    /**
+     * Checks if two actions are compatible
+     * @param existingAction - The action already registered
+     * @param newAction - The action being registered
+     * @returns true if the actions are compatible, false if they have conflicting options
+     */
+    private areActionsCompatible;
+    /**
+     * Registers actions defined in the entity definition with the binding manager
+     * @param entityDef - The entity definition containing actions to register
+     */
+    private registerEntityActions;
+    $frameUpdate(dt: number): void;
+    /**
+     * Registers a new entity definition.
+     * @param entityDef - The definition of the entity.
+     */
+    registerEntityDefinition(entityDef: GameEntityDefinition): void;
+    /**
+     * Creates a new entity of the given type.
+     * @param type - The type of the entity to create.
+     * @param initialState - The initial state of the entity.
+     * @returns The created entity.
+     */
+    createEntity<State extends object = object>(type: string, initialState?: Partial<State>): GameEntity<State>;
+    /**
+     * Destroys the entity with the given ID.
+     * @param entityID - The ID of the entity to destroy.
+     */
+    destroyEntity(entityID: string): void;
+    /**
+     * Gets the entity with the given ID.
+     * @param entityID - The ID of the entity to get.
+     * @returns The entity with the given ID, or null if it does not exist.
+     */
+    getEntity(entityID: string): GameEntity | null;
+    /**
+     * Adds an existing entity to the entity manager.
+     * @param entity - The entity to add.
+     */
+    addEntity(entity: GameEntity): void;
+    /**
+     * Removes the entity with the given ID, without destroying it.
+     * @param entityID - The ID of the entity to remove.
+     */
+    removeEntity(entityID: string): void;
+}

package/dist/managers/game.d.ts

@@ -0,0 +1,20 @@
+import { AbstractEngine } from '@babylonjs/core';
+import { GameCanvas } from '../interfaces/game.ts';
+import { GameEntityManager } from './entity.ts';
+import { UserInputManager } from './input.ts';
+import { SceneEngine } from '../engines/scene.ts';
+import { LoggingUtility } from '../utils/logger.ts';
+export declare class GameManager {
+    private _engine;
+    private _entityManager;
+    private _inputManager;
+    private _sceneEngine;
+    private _currentScene;
+    private _log;
+    started: boolean;
+    constructor(engine: AbstractEngine, sceneEngine: SceneEngine, entityManager: GameEntityManager, inputManager: UserInputManager, logger?: LoggingUtility);
+    private _renderLoop;
+    private _resizeHandler;
+    start(canvas: GameCanvas): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/managers/input.d.ts

@@ -0,0 +1,56 @@
+import type { InputDevice } from '../interfaces/input.ts';
+import { GameEventBus } from '../classes/eventBus.ts';
+import { LoggingUtility } from '../utils/logger.ts';
+/**
+ * Manager for handling user input from various devices (keyboard, mouse, gamepad)
+ */
+export declare class UserInputManager {
+    private _eventBus;
+    private _keyboardRA;
+    private _mouseRA;
+    private _gamepadRA;
+    /** Logger instance */
+    private _log;
+    /**
+     * Create a new UserInputManager
+     *
+     * @param eventBus - The game event bus to publish events to
+     * @param canvas - The DOM element to attach input listeners to
+     * @param logger - The logging utility to use
+     */
+    constructor(eventBus: GameEventBus, canvas: HTMLElement, logger?: LoggingUtility);
+    /**
+     * Publish device connected event to the event bus
+     */
+    private _publishDeviceConnected;
+    /**
+     * Publish device disconnected event to the event bus
+     */
+    private _publishDeviceDisconnected;
+    /**
+     * Publish input changed event to the event bus, used by all device types
+     */
+    private _publishInputChanged;
+    /**
+     * Destroy the input manager and clean up event listeners
+     */
+    $destroy(): void;
+    /**
+     * Get all input devices
+     *
+     * @return An array of input devices
+     */
+    listDevices(): InputDevice[];
+    /**
+     * Get a specific input device by ID
+     *
+     * @param deviceId - The ID of the device to get
+     *
+     * @return The input device, or null if not found
+     */
+    getDevice(deviceId: string): InputDevice | null;
+    /**
+     * Poll for gamepad state updates - call this in your game loop
+     */
+    pollGamepads(): void;
+}

package/dist/managers/level.d.ts

@@ -0,0 +1,55 @@
+import { Engine, Scene } from '@babylonjs/core';
+import '@babylonjs/loaders';
+import { GameEntityManager } from './entity.ts';
+export interface LevelLoadOptions {
+    rootUrl: string;
+    filename: string;
+    useAssetContainer?: boolean;
+    showLoadingUI?: boolean;
+    onProgress?: (percent: number) => void;
+    onSuccess?: (scene: Scene) => void;
+    onError?: (message: string, exception?: any) => void;
+}
+/**
+/**
+ * Manages level loading and streaming using BabylonJS SceneLoader and AssetContainer.
+ * Also includes tagging for auto-detection (e.g. "Door", "Trigger", "Enemy"),
+ * and automatically spawns entities via an entity manager if an 'entityType' is found.
+ *
+ * Additionally, this version checks for audio metadata (e.g. sound files) and automatically
+ * creates BabylonJS Sound objects when found.
+ */
+export declare class LevelManager {
+    private engine;
+    private currentScene;
+    private activeContainer;
+    private entityManager;
+    constructor(engine: Engine, entityManager: GameEntityManager);
+    /**
+     * Loads a level, either as a full scene or into a container.
+     * @param options - Specifies rootUrl, filename, and optional callbacks.
+     */
+    loadLevel(options: LevelLoadOptions): Promise<void>;
+    /**
+     * Disposes the current scene and container (if any), freeing up memory.
+     */
+    disposeCurrentScene(): void;
+    /**
+     * Returns the current active scene, if one is loaded.
+     */
+    getScene(): Scene | null;
+    /**
+     * Internal helper: Reports loading progress as a percentage.
+     * @param evt ISceneLoaderProgressEvent data
+     * @param callback optional progress callback
+     */
+    private reportProgress;
+    /**
+     * Automatically tag loaded meshes and create entities based on metadata.
+     * Also, if audio metadata is present, create spatial sounds.
+     *
+     * @param meshes An array of loaded AbstractMesh objects.
+     * @param scene The scene into which these meshes have been loaded.
+     */
+    private autoTagAndEntityHook;
+}

package/dist/sage.d.ts

@@ -0,0 +1,20 @@
+import { GameCanvas, RenderEngineOptions, SageOptions } from './interfaces/game.ts';
+import { SkewedAspectGameEngine } from './classes/gameEngine.ts';
+import { GameEventBus } from './classes/eventBus.ts';
+/**
+ * Creates an instance of SkewedAspectGameEngine.
+ * @param canvas - The game canvas.
+ * @param options - The game engine options including rendering options and log level.
+ * @returns A promise that resolves to an instance of SkewedAspectGameEngine.
+ */
+export declare function createGameEngine(canvas: GameCanvas, options?: SageOptions): Promise<SkewedAspectGameEngine>;
+export type { GameCanvas, RenderEngineOptions, SageOptions };
+export type { GameEvent, GameEventCallback } from './classes/eventBus.ts';
+export type { Action, AnalogAction, DigitalAction } from './interfaces/action.ts';
+export type { GameEntityDefinition, GameEntityBehaviorConstructor } from './interfaces/entity.ts';
+export type { LogLevel, LoggerInterface } from './interfaces/logger.ts';
+export { GameEventBus, SkewedAspectGameEngine };
+export { GameEntity } from './classes/entity.ts';
+export { LoggingUtility, ConsoleBackend, NullBackend } from './utils/logger.ts';
+export { GameEntityBehavior } from './classes/entity.ts';
+export { VERSION } from './utils/version.ts';