incanto 0.4.2 → 0.5.0

package/dist/gameplay.d.ts

@@ -1,5 +1,5 @@
 import { c as JsonValue } from "./schema-CcoWb32N.js";
-import { T as Node, l as PropSchema, n as BehaviorCtor, t as Behavior } from "./behavior-BAQq7HGM.js";
+import { T as Node, l as PropSchema, n as BehaviorCtor, t as Behavior, v as Engine } from "./behavior-CWhW3oa6.js";
 
 //#region src/gameplay/chase.d.ts
 /**
@@ -154,6 +154,11 @@ declare class FollowCamera extends Behavior {
   smoothing: number;
   deadzone: number;
   override onReady(): void;
+  private shakeMag;
+  private shakeT;
+  private shakeFalloff;
+  /** Kick the camera (impacts, explosions). Composes with the follow. */
+  shake(magnitude: number, seconds?: number): void;
   override update(dt: number): void;
 }
 //#endregion
@@ -528,6 +533,112 @@ declare class ZombieAI extends Behavior {
   private pickGoal;
 }
 //#endregion
+//#region src/gameplay/game-flow.d.ts
+/**
+* Reload the CURRENT scene from its source JSON — fresh nodes, reset physics,
+* rewired input. The restart primitive every game-over screen wants.
+*/
+declare function restartScene(engine: Engine): void;
+type GameFlowState = "playing" | "paused" | "gameover" | "won";
+/**
+* The win/lose/restart state machine 6+ examples hand-rolled as `over`/`win`
+* booleans. Attach to any node (the scene root is natural):
+*
+*   const flow = root.behavior as GameFlow;   // script: { "name": "GameFlow" }
+*   flow.gameOver('YOU DIED');                 // freezes time, sticky banner
+*   flow.win('AREA CLEAR');
+*   flow.pause(); flow.resume();
+*
+* While in `gameover`/`won`, pressing `restartAction` (default action name
+* 'restart' — declare it in the scene input map, or leave undeclared and call
+* `flow.restart()` yourself) reloads the scene from source. Banners render
+* through a `%Banner` UiBanner when one exists; otherwise states are silent
+* (drive your own UI off the `flowChanged` signal).
+*/
+declare class GameFlow extends Behavior {
+  static readonly signals: readonly string[];
+  static readonly props: Record<string, {
+    default: string | boolean;
+  }>;
+  /** Input action that restarts from gameover/won (declare it in `input{}`). */
+  restartAction: string;
+  /** Freeze `engine.timeScale` on gameover/won (banner UI keeps rendering). */
+  freezeOnEnd: boolean;
+  /** Where the flow looks for a UiBanner ('' = never). */
+  bannerPath: string;
+  state: GameFlowState;
+  private frozeScale;
+  gameOver(text?: string, color?: string): void;
+  win(text?: string, color?: string): void;
+  pause(): void;
+  resume(): void;
+  restart(): void;
+  private transition;
+  private freeze;
+  private thaw;
+  override update(): void;
+}
+//#endregion
+//#region src/gameplay/juice.d.ts
+/**
+* Game-feel primitives ("juice"): the weapon cooldown, camera shake, screen
+* flash and hit-stop that action examples kept hand-rolling.
+*/
+/**
+* A fire-rate / ability cooldown — replaces the copy-pasted
+* `this.clock += dt * 1000; if (now > nextFire)` pattern:
+*
+*   private gun = new Cooldown(0.2);
+*   override update(dt: number): void {
+*     this.gun.tick(dt);
+*     if (this.engine.input.isPressed('fire') && this.gun.tryUse()) this.shoot();
+*   }
+*/
+declare class Cooldown {
+  readonly seconds: number;
+  private remaining;
+  constructor(seconds: number);
+  /** Advance time. Call once per update with the frame dt. */
+  tick(dt: number): void;
+  get ready(): boolean;
+  /** 0..1 — how far through the cooldown we are (1 = ready). UiBar-friendly. */
+  get progress(): number;
+  /** Consume if ready. Returns whether the action should fire. */
+  tryUse(): boolean;
+  /** Force-ready (pickups that reset your reload). */
+  reset(): void;
+}
+/**
+* Camera shake as a standalone behavior for cameras WITHOUT another script.
+* (FollowCamera has this built in — one script per node.) Composes with any
+* other position writer by applying only the DELTA of its own offset, so the
+* camera returns exactly to where the other writer left it.
+*
+*   (camera.behavior as CameraShake).shake(8);           // pixels (2D) / meters·100 feel (3D: use ~0.2)
+*/
+declare class CameraShake extends Behavior {
+  static readonly props: Record<string, {
+    default: number;
+  }>;
+  /** Seconds a shake takes to decay to zero. */
+  falloff: number;
+  private magnitude;
+  private t;
+  private prev;
+  shake(magnitude: number, seconds?: number): void;
+  override update(dt: number): void;
+}
+/**
+* Full-screen color flash (damage red, pickup white). DOM overlay above
+* everything; headless no-op. Repeated calls restart the fade.
+*/
+declare function screenFlash(color?: string, opacity?: number, seconds?: number): void;
+/**
+* Hit-stop: freeze game time for `seconds` of REAL time, then restore the
+* previous timeScale. Stacking calls extend the freeze instead of fighting.
+*/
+declare function hitStop(engine: Engine, seconds?: number): void;
+//#endregion
 //#region src/gameplay/index.d.ts
 /** Every built-in gameplay behavior, keyed by its registration name. */
 declare const GAMEPLAY_BEHAVIORS: Readonly<Record<string, BehaviorCtor>>;
@@ -540,4 +651,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { Chase, Collector, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, registerGameplayBehaviors };
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, hitStop, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { _ as Health, a as Wander, c as Projectile, d as Oscillate, f as MoveTo, g as DamageOnContact, h as FollowCamera, i as WaveSpawner, l as Pickup, m as Interactable, n as registerGameplayBehaviors, o as Spawner, p as Lifetime, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as Collector, y as Chase } from "./gameplay-Ccruc3Wd.js";
-export { Chase, Collector, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, registerGameplayBehaviors };
+import { C as Health, S as DamageOnContact, T as Chase, _ as screenFlash, a as Wander, b as restartScene, c as Projectile, d as Oscillate, f as MoveTo, g as hitStop, h as Cooldown, i as WaveSpawner, l as Pickup, m as CameraShake, n as registerGameplayBehaviors, o as Spawner, p as Lifetime, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as Interactable, w as Collector, x as FollowCamera, y as GameFlow } from "./gameplay-CDFgSG6z.js";
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, hitStop, registerGameplayBehaviors, restartScene, screenFlash };

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.2";
+const VERSION = "0.5.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;
 	}