incanto 0.4.3 → 0.6.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { a as Rng, c as JsonValue, d as jsonKind, i as SceneJson, l as jsonClone, n as NodeJson, o as JsonKind, r as SCENE_FORMAT, s as JsonObject, t as ConnectionJson, u as jsonEquals } from "./schema-CcoWb32N.js";
-import { $ as BusName, A as LogManager, B as spatialGain, C as RendererStats, D as SceneTree, E as NodeLifecycle, F as Listener, G as SfxWave, H as SFX_PRESETS, I as ROLLOFF_MODELS, J as MusicBackend, K as SynthOptions, L as RolloffModel, M as SfxEngine, N as SfxPlayOptions, O as LogEntry, P as isAudioContextAvailable, Q as AudioBuses, R as SpatialParams, S as GameStats, T as Node, U as SFX_PRESET_NAMES, V as spatialPan, W as SfxParams, X as MusicTrack, Y as MusicManager, Z as PlayMusicOptions, _ as registeredTypes, a as registerBehavior, b as Scheduler, c as PropDef, d as createNode, et as Signal, f as getNodeSchema, g as registerNode, h as mergeStaticSignals, i as getBehavior, j as InputMap, k as LogLevel, l as PropSchema, m as getNodeType, n as BehaviorCtor, o as registeredBehaviors, p as getNodeSignals, q as synthSfx, r as clearBehaviors, s as NodeCtor, t as Behavior, tt as SignalListener, u as clearRegistry, v as Engine, w as Scene, x as EngineStats, y as EngineOptions, z as Vec3 } from "./behavior-BAQq7HGM.js";
-import { n as loadScene, t as LoadSceneOptions } from "./loader-Mo0KghCv.js";
-import { n as ParticleSimConfig, r as ParticleView, t as ParticleSim } from "./particle-sim-CbN4YUuH.js";
-import { n as AudioPlayer, t as AudioElementLike } from "./audio-player-DqUR3XFs.js";
+import { $ as BusName, A as LogManager, B as spatialGain, C as RendererStats, D as SceneTree, E as NodeLifecycle, F as Listener, G as SfxWave, H as SFX_PRESETS, I as ROLLOFF_MODELS, J as MusicBackend, K as SynthOptions, L as RolloffModel, M as SfxEngine, N as SfxPlayOptions, O as LogEntry, P as isAudioContextAvailable, Q as AudioBuses, R as SpatialParams, S as GameStats, T as Node, U as SFX_PRESET_NAMES, V as spatialPan, W as SfxParams, X as MusicTrack, Y as MusicManager, Z as PlayMusicOptions, _ as registeredTypes, a as registerBehavior, b as Scheduler, c as PropDef, d as createNode, et as Signal, f as getNodeSchema, g as registerNode, h as mergeStaticSignals, i as getBehavior, j as InputMap, k as LogLevel, l as PropSchema, m as getNodeType, n as BehaviorCtor, o as registeredBehaviors, p as getNodeSignals, q as synthSfx, r as clearBehaviors, s as NodeCtor, t as Behavior, tt as SignalListener, u as clearRegistry, v as Engine, w as Scene, x as EngineStats, y as EngineOptions, z as Vec3 } from "./behavior-CWhW3oa6.js";
+import { n as loadScene, t as LoadSceneOptions } from "./loader-D2u0fVW2.js";
+import { n as ParticleSimConfig, r as ParticleView, t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
+import { n as AudioPlayer, t as AudioElementLike } from "./audio-player-DkBqRTs4.js";
 import { n as IncantoErrorCode, r as IncantoErrorDetails, t as IncantoError } from "./errors-BMFaY68Q.js";
 
 //#region src/core/audio/crossfade.d.ts
@@ -72,6 +72,121 @@ type ParsedNodePath = {
 };
 declare function parseNodePath(path: string): ParsedNodePath;
 //#endregion
+//#region src/core/nodes/hud.d.ts
+/**
+* DOM-backed HUD widgets — the layer 18 of 22 example games hand-rolled.
+*
+* These are CORE nodes (no three.js): they render into a fixed, pointer-
+* transparent overlay ABOVE the canvas, so the same JSON works over the 2D
+* and 3D renderers alike. Headless (no `document`) every widget is a silent
+* no-op — scenes stay fully testable in plain node.
+*
+*   { "name": "HUD", "type": "HudLayer", "children": [
+*     { "name": "Health", "type": "UiBar",
+*       "props": { "anchor": "topLeft", "value": 100, "max": 100, "label": "HP" } },
+*     { "name": "Score", "type": "UiText",
+*       "props": { "anchor": "topRight", "text": "0", "size": 22 } },
+*     { "name": "Banner", "type": "UiBanner" }
+*   ]}
+*
+* Behaviors talk to them like any node:
+*   (this.node.getNode('%Score') as UiText).text = `${score}`;
+*   (this.node.getNode('%Banner') as UiBanner).show('WAVE 2', { color: '#f66' });
+*/
+type HudAnchor = "topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight";
+/**
+* The overlay container. One per scene is plenty; widgets mount into its
+* anchor slots. `zIndex` lifts it above game canvases; the layer never eats
+* pointer events (widgets that need clicks opt in individually).
+*/
+declare class HudLayer extends Node {
+  static override readonly typeName: string;
+  static readonly props: PropSchema;
+  zIndex: number;
+  visible: boolean;
+  /** @internal root overlay element (null headless). */
+  _element: HTMLElement | null;
+  private readonly slots;
+  override onEnterTree(): void;
+  override onExitTree(): void;
+  override update(): void;
+  /** @internal Widgets mount into per-anchor flex columns. */
+  _slot(anchor: HudAnchor): HTMLElement | null;
+}
+/** Shared plumbing: mount into the parent HudLayer's anchor slot. */
+declare abstract class HudWidget extends Node {
+  static readonly props: PropSchema;
+  anchor: HudAnchor;
+  visible: boolean;
+  /** @internal */
+  _element: HTMLElement | null;
+  protected abstract _build(): HTMLElement;
+  private layer;
+  override onReady(): void;
+  override onExitTree(): void;
+  override update(_dt: number): void;
+  protected _sync(): void;
+}
+/** A text line (score, timer, hints). Set `.text` from behaviors. */
+declare class UiText extends HudWidget {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  text: string;
+  size: number;
+  color: string;
+  shadow: boolean;
+  private last;
+  protected _build(): HTMLElement;
+  protected override _sync(): void;
+}
+/** A labeled progress bar (health, stamina, reload, boss HP). */
+declare class UiBar extends HudWidget {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  value: number;
+  max: number;
+  width: number;
+  height: number;
+  color: string;
+  lowColor: string;
+  lowThreshold: number;
+  background: string;
+  label: string;
+  private fill;
+  private lastRatio;
+  /** Current fill ratio 0..1 (what the bar shows). */
+  get ratio(): number;
+  protected _build(): HTMLElement;
+  protected override _sync(): void;
+}
+/**
+* Center-screen announcements ("WAVE 2", "YOU DIED", "LEVEL UP") with fade
+* in/out and a queue — call `.show(text, { color, seconds })`; `sticky:true`
+* (seconds: 0) keeps it until the next show(). Emits `bannerShown(text)`.
+*/
+declare class UiBanner extends HudWidget {
+  static override readonly typeName: string;
+  static readonly signals: string[];
+  static override readonly props: PropSchema;
+  override anchor: HudAnchor;
+  size: number;
+  /** Default display time (per-show override via options). */
+  seconds: number;
+  private queue;
+  private current;
+  private remaining;
+  /** What the banner is showing right now ('' when idle) — test-friendly. */
+  get showing(): string;
+  show(text: string, opts?: {
+    color?: string;
+    seconds?: number;
+  }): void;
+  /** Drop everything (scene transitions). */
+  clear(): void;
+  protected _build(): HTMLElement;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/core/nodes/timer.d.ts
 /**
 * The canonical serializable game clock — never `setTimeout` in game logic.
@@ -178,6 +293,25 @@ declare function resolveRendering(environment: JsonObject | undefined, fallback:
   pixelRatio?: number;
 }): ResolvedRendering;
 //#endregion
+//#region src/core/save.d.ts
+/**
+* Namespaced game persistence — high scores, unlocks, settings. localStorage
+* in the browser, in-memory headless (tests and SSR stay green). Values are
+* JSON round-tripped, so what you get back is what you saved.
+*
+*   const save = createSaveStore('my-game');
+*   save.set('highScore', 4200);
+*   const best = save.get('highScore', 0);
+*/
+interface SaveStore {
+  get<T extends JsonValue>(key: string, fallback: T): T;
+  set(key: string, value: JsonValue): void;
+  remove(key: string): void;
+  /** Wipe THIS namespace only. */
+  clear(): void;
+}
+declare function createSaveStore(namespace: string): SaveStore;
+//#endregion
 //#region src/core/scene/constants.d.ts
 /** The single reserved key marking a prop value as a constant reference. */
 declare const CONST_REF_KEY = "@const";
@@ -302,4 +436,4 @@ declare function computeViewport(canvasW: number, canvasH: number, viewport: {
 /** Engine version. Kept in sync with package.json by the release pipeline. */
 declare const VERSION: string;
 //#endregion
-export { AudioBuses, type AudioElementLike, AudioPlayer, Behavior, type BehaviorCtor, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, Engine, type EngineOptions, type EngineStats, type GameStats, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, ROLLOFF_MODELS, type RendererStats, type ResolvedRendering, type ResolvedViewport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, type SceneJson, SceneTree, type Scheduler, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, Timer, TouchControls, type TouchControlsOptions, VERSION, type Vec3, type ViewportFit, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, crossfadeGains, duplicateNode, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };
+export { AudioBuses, type AudioElementLike, AudioPlayer, Behavior, type BehaviorCtor, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, Engine, type EngineOptions, type EngineStats, type GameStats, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, ROLLOFF_MODELS, type RendererStats, type ResolvedRendering, type ResolvedViewport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiText, VERSION, type Vec3, type ViewportFit, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };

package/dist/index.js

@@ -1,13 +1,13 @@
-import { _ as registerBehavior, a as SCENE_FORMAT, c as SceneTree, d as resolveConstants, f as Node, g as getBehavior, h as clearBehaviors, i as serializeNode, l as CONST_REF_KEY, m as Behavior, n as loadScene, o as computeViewport, p as parseNodePath, r as Scene, s as resolveViewport, u as isConstRef, v as registeredBehaviors, y as Signal } from "./loader-CGs_G-r0.js";
-import { a as Engine, c as SfxEngine, d as WebAudioMusicBackend, f as crossfadeGains, i as applyParticlePreset, l as isAudioContextAvailable, m as AudioBuses, n as PARTICLE_PRESETS, o as LogManager, p as fadeGain, r as PARTICLE_PRESET_NAMES, s as InputMap, t as ParticleSim, u as MusicManager } from "./particle-sim-DYuSUxvK.js";
+import { _ as registerBehavior, a as SCENE_FORMAT, c as SceneTree, d as resolveConstants, f as Node, g as getBehavior, h as clearBehaviors, i as serializeNode, l as CONST_REF_KEY, m as Behavior, n as loadScene, o as computeViewport, p as parseNodePath, r as Scene, s as resolveViewport, u as isConstRef, v as registeredBehaviors, y as Signal } from "./loader-B4OEXDZ8.js";
+import { a as Engine, c as SfxEngine, d as WebAudioMusicBackend, f as crossfadeGains, i as applyParticlePreset, l as isAudioContextAvailable, m as AudioBuses, n as PARTICLE_PRESETS, o as LogManager, p as fadeGain, r as PARTICLE_PRESET_NAMES, s as InputMap, t as ParticleSim, u as MusicManager } from "./particle-sim-CFkILGwh.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { a as spatialGain, c as SFX_PRESET_NAMES, i as ROLLOFF_MODELS, l as synthSfx, n as Timer, o as spatialPan, r as AudioPlayer, s as SFX_PRESETS, t as registerCoreNodes } from "./register-BuUV1_KB.js";
+import { a as UiBar, c as ROLLOFF_MODELS, d as SFX_PRESETS, f as SFX_PRESET_NAMES, i as UiBanner, l as spatialGain, n as Timer, o as UiText, p as synthSfx, r as HudLayer, s as AudioPlayer, t as registerCoreNodes, u as spatialPan } from "./register-Dl_ixIJe.js";
 import { n as jsonEquals, r as jsonKind, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { a as getNodeSignals, c as mergeStaticSignals, i as getNodeSchema, l as registerNode, n as clearRegistry, o as getNodeType, r as createNode, u as registeredTypes } from "./registry-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as resolveRendering, n as attachTouchControls, r as joystickVector, t as TouchControls } from "./touch-031PxtCR.js";
-import { t as duplicateNode } from "./duplicate-DP2WPYom.js";
+import { t as duplicateNode } from "./duplicate-BEvGBtb_.js";
 //#region src/core/preload.ts
 /**
 * Warm the HTTP cache for a list of asset urls with a progress callback —
@@ -40,6 +40,59 @@ function assetUrls(assets) {
 	return Object.values(assets ?? {}).map((a) => a.url).filter((u) => typeof u === "string" && !u.startsWith("data:"));
 }
 //#endregion
+//#region src/core/save.ts
+const memoryStores = /* @__PURE__ */ new Map();
+function createSaveStore(namespace) {
+	const prefix = `incanto:${namespace}:`;
+	const local = storageOrNull();
+	if (!local) {
+		let mem = memoryStores.get(namespace);
+		if (!mem) {
+			mem = /* @__PURE__ */ new Map();
+			memoryStores.set(namespace, mem);
+		}
+		const backing = mem;
+		return {
+			get: (key, fallback) => parse(backing.get(key), fallback),
+			set: (key, value) => void backing.set(key, JSON.stringify(value)),
+			remove: (key) => void backing.delete(key),
+			clear: () => backing.clear()
+		};
+	}
+	return {
+		get: (key, fallback) => parse(local.getItem(prefix + key) ?? void 0, fallback),
+		set: (key, value) => local.setItem(prefix + key, JSON.stringify(value)),
+		remove: (key) => local.removeItem(prefix + key),
+		clear: () => {
+			const doomed = [];
+			for (let i = 0; i < local.length; i++) {
+				const k = local.key(i);
+				if (k?.startsWith(prefix)) doomed.push(k);
+			}
+			for (const k of doomed) local.removeItem(k);
+		}
+	};
+}
+function parse(raw, fallback) {
+	if (raw === void 0 || raw === null) return fallback;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return fallback;
+	}
+}
+function storageOrNull() {
+	try {
+		if (typeof localStorage === "undefined") return null;
+		const probe = "__incanto_probe__";
+		localStorage.setItem(probe, "1");
+		localStorage.removeItem(probe);
+		return localStorage;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/core/uid-gen.ts
 /**
 * The ONE way to mint a node uid: crypto-strength, `n_` + 16 base36 chars
@@ -57,6 +110,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.4.3";
+const VERSION = "0.6.0";
 //#endregion
-export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, IncantoError, InputMap, LogManager, MusicManager, Node, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, crossfadeGains, duplicateNode, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };
+export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, LogManager, MusicManager, Node, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, UiBanner, UiBar, UiText, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };

package/dist/{loader-CGs_G-r0.js → loader-B4OEXDZ8.js}

@@ -192,8 +192,13 @@ var Node = class {
 	}
 	set name(value) {
 		validateName(value);
+		const old = this._name;
 		if (this._parent) this._name = uniqueSiblingName(value, this._parent._children, this);
 		else this._name = value;
+		if (this._tree && this._name !== old) {
+			this._tree._unindexName(this, old);
+			this._tree._indexName(this);
+		}
 	}
 	get parent() {
 		return this._parent;
@@ -260,6 +265,10 @@ var Node = class {
 	}
 	/** Every node in THIS subtree named `name` — names repeat, so a list. */
 	getNodesByName(name) {
+		if (this._tree && this._parent === null) {
+			const set = this._tree._nodesNamed(name);
+			return set ? [...set] : [];
+		}
 		const out = [];
 		const walk = (node) => {
 			if (node.name === name) out.push(node);
@@ -284,6 +293,17 @@ var Node = class {
 	resolve(path) {
 		const parsed = parseNodePath(path);
 		if (parsed.kind === "unique") {
+			const tree = this._tree;
+			if (tree) {
+				const set = tree._nodesNamed(parsed.name);
+				if (!set || set.size === 0) return null;
+				if (set.size > 1) {
+					const paths = [];
+					for (const m of set) paths.push(m.getPath());
+					throw new IncantoError("DUPLICATE_UNIQUE_NAME", `'%${parsed.name}' is ambiguous: ${set.size} nodes named '${parsed.name}' (${paths.join(", ")}).`);
+				}
+				for (const m of set) return m;
+			}
 			const matches = [];
 			collectByName(this.getRoot(), parsed.name, matches);
 			if (matches.length > 1) throw new IncantoError("DUPLICATE_UNIQUE_NAME", `'%${parsed.name}' is ambiguous: ${matches.length} nodes named '${parsed.name}' (${matches.map((m) => m.getPath()).join(", ")}).`);
@@ -388,6 +408,7 @@ var Node = class {
 	/** @internal */
 	_propagateEnterTree(tree) {
 		this._tree = tree;
+		tree._indexName(this);
 		this.onEnterTree();
 		this.behavior?.onEnterTree?.();
 		for (const c of [...this._children]) if (c._tree !== tree) c._propagateEnterTree(tree);
@@ -406,6 +427,7 @@ var Node = class {
 		for (const c of [...this._children]) c._propagateExitTree();
 		this.onExitTree();
 		this.behavior?.onExitTree?.();
+		this._tree?._unindexName(this);
 		this._tree = null;
 	}
 	/** @internal */
@@ -507,6 +529,18 @@ var SceneTree = class {
 	_root = null;
 	_engine = null;
 	freeQueue = /* @__PURE__ */ new Set();
+	/**
+	* name → attached nodes with that name. Maintained by Node enter/exit/rename
+	* so `%name` targeting and root-level getNodesByName are O(1) — behaviors
+	* resolve targets every frame and a full-tree walk per chaser melted horde
+	* scenes (N chasers × whole tree, 60×/s).
+	*/
+	_nameIndex = /* @__PURE__ */ new Map();
+	/**
+	* Bumped whenever ANY node attaches or detaches — cheap "did the tree
+	* change shape?" check for per-step body gathers and similar caches.
+	*/
+	_structureVersion = 0;
 	_frameId = 0;
 	/**
 	* Monotonic update-frame counter — bumped once per `update()`. Per-frame
@@ -516,6 +550,29 @@ var SceneTree = class {
 	get frameId() {
 		return this._frameId;
 	}
+	/** @internal Node attach hook. */
+	_indexName(node) {
+		this._structureVersion++;
+		let set = this._nameIndex.get(node.name);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this._nameIndex.set(node.name, set);
+		}
+		set.add(node);
+	}
+	/** @internal Node detach/rename hook (`name` = the entry to remove). */
+	_unindexName(node, name = node.name) {
+		this._structureVersion++;
+		const set = this._nameIndex.get(name);
+		if (set) {
+			set.delete(node);
+			if (set.size === 0) this._nameIndex.delete(name);
+		}
+	}
+	/** @internal Every ATTACHED node named `name` (undefined = none). */
+	_nodesNamed(name) {
+		return this._nameIndex.get(name);
+	}
 	/**
 	* @internal Opaque per-frame scratch the 3d layer parks its shared moving-body
 	* snapshot on (kept here so it is per-tree-instance, never a module global —
@@ -709,7 +766,10 @@ var Scene = class {
 	/** Design-resolution viewport (consumed by renderers via resolveViewport). */
 	viewport;
 	connections;
+	/** The full source JSON this scene was loaded from — `restartScene` fuel. */
+	source;
 	constructor(source, root, tree) {
+		this.source = jsonClone(source);
 		this.name = source.name;
 		this.dimension = source.dimension;
 		this.root = root;

package/dist/{loader-Mo0KghCv.d.ts → loader-D2u0fVW2.d.ts}

@@ -1,5 +1,5 @@
 import { i as SceneJson } from "./schema-CcoWb32N.js";
-import { v as Engine, w as Scene } from "./behavior-BAQq7HGM.js";
+import { v as Engine, w as Scene } from "./behavior-CWhW3oa6.js";
 
 //#region src/core/scene/loader.d.ts
 interface LoadSceneOptions {

package/dist/net.d.ts

@@ -1,5 +1,5 @@
 import { c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
-import { T as Node, et as Signal, l as PropSchema, v as Engine } from "./behavior-BAQq7HGM.js";
+import { T as Node, et as Signal, l as PropSchema, v as Engine } from "./behavior-CWhW3oa6.js";
 
 //#region src/net/types.d.ts
 type Unsubscribe = () => void;

package/dist/net.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
 import { n as createAgent8Server } from "./agent8-CvsfVskX.js";
-import { i as applySyncPatch, n as NetworkSpawner, r as NetworkManager, t as registerNodesNet } from "./register-B0gq63VW.js";
+import { i as applySyncPatch, n as NetworkSpawner, r as NetworkManager, t as registerNodesNet } from "./register-C35HDZpm.js";
 //#region src/net/loopback.ts
 /**
 * In-memory multiplayer hub implementing the SAME kernel contract as

package/dist/{particle-sim-DYuSUxvK.js → particle-sim-CFkILGwh.js}

@@ -1,7 +1,7 @@
-import { y as Signal } from "./loader-CGs_G-r0.js";
+import { y as Signal } from "./loader-B4OEXDZ8.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { l as synthSfx } from "./register-BuUV1_KB.js";
+import { p as synthSfx } from "./register-Dl_ixIJe.js";
 import { n as jsonEquals } from "./json-BLk7H2Qa.js";
 //#region src/core/audio/buses.ts
 /**
@@ -684,6 +684,75 @@ var InputMap = class {
 	* wheel → wheelDelta. `lockOnClick` requests pointer lock on mousedown
 	* (the FPS pattern).
 	*/
+	padAxesState = {
+		lx: 0,
+		ly: 0,
+		rx: 0,
+		ry: 0
+	};
+	padButtonsDown = 0;
+	/**
+	* Feed one polled gamepad snapshot (standard mapping). Buttons become
+	* codes `Pad0`..`Pad16` in the same space as keys — declare them in input
+	* actions like any key ("jump": ["Space", "Pad0"]). Axes land in
+	* `padAxes()` with a deadzone. Pass null when no pad is connected.
+	*/
+	pollGamepad(pad) {
+		const dead = .15;
+		const shape = (v) => Math.abs(v) < dead ? 0 : v;
+		if (!pad) {
+			for (let i = 0; i < 17; i++) if (this.padButtonsDown & 1 << i) this.handleKey(`Pad${i}`, false);
+			this.padButtonsDown = 0;
+			this.padAxesState.lx = 0;
+			this.padAxesState.ly = 0;
+			this.padAxesState.rx = 0;
+			this.padAxesState.ry = 0;
+			return;
+		}
+		for (let i = 0; i < Math.min(17, pad.buttons.length); i++) {
+			const down = pad.buttons[i]?.pressed === true;
+			if (down !== ((this.padButtonsDown & 1 << i) !== 0)) {
+				this.handleKey(`Pad${i}`, down);
+				this.padButtonsDown = down ? this.padButtonsDown | 1 << i : this.padButtonsDown & ~(1 << i);
+			}
+		}
+		this.padAxesState.lx = shape(pad.axes[0] ?? 0);
+		this.padAxesState.ly = shape(pad.axes[1] ?? 0);
+		this.padAxesState.rx = shape(pad.axes[2] ?? 0);
+		this.padAxesState.ry = shape(pad.axes[3] ?? 0);
+	}
+	/** Deadzoned analog sticks: 0 = left {x,y}, 1 = right. */
+	padAxes(stick = 0) {
+		return stick === 0 ? {
+			x: this.padAxesState.lx,
+			y: this.padAxesState.ly
+		} : {
+			x: this.padAxesState.rx,
+			y: this.padAxesState.ry
+		};
+	}
+	/**
+	* Poll the browser Gamepad API every frame (the first connected pad).
+	* Wire once at boot: `engine.input.attachGamepad(engine)`. Headless no-op.
+	*/
+	attachGamepad(engine) {
+		if (typeof navigator === "undefined" || typeof navigator.getGamepads !== "function") return () => {};
+		const disconnect = engine.updated.connect(() => {
+			const pads = navigator.getGamepads();
+			let pad = null;
+			for (const p of pads) if (p?.connected) {
+				pad = p;
+				break;
+			}
+			this.pollGamepad(pad);
+		});
+		const prev = this.detach;
+		this.detach = () => {
+			prev?.();
+			disconnect();
+		};
+		return disconnect;
+	}
 	attachPointer(target, opts) {
 		let buttonsHeld = 0;
 		const onDown = (e) => {
@@ -936,6 +1005,12 @@ var Engine = class {
 	accumulator = 0;
 	disposeScheduler = null;
 	frameStats = new FrameStatsRing();
+	/**
+	* Game-time multiplier: 1 = realtime, 0.5 = slow motion, 0 = frozen
+	* (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
+	* timers, behaviors all breathe together. See `gameplay` `hitStop()`.
+	*/
+	timeScale = 1;
 	constructor(opts = {}) {
 		this.fixedStep = 1 / (opts.fixedHz ?? 60);
 		this.maxFixedSteps = opts.maxFixedStepsPerTick ?? 5;
@@ -1032,7 +1107,7 @@ var Engine = class {
 			this.lastMs = nowMs;
 			return;
 		}
-		const dt = Math.min((nowMs - this.lastMs) / 1e3, MAX_DT_SECONDS);
+		const dt = Math.min((nowMs - this.lastMs) / 1e3, MAX_DT_SECONDS) * this.timeScale;
 		this.lastMs = nowMs;
 		const scene = this._scene;
 		if (!scene) return;
@@ -1228,6 +1303,12 @@ var ParticleSim = class {
 		this.rng = rng;
 		this.data = new Float64Array(Math.max(1, config.maxParticles) * FIELDS);
 	}
+	/** Change the emission rate LIVE (particles/sec; 0 pauses emission) — lets an
+	* emitter toggle on/off at runtime (drift smoke, throttle flames). */
+	setRate(rate) {
+		this.config.rate = rate;
+		if (rate <= 0) this.spawnAccumulator = 0;
+	}
 	get count() {
 		return this.alive;
 	}

package/dist/{particle-sim-CbN4YUuH.d.ts → particle-sim-CwJ5rI_P.d.ts}

@@ -49,6 +49,9 @@ declare class ParticleSim {
   private spawnAccumulator;
   private everSpawned;
   constructor(config: ParticleSimConfig, rng: Rng);
+  /** Change the emission rate LIVE (particles/sec; 0 pauses emission) — lets an
+  * emitter toggle on/off at runtime (drift smoke, throttle flames). */
+  setRate(rate: number): void;
   get count(): number;
   /** True when nothing is alive and at least one particle has ever spawned. */
   get done(): boolean;