@skewedaspect/sage 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christopher Case
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,53 @@
+
+# SkewedAspect Game Engine (SAGE)
+
+<div align="center">
+
+![SAGE Logo](https://gitlab.com/skewed-aspect/games/sa-game-engine/-/raw/main/docs/images/sage_logo.png)
+</div>
+
+The SkewedAspect Game Engine (SAGE) is a powerful and flexible game engine designed for creating 2D and 3D games. It leverages BabylonJS for rendering and Havok for physics simulation.
+
+## Installation
+
+To install the SAGE library, use npm:
+
+```sh
+npm install @skewedaspect/sage
+```
+
+## Usage
+
+### Creating a Game Engine Instance
+
+To create an instance of the SkewedAspect Game Engine, you need to provide a game canvas and rendering options.
+
+```typescript
+import { createGameEngine, GameCanvas, RenderEngineOptions } from '@skewedaspect/sage';
+
+const canvas: GameCanvas = document.getElementById('gameCanvas') as HTMLCanvasElement;
+const renderOptions: RenderEngineOptions = {
+    // ...your rendering options...
+};
+
+const gameEngine = await createGameEngine(canvas, renderOptions);
+
+// Start the game engine
+gameEngine.start();
+```
+
+### Stopping the Game Engine
+
+To stop the game engine, simply call the `stop` method on the game engine instance.
+
+```typescript
+gameEngine.stop();
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.
+
+## License
+
+This project is licensed under the MIT License.

package/dist/classes/bindings/toggle.d.ts

@@ -0,0 +1,122 @@
+import type { GameEventBus } from '../eventBus.ts';
+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 declare class ToggleBinding implements Binding {
+    readonly type: "toggle";
+    readonly action: Action;
+    readonly context?: string;
+    readonly deviceID: string;
+    readonly reader: DeviceValueReader;
+    private readonly _invert;
+    private readonly _threshold;
+    private readonly _initialState;
+    private readonly _onValue;
+    private readonly _offValue;
+    private _lastDigitalState;
+    private _toggleState;
+    /**
+     * Get the current toggle state
+     *
+     * @returns Current toggle state (true = on, false = off)
+     */
+    get state(): boolean;
+    /**
+     * Set the toggle state directly (useful for programmatic control)
+     *
+     * @param value - New toggle state
+     */
+    set state(value: boolean);
+    /**
+     * Get the value emitted when toggle is in the "on" state
+     *
+     * @returns The value for the "on" state
+     */
+    get onValue(): boolean | number;
+    /**
+     * Get the value emitted when toggle is in the "off" state
+     *
+     * @returns The value for the "off" state
+     */
+    get offValue(): boolean | number;
+    /**
+     * Get the current value based on toggle state
+     *
+     * @returns The current value (boolean or number)
+     */
+    get value(): boolean | number;
+    /**
+     * Get the current options for this toggle binding.
+     *
+     * @returns The current options for this toggle binding
+     */
+    get options(): ToggleBindingOptions;
+    /**
+     * 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);
+    /**
+     * Process input state and emit a digital action if toggled
+     *
+     * @param state - Current input state
+     * @param eventBus - Event bus to emit action events to
+     */
+    process(state: InputState, eventBus: GameEventBus): void;
+    /**
+     * Reset toggle to its initial state
+     */
+    reset(): void;
+    /**
+     * Returns a JSON-serializable representation of this toggle binding
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    toJSON(): ToggleBindingDefinition;
+}

package/dist/classes/bindings/trigger.d.ts

@@ -0,0 +1,79 @@
+import type { GameEventBus } from '../eventBus.ts';
+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 declare const edgeModes: readonly ["rising", "falling", "both"];
+/**
+ * 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 declare class TriggerBinding implements Binding {
+    readonly type: "trigger";
+    readonly action: Action;
+    readonly context?: string;
+    readonly deviceID: string;
+    readonly reader: DeviceValueReader;
+    private readonly _edgeMode;
+    private readonly _threshold;
+    private _lastDigitalState;
+    /**
+     * Get the current options for this trigger binding.
+     *
+     * @returns The current options for this trigger binding
+     */
+    get options(): TriggerBindingOptions;
+    /**
+     * 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);
+    /**
+     * 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
+     */
+    process(state: InputState, eventBus: GameEventBus): void;
+    /**
+     * Returns a JSON-serializable representation of this trigger binding
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    toJSON(): TriggerBindingDefinition;
+}

package/dist/classes/bindings/value.d.ts

@@ -0,0 +1,104 @@
+import type { GameEventBus } from '../eventBus.ts';
+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 declare class ValueBinding implements Binding {
+    readonly type: "value";
+    readonly action: Action;
+    readonly context?: string;
+    readonly deviceID: string;
+    readonly reader: DeviceValueReader;
+    private readonly _scale;
+    private readonly _offset;
+    private readonly _invert;
+    private readonly _emitOnChange;
+    private readonly _deadzone;
+    private readonly _onValue;
+    private readonly _offValue;
+    private readonly _min;
+    private readonly _max;
+    private _lastValue;
+    /**
+     * Get the current options for this value binding.
+     *
+     * @returns The current options for this value binding
+     */
+    get options(): ValueBindingOptions;
+    /**
+     * 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);
+    /**
+     * 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
+     */
+    process(state: InputState, eventBus: GameEventBus): void;
+    /**
+     * Returns a JSON-serializable representation of this value binding
+     *
+     * @returns A simple object representation that can be converted to JSON
+     */
+    toJSON(): ValueBindingDefinition;
+}

package/dist/classes/entity.d.ts

@@ -0,0 +1,83 @@
+import type { GameEntityBehaviorConstructor } from '../interfaces/entity.ts';
+import { type GameEvent, GameEventBus } from './eventBus.ts';
+/**
+ * Interface representing the context of a game entity.
+ * @template EntityState - The type of the state object.
+ */
+interface SimpleGameEntity<EntityState extends object = object> {
+    id: string;
+    type: string;
+    state: EntityState;
+    eventBus: GameEventBus;
+}
+/**
+ * Base class for game entity behaviors.
+ */
+export declare abstract class GameEntityBehavior<RequiredState extends object = object> {
+    abstract name: string;
+    abstract eventSubscriptions: string[];
+    protected entity: SimpleGameEntity | null;
+    $emit(event: GameEvent): void;
+    /**
+     * Sets the entity for this behavior.
+     * @param entity - The entity to set.
+     */
+    $setEntity(entity: SimpleGameEntity | null): void;
+    abstract processEvent(event: GameEvent, state: RequiredState): Promise<boolean> | boolean;
+    update?(dt: number, state: RequiredState): void;
+    destroy?(): Promise<void>;
+}
+/**
+ * Base class for game entities.
+ * @template EntityState - The type of the state object.
+ */
+export declare class GameEntity<EntityState extends object = object> implements SimpleGameEntity<EntityState> {
+    /** The unique identifier of the entity. */
+    readonly id: string;
+    /** The type of the entity. */
+    readonly type: string;
+    /** The state of the entity. */
+    state: EntityState;
+    /** A map of behaviors attached to the entity. */
+    behaviors: Map<string, GameEntityBehavior>;
+    /** The event bus for the entity. */
+    eventBus: GameEventBus;
+    /** The event subscriptions for the entity. */
+    private subscriptions;
+    /**
+     * Creates an instance of GameEntityBase.
+     * @param type - The type of the entity.
+     * @param initialState - The initial state of the entity.
+     * @param behaviors - An array of behaviors to attach to the entity.
+     * @param eventBus
+     */
+    constructor(type: string, eventBus: GameEventBus, initialState: EntityState, behaviors: GameEntityBehaviorConstructor[]);
+    /**
+     * Processes a game event by passing it to the entity's behaviors.
+     * @param event - The game event to process.
+     * @returns A promise that resolves when the event has been processed.
+     */
+    $processEvent(event: GameEvent): Promise<void>;
+    /**
+     * Updates the entity by calling the update method of its behaviors.
+     * @param dt - The delta time since the last update.
+     */
+    $update(dt: number): void;
+    /**
+     * Destroys the entity by calling the destroy method of its behaviors.
+     * @returns A promise that resolves when the entity has been destroyed.
+     */
+    $destroy(): Promise<void>;
+    /**
+     * Attaches a behavior to the entity.
+     * @param behavior - The behavior to attach.
+     * @throws Will throw an error if the behavior is already attached.
+     */
+    attachBehavior(behavior: GameEntityBehavior): void;
+    /**
+     * Detaches a behavior from the entity.
+     * @param behaviorName - The behavior to detach.
+     */
+    detachBehavior(behaviorName: string): void;
+}
+export {};

package/dist/classes/eventBus.d.ts

@@ -0,0 +1,94 @@
+import { LoggingUtility } from '../utils/logger.ts';
+/**
+ * A generic game event type.
+ *
+ * @template P - The shape of the payload. Default is a generic object if omitted.
+ */
+export interface GameEvent<P extends Record<string, any> = Record<string, any>> {
+    /** The string identifier/category of the event (e.g. "input:keydown"). */
+    type: string;
+    /** The optional ID of whoever sent this event. */
+    senderID?: string;
+    /** The optional ID of who should receive this event. */
+    targetID?: string;
+    /** The payload, with user-defined shape. */
+    payload?: P;
+}
+/**
+ * A callback function that receives a {@link GameEvent} with a given payload type.
+ *
+ * @template P - The shape of the payload in the event.
+ */
+export type GameEventCallback<P extends Record<string, any> = Record<string, any>> = (event: GameEvent<P>) => void | Promise<void>;
+/**
+ * An unsubscribe function, returned by any subscribe method.
+ */
+export type Unsubscribe = () => void;
+/**
+ * A high-performance event bus that supports exact or pattern-based subscriptions,
+ * and allows subscribers to specify a more specific `payload` type for convenience.
+ *
+ * **Note**: This does NOT enforce that a given `type` always has a certain payload shape.
+ * It's a best-effort approach that lets you avoid `as` casts in callbacks.
+ */
+export declare class GameEventBus {
+    /**
+     * For exact event-type matches:
+     * - Key = event type string (e.g. "input:keydown")
+     * - Value = set of subscriptions for that exact type
+     */
+    private directMap;
+    /**
+     * For pattern-based (wildcard or RegExp) subscriptions.
+     */
+    private patternSubs;
+    /**
+     * Logger instance
+     */
+    private _log;
+    /**
+     * Creates a new GameEventBus instance
+     *
+     * @param logger - The logging utility to use
+     */
+    constructor(logger?: LoggingUtility);
+    /**
+     * Subscribe with automatic detection:
+     *   - If `eventTypeOrPattern` is a `RegExp` or a string containing `*`, treat it as a pattern subscription.
+     *   - Otherwise, treat it as an exact subscription.
+     *
+     * @template P - The payload shape you want to expect in the callback.
+     * @param {string | RegExp} eventTypeOrPattern - The exact event type or a wildcard/RegExp pattern.
+     * @param {GameEventCallback<P>} callback - A callback expecting a `GameEvent<P>`.
+     * @returns {Unsubscribe} function that, when called, removes this subscription.
+     */
+    subscribe<P extends Record<string, any> = Record<string, any>>(eventTypeOrPattern: string | RegExp, callback: GameEventCallback<P>): Unsubscribe;
+    /**
+     * Subscribes to an exact event type (e.g. "input:keydown").
+     *
+     * @template P - The payload shape you want to expect in the callback.
+     * @param {string} eventType - The exact string to match.
+     * @param {GameEventCallback<P>} callback - A callback expecting a `GameEvent<P>`.
+     * @returns {Unsubscribe} function that unsubscribes this exact subscription.
+     */
+    subscribeExact<P extends Record<string, any> = Record<string, any>>(eventType: string, callback: GameEventCallback<P>): Unsubscribe;
+    /**
+     * Subscribes with either:
+     *  - a wildcard string (contains `*`) that gets converted to a RegExp
+     *  - a RegExp directly
+     *
+     * @template P - The payload shape you want to expect in the callback.
+     * @param {string | RegExp} patternOrRegExp - The pattern to match (`"input:*"` or `/^input:/`).
+     * @param {GameEventCallback<P>} callback - A callback expecting a `GameEvent<P>`.
+     * @returns {Unsubscribe} function that unsubscribes this pattern-based subscription.
+     */
+    subscribePattern<P extends Record<string, any> = Record<string, any>>(patternOrRegExp: string | RegExp, callback: GameEventCallback<P>): Unsubscribe;
+    /**
+     * Publishes an event, invoking all matching callbacks.
+     *
+     * Callbacks are called asynchronously (microtask) via `Promise.resolve()`.
+     *
+     * @param {GameEvent<any>} event - The event object to publish.
+     */
+    publish(event: GameEvent<any>): void;
+}

package/dist/classes/gameEngine.d.ts

@@ -0,0 +1,57 @@
+import { AbstractEngine, HavokPlugin } from '@babylonjs/core';
+import { GameCanvas } from '../interfaces/game.ts';
+import { SceneEngine } from '../engines/scene.ts';
+import { BindingManager } from '../managers/binding.ts';
+import { GameManager } from '../managers/game.ts';
+import { GameEntityManager } from '../managers/entity.ts';
+import { UserInputManager } from '../managers/input.ts';
+import { GameEventBus } from './eventBus.ts';
+import { LoggingUtility } from '../utils/logger.ts';
+/**
+ * Interface representing the engines used in the game.
+ */
+interface Engines {
+    sceneEngine: SceneEngine;
+}
+/**
+ * Interface representing the managers used in the game.
+ */
+interface Managers {
+    bindingManager: BindingManager;
+    gameManager: GameManager;
+    entityManager: GameEntityManager;
+    inputManager: UserInputManager;
+}
+/**
+ * Class representing the SkewedAspect Game Engine.
+ */
+export declare class SkewedAspectGameEngine {
+    canvas: GameCanvas;
+    renderEngine: AbstractEngine;
+    physics: HavokPlugin;
+    managers: Managers;
+    engines: Engines;
+    eventBus: GameEventBus;
+    logger: LoggingUtility;
+    private _log;
+    /**
+     * Creates an instance of SkewedAspectGameEngine.
+     * @param canvas - The game canvas.
+     * @param renderEngine - The rendering engine.
+     * @param physics - The physics engine.
+     * @param eventBus - The event bus.
+     * @param logger - The logging utility.
+     * @param engines - The engines used in the game.
+     * @param managers - The managers used in the game.
+     */
+    constructor(canvas: GameCanvas, renderEngine: AbstractEngine, physics: HavokPlugin, eventBus: GameEventBus, logger: LoggingUtility, engines: Engines, managers: Managers);
+    /**
+     * Starts the game engine.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the game engine.
+     */
+    stop(): Promise<void>;
+}
+export {};