@skewedaspect/sage 0.9.6 → 0.10.0-beta.1

package/dist/utils/physics.d.ts

@@ -5,8 +5,11 @@ import { HavokPlugin } from '@babylonjs/core';
  *
  * Each BabylonJS scene needs its own HavokPlugin instance (because scene.dispose() disposes the
  * plugin attached to it). The raw WASM module can be shared across plugins safely.
+ *
+ * @param wasmBinary - Pre-loaded Havok WASM. Left unset, Havok fetches its own over HTTP, which
+ * only works in a browser.
  */
-export declare function initHavok(): Promise<HavokPhysicsWithBindings>;
+export declare function initHavok(wasmBinary?: BufferSource): Promise<HavokPhysicsWithBindings>;
 /**
  * Creates a new HavokPlugin from an existing WASM instance.
  */

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@skewedaspect/sage",
-  "version": "0.9.6",
+  "version": "0.10.0-beta.1",
+  "type": "module",
+  "sideEffects": true,
   "main": "dist/sage.umd.js",
   "module": "dist/sage.es.js",
   "types": "dist/sage.d.ts",
-  "type": "module",
-  "sideEffects": true,
   "exports": {
     ".": {
       "types": "./dist/sage.d.ts",
@@ -14,87 +14,50 @@
       "default": "./dist/sage.es.js"
     }
   },
-  "workspaces": [
-    "packages/sage-vue",
-    "examples",
-    "site"
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/skewed-aspect/sage/sage",
+    "directory": "packages/sage"
+  },
+  "author": "Christopher S. Case<chris.case@g33xnexus.com>",
+  "license": "MIT",
+  "description": "A modern JavaScript/TypeScript game engine built on top of BabylonJS that provides simplified abstractions for 3D game development.",
+  "keywords": [
+    "engine",
+    "babylonjs",
+    "babylon.js",
+    "game"
   ],
   "scripts": {
     "build": "vite build",
     "dev": "vite",
-    "examples": "vite --config examples/vite.config.ts",
-    "examples:build": "vite build --config examples/vite.config.ts",
-    "docs": "npm run examples:build -- --base /examples/ && rm -rf site/docs/public/examples && cp -r examples/dist site/docs/public/examples && cd site && npx vitepress dev docs",
-    "docs:build": "npm run examples:build -- --base /examples/ && node scripts/examples-spa-fallback.mjs && rm -rf site/docs/public/examples && cp -r examples/dist site/docs/public/examples && cd site && npx vitepress build docs",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --config vitest.config.ts",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
-    "test:bench": "node ./benchmark/eventbus.bench.ts",
-    "test:bench:id": "node ./benchmark/id-generation.bench.ts",
-    "lint": "eslint \"{src,tests,benchmark}/**/*.{ts,js,vue}\" --max-warnings=0 --no-warn-ignored",
-    "lint:staged": "lint-staged",
-    "prepare": "if-env NODE_ENV=production && exit 0 || husky",
-    "release": "bash scripts/release.sh"
+    "lint:types": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tests/tsconfig.json"
   },
   "files": [
     "dist"
   ],
-  "keywords": [
-    "engine",
-    "babylonjs",
-    "babylon.js",
-    "game"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.com/skewed-aspect/sage/sage"
+  "dependencies": {
+    "@skewedaspect/sage-core": "*",
+    "hexoid": "^2.0.0",
+    "js-yaml": "^4.1.1"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": "^9.0.0",
+    "@babylonjs/havok": "^1.3.10",
+    "@babylonjs/loaders": "^9.0.0"
   },
-  "author": "Christopher S. Case<chris.case@g33xnexus.com>",
-  "license": "MIT",
-  "description": "A modern JavaScript/TypeScript game engine built on top of BabylonJS that provides simplified abstractions for 3D game development.",
   "devDependencies": {
     "@babylonjs/core": "^9.0.0",
     "@babylonjs/havok": "^1.3.12",
     "@babylonjs/loaders": "^9.0.0",
-    "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.58.0",
-    "@stylistic/eslint-plugin": "^5.10.0",
-    "@types/eslint__js": "^8.42.3",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
-    "@types/sinon": "^21.0.0",
-    "eslint": "^10.1.0",
-    "eslint-formatter-junit": "^9.0.1",
-    "husky": "^9.1.7",
-    "if-env": "^1.0.4",
-    "jsdom": "^29.0.1",
-    "lint-staged": "^16.4.0",
-    "sinon": "^21.0.3",
-    "tinybench": "^6.0.0",
-    "tslib": "^2.8.1",
     "typescript": "^6.0.2",
-    "typescript-eslint": "^8.29.0",
-    "uid": "^2.0.2",
     "vite": "^8.0.3",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.2"
-  },
-  "lint-staged": {
-    "*.{ts,js}": "npm run lint"
-  },
-  "peerDependencies": {
-    "@babylonjs/core": "^9.0.0",
-    "@babylonjs/havok": "^1.3.10",
-    "@babylonjs/loaders": "^9.0.0"
-  },
-  "overrides": {
-    "typescript-eslint": {
-      "typescript": "$typescript"
-    }
-  },
-  "dependencies": {
-    "hexoid": "^2.0.0",
-    "js-yaml": "^4.1.1"
+    "vite-plugin-checker": "^0.12.0",
+    "vite-plugin-dts": "^4.5.4"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-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

@@ -1,73 +0,0 @@
-
-# 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();
-```
-
-## Releasing
-
-Releases are done locally via the release script, which bumps the version, stamps the changelog, commits, tags,
-and pushes. CI then auto-publishes to npm when it sees the version tag.
-
-```sh
-npm run release -- patch        # 0.8.0 -> 0.8.1
-npm run release -- minor        # 0.8.0 -> 0.9.0
-npm run release -- major        # 0.8.0 -> 1.0.0
-npm run release -- prerelease --preid=beta   # 0.9.0 -> 0.9.1-beta.0
-```
-
-Requirements:
-- Clean working tree (commit or stash first)
-- On the `main` branch
-- GitLab CI needs `NPM_ID_TOKEN` OIDC configured for npm provenance publishing
-
-The script publishes both `@skewedaspect/sage` and `@skewedaspect/sage-vue` at the same version. Prereleases are
-tagged as `next` on npm.
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a merge request on GitLab.
-
-## License
-
-This project is licensed under the MIT License.

package/dist/behaviors/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./sound.d.ts";
-export * from "./stateMachine.d.ts";

package/dist/behaviors/sound.d.ts

@@ -1,137 +0,0 @@
-import { TransformNode } from '@babylonjs/core';
-import { GameEntityBehavior } from "../classes/entity.d.ts";
-import { GameEngine } from "../classes/gameEngine.d.ts";
-import { GameEvent } from "../classes/eventBus.d.ts";
-/**
- * Configuration for a single sound.
- */
-export interface SoundConfig {
-    /** Path to the sound file */
-    url: string;
-    /** Volume level (0-1), default 1 */
-    volume?: number;
-    /** Whether to loop the sound, default false */
-    loop?: boolean;
-    /** Whether to use spatial 3D audio, default false */
-    spatial?: boolean;
-    /** Maximum distance for spatial audio, default 100 */
-    maxDistance?: number;
-    /** Whether to autoplay when registered, default false */
-    autoplay?: boolean;
-    /** Audio channel name (e.g., 'sfx', 'music'). Used with AudioManager. */
-    channel?: string;
-}
-/**
- * State interface for entities using SoundBehavior.
- * Entity state should include a `sounds` property with sound configurations.
- */
-export interface SoundEntityState {
-    /** Map of sound name to configuration */
-    sounds?: Record<string, SoundConfig>;
-}
-/**
- * Behavior for managing sounds on an entity.
- *
- * Sounds are configured in the entity's state under the `sounds` property.
- * The behavior creates sounds via AudioManager (BabylonJS AudioV2).
- *
- * Requires AudioManager to be configured on the GameEngine. If no AudioManager is found,
- * a warning is logged and no sounds are created.
- *
- * @example
- * ```typescript
- * // Entity definition
- * {
- *     type: 'player',
- *     behaviors: [SoundBehavior, ...],
- *     defaultState: {
- *         sounds: {
- *             jump: { url: 'sounds/jump.mp3', volume: 0.8, channel: 'sfx' },
- *             footstep: { url: 'sounds/footstep.mp3', loop: true, channel: 'sfx' }
- *         }
- *     }
- * }
- *
- * // In another behavior, get the sound behavior and control sounds
- * const soundBehavior = entity.getBehavior(SoundBehavior);
- * soundBehavior?.play('jump');
- * ```
- */
-export declare class SoundBehavior extends GameEntityBehavior<SoundEntityState> {
-    name: string;
-    eventSubscriptions: string[];
-    /** Map of sound name to StaticSound instance */
-    private _sounds;
-    /** Whether sounds have been initialized */
-    private _initialized;
-    /** AudioManager reference */
-    private _audioManager;
-    /** Node reference for spatial detach on cleanup */
-    private _node;
-    private _log;
-    onNodeAttached(node: TransformNode, gameEngine: GameEngine): void;
-    processEvent(_event: GameEvent, _state: SoundEntityState): boolean;
-    onReset(_state: SoundEntityState): void;
-    destroy(): Promise<void>;
-    private _createSound;
-    private _disposeSounds;
-    /**
-     * Play a sound by name.
-     *
-     * @param name - The name of the sound to play. If omitted and only one sound exists, plays that sound.
-     * @param time - Optional time offset in seconds to start playing from
-     */
-    play(name?: string, time?: number): void;
-    /**
-     * Stop a sound by name.
-     *
-     * @param name - The name of the sound to stop. If omitted, stops all sounds.
-     */
-    stop(name?: string): void;
-    /**
-     * Pause a sound by name.
-     *
-     * @param name - The name of the sound to pause. If omitted and only one sound exists, pauses that sound.
-     */
-    pause(name?: string): void;
-    /**
-     * Set the volume of a sound.
-     *
-     * @param volume - Volume level (0-1)
-     * @param name - The name of the sound. If omitted, sets volume for all sounds.
-     */
-    setVolume(volume: number, name?: string): void;
-    /**
-     * Check if a sound is currently playing.
-     *
-     * @param name - The name of the sound. If omitted and only one sound exists, checks that sound.
-     */
-    isPlaying(name?: string): boolean;
-    /**
-     * Get all registered sound names.
-     */
-    getSoundNames(): string[];
-    /**
-     * Check if a sound with the given name exists.
-     *
-     * @param name
-     */
-    hasSound(name: string): boolean;
-    /**
-     * Register a new sound at runtime. Replaces any existing sound with the same name.
-     *
-     * @param name
-     * @param config
-     */
-    registerSound(name: string, config: SoundConfig): void;
-    /**
-     * Unregister and dispose a sound.
-     *
-     * @param name
-     */
-    unregisterSound(name: string): void;
-    /**
-     * Get a sound by name. If name is omitted and only one sound exists, returns that sound.
-     */
-    private _getSound;
-}

package/dist/behaviors/stateMachine.d.ts

@@ -1,76 +0,0 @@
-import { GameEntityBehavior } from "../classes/entity.d.ts";
-import { GameEvent } from "../classes/eventBus.d.ts";
-import { StateMachine } from "../utils/stateMachine.d.ts";
-/**
- * A single transition definition for the state machine behavior configuration.
- */
-export interface TransitionConfig<States extends string> {
-    from: States;
-    to: States;
-    guard?: () => boolean;
-}
-/**
- * A wildcard transition definition (from any state).
- */
-export interface WildcardTransitionConfig<States extends string> {
-    to: States;
-    guard?: () => boolean;
-}
-/**
- * Configuration for creating a StateMachineBehavior subclass.
- */
-export interface StateMachineBehaviorConfig<States extends string, EntityState extends object> {
-    /** The initial state of the state machine. */
-    initialState: States;
-    /** The key in the entity's state object to update when state changes. */
-    stateKey: keyof EntityState & string;
-    /** Valid transitions between states. */
-    transitions: TransitionConfig<States>[];
-    /** Wildcard transitions (from any state). */
-    wildcardTransitions?: WildcardTransitionConfig<States>[];
-}
-/**
- * A behavior that wraps a {@link StateMachine} and ties it to entity state.
- *
- * Since behaviors are instantiated with `new BehaviorClass()` (no constructor args),
- * use the static factory `StateMachineBehavior.create(config)` to produce a configured subclass.
- *
- * @example
- * ```typescript
- * const EnemyAI = StateMachineBehavior.create<EnemyStates, EnemyState>({
- *     initialState: 'idle',
- *     stateKey: 'aiState',
- *     transitions: [
- *         { from: 'idle', to: 'patrol' },
- *         { from: 'patrol', to: 'chase' },
- *         { from: 'chase', to: 'attack' },
- *     ],
- *     wildcardTransitions: [
- *         { to: 'dead' },
- *     ],
- * });
- * ```
- */
-export declare class StateMachineBehavior<States extends string = string, EntityState extends object = object> extends GameEntityBehavior<EntityState> {
-    name: string;
-    eventSubscriptions: string[];
-    protected stateMachine: StateMachine<States>;
-    protected stateKey: keyof EntityState & string;
-    protected constructor();
-    /**
-     * The current state of the state machine.
-     */
-    get currentState(): States;
-    /**
-     * Transition to a new state. Updates the entity's state and emits a state changed event.
-     *
-     * @throws If the transition is not defined or a guard rejects it.
-     */
-    transition(to: States): void;
-    processEvent(_event: GameEvent, _state: EntityState): boolean;
-    /**
-     * Creates a configured StateMachineBehavior subclass with the given state machine configuration baked in.
-     * The returned class can be used directly as a behavior constructor.
-     */
-    static create<States extends string, EntityState extends object>(config: StateMachineBehaviorConfig<States, EntityState>): new () => StateMachineBehavior<States, EntityState>;
-}

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

@@ -1,116 +0,0 @@
-import { GameEventBus } from "../eventBus.d.ts";
-import { Action } from "../../interfaces/action.d.ts";
-import { Binding, ToggleBindingDefinition } from "../../interfaces/binding.d.ts";
-import { DeviceType, DeviceValueReader, InputState } from "../../interfaces/input.d.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 deviceType: DeviceType;
-    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 (true = on, false = off)
-     */
-    get state(): boolean;
-    /**
-     * Set the toggle state directly (useful for programmatic control)
-     */
-    set state(value: boolean);
-    /**
-     * Get the value emitted when toggle is in the "on" state
-     */
-    get onValue(): boolean | number;
-    /**
-     * Get the value emitted when toggle is in the "off" state
-     */
-    get offValue(): boolean | number;
-    /**
-     * Get the current value based on toggle state.
-     * For analog actions, returns min/max value. For digital, returns on/off value.
-     */
-    get value(): boolean | number;
-    /**
-     * Get the current options for this toggle binding.
-     */
-    get options(): ToggleBindingOptions;
-    /**
-     * Create a new toggle binding
-     *
-     * @param action
-     * @param deviceID
-     * @param deviceType
-     * @param reader
-     * @param options
-     */
-    constructor(action: Action, deviceID: string, deviceType: DeviceType, reader: DeviceValueReader, options?: ToggleBindingOptions);
-    /**
-     * Process input state and emit an action event if the toggle flipped.
-     *
-     * @param state
-     * @param eventBus
-     */
-    process(state: InputState, eventBus: GameEventBus): void;
-    /**
-     * Reset edge-detection state for a context activation. When a state is provided, primes from the current physical
-     * input so that already-held inputs don't produce phantom edges in the newly activated context.
-     */
-    resetEdgeState(state?: InputState): void;
-    /**
-     * Reset toggle to its initial state
-     */
-    reset(): void;
-    /**
-     * Returns a JSON-serializable representation of this toggle binding.
-     */
-    toJSON(): ToggleBindingDefinition;
-}

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

@@ -1,81 +0,0 @@
-import { GameEventBus } from "../eventBus.d.ts";
-import { Action } from "../../interfaces/action.d.ts";
-import { Binding, TriggerBindingDefinition } from "../../interfaces/binding.d.ts";
-import { DeviceType, DeviceValueReader, InputState } from "../../interfaces/input.d.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 deviceType: DeviceType;
-    readonly reader: DeviceValueReader;
-    private readonly _edgeMode;
-    private readonly _threshold;
-    private _lastDigitalState;
-    /**
-     * Get the current options for this trigger binding.
-     */
-    get options(): TriggerBindingOptions;
-    /**
-     * Create a new trigger binding
-     *
-     * @param action
-     * @param deviceID
-     * @param deviceType
-     * @param reader
-     * @param options
-     */
-    constructor(action: Action, deviceID: string, deviceType: DeviceType, reader: DeviceValueReader, options?: TriggerBindingOptions);
-    /**
-     * Process input state and emit an action event on the configured edge transition(s).
-     *
-     * @param state
-     * @param eventBus
-     */
-    process(state: InputState, eventBus: GameEventBus): void;
-    /**
-     * Reset edge-detection state for a context activation. When a state is provided, primes from the current physical
-     * input so that already-held inputs don't produce phantom rising edges in the newly activated context.
-     */
-    resetEdgeState(state?: InputState): void;
-    /**
-     * Returns a JSON-serializable representation of this trigger binding.
-     */
-    toJSON(): TriggerBindingDefinition;
-}