@skewedaspect/sage 0.3.0

package/src/classes/entity.ts

@@ -0,0 +1,256 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Game Entity
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { GameEntityBehaviorConstructor } from '../interfaces/entity.ts';
+import { type GameEvent, GameEventBus } from './eventBus.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Interface representing a subscription to a game event.
+ */
+interface GameEventSubscription
+{
+    count : number;
+    unsubscribe : () => void;
+}
+
+/**
+ * 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 abstract class GameEntityBehavior<RequiredState extends object = object>
+{
+    abstract name : string;
+    abstract eventSubscriptions : string[];
+
+    protected entity : SimpleGameEntity | null = null;
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Internal API
+    //------------------------------------------------------------------------------------------------------------------
+
+    $emit(event : GameEvent) : void
+    {
+        if(!this.entity)
+        {
+            throw new Error('Entity is not set for this behavior.');
+        }
+
+        event.senderID = this.entity.id;
+        this.entity.eventBus.publish(event);
+    }
+
+    /**
+     * Sets the entity for this behavior.
+     * @param entity - The entity to set.
+     */
+    $setEntity(entity : SimpleGameEntity | null) : void
+    {
+        this.entity = entity;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Implementation API
+    //------------------------------------------------------------------------------------------------------------------
+
+    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 class GameEntity<EntityState extends object = object> implements SimpleGameEntity<EntityState>
+{
+    /** The unique identifier of the entity. */
+    public readonly id : string;
+
+    /** The type of the entity. */
+    public readonly type : string;
+
+    /** The state of the entity. */
+    public state : EntityState;
+
+    /** A map of behaviors attached to the entity. */
+    public behaviors : Map<string, GameEntityBehavior> = new Map<string, GameEntityBehavior>();
+
+    /** The event bus for the entity. */
+    public eventBus : GameEventBus;
+
+    /** The event subscriptions for the entity. */
+    private subscriptions : Map<string, GameEventSubscription> = new Map<string, GameEventSubscription>();
+
+    /**
+     * 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[]
+    )
+    {
+        this.id = crypto.randomUUID();
+        this.type = type;
+        this.state = initialState;
+        this.eventBus = eventBus;
+
+        // Attach behaviors
+        for(const behaviorCtor of behaviors)
+        {
+            this.attachBehavior(new behaviorCtor());
+        }
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Internal Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * 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.
+     */
+    async $processEvent(event : GameEvent) : Promise<void>
+    {
+        for(const behavior of this.behaviors.values())
+        {
+            // eslint-disable-next-line no-await-in-loop
+            const result = await behavior.processEvent(event, this.state);
+            if(result)
+            {
+                // If the behavior returns true, stop other behaviors from processing the event.
+                break;
+            }
+        }
+    }
+
+    /**
+     * Updates the entity by calling the update method of its behaviors.
+     * @param dt - The delta time since the last update.
+     */
+    $update(dt : number) : void
+    {
+        for(const behavior of this.behaviors.values())
+        {
+            behavior.update?.(dt, this.state);
+        }
+    }
+
+    /**
+     * Destroys the entity by calling the destroy method of its behaviors.
+     * @returns A promise that resolves when the entity has been destroyed.
+     */
+    async $destroy() : Promise<void>
+    {
+        for(const behavior of this.behaviors.values())
+        {
+            behavior.destroy?.();
+        }
+
+        // Unsubscribe from all event subscriptions
+        for(const subscription of this.subscriptions.values())
+        {
+            subscription.unsubscribe();
+        }
+
+        this.behaviors.clear();
+        this.subscriptions.clear();
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * 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
+    {
+        if(this.behaviors.has(behavior.name))
+        {
+            throw new Error(`Behavior ${ behavior.name } is already attached to this entity.`);
+        }
+
+        // Subscribe to the behavior's event subscriptions
+        for(const event of behavior.eventSubscriptions)
+        {
+            // Check if the event is already subscribed
+            const existingSubscription = this.subscriptions.get(event);
+            if(existingSubscription)
+            {
+                existingSubscription.count++;
+            }
+            else
+            {
+                // Create a new subscription
+                const unsubscribe = this.eventBus.subscribe(event, this.$processEvent.bind(this));
+                this.subscriptions.set(event, { count: 1, unsubscribe });
+            }
+        }
+
+        // Attach the behavior
+        this.behaviors.set(behavior.name, behavior);
+        behavior.$setEntity(this);
+    }
+
+    /**
+     * Detaches a behavior from the entity.
+     * @param behaviorName - The behavior to detach.
+     */
+    detachBehavior(behaviorName : string) : void
+    {
+        const behavior = this.behaviors.get(behaviorName);
+        if(behavior)
+        {
+            // Remove the behavior's event subscriptions
+            for(const event of behavior.eventSubscriptions)
+            {
+                const subscription = this.subscriptions.get(event);
+                if(subscription)
+                {
+                    subscription.count--;
+                    if(subscription.count <= 0)
+                    {
+                        subscription.unsubscribe();
+                        this.subscriptions.delete(event);
+                    }
+                }
+            }
+
+            // Remove the behavior
+            this.behaviors.delete(behavior.name);
+            behavior.$setEntity(null);
+        }
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+

package/src/classes/eventBus.ts

@@ -0,0 +1,259 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Event Bus
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { LoggerInterface } from '../interfaces/logger.ts';
+import { LoggingUtility, SAGELogger } 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>;
+
+/**
+ * Represents a subscription record internally within the EventBus.
+ *
+ * We store the callback as if it handles `GameEvent<any>`
+ * because we can’t unify multiple different payload types in the same structure.
+ */
+interface Subscription
+{
+    /** Precompiled RegExp if this subscription is pattern-based. */
+    pattern ?: RegExp;
+    /** The callback, but stored to accept any payload type (due to the union nature). */
+    callback : (event : GameEvent<any>) => 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 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 = new Map<string, Set<Subscription>>();
+
+    /**
+     * For pattern-based (wildcard or RegExp) subscriptions.
+     */
+    private patternSubs = new Set<Subscription>();
+
+    /**
+     * Logger instance
+     */
+    private _log : LoggerInterface;
+
+    /**
+     * Creates a new GameEventBus instance
+     *
+     * @param logger - The logging utility to use
+     */
+    constructor(logger ?: LoggingUtility)
+    {
+        this._log = logger?.getLogger('EventBus') || new SAGELogger('EventBus');
+    }
+
+    /**
+     * 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.
+     */
+    public subscribe<P extends Record<string, any> = Record<string, any>>(
+        eventTypeOrPattern : string | RegExp,
+        callback : GameEventCallback<P>
+    ) : Unsubscribe
+    {
+        this._log.trace(`Subscribe request for: ${ eventTypeOrPattern.toString() }`);
+
+        // If it's explicitly a RegExp or includes '*', treat as pattern:
+        if(
+            eventTypeOrPattern instanceof RegExp
+            || (typeof eventTypeOrPattern === 'string' && eventTypeOrPattern.includes('*'))
+        )
+        {
+            return this.subscribePattern(eventTypeOrPattern, callback);
+        }
+        else
+        {
+            return this.subscribeExact(eventTypeOrPattern, callback);
+        }
+    }
+
+    /**
+     * 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.
+     */
+    public subscribeExact<P extends Record<string, any> = Record<string, any>>(
+        eventType : string,
+        callback : GameEventCallback<P>
+    ) : Unsubscribe
+    {
+        this._log.debug(`Adding exact subscription for: ${ eventType }`);
+
+        let subs = this.directMap.get(eventType);
+        if(!subs)
+        {
+            subs = new Set();
+            this.directMap.set(eventType, subs);
+        }
+
+        // Store as a Subscription that accepts `GameEvent<any>`
+        const subscription : Subscription = {
+            callback: (event) => callback(event as GameEvent<P>), // runtime "type-lie" cast
+        };
+        subs.add(subscription);
+
+        return () =>
+        {
+            this._log.debug(`Removing exact subscription for: ${ eventType }`);
+            subs.delete(subscription);
+            if(subs.size === 0)
+            {
+                this.directMap.delete(eventType);
+            }
+        };
+    }
+
+    /**
+     * 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.
+     */
+    public subscribePattern<P extends Record<string, any> = Record<string, any>>(
+        patternOrRegExp : string | RegExp,
+        callback : GameEventCallback<P>
+    ) : Unsubscribe
+    {
+        let regex : RegExp;
+
+        if(typeof patternOrRegExp === 'string')
+        {
+            // MAIN BUG FIX:
+            // We replace '*' with '.*' (not '\*' or '\\*').
+            // The prior code was .replace('\\*', '.*'), which never matched 'input:*'
+            const escaped = patternOrRegExp
+                .replace(/[-/\\^$+?.()|[\]{}]/g, '\\$&') // escape special chars
+                .replace(/\*/g, '.*'); // replace '*' with '.*'
+
+            // e.g. "input:*" => "input:.*" => new RegExp("^input:.*$")
+            regex = new RegExp(`^${ escaped }$`);
+            this._log.debug(
+                `Adding pattern subscription for string: ${ patternOrRegExp }, regex: ${ regex.toString() }`
+            );
+        }
+        else
+        {
+            // If already a RegExp, use as-is
+            regex = patternOrRegExp;
+            this._log.debug(`Adding pattern subscription for regex: ${ regex.toString() }`);
+        }
+
+        const subscription : Subscription = {
+            pattern: regex,
+            callback: (event) => callback(event as GameEvent<P>),
+        };
+        this.patternSubs.add(subscription);
+
+        return () =>
+        {
+            this._log.debug(`Removing pattern subscription: ${ regex.toString() }`);
+            this.patternSubs.delete(subscription);
+        };
+    }
+
+    /**
+     * Publishes an event, invoking all matching callbacks.
+     *
+     * Callbacks are called asynchronously (microtask) via `Promise.resolve()`.
+     *
+     * @param {GameEvent<any>} event - The event object to publish.
+     */
+    public publish(event : GameEvent<any>) : void
+    {
+        this._log.trace(`Publishing event: ${ event.type }`, event);
+
+        let callbackCount = 0;
+
+        // 1) Exact match
+        const directSubs = this.directMap.get(event.type);
+        if(directSubs)
+        {
+            callbackCount += directSubs.size;
+            for(const sub of directSubs)
+            {
+                Promise.resolve().then(() => sub.callback(event));
+            }
+        }
+
+        // 2) Pattern subscriptions
+        for(const sub of this.patternSubs)
+        {
+            if(sub.pattern && sub.pattern.test(event.type))
+            {
+                callbackCount++;
+                Promise.resolve().then(() => sub.callback(event));
+            }
+        }
+
+        if(callbackCount === 0)
+        {
+            this._log.debug(`No subscribers found for event: ${ event.type }`);
+        }
+        else
+        {
+            this._log.trace(`Event ${ event.type } dispatched to ${ callbackCount } subscribers`);
+        }
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/classes/gameEngine.ts

@@ -0,0 +1,125 @@
+//------------------------------------------------------------------------------------------------------------------
+// SkewedAspect Game Engine
+//------------------------------------------------------------------------------------------------------------------
+
+import { AbstractEngine, HavokPlugin } from '@babylonjs/core';
+
+// Interfaces
+import { GameCanvas } from '../interfaces/game.ts';
+import { LoggerInterface } from '../interfaces/logger.ts';
+
+// Engines
+import { SceneEngine } from '../engines/scene.ts';
+
+// Managers
+import { BindingManager } from '../managers/binding.ts';
+import { GameManager } from '../managers/game.ts';
+import { GameEntityManager } from '../managers/entity.ts';
+import { UserInputManager } from '../managers/input.ts';
+
+// Utils
+import { GameEventBus } from './eventBus.ts';
+import { LoggingUtility } from '../utils/logger.ts';
+import { VERSION } from '../utils/version.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 class SkewedAspectGameEngine
+{
+    public canvas : GameCanvas;
+    public renderEngine : AbstractEngine;
+    public physics : HavokPlugin;
+    public managers : Managers;
+    public engines : Engines;
+    public eventBus : GameEventBus;
+    public logger : LoggingUtility;
+
+    private _log : LoggerInterface;
+
+    /**
+     * 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
+    )
+    {
+        this.canvas = canvas;
+        this.renderEngine = renderEngine;
+        this.physics = physics;
+        this.eventBus = eventBus;
+        this.logger = logger;
+        this.engines = engines;
+        this.managers = managers;
+
+        this._log = logger.getLogger('GameEngine');
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Public API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Starts the game engine.
+     */
+    async start() : Promise<void>
+    {
+        this._log.info(`Starting SkewedAspect Game Engine (Version: ${ VERSION })...`);
+
+        // Start the game manager
+        await this.managers.gameManager.start(this.canvas);
+
+        this._log.info('Game engine started successfully');
+    }
+
+    /**
+     * Stops the game engine.
+     */
+    async stop() : Promise<void>
+    {
+        this._log.info(`Stopping SkewedAspect Game Engine (Version: ${ VERSION })...`);
+
+        // Stop the game manager
+        await this.managers.gameManager.stop();
+
+        this._log.info('Game engine stopped successfully');
+    }
+}
+
+//------------------------------------------------------------------------------------------------------------------