@skewedaspect/sage 0.3.0

package/src/managers/level.ts

@@ -0,0 +1,261 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Level Manager
+//----------------------------------------------------------------------------------------------------------------------
+
+import {
+    AbstractMesh,
+    AssetContainer,
+    Engine,
+    ISceneLoaderProgressEvent,
+    LoadAssetContainerAsync,
+    LoadSceneAsync,
+    Scene,
+    Sound,
+    Tags,
+} from '@babylonjs/core';
+import '@babylonjs/loaders'; // Ensure loaders (glTF, .babylon, etc.) are available
+
+// Managers
+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 class LevelManager
+{
+    private engine : Engine;
+    private currentScene : Scene | null = null;
+    private activeContainer : AssetContainer | null = null;
+    private entityManager : GameEntityManager;
+
+    constructor(engine : Engine, entityManager : GameEntityManager)
+    {
+        this.engine = engine;
+        this.entityManager = entityManager;
+    }
+
+    /**
+     * Loads a level, either as a full scene or into a container.
+     * @param options - Specifies rootUrl, filename, and optional callbacks.
+     */
+    public async loadLevel(options : LevelLoadOptions) : Promise<void>
+    {
+        if(options.showLoadingUI)
+        {
+            this.engine.displayLoadingUI();
+        }
+
+        try
+        {
+            if(options.useAssetContainer)
+            {
+                // Load into AssetContainer (additive style)
+                const tempScene = this.currentScene ?? new Scene(this.engine);
+                const container = await LoadAssetContainerAsync(
+                    options.filename,
+                    tempScene,
+                    {
+                        rootUrl: options.rootUrl,
+                        onProgress: (evt) => this.reportProgress(evt, options.onProgress),
+                    }
+                );
+
+                this.activeContainer = container;
+                container.addAllToScene();
+
+                // Identify the final scene in use after adding to scene
+                // (meshes[0]?.getScene() ensures we get the correct scene reference)
+                const usedScene = container.meshes.length > 0
+                    ? container.meshes[0].getScene()
+                    : tempScene;
+
+                this.autoTagAndEntityHook(container.meshes, usedScene);
+
+                if(options.onSuccess && this.currentScene)
+                {
+                    options.onSuccess(this.currentScene);
+                }
+            }
+            else
+            {
+                // Load as a new Scene (full replacement)
+                const scene = await LoadSceneAsync(
+                    options.filename,
+                    this.engine,
+                    {
+                        rootUrl: options.rootUrl,
+                        onProgress: (evt) => this.reportProgress(evt, options.onProgress),
+                    }
+                );
+
+                // Dispose any previous scene
+                this.disposeCurrentScene();
+
+                this.currentScene = scene;
+                // Now that we've loaded a fresh scene, do tagging & entity creation
+                this.autoTagAndEntityHook(scene.meshes, scene);
+
+                if(options.onSuccess)
+                {
+                    options.onSuccess(scene);
+                }
+            }
+        }
+        catch (error : any)
+        {
+            console.error('Level load failed:', error);
+            if(options.onError)
+            {
+                options.onError('Level loading failed.', error);
+            }
+        }
+        finally
+        {
+            if(options.showLoadingUI)
+            {
+                this.engine.hideLoadingUI();
+            }
+        }
+    }
+
+    /**
+     * Disposes the current scene and container (if any), freeing up memory.
+     */
+    public disposeCurrentScene() : void
+    {
+        if(this.activeContainer)
+        {
+            this.activeContainer.removeAllFromScene();
+            this.activeContainer.dispose();
+            this.activeContainer = null;
+        }
+
+        if(this.currentScene)
+        {
+            this.currentScene.dispose();
+            this.currentScene = null;
+        }
+    }
+
+    /**
+     * Returns the current active scene, if one is loaded.
+     */
+    public getScene() : Scene | null
+    {
+        return this.currentScene;
+    }
+
+    /**
+     * Internal helper: Reports loading progress as a percentage.
+     * @param evt ISceneLoaderProgressEvent data
+     * @param callback optional progress callback
+     */
+    private reportProgress(evt : ISceneLoaderProgressEvent, callback ?: (percent : number) => void) : void
+    {
+        if(!callback) { return; }
+
+        if(evt.lengthComputable && evt.total > 0)
+        {
+            const percent = (evt.loaded / evt.total) * 100;
+            callback(percent);
+        }
+        else
+        {
+            // If total size is unknown, just guess an arbitrary in-progress value
+            callback(50);
+        }
+    }
+
+    /**
+     * 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(meshes : AbstractMesh[], scene : Scene) : void
+    {
+        for(const mesh of meshes)
+        {
+            // Auto-tag common patterns by name
+            if(mesh.name)
+            {
+                if(mesh.name.startsWith('Door'))
+                {
+                    Tags.AddTagsTo(mesh, 'Door');
+                }
+                if(mesh.name.startsWith('Trigger'))
+                {
+                    Tags.AddTagsTo(mesh, 'Trigger');
+                }
+                if(mesh.name.startsWith('Enemy'))
+                {
+                    Tags.AddTagsTo(mesh, 'EnemySpawn');
+                }
+                if(mesh.name.startsWith('SND_'))
+                {
+                    Tags.AddTagsTo(mesh, 'AudioSource');
+                }
+            }
+
+            // Ensure mesh.metadata exists
+            const metadata = mesh.metadata ?? (mesh.metadata = {});
+
+            // 1) Check for entityType (from .babylon or glTF extras)
+            const entityType = metadata.entityType || metadata?.gltf?.extras?.entityType;
+            if(entityType)
+            {
+                this.entityManager.createEntity(entityType, {
+                    mesh,
+                    position: mesh.position.clone(),
+                    rotation: mesh.rotation.clone(),
+                    metadata,
+                });
+            }
+
+            // 2) Check for audio data: e.g. { soundFile: "AmbienceHum.wav", loop: true, autoplay: true }
+            // We also check if glTF extras has audio info.
+            const soundFile = metadata.soundFile ?? metadata?.gltf?.extras?.soundFile;
+            if(soundFile)
+            {
+                // Mark it as an audio source if not already
+                Tags.AddTagsTo(mesh, 'AudioSource');
+
+                // We'll read optional loop/autoplay from metadata too
+                const loop = metadata.loop ?? metadata?.gltf?.extras?.loop ?? false;
+                const autoplay = metadata.autoplay ?? metadata?.gltf?.extras?.autoplay ?? false;
+                const volume = metadata.volume ?? metadata?.gltf?.extras?.volume ?? 1.0;
+
+                const newSound = new Sound(`${ mesh.name }_sound`, soundFile, scene, null, {
+                    loop: !!loop,
+                    autoplay: !!autoplay,
+                    spatialSound: true,
+                    volume,
+                });
+
+                // If the mesh has a position, set the sound's 3D location
+                // (Note: if it's an empty or node, mesh.position will define the center)
+                newSound.setPosition(mesh.position);
+            }
+        }
+    }
+}

package/src/sage.ts

@@ -0,0 +1,119 @@
+//----------------------------------------------------------------------------------------------------------------------
+// SkewedAspect Game Engine
+//----------------------------------------------------------------------------------------------------------------------
+
+// Interfaces
+import { GameCanvas, RenderEngineOptions, SageOptions } from './interfaces/game.ts';
+
+// Base Classes
+import { SkewedAspectGameEngine } from './classes/gameEngine.ts';
+import { GameEventBus } from './classes/eventBus.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 { createEngine } from './utils/graphics.ts';
+import { createPhysics } from './utils/physics.ts';
+import { LoggingUtility } from './utils/logger.ts';
+import { VERSION } from './utils/version.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 async function createGameEngine(
+    canvas : GameCanvas,
+    options : SageOptions = {}
+) : Promise<SkewedAspectGameEngine>
+{
+    // Initialize logging
+    const logger = new LoggingUtility(options.logLevel || 'debug');
+    const engineLogger = logger.getLogger('SAGE');
+
+    engineLogger.info(`Initializing SAGE Game Engine v${ VERSION }...`);
+
+    // Initialize BabylonJS stuff
+    engineLogger.debug('Creating rendering engine...');
+    const engine = await createEngine(canvas, options.renderOptions || {});
+
+    engineLogger.debug('Creating physics engine...');
+    const physics = await createPhysics();
+
+    // Initialize internals
+    engineLogger.debug('Creating event bus...');
+    const eventBus = new GameEventBus(logger);
+
+    // Initialize SAGE Engines
+    engineLogger.debug('Creating scene engine...');
+    const sceneEngine = new SceneEngine(engine, physics, logger);
+
+    // Initialize SAGE Managers
+    engineLogger.debug('Creating managers...');
+    const inputManager = new UserInputManager(eventBus, canvas as HTMLElement, logger);
+    const bindingManager = new BindingManager(eventBus, logger);
+    const entityManager = new GameEntityManager(eventBus, logger, bindingManager);
+    const gameManager = new GameManager(engine, sceneEngine, entityManager, inputManager, logger);
+
+    engineLogger.info(`SAGE Game Engine v${ VERSION } initialized successfully.`);
+
+    // Register default input bindings
+    engineLogger.debug('Registering default input bindings...');
+    if(options.bindings)
+    {
+        for(const binding of options.bindings)
+        {
+            bindingManager.registerBinding(binding);
+        }
+    }
+
+    return new SkewedAspectGameEngine(
+        canvas,
+        engine,
+        physics,
+        eventBus,
+        logger,
+
+        // Engines
+        {
+            sceneEngine,
+        },
+
+        // Managers
+        {
+            bindingManager,
+            entityManager,
+            gameManager,
+            inputManager,
+        }
+    );
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Exports
+//----------------------------------------------------------------------------------------------------------------------
+
+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 base classes
+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';
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/types/global.d.ts

@@ -0,0 +1,11 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Global type declarations for the SAGE engine
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Global application version injected by Vite during build.
+ * This is read from package.json.
+ */
+declare const __APP_VERSION__ : string;
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/utils/capabilities.ts

@@ -0,0 +1,16 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Utilities to test for capability of the current environment
+//----------------------------------------------------------------------------------------------------------------------
+
+export function isBrowser() : boolean
+{
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+
+export function hasWebGPU() : boolean
+{
+    return isBrowser()
+        && !!window.navigator.gpu;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/utils/graphics.ts

@@ -0,0 +1,148 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Graphics Utility
+//----------------------------------------------------------------------------------------------------------------------
+
+import {
+    AbstractEngine,
+    Engine,
+    type EngineOptions,
+    NullEngine,
+    type NullEngineOptions,
+    WebGPUEngine,
+    type WebGPUEngineOptions,
+} from '@babylonjs/core';
+
+// Interfaces
+import type { BabylonEngineOptions, GameCanvas, RenderEngineOptions } from '../interfaces/game.ts';
+
+// Utilities
+import { hasWebGPU } from './capabilities.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Builds and initializes a WebGPU engine.
+ *
+ * @param canvas - The canvas element to render on (HTMLCanvasElement or OffscreenCanvas)
+ * @param options - Options specific to the WebGPU engine
+ * @returns A promise that resolves to an initialized WebGPUEngine
+ */
+async function _buildWebGPUEngine(
+    canvas : HTMLCanvasElement | OffscreenCanvas,
+    options : WebGPUEngineOptions
+) : Promise<WebGPUEngine>
+{
+    const engine = new WebGPUEngine(canvas, options);
+    await engine.initAsync();
+    return engine;
+}
+
+/**
+ * Builds a WebGL engine.
+ *
+ * @param canvas - The canvas element to render on (GameCanvas)
+ * @param options - Options for configuring the engine
+ * @returns An initialized WebGL Engine
+ */
+function _buildWebGLEngine(canvas : GameCanvas, options : BabylonEngineOptions) : Engine
+{
+    return new Engine(canvas, options.antialias, options.options, options.adaptToDeviceRatio);
+}
+
+/**
+ * Builds a Null engine, which is used when no rendering is required.
+ *
+ * @param options - Options specific to the Null engine
+ * @returns An initialized Null Engine
+ */
+function _buildNullEngine(options : NullEngineOptions) : NullEngine
+{
+    return new NullEngine(options as NullEngineOptions);
+}
+
+//------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Creates an appropriate engine based on the provided canvas and options.
+ *
+ * @param canvas - The canvas element to render on, or null for a Null engine
+ * @param options - Options for configuring the engine (EngineOptions, WebGPUEngineOptions, or NullEngineOptions)
+ * @returns A promise that resolves to an initialized AbstractEngine
+ */
+export async function createEngine(
+    canvas : GameCanvas | null,
+    options : RenderEngineOptions
+) : Promise<AbstractEngine>
+{
+    // Check if we should use a null engine (no canvas provided)
+    if(canvas === null)
+    {
+        console.debug('Using Null Engine');
+        return _buildNullEngine(options as NullEngineOptions);
+    }
+
+    // Extract the forceEngine option if available
+    const forceEngine = options.forceEngine || 'auto';
+
+    // Force WebGPU engine if specified and available
+    if(forceEngine === 'webgpu')
+    {
+        if(hasWebGPU())
+        {
+            try
+            {
+                console.debug('Using forced WebGPU engine');
+                return await _buildWebGPUEngine(canvas, options);
+            }
+            catch (error)
+            {
+                console.error('Forced WebGPU initialization failed:', error);
+                throw new Error(
+                    'Forced WebGPU failed to initialize. If WebGPU is required, check browser compatibility.'
+                );
+            }
+        }
+        else
+        {
+            throw new Error('WebGPU was forced but is not available in this browser.');
+        }
+    }
+
+    // Force WebGL engine if specified
+    if(forceEngine === 'webgl')
+    {
+        console.debug('Using forced WebGL engine');
+        return _buildWebGLEngine(canvas, options as BabylonEngineOptions);
+    }
+
+    // Auto detection (default behavior)
+    if(hasWebGPU())
+    {
+        try
+        {
+            console.debug('Using WebGPU');
+
+            return _buildWebGPUEngine(canvas, options)
+                .catch((error) =>
+                {
+                    console.warn('WebGPU initialization failed, falling back to WebGL:', error);
+                    return _buildWebGLEngine(canvas, options as EngineOptions);
+                });
+        }
+        catch (error)
+        {
+            console.warn('WebGPU initialization failed, falling back to WebGL:', error);
+        }
+    }
+    else
+    {
+        console.warn('WebGPU not supported, falling back to WebGL.');
+    }
+
+    console.debug('Using WebGL');
+
+    return _buildWebGLEngine(canvas, options as EngineOptions);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+