@skewedaspect/sage 0.10.0-beta.2 → 0.10.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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,11 @@
+# @skewedaspect/sage
+
+The Babylon.js game engine: `NodeEntity` and `NodeSimulation` on top of `@skewedaspect/sage-core`'s entity
+system, levels and their scenes, physics through Havok, the input system, audio, pooling, the parent-child
+hierarchy, debug tooling, and the save manager.
+
+```
+npm install @skewedaspect/sage @babylonjs/core @babylonjs/havok @babylonjs/loaders
+```
+
+Documentation: the site built from `site/docs` in https://gitlab.com/skewed-aspect/sage/sage

package/dist/behaviors/characterController.d.ts

@@ -0,0 +1,58 @@
+import { Vector3, CharacterSurfaceInfo } from '@babylonjs/core';
+import { Behavior } from '@skewedaspect/sage-core';
+import { NodeBehaviorHooks, NodeEntity, Vector3State } from "../entities/nodeEntity.js";
+/** A capsule height and a speed under a name (design/character.md#stances). */
+export interface StanceConfig {
+    height: number;
+    radius: number;
+    /** Metres per second. */
+    speed: number;
+}
+export interface CharacterControllerState {
+    /** How hard a game is asking to move right, -1 to 1. */
+    moveX: number;
+    /** How hard a game is asking to move forward, -1 to 1. */
+    moveZ: number;
+    wantsJump: boolean;
+    wantsSprint: boolean;
+    /** The stance a game is asking for, by name. */
+    wantsStance: string;
+    stances: Record<string, StanceConfig>;
+    /** Take the tallest stance's capsule from the mesh instead. */
+    measureCapsule: boolean;
+    /** What sprinting multiplies the current stance's speed by. */
+    sprintScale: number;
+    /** Upward metres per second a jump starts with. */
+    jumpSpeed: number;
+    /** How long a jump request survives, in fixed steps. */
+    jumpBufferSteps: number;
+    /** How long after leaving the ground a jump is still allowed, in fixed steps. */
+    coyoteSteps: number;
+    /** Metres per second. */
+    velocity: Vector3State;
+    /** The character's foot, not the middle of its capsule (design/character.md#state). */
+    position: Vector3State;
+    /** True only when the last step's support query answered `SUPPORTED`. */
+    grounded: boolean;
+    /** The stance the character is actually in, which names an entry in `stances`. */
+    stance: string;
+}
+export declare class CharacterControllerBehavior extends Behavior<CharacterControllerState, object, NodeEntity> implements NodeBehaviorHooks {
+    #private;
+    readonly defaults: CharacterControllerState;
+    onCreate(): void;
+    onMeshLoaded(): void;
+    onUpdate(duration: number): void;
+    onDestroy(): void;
+    /**
+     * The velocity the character wants this step, in world space, before the surface it is standing on is added
+     * (design/character.md#what-a-game-overrides). The jump is not this method's: an override answers for
+     * intent, and the behavior takes the jump around it.
+     */
+    protected desiredVelocity(duration: number, surface: CharacterSurfaceInfo): Vector3;
+    /**
+     * Whether that stance's capsule fits where the character is standing
+     * (design/character.md#what-a-game-overrides).
+     */
+    protected stanceFits(stance: string): boolean;
+}

package/dist/behaviors/physicsBody.d.ts

@@ -0,0 +1,38 @@
+import { Behavior } from '@skewedaspect/sage-core';
+import { NodeBehaviorHooks, NodeEntity, QuaternionState, Vector3State } from "../entities/nodeEntity.js";
+/** What a body's outline can be (design/physics.md#shapes). */
+export type BodyShape = 'box' | 'sphere' | 'cylinder' | 'convex' | 'mesh' | 'compound';
+/** Who decides where a body goes (design/physics.md#static-dynamic-and-kinematic). */
+export type BodyMotion = 'static' | 'dynamic' | 'kinematic';
+/** One child of a compound shape, placed relative to the entity's node. */
+export interface CompoundPart {
+    shape: 'box' | 'sphere' | 'cylinder';
+    position: Vector3State;
+    rotation: QuaternionState;
+    /** Full size: a box's width, height, depth; a sphere's diameter in x; a cylinder's diameter in x, height in y. */
+    extents: Vector3State;
+}
+export interface PhysicsBodyState {
+    shape: BodyShape;
+    /** The children of a `compound` shape. Unused by every other shape. */
+    parts: CompoundPart[];
+    motion: BodyMotion;
+    /** In kilograms. */
+    mass: number;
+    friction: number;
+    restitution: number;
+    position: Vector3State;
+    rotation: QuaternionState;
+    /** Metres per second. */
+    velocity: Vector3State;
+    /** Radians per second. */
+    angularVelocity: Vector3State;
+}
+export declare class HavokPhysicsBodyBehavior extends Behavior<PhysicsBodyState, object, NodeEntity> implements NodeBehaviorHooks {
+    #private;
+    static readonly ops: readonly ["applyImpulse"];
+    readonly defaults: PhysicsBodyState;
+    onMeshLoaded(): void;
+    onDestroy(): void;
+    applyImpulse(impulse: Vector3State, location?: Vector3State): void;
+}

package/dist/behaviors/sound.d.ts

@@ -1,5 +1,5 @@
 import { Behavior } from '@skewedaspect/sage-core';
-import { NodeBehaviorHooks } from "../entities/nodeEntity.d.ts";
+import { NodeBehaviorHooks, NodeEntity } from "../entities/nodeEntity.js";
 export interface SoundConfig {
     url: string;
     volume?: number;
@@ -11,7 +11,7 @@ export interface SoundConfig {
 export interface SoundState {
     sounds: Record<string, SoundConfig>;
 }
-export declare class SoundBehavior extends Behavior<SoundState> implements NodeBehaviorHooks {
+export declare class SoundBehavior extends Behavior<SoundState, object, NodeEntity> implements NodeBehaviorHooks {
     #private;
     static readonly ops: readonly ["play", "stop"];
     readonly defaults: SoundState;

package/dist/classes/debugConsole.d.ts

@@ -1,23 +1,15 @@
-import { Disposable } from "../interfaces/lifecycle.d.ts";
-interface DynamicGetter {
+/** What `expose` takes to define a property that resolves fresh on every read. */
+export interface DynamicGetter {
     get: () => unknown;
 }
-export declare class DebugConsole implements Disposable {
-    private _namespaceName;
-    private _entries;
-    private _disposed;
+export declare class DebugConsole {
+    #private;
     constructor(namespaceName?: string);
-    expose(name: string, value: unknown | DynamicGetter): void;
+    /** Defines a property that resolves fresh on every read (design/debugging.md#debug-tooling). */
+    expose(name: string, getter: DynamicGetter): void;
+    /** Puts a value, a callable command included, on the namespace (design/debugging.md#debug-tooling). */
+    expose(name: string, value: unknown): void;
     setNamespace(name: string): void;
     get namespaceName(): string;
     dispose(): void;
-    $teardown(): Promise<void>;
-    private _isDynamicGetter;
-    private _getNamespace;
-    private _assertNamespaceFree;
-    private _installNamespace;
-    private _removeNamespace;
-    private _defineGetter;
-    private _defineValue;
 }
-export {};

package/dist/classes/gameEngine.d.ts

@@ -1,33 +1,32 @@
-import { AbstractEngine, HavokPlugin, Scene } from '@babylonjs/core';
-import { EntityMeshLoader, GameCanvas } from "../interfaces/game.d.ts";
-import { Disposable } from "../interfaces/lifecycle.d.ts";
-import { NodeSimulation } from "../entities/nodeSimulation.d.ts";
-import { SceneEngine } from "../engines/scene.d.ts";
-import { AudioEngine } from "../engines/audio.d.ts";
-import { AssetManager } from "../managers/asset.d.ts";
-import { ColliderDebugManager } from "../managers/colliderDebug.d.ts";
-import { DebugConsole } from "./debugConsole.d.ts";
-import { GameManager } from "../managers/game.d.ts";
-import { InputManager } from "../managers/input.d.ts";
-import { LevelManager } from "../managers/level.d.ts";
-import { SimulationSaveManager } from "../managers/simulationSave.d.ts";
-import { AudioManager } from "../managers/audio.d.ts";
-import { GameEventBus, GameEventCallback, Unsubscribe } from "./eventBus.d.ts";
-import { LibraryEventPayloadMap } from "../events/payloads.d.ts";
-import { WildcardPattern } from "../events/types.d.ts";
-import { LoggingUtility } from "../utils/logger.d.ts";
-import { GameTimer } from "../utils/timer.d.ts";
+import { AbstractEngine, Scene } from '@babylonjs/core';
+import { EventBus, Unsubscribe } from '@skewedaspect/sage-core';
+import { GameCanvas } from "../interfaces/game.js";
+import { Disposable } from "../interfaces/lifecycle.js";
+import { NodeEntityRegistry, NodeSimulation } from "../entities/nodeSimulation.js";
+import { MeshLoader } from "../entities/nodeSimulationContext.js";
+import { SceneEngine } from "../engines/scene.js";
+import { AudioEngine } from "../engines/audio.js";
+import { AssetManager } from "../managers/asset.js";
+import { ColliderDebugManager } from "../managers/colliderDebug.js";
+import { DebugConsole } from "./debugConsole.js";
+import { GameManager } from "../managers/game.js";
+import { InputManager } from "../managers/input.js";
+import { LevelManager } from "../managers/level.js";
+import { SimulationSaveManager } from "../managers/simulationSave.js";
+import { AudioManager } from "../managers/audio.js";
+import { LoggingUtility } from "../utils/logger.js";
+import { GameTimer } from "../utils/timer.js";
 /**
  * Type definition for game lifecycle hook functions
  */
-export type GameHook = (gameEngine: GameEngine) => Promise<void>;
-/** Builds a NodeSimulation bound to a scene and a mesh source -- a fresh one is built for every level that loads. */
-export type SimulationFactory = (scene: Scene, meshSource?: EntityMeshLoader) => NodeSimulation;
+export type GameHook<Registry extends NodeEntityRegistry = NodeEntityRegistry> = (gameEngine: GameEngine<Registry>) => Promise<void>;
+/** Builds a NodeSimulation named and bound to a scene and a mesh source -- a fresh one for every level that loads. */
+export type SimulationFactory<Registry extends NodeEntityRegistry = NodeEntityRegistry> = (scene: Scene, name: string, meshSource?: MeshLoader) => NodeSimulation<Registry>;
 /**
  * Interface representing the engines used in the game.
  * All engines must implement Disposable for proper cleanup.
  */
-interface Engines extends Record<string, Disposable | undefined> {
+export interface Engines extends Record<string, Disposable | undefined> {
     sceneEngine: SceneEngine;
     audioEngine?: AudioEngine;
 }
@@ -35,35 +34,34 @@ interface Engines extends Record<string, Disposable | undefined> {
  * Interface representing the managers used in the game.
  * All managers must implement Disposable for proper cleanup.
  */
-interface Managers extends Record<string, Disposable | undefined> {
+export interface Managers<Registry extends NodeEntityRegistry = NodeEntityRegistry> extends Record<string, Disposable | undefined> {
     assetManager: AssetManager;
-    gameManager: GameManager;
+    gameManager: GameManager<Registry>;
     inputManager: InputManager;
-    levelManager: LevelManager;
-    saveManager: SimulationSaveManager;
+    levelManager: LevelManager<Registry>;
+    saveManager: SimulationSaveManager<Registry>;
     audioManager?: AudioManager;
 }
 /**
  * Interface representing the debug tools available on the engine.
  */
-interface DebugTools {
+export interface DebugTools {
     colliders: ColliderDebugManager;
     console: DebugConsole | null;
     expose(name: string, value: unknown): void;
 }
 /**
- * Central hub that owns the render loop, physics, event bus, and all managers.
+ * Central hub that owns the render loop, the event bus, and all managers.
  * Created via `createGameEngine()` in sage.ts.
  */
-export declare class GameEngine {
+export declare class GameEngine<Registry extends NodeEntityRegistry = NodeEntityRegistry> {
+    #private;
     canvas: GameCanvas;
     renderEngine: AbstractEngine;
-    physics: HavokPlugin;
-    managers: Managers;
+    managers: Managers<Registry>;
     engines: Engines;
-    eventBus: GameEventBus;
+    bus: EventBus;
     logger: LoggingUtility;
-    simulation: NodeSimulation | null;
     timer: GameTimer;
     debug: DebugTools;
     largeWorldRendering: boolean;
@@ -71,78 +69,42 @@ export declare class GameEngine {
     private _stopped;
     private _log;
     private _buildSimulation;
-    private _beforeStartHook;
-    private _onStartHook;
-    private _onTeardownHook;
     /**
      * Creates an instance of GameEngine.
-     * @param canvas
-     * @param renderEngine
-     * @param physics
-     * @param eventBus
-     * @param logger
-     * @param timer
      * @param buildSimulation - Builds a fresh simulation for a scene, once rebuildSimulation is called with one.
-     * @param engines
-     * @param managers
      */
-    constructor(canvas: GameCanvas, renderEngine: AbstractEngine, physics: HavokPlugin, eventBus: GameEventBus, logger: LoggingUtility, timer: GameTimer, buildSimulation: SimulationFactory, engines: Engines, managers: Managers, largeWorldRendering?: boolean, debug?: DebugTools);
+    constructor(canvas: GameCanvas, renderEngine: AbstractEngine, bus: EventBus, logger: LoggingUtility, timer: GameTimer, buildSimulation: SimulationFactory<Registry>, engines: Engines, managers: Managers<Registry>, largeWorldRendering: boolean | undefined, debug: DebugTools);
+    /** The simulation the engine holds: attached to the bus, stepped by the frame loop, and what a view reads. */
+    get simulation(): NodeSimulation<Registry> | null;
     /**
-     * Builds a fresh NodeSimulation bound to the given scene and mesh source, and swaps it in. A level calls
-     * this once its own scene is ready, so every NodeEntity it spawns gets a node in that scene and loads its
-     * mesh through that source. Left unset, a spawned entity gets a node with no mesh.
+     * Builds a fresh NodeSimulation named `name` for the given scene and mesh source, handed this engine's bus and
+     * not yet bound. A level calls this once its own scene exists, naming the simulation after itself, so every
+     * NodeEntity it spawns gets a node in that scene and loads its mesh through that source; left unset, a spawned
+     * entity gets a node with no mesh (design/simulation.md#the-simulations-name).
      */
-    rebuildSimulation(scene: Scene, meshSource?: EntityMeshLoader): NodeSimulation;
+    rebuildSimulation(scene: Scene, name: string, meshSource?: MeshLoader): NodeSimulation<Registry>;
     /**
-     * Register a function to be called before the game engine starts
-     * @param hook
-     * @throws Error if a hook is already registered
+     * Binds the engine to a simulation, or to none. The one bound before detaches from the bus and the new one
+     * attaches, carrying its entities' subscriptions and held emissions across
+     * (design/events.md#one-bus-per-engine).
      */
-    onBeforeStart(hook: GameHook): void;
+    bindSimulation(simulation: NodeSimulation<Registry> | null): void;
+    /** Runs before the frame loop starts, awaited, in registration order (design/engine.md#lifecycle-hooks). */
+    onBeforeStart(hook: GameHook<Registry>): Unsubscribe;
+    /** Runs after the frame loop has started, awaited, in registration order. */
+    onStart(hook: GameHook<Registry>): Unsubscribe;
+    /** Runs before anything is disposed, awaited; a hook that throws is logged and does not stop the teardown. */
+    onTeardown(hook: GameHook<Registry>): Unsubscribe;
     /**
-     * Register a function to be called after the game engine starts
-     * @param hook
-     * @throws Error if a hook is already registered
-     */
-    onStart(hook: GameHook): void;
-    /**
-     * Register a function to be called when the game engine stops
-     * @param hook
-     * @throws Error if a hook is already registered
-     */
-    onTeardown(hook: GameHook): void;
-    /**
-     * Subscribe to an event on the event bus.
-     *
-     * This is a convenience method that forwards to `eventBus.subscribe()`.
-     *
-     * @param eventType - Exact event type string, wildcard pattern (e.g. 'level:*'), or RegExp
-     * @param callback
-     * @returns A function that removes this subscription when called
-     *
-     * @example
-     * // Subscribe to a specific event
-     * const unsub = engine.subscribe('level:complete', (event) => {
-     *     console.log('Level complete:', event.payload.levelName);
-     * });
-     *
-     * // Subscribe to every level event
-     * engine.subscribe('level:*', (event) => {
-     *     console.log('Level event:', event.type);
-     * });
-     */
-    subscribe<T extends keyof LibraryEventPayloadMap & string>(eventType: T | WildcardPattern | RegExp, callback: GameEventCallback<T, LibraryEventPayloadMap>): Unsubscribe;
-    /**
-     * Start the engine: runs beforeStart hook, starts the game manager, then runs onStart hook.
+     * Starts the frame loop, with the before-start hooks ahead of it and the start hooks after. An engine that has
+     * stopped does not start again (design/architecture.md#teardown).
      */
     start(): Promise<void>;
     /**
-     * Stop the engine: runs the teardown hook, then tears down all managers and engines in order.
-     *
-     * Managers claim what they need when they are built, not when the engine starts -- the input manager's
-     * window listeners, the debug console's namespace -- so an engine that never started still has
-     * everything to release. Tearing down twice is the no-op.
+     * Tears the engine down in one order: the frame loop stops, the teardown hooks run, then the debug console, the
+     * managers, and the engines dispose. A failure in one disposal does not stop the rest, and the first one raised
+     * is raised again once everything else is disposed. Stopping twice changes nothing
+     * (design/architecture.md#teardown).
      */
     stop(): Promise<void>;
 }
-export {};

package/dist/classes/gameLevel.d.ts

@@ -1,8 +1,8 @@
 import { Quaternion, Scene, StaticSound, TransformNode, Vector3 } from '@babylonjs/core';
-import { LevelConfig, LevelContext } from "../interfaces/level.d.ts";
-import { NodeEntity } from "../entities/nodeEntity.d.ts";
-import { NodeSimulation } from "../entities/nodeSimulation.d.ts";
-import { Level } from "./level.d.ts";
+import { LevelConfig, LevelContext } from "../interfaces/level.js";
+import { NodeEntity } from "../entities/nodeEntity.js";
+import { NodeEntityRegistry, NodeSimulation } from "../entities/nodeSimulation.js";
+import { Level } from "./level.js";
 /**
  * Metadata collected from a spawn point node.
  * Transforms are normalized to canonical Babylon space — the source level's __root__
@@ -23,10 +23,12 @@ interface EntityNodeData {
     node: TransformNode;
 }
 /**
- * Default Level implementation that loads from YAML configuration.
- * Supports property handlers for processing scene node metadata.
+ * The level a game gets when it describes a scene in configuration instead of writing a `Level` subclass: it
+ * builds the scene its configuration names, in one fixed order, and spawns what the scene's own markers name
+ * (design/levels.md#gamelevel).
  */
-export declare class GameLevel extends Level {
+export declare class GameLevel<Registry extends NodeEntityRegistry = NodeEntityRegistry> extends Level<Registry> {
+    #private;
     /** The level configuration */
     protected _config: LevelConfig;
     /** Collected spawn points from the scene */
@@ -39,20 +41,14 @@ export declare class GameLevel extends Level {
     protected _levelSounds: Map<string, StaticSound>;
     /** Sounds that were playing before deactivation (for resume on activate) */
     private _playingSoundsBeforeDeactivate;
-    /**
-     * Create a GameLevel from a configuration object
-     *
-     * @param config
-     * @param context
-     */
-    constructor(config: LevelConfig, context: LevelContext);
+    constructor(config: LevelConfig, context: LevelContext<Registry>);
     get config(): LevelConfig;
     get spawnedEntities(): readonly NodeEntity[];
     /**
      * The simulation this level built its scene against: the one its own spawns and despawns go through,
      * whichever simulation the engine holds at the time. Throws before `buildScene` has bound one.
      */
-    protected get simulation(): NodeSimulation;
+    protected get simulation(): NodeSimulation<Registry>;
     /**
      * Build the scene by loading assets, processing node metadata, and spawning entities.
      */
@@ -78,13 +74,15 @@ export declare class GameLevel extends Level {
      */
     private _createEnvironmentTexture;
     private _getFileExtension;
+    private _attachableCanvas;
     /**
-     * Process cameras: apply YAML overrides to imported cameras, create new ones, and set the active camera.
-     * If no YAML cameras config exists, the first imported camera (if any) is activated.
+     * An entry whose key names an imported camera overrides it, and one whose key names none creates a camera
+     * of the type it declares. With no camera configuration at all, the first imported camera activates.
      */
     private _processCameras;
     /**
-     * Create a new camera from a YAML definition.
+     * Create a camera of the type an entry declares, or nothing for an entry that cannot be built, which is
+     * logged and skipped (design/levels.md#the-load-sequence).
      */
     private _createCamera;
     /**
@@ -92,12 +90,12 @@ export declare class GameLevel extends Level {
      */
     private _applyCameraConfig;
     /**
-     * Process lights: apply YAML overrides to imported lights and create new ones.
-     * If no YAML lights config exists, imported lights are left unchanged.
+     * Lights override and create by key the way cameras do. With no light configuration at all, imported
+     * lights are left as they are.
      */
     private _processLights;
     /**
-     * Create a new light from a YAML definition.
+     * Create a light of the type an entry declares.
      */
     private _createLight;
     /**
@@ -117,6 +115,7 @@ export declare class GameLevel extends Level {
      * Walk all transform nodes and meshes, normalizing glTF metadata and dispatching to property handlers.
      */
     private _processNodeProperties;
+    private _warnUnhandledProperties;
     /**
      * Check a node's metadata for spawn/entity markers and run any registered property handlers.
      */
@@ -150,8 +149,8 @@ export declare class GameLevel extends Level {
      */
     private _spawnEntityNode;
     /**
-     * Create level-scoped sounds from YAML config. Sounds are tracked for lifecycle management
-     * (pause on deactivate, resume on activate, dispose on unload).
+     * Create the sounds the configuration names, keeping each by name so it follows the level: paused on
+     * deactivation, played again on activation, disposed with the level (design/levels.md#level-sounds).
      */
     private _processLevelSounds;
     /**
@@ -167,6 +166,6 @@ export declare class GameLevel extends Level {
     /**
      * Dispose of this level's resources
      */
-    $dispose(): Promise<void>;
+    dispose(): Promise<void>;
 }
 export {};