@skewedaspect/sage 0.9.3 → 0.9.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Christopher Case
+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

package/dist/classes/gameLevel.d.ts

@@ -103,7 +103,6 @@ export declare class GameLevel extends Level {
      * and fix PBR material falloff for compatibility.
      */
     private _setupClustering;
-    private _toColor3;
     /**
      * Configure and enable the Havok physics plugin with the level's gravity settings.
      */
@@ -112,21 +111,10 @@ export declare class GameLevel extends Level {
      * Walk all transform nodes and meshes, normalizing glTF metadata and dispatching to property handlers.
      */
     private _processNodeProperties;
-    /**
-     * Get normalized metadata from a node, handling glTF extras.
-     *
-     * Babylon.js stores glTF custom properties in node.metadata.gltf.extras,
-     * so we need to extract them for easier access.
-     */
-    private _getNormalizedMetadata;
     /**
      * Check a node's metadata for spawn/entity markers and run any registered property handlers.
      */
     private _processNodeMetadata;
-    /**
-     * Run registered property handlers on a node.
-     */
-    private _runPropertyHandlers;
     /**
      * Match collected spawn points against the level config's spawn definitions and instantiate entities.
      */
@@ -144,11 +132,6 @@ export declare class GameLevel extends Level {
      * Create an entity from a spawn definition, inheriting position/rotation/scaling from the spawn point.
      */
     private _spawnEntity;
-    /**
-     * Build or import a mesh from the entity definition and attach it to the entity.
-     * Supports primitive shapes (box/sphere/capsule/cylinder) and GLB/GLTF file paths.
-     */
-    private _createEntityMesh;
     /**
      * Create game entities for all nodes marked with the 'entity' metadata property.
      */

package/dist/classes/input/mouse.d.ts

@@ -68,9 +68,18 @@ export declare class MouseInputPlugin {
      */
     private _handlePointerMove;
     /**
-     * Handle mouse wheel events
+     * Handle mouse wheel events.
+     *
+     * The wheel is a pulse, not a level: the browser reports a delta per notch and never reports "stopped scrolling".
+     * So each event notifies twice — once carrying the deltas, once carrying zeros. Without that trailing zero,
+     * `emitOnChange` value bindings swallow every notch after the first (consecutive notches report identical deltas),
+     * trigger bindings never see a falling edge to re-arm on, and `getState()` latches the last scroll forever.
      */
     private _handleMouseWheel;
+    /**
+     * Notify subscribers of the current wheel state, attributed to the wheel event that produced it
+     */
+    private _notifyWheelState;
     /**
      * Notify subscribers of device connected event
      */

package/dist/classes/level.d.ts

@@ -1,9 +1,23 @@
-import { Scene } from '@babylonjs/core';
+import { Color3, Quaternion, Scene, TransformNode, Vector3 } from '@babylonjs/core';
 import { ClusteredLightContainer } from '@babylonjs/core/Lights/Clustered/clusteredLightContainer';
 import { LoggerInterface } from "../interfaces/logger.d.ts";
-import { LevelConfig, LevelContext, LevelInstance, PropertyHandler } from "../interfaces/level.d.ts";
+import { ColorConfig, LevelConfig, LevelContext, LevelInstance, PropertyHandler } from "../interfaces/level.d.ts";
+import { GameEntity } from "./entity.d.ts";
 import { GameEngine } from "./gameEngine.d.ts";
 import { OutlineManager } from "../managers/outline.d.ts";
+/**
+ * Transform and visibility overrides applied to a mesh built by `Level.createEntityMesh()`.
+ */
+export interface CreateEntityMeshOptions {
+    /** World position for the entity's root node. Left at the node default when omitted. */
+    position?: Vector3;
+    /** World rotation for the entity's root node. Left at the node default when omitted. */
+    rotation?: Quaternion;
+    /** Scaling for the entity's root node. Left at the node default when omitted. */
+    scaling?: Vector3;
+    /** When false, the node is disabled immediately on creation so nothing ever renders. Default true. */
+    enabled?: boolean;
+}
 /**
  * Abstract base class for game levels.
  *
@@ -47,11 +61,34 @@ export declare abstract class Level implements LevelInstance {
      * @param message
      */
     protected $emitProgress(progress: number, message: string): void;
+    protected _toColor3(color: ColorConfig): Color3;
+    /**
+     * Get normalized metadata from a node, handling glTF extras.
+     *
+     * Babylon.js stores glTF custom properties in node.metadata.gltf.extras,
+     * so we need to extract them for easier access.
+     */
+    protected _getNormalizedMetadata(node: TransformNode): Record<string, unknown> | null;
+    /**
+     * Run registered property handlers on a node.
+     */
+    protected _runPropertyHandlers(node: TransformNode): Promise<void>;
     /**
      * Load and create the scene for this level.
      * Progress events will be emitted during loading.
      */
     load(): Promise<Scene>;
+    /**
+     * Build or import a mesh from the entity definition and attach it to the entity.
+     * Supports primitive shapes (box/sphere/capsule/cylinder) and GLB/GLTF file paths.
+     *
+     * @param entity - The entity whose definition supplies the mesh spec
+     * @param options - Transform overrides and initial enabled state
+     *
+     * @returns The root node the mesh was built under, or null if the level has no scene, the definition has no
+     * mesh spec, or the GLB import produced no meshes.
+     */
+    createEntityMesh(entity: GameEntity, options?: CreateEntityMeshOptions): Promise<TransformNode | null>;
     /**
      * Abstract method for building the scene content.
      * Concrete levels must implement this to create their specific content.

package/dist/interfaces/entity.d.ts

@@ -34,6 +34,8 @@ export interface GameEntityDefinition<State extends object = object> {
             y: number;
             z: number;
         };
+        /** If false, meshes spawn hidden (isVisible = false); they still collide and block raycasts. Default: true */
+        visible?: boolean;
         /** Material configuration */
         material?: {
             /** Material type: 'standard' (default) or 'pbr' */

package/dist/managers/entity.d.ts

@@ -18,6 +18,11 @@ export interface CreateEntityOptions<State extends object = object> {
     tags?: string[];
     /** Scene node to attach the entity to. */
     node?: TransformNode;
+    /**
+     * Build the definition's mesh via the current level ('disabled' loads it setEnabled(false)).
+     * Mutually exclusive with `node`.
+     */
+    mesh?: 'enabled' | 'disabled';
 }
 export declare class GameEntityManager implements Disposable {
     /** The event bus for the entity manager. */
@@ -85,6 +90,10 @@ export declare class GameEntityManager implements Disposable {
      */
     private _registerEntityActions;
     $frameUpdate(dt: number): void;
+    /**
+     * Honor the `mesh` create option by building the definition's mesh on the current level.
+     */
+    private _buildDefinitionMesh;
     /**
      * Registers a new entity definition.
      * Also registers any actions declared in the definition with the binding manager.

package/dist/sage.es.js

@@ -59,7 +59,7 @@ var he = class {
 			configurable: !0
 		});
 	}
-}, k = "0.9.3", A = class {
+}, k = "0.9.5", A = class {
 	canvas;
 	renderEngine;
 	physics;
@@ -1606,6 +1606,19 @@ var Ae = ke(16), G = class {
 		this._log.trace(`Updating ${this.entities.size} entities with dt=${e}`);
 		for (let t of this.entities.values()) t.parent || t.$update(e);
 	}
+	async _buildDefinitionMesh(e, t) {
+		if (!t.mesh) return;
+		if (t.node) {
+			this._log.warn(`Ignoring 'mesh' option for entity ${e.id}: 'node' was supplied, and the two are exclusive.`);
+			return;
+		}
+		let n = this._engine.managers.levelManager.currentLevel;
+		if (!n?.isLoaded) {
+			this._log.warn(`Cannot build a mesh for entity ${e.id}: no level is loaded.`);
+			return;
+		}
+		await n.createEntityMesh(e, { enabled: t.mesh === "enabled" });
+	}
 	registerEntityDefinition(e) {
 		this._log.debug(`Registering entity definition: ${e.type}`);
 		let t = e.extends ? this._resolveInheritance(e) : e;
@@ -1630,7 +1643,7 @@ var Ae = ke(16), G = class {
 					...i.state,
 					...t.initialState
 				}), t.tags) for (let e of t.tags) i.$addTag(e);
-				return t.node && i.$attachToNode(t.node, this._engine), this.entities.set(i.id, i), this._indexEntity(i), this._log.debug(`Recycled entity ${i.id} from pool`), i;
+				return t.node && i.$attachToNode(t.node, this._engine), this.entities.set(i.id, i), this._indexEntity(i), await this._buildDefinitionMesh(i, t), this._log.debug(`Recycled entity ${i.id} from pool`), i;
 			}
 		}
 		this._log.trace(`Using entity definition with ${n.behaviors?.length || 0} behaviors`);
@@ -1660,7 +1673,7 @@ var Ae = ke(16), G = class {
 			});
 			a.$addChild(n);
 		}
-		return a;
+		return await this._buildDefinitionMesh(a, t), a;
 	}
 	async destroyEntity(e) {
 		this._log.debug(`Destroying entity: ${e}`);
@@ -1912,6 +1925,21 @@ var ze = class {
 			}
 		});
 	}
+	_toColor3(e) {
+		return new r(e.r, e.g, e.b);
+	}
+	_getNormalizedMetadata(e) {
+		if (!e.metadata) return null;
+		let t = e.metadata?.gltf?.extras;
+		return t ? { ...t } : e.metadata;
+	}
+	async _runPropertyHandlers(e) {
+		for (let [t, n] of this.propertyHandlers) if (t in e.metadata) try {
+			await n(e, e.metadata[t], this, this.gameEngine);
+		} catch (n) {
+			this._log.error(`Error in property handler '${t}' for node '${e.name}':`, n);
+		}
+	}
 	async load() {
 		if (this._scene) return this._log.warn(`Level ${this.name} is already loaded`), this._scene;
 		this._log.info(`Loading level: ${this.name}`), this._log.time(`level-${this.name}-load`);
@@ -1935,6 +1963,74 @@ var ze = class {
 			}), e;
 		}
 	}
+	async createEntityMesh(e, t = {}) {
+		if (!this._scene) return null;
+		let n = this.gameEngine.managers.entityManager.getDefinition(e.type);
+		if (!n?.mesh) return null;
+		let r = n.mesh, i = this._scene, a = new D(`entity-${e.id}`, i);
+		t.enabled === !1 && a.setEnabled(!1);
+		let o;
+		switch (r.source) {
+			case "box":
+				o = [b.CreateBox(`${e.type}-mesh`, {
+					size: r.params?.size ?? 1,
+					width: r.params?.width,
+					height: r.params?.height,
+					depth: r.params?.depth
+				}, i)];
+				break;
+			case "sphere":
+				o = [b.CreateSphere(`${e.type}-mesh`, {
+					diameter: r.params?.diameter ?? 1,
+					segments: r.params?.segments ?? 16
+				}, i)];
+				break;
+			case "capsule":
+				o = [b.CreateCapsule(`${e.type}-mesh`, {
+					height: r.params?.height ?? 1.8,
+					radius: r.params?.radius ?? .4
+				}, i)];
+				break;
+			case "cylinder":
+				o = [b.CreateCylinder(`${e.type}-mesh`, {
+					height: r.params?.height ?? 1,
+					diameter: r.params?.diameter ?? 1
+				}, i)];
+				break;
+			default: {
+				let e = await this.gameEngine.engines.sceneEngine.importMeshes([], r.source, i);
+				if (e.meshes.length === 0) return this._log.warn(`No meshes loaded from: ${r.source}`), a.dispose(), null;
+				o = e.meshes;
+				for (let t of e.transformNodes) t.parent ||= a;
+				break;
+			}
+		}
+		for (let e of o) e.parent ||= a;
+		t.position && a.position.copyFrom(t.position), t.rotation && (a.rotationQuaternion = t.rotation.clone()), t.scaling && a.scaling.copyFrom(t.scaling), r.scale && (typeof r.scale == "number" ? a.scaling.setAll(r.scale) : a.scaling.set(r.scale.x, r.scale.y, r.scale.z));
+		let s = r.material;
+		if (s?.color) {
+			let t = s.color;
+			if (s.type === "pbr") {
+				let n = new S(`${e.type}-material`, i);
+				n.albedoColor = this._toColor3(t), s.emissive && (n.emissiveColor = this._toColor3(s.emissive)), n.metallic = s.metallic ?? 0, n.roughness = s.roughness ?? 1;
+				for (let e of o) e.material = n;
+			} else {
+				let n = new E(`${e.type}-material`, i);
+				n.diffuseColor = this._toColor3(t), s.emissive && (n.emissiveColor = this._toColor3(s.emissive));
+				for (let e of o) e.material = n;
+			}
+		}
+		if (r.visible === !1) for (let e of o) e.isVisible = !1;
+		let c = a.getDescendants(!1).filter((e) => e instanceof D);
+		for (let e of c) {
+			let t = this._getNormalizedMetadata(e);
+			t && Object.keys(t).length > 0 && (e.metadata = {
+				...e.metadata,
+				...t
+			}, await this._runPropertyHandlers(e));
+		}
+		return this.gameEngine.managers.entityManager.attachToNode(e, a), a;
+	}
 	async $dispose() {
 		if (this._scene) {
 			this._log.info(`Disposing level: ${this.name}`);
@@ -2163,9 +2259,6 @@ var ze = class {
 		t.horizontalTiles !== void 0 && (r.horizontalTiles = t.horizontalTiles), t.verticalTiles !== void 0 && (r.verticalTiles = t.verticalTiles), t.depthSlices !== void 0 && (r.depthSlices = t.depthSlices), t.maxRange !== void 0 && (r.maxRange = t.maxRange), this.clusteredLights = r, this._log.debug(`Clustered lighting enabled: ${n.length} lights, ${r.horizontalTiles}x${r.verticalTiles} tiles, ${r.depthSlices} depth slices`);
 		for (let t of e.materials) t instanceof S && (t.useGLTFLightFalloff = !0);
 	}
-	_toColor3(e) {
-		return new r(e.r, e.g, e.b);
-	}
 	async _enablePhysics(e) {
 		let t = this._config.physics, n = new O(0, -9.81, 0);
 		typeof t == "object" && t.gravity && (n = new O(t.gravity.x, t.gravity.y, t.gravity.z));
@@ -2183,11 +2276,6 @@ var ze = class {
 		}
 		this._log.debug(`Processed ${t.length} nodes, found ${this._spawnPoints.length} spawn points and ${this._entityNodes.length} entity nodes`);
 	}
-	_getNormalizedMetadata(e) {
-		if (!e.metadata) return null;
-		let t = e.metadata?.gltf?.extras;
-		return t ? { ...t } : e.metadata;
-	}
 	async _processNodeMetadata(e) {
 		if ("spawn" in e.metadata) {
 			let { position: t, rotation: n, scaling: r } = Re(e);
@@ -2204,13 +2292,6 @@ var ze = class {
 			node: e
 		}), await this._runPropertyHandlers(e);
 	}
-	async _runPropertyHandlers(e) {
-		for (let [t, n] of this.propertyHandlers) if (t in e.metadata) try {
-			await n(e, e.metadata[t], this, this.gameEngine);
-		} catch (n) {
-			this._log.error(`Error in property handler '${t}' for node '${e.name}':`, n);
-		}
-	}
 	async _processSpawnPoints() {
 		for (let e of this._spawnPoints) {
 			let t = this._config.spawns?.[e.name];
@@ -2240,75 +2321,11 @@ var ze = class {
 			tags: e.tags,
 			initialState: n
 		});
-		return await this._createEntityMesh(r, t), r;
-	}
-	async _createEntityMesh(e, t) {
-		if (!this._scene) return;
-		let n = this.gameEngine.managers.entityManager.getDefinition(e.type);
-		if (!n?.mesh) return;
-		let r = n.mesh, i = this._scene, a = new D(`entity-${e.id}`, i), o;
-		switch (r.source) {
-			case "box":
-				o = [b.CreateBox(`${e.type}-mesh`, {
-					size: r.params?.size ?? 1,
-					width: r.params?.width,
-					height: r.params?.height,
-					depth: r.params?.depth
-				}, i)];
-				break;
-			case "sphere":
-				o = [b.CreateSphere(`${e.type}-mesh`, {
-					diameter: r.params?.diameter ?? 1,
-					segments: r.params?.segments ?? 16
-				}, i)];
-				break;
-			case "capsule":
-				o = [b.CreateCapsule(`${e.type}-mesh`, {
-					height: r.params?.height ?? 1.8,
-					radius: r.params?.radius ?? .4
-				}, i)];
-				break;
-			case "cylinder":
-				o = [b.CreateCylinder(`${e.type}-mesh`, {
-					height: r.params?.height ?? 1,
-					diameter: r.params?.diameter ?? 1
-				}, i)];
-				break;
-			default: {
-				let e = await this.gameEngine.engines.sceneEngine.importMeshes([], r.source, i);
-				if (e.meshes.length === 0) {
-					this._log.warn(`No meshes loaded from: ${r.source}`), a.dispose();
-					return;
-				}
-				o = e.meshes;
-				for (let t of e.transformNodes) t.parent ||= a;
-				break;
-			}
-		}
-		for (let e of o) e.parent ||= a;
-		a.position.copyFrom(t.position), a.rotationQuaternion = t.rotation.clone(), a.scaling.copyFrom(t.scaling), r.scale && (typeof r.scale == "number" ? a.scaling.setAll(r.scale) : a.scaling.set(r.scale.x, r.scale.y, r.scale.z));
-		let s = r.material;
-		if (s?.color) {
-			let t = s.color;
-			if (s.type === "pbr") {
-				let n = new S(`${e.type}-material`, i);
-				n.albedoColor = this._toColor3(t), s.emissive && (n.emissiveColor = this._toColor3(s.emissive)), n.metallic = s.metallic ?? 0, n.roughness = s.roughness ?? 1;
-				for (let e of o) e.material = n;
-			} else {
-				let n = new E(`${e.type}-material`, i);
-				n.diffuseColor = this._toColor3(t), s.emissive && (n.emissiveColor = this._toColor3(s.emissive));
-				for (let e of o) e.material = n;
-			}
-		}
-		let c = a.getDescendants(!1).filter((e) => e instanceof D);
-		for (let e of c) {
-			let t = this._getNormalizedMetadata(e);
-			t && Object.keys(t).length > 0 && (e.metadata = {
-				...e.metadata,
-				...t
-			}, await this._runPropertyHandlers(e));
-		}
-		this.gameEngine.managers.entityManager.attachToNode(e, a);
+		return await this.createEntityMesh(r, {
+			position: t.position,
+			rotation: t.rotation,
+			scaling: t.scaling
+		}), r;
 	}
 	async _processEntityNodes() {
 		for (let e of this._entityNodes) await this._processEntityNode(e);
@@ -2878,7 +2895,15 @@ var ze = class {
 			deltaY: e.deltaY,
 			deltaZ: e.deltaZ,
 			deltaMode: e.deltaMode
-		}, this._notifyInputChanged({
+		}, this._notifyWheelState(e), this._wheelState = {
+			deltaX: 0,
+			deltaY: 0,
+			deltaZ: 0,
+			deltaMode: 0
+		}, this._notifyWheelState(e);
+	}
+	_notifyWheelState(e) {
+		this._notifyInputChanged({
 			type: "mouse",
 			event: e,
 			buttons: { ...this._buttonState },