incanto 0.31.0 → 0.33.0

package/bin/incanto-play.mjs

@@ -17,6 +17,7 @@ import { dirname, join, resolve } from 'node:path';
  *   pointer <dx> <dy>        look deltas               wheel <dy>
  *   capture [file]           current state as scene JSON (stdout or file)
  *   describe                 one line per node, non-default props only
+ *   framing                  what the camera SEES: on/off screen, lights, overlaps
  *   logs                     engine.log entries since the last call
  *   quit
  *
@@ -56,7 +57,7 @@ if (args.help || !args.scene) {
   console.error(`Usage: incanto-play <scene.json> [--behaviors <file.ts|.js>] [--seed N] [--fixed-hz 60] [--commands <file>]
 
 Headless play: stdin commands (step/press/release/vector/key/mouse/pointer/
-wheel/capture/describe/logs/quit), JSON-line responses on stdout.`);
+wheel/capture/describe/framing/logs/quit), JSON-line responses on stdout.`);
   process.exit(args.help && args.scene !== undefined ? 0 : 1);
 }
 
@@ -175,6 +176,10 @@ function handle(line) {
       case 'describe':
         out({ ok: true, cmd, text: session.describe() });
         break;
+      case 'framing':
+        // what the camera can SEE — on/off screen, lit or black, overlaps
+        out({ ok: true, cmd, text: session.framing() });
+        break;
       case 'logs':
         out({ ok: true, cmd, entries: session.drainLogs() });
         break;
@@ -188,7 +193,7 @@ function handle(line) {
           cmd,
           error: {
             code: 'UNKNOWN_COMMAND',
-            message: `unknown command '${cmd}'. Commands: step press release vector key mouse pointer wheel capture describe logs quit`,
+            message: `unknown command '${cmd}'. Commands: step press release vector key mouse pointer wheel capture describe framing logs quit`,
           },
         });
     }

package/dist/2d.d.ts

@@ -1,7 +1,7 @@
-import { C as RendererStats, S as GameStats, X as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-D_jMpFh8.js";
+import { C as RendererStats, N as Scene$1, S as GameStats, at as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine } from "./behavior-CKwTCjfR.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-BJb-CWfA.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
-import { t as LoadSceneOptions } from "./loader-BYBrqTxP.js";
+import { t as LoadSceneOptions } from "./loader-COn5fS0o.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -144,6 +144,22 @@ declare class CharacterBody2D extends PhysicsBody2D {
   /** @internal Updated by Physics2D.moveAndSlide. */
   _grounded: boolean;
   moveAndSlide(): void;
+  /** @internal Set by the physics step from the KCC's resolved collisions. */
+  _onWall: number;
+  /** @internal */
+  _onCeiling: boolean;
+  /**
+  * Touching a wall, and which side (-1 left, +1 right, 0 neither).
+  *
+  * Wall jump and wall slide are unbuildable without it — not awkward to build,
+  * impossible: `isOnFloor()` was the only surface a character could report, so
+  * even a hand-written behavior had nothing to ask.
+  */
+  isOnWall(): boolean;
+  /** -1 the wall is to the left, +1 to the right, 0 no wall. */
+  wallSide(): number;
+  /** Head hit something — cut the jump short, the way every platformer does. */
+  isOnCeiling(): boolean;
   isOnFloor(): boolean;
 }
 //#endregion
@@ -321,6 +337,11 @@ interface Game2D {
   sourceJson: SceneJson;
   renderer: GameRenderer;
   physics: Physics2D | null;
+  /**
+  * The node under a screen pixel, or null. The raycast the renderer already
+  * does — reachable now without holding the renderer.
+  */
+  pick(x: number, y: number): Node | null;
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
   /**
@@ -463,18 +484,54 @@ declare class Camera2D extends Node2D {
 * - `platformer`: x movement + gravity (from the scene `physics.gravity[1]`,
 *   default 980) + jump (`jumpHeight` px → impulse √(2·g·h))
 * - `topDown`: full-axis movement, no gravity
+*
+* ## Why the extra platformer props exist
+*
+* A jump that only works while `isOnFloor()` is true feels BROKEN, and players
+* do not report it as "the coyote time is missing" — they report the game as
+* unresponsive. The whole schema used to be five props, so a JSON-only game got
+* a character that felt wrong and could not drive `AnimatedSprite2D.play('run')`
+* either. `examples/platformer-2d` hand-rolls all of this in a 541-line
+* behavior; these are those constants, as props.
+*
+* Every one defaults to OFF (0 / 1 / false), so an existing scene behaves
+* exactly as before until it asks for something.
 */
 declare class CharacterController2D extends Node {
   static override readonly typeName: string;
   static readonly props: PropSchema;
+  static readonly signals: readonly string[];
   mode: string;
   maxSpeed: number;
   /** Pixels (platformer mode). */
   jumpHeight: number;
   moveAction: string;
   jumpAction: string;
+  coyoteSeconds: number;
+  jumpBufferSeconds: number;
+  jumpCutMultiplier: number;
+  maxJumps: number;
+  dashSpeed: number;
+  dashSeconds: number;
+  dashAction: string;
+  wallSlideSpeed: number;
+  wallJumpImpulse: number[];
+  /** What the character is doing — drive `AnimatedSprite2D.play(state)` off it. */
+  state: "idle" | "run" | "jump" | "fall" | "wallSlide" | "dash";
+  private coyoteLeft;
+  private bufferLeft;
+  private jumpsUsed;
+  private dashLeft;
+  private dashDir;
+  private rising;
   override onReady(): void;
   override fixedUpdate(dt: number): void;
+  /**
+  * Emits `movementStateChanged(state)` on a change — the 3D sibling has had
+  * this since it shipped, and it is what drives `AnimatedSprite2D.play(...)`
+  * from scene JSON instead of a behavior polling velocities.
+  */
+  private setState;
 }
 //#endregion
 //#region src/2d/nodes/color-rect-2d.d.ts

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-z5XaB1p5.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-tkR_8tWg.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-D9wquBvK.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-D2QU5x7S.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-FIJtNbub.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-DjXR5DMu.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { C as RendererStats, S as GameStats, X as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-D_jMpFh8.js";
+import { C as RendererStats, N as Scene$1, S as GameStats, at as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine } from "./behavior-CKwTCjfR.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-BJb-CWfA.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
-import { t as LoadSceneOptions } from "./loader-BYBrqTxP.js";
+import { t as LoadSceneOptions } from "./loader-COn5fS0o.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-BwhqPD3i.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-DUw9mir9.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -488,6 +488,16 @@ interface CreateGame3DOptions {
   /** Keep the frame rate by rendering fewer pixels while frames run slow
   * (default ON). `false` pins the resolution — screenshots, capture, tests. */
   adaptiveResolution?: boolean;
+  /**
+  * Keep the drawing buffer readable so the canvas can be screenshot.
+  *
+  * WebGL clears it the instant a frame composites, so `toDataURL()` — and every
+  * screenshot built on it — is BLANK without this. Off by default: it costs a
+  * buffer copy per frame and only a run that means to look at the output should
+  * pay for it. `environment.rendering.preserveDrawingBuffer` does the same from
+  * the scene.
+  */
+  preserveDrawingBuffer?: boolean;
   resolveScene?: LoadSceneOptions["resolveScene"];
   /**
   * Boot progress, for the loading screen an app already has.
@@ -534,6 +544,11 @@ interface Game3D {
   sourceJson: SceneJson;
   renderer: GameRenderer;
   physics: Physics3D | null;
+  /**
+  * The node under a screen pixel, or null. The raycast the renderer already
+  * does — reachable now without holding the renderer.
+  */
+  pick(x: number, y: number): Node | null;
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
   /**
@@ -2998,6 +3013,16 @@ interface Renderer3DOptions {
   * the resolution — for screenshots, video capture and pixel-diff tests.
   */
   adaptiveResolution?: boolean;
+  /**
+  * Keep the drawing buffer readable so the canvas can be SCREENSHOT.
+  *
+  * WebGL clears it the moment a frame composites, so `canvas.toDataURL()` and
+  * anything built on it (a Playwright screenshot, a pixel-diff test) comes
+  * back blank without this. Off by default — it costs a buffer copy per frame
+  * and only a run that intends to look at the output should pay it. The scene
+  * can ask for it too: `environment.rendering.preserveDrawingBuffer`.
+  */
+  preserveDrawingBuffer?: boolean;
 }
 /**
 * WebGL presentation layer: subscribes to `engine.updated`, mirrors the active

package/dist/3d.js

@@ -1,9 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-BftxM_It.js";
-import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-DqOjMBUS.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, V as movementState, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets--DigHNg4.js";
+import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-BpQCbABv.js";
+import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-sFuTLqjD.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, V as movementState, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-CQtEGogB.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CnPygVGo.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DF8npb1O.js";
 //#region src/3d/environment-runtime.ts
 /**
 * Live environment editing — the renderer re-applies `scene.environment`

package/dist/{behavior-D_jMpFh8.d.ts → behavior-CKwTCjfR.d.ts}

@@ -298,6 +298,14 @@ declare class AudioBuses {
   /** Final gain for a sound on `bus` with its own `sourceVolume` (all clamped). */
   effectiveVolume(bus: BusName, sourceVolume: number): number;
   /** Clamp + finite-guard a new value; emit only on a real change. */
+  /**
+  * Write THEN emit.
+  *
+  * This used to emit from inside the expression assigning the field, so every
+  * listener of `changed` read the OLD value — including the thing the signal
+  * exists for ("live re-gain of playing sounds"), which therefore re-gained to
+  * the volume you just left.
+  */
   private assign;
 }
 //#endregion
@@ -595,6 +603,25 @@ declare class InputMap {
   private detach;
   /** Load (or extend with) scene-JSON action declarations. Hard-validates shape. */
   declare(decls: Record<string, unknown>): void;
+  /**
+  * Where the pointer is, in CANVAS pixels (top-left origin), or null when it
+  * has never been over the canvas.
+  *
+  * This is what a click-driven game asks for. `pointerDelta()` answers "how far
+  * did the mouse move" — the mouse-look question — and for a whole class of
+  * genres that is the wrong question and the only one the engine could answer.
+  * Pair it with `renderer.pick(x, y)` to get the node under the cursor.
+  */
+  pointerPosition(): {
+    x: number;
+    y: number;
+  } | null;
+  /**
+  * @internal Feed a pointer position. `target` scales client → canvas pixels
+  * so a CSS-stretched canvas still reports coordinates its renderer can use.
+  */
+  setPointerPosition(clientX: number, clientY: number, target?: HTMLElement): void;
+  private pointerPos;
   /** Feed a key state change (code = KeyboardEvent.code, e.g. 'Space', 'KeyW'). */
   handleKey(code: string, isDown: boolean): void;
   private readonly injectedDown;
@@ -699,6 +726,17 @@ declare class InputMap {
   isPressed(action: string): boolean;
   justPressed(action: string): boolean;
   justReleased(action: string): boolean;
+  /**
+  * Mouse button state WITHOUT declaring an action for it.
+  *
+  * A click on a tile is not a bindable action — there is no key to remap, and
+  * asking a match-3 to declare `"click": { "keys": ["Mouse0"] }` in every scene
+  * is ceremony. Buttons already live in the key set as `Mouse0`/`Mouse1`/…;
+  * these read them directly. 0 left, 1 middle, 2 right.
+  */
+  mousePressed(button?: number): boolean;
+  mouseJustPressed(button?: number): boolean;
+  mouseJustReleased(button?: number): boolean;
   /** Normalized direction for a vector2 action (y-down: up = -y). */
   getVector(action: string): {
     x: number;
@@ -753,6 +791,89 @@ declare class Scene {
   toJSON(): SceneJson;
 }
 //#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/settings.d.ts
+/** One of three tiers, resolved once at boot and adjustable in an options menu. */
+type QualityTier = "low" | "medium" | "high";
+interface SettingsValues {
+  master: number;
+  sfx: number;
+  music: number;
+  muted: boolean;
+  quality: QualityTier;
+  /** Mouse/stick look sensitivity multiplier. */
+  sensitivity: number;
+  invertY: boolean;
+  /** Reduce camera shake, flashes and other motion. */
+  reduceMotion: boolean;
+}
+/** What a device probe can see without a GPU context. */
+interface DeviceHints {
+  hardwareConcurrency?: number;
+  deviceMemory?: number;
+  coarsePointer?: boolean;
+  maxTextureSize?: number;
+}
+/**
+* A default tier from what the browser will admit to.
+*
+* Deliberately crude: this picks a STARTING point, and the options menu is the
+* real answer. A phone that reports four cores and a coarse pointer should not
+* open on the setting tuned for a desktop GPU.
+*/
+declare function suggestQuality(hints: DeviceHints): QualityTier;
+/** Read what this environment will tell us, safely, without touching WebGL. */
+declare function readDeviceHints(): DeviceHints;
+declare class Settings {
+  /** Fires after any change, with the key that changed. */
+  readonly changed: Signal<[keyof SettingsValues]>;
+  private readonly store;
+  private readonly values;
+  constructor(namespace?: string, store?: SaveStore);
+  get<K extends keyof SettingsValues>(key: K): SettingsValues[K];
+  set<K extends keyof SettingsValues>(key: K, value: SettingsValues[K]): void;
+  /** Every value at once — for an options screen, or a save-file dump. */
+  all(): SettingsValues;
+  /** Back to defaults, on disk too. */
+  reset(): void;
+  /**
+  * Push the saved volumes into the engine's buses, and keep writing them back
+  * whenever anything changes them.
+  *
+  * The subscription is the point: a game that sets `engine.audio.music = 0.4`
+  * from a slider has already persisted it, without knowing this class exists.
+  */
+  bindAudio(audio: AudioBuses): () => void;
+}
+/**
+* What a quality tier MEANS, as an environment patch.
+*
+* Only the levers that actually cost: shadows, post, clouds, and the resolution
+* the renderer draws at. Deliberately an `environment` patch, because
+* `setEnvironment3D(engine, patch)` already applies one live and validated —
+* this is not a second rendering pipeline, it is three presets for the one that
+* exists.
+*/
+declare function qualityEnvironment(tier: QualityTier): Record<string, JsonValue>;
+//#endregion
 //#region src/core/stats.d.ts
 /**
 * Performance-stats shapes — pure data, importable everywhere (core stays
@@ -824,9 +945,27 @@ declare class Engine {
   readonly rng: Rng;
   /** The engine log channel (debug overlay + headless harness tail this). */
   readonly log: LogManager;
+  /**
+  * Screen pixel → the node under it, when a renderer has offered one.
+  *
+  * The raycast has always existed (`Renderer3D.pick` / `Renderer2D.pick`) and
+  * was reachable only from whoever held the renderer — so a Behavior, which
+  * holds a node, could not use it. Every mouse-driven genre needs exactly this
+  * and had no way to ask. Instance-scoped, set by the renderer on construction
+  * and cleared on dispose; null when nothing renders (headless).
+  */
+  picker: ((x: number, y: number) => Node | null) | null;
   /** Global volume buses — `master` × `sfx`/`music` gain + `muted`. AudioPlayer
   *  routes its volume through this; games set it for global volume/mute. */
   readonly audio: AudioBuses;
+  /**
+  * Persisted player settings — volume, quality, sensitivity.
+  *
+  * `createSaveStore` was good and had zero callers, so every game's volume
+  * reset on reload. Reading it here costs nothing (localStorage, once) and
+  * `bindAudio` makes the volumes write themselves.
+  */
+  readonly settings: Settings;
   /** Low-latency procedural-SFX player (WebAudio, headless-safe). AudioPlayer
   *  presets play through it; games may call `engine.sfx.play(...)` directly. */
   readonly sfx: SfxEngine;
@@ -1035,4 +1174,4 @@ declare function registeredBehaviors(): string[];
 /** Test isolation helper. */
 declare function clearBehaviors(): void;
 //#endregion
-export { LogEntry as $, VoicePreset as A, SfxParams as B, RendererStats as C, SfxPlayOptions as D, SfxEngine as E, Vec3 as F, MusicManager as G, SynthOptions as H, spatialGain as I, AudioBuses as J, MusicTrack as K, spatialPan as L, ROLLOFF_MODELS as M, RolloffModel as N, isAudioContextAvailable as O, SpatialParams as P, SceneTree as Q, SFX_PRESETS as R, GameStats as S, InputMap as T, synthSfx as U, SfxWave as V, MusicBackend as W, Node as X, BusName as Y, NodeLifecycle as Z, registeredTypes as _, registerBehavior as a, Scheduler as b, PropDef as c, createNode as d, LogLevel as et, getNodeSchema as f, registerNode as g, mergeStaticSignals as h, getBehavior as i, Listener as j, Voice as k, PropSchema as l, getNodeType as m, BehaviorCtor as n, Signal as nt, registeredBehaviors as o, getNodeSignals as p, PlayMusicOptions as q, clearBehaviors as r, SignalListener as rt, NodeCtor as s, Behavior as t, LogManager as tt, clearRegistry as u, Engine as v, Scene as w, EngineStats as x, EngineOptions as y, SFX_PRESET_NAMES as z };
+export { MusicBackend as $, suggestQuality as A, Listener as B, RendererStats as C, SettingsValues as D, Settings as E, SfxEngine as F, spatialGain as G, RolloffModel as H, SfxPlayOptions as I, SFX_PRESET_NAMES as J, spatialPan as K, isAudioContextAvailable as L, createSaveStore as M, Scene as N, qualityEnvironment as O, InputMap as P, synthSfx as Q, Voice as R, GameStats as S, QualityTier as T, SpatialParams as U, ROLLOFF_MODELS as V, Vec3 as W, SfxWave as X, SfxParams as Y, SynthOptions as Z, registeredTypes as _, registerBehavior as a, Node as at, Scheduler as b, PropDef as c, LogEntry as ct, createNode as d, Signal as dt, MusicManager as et, getNodeSchema as f, SignalListener as ft, registerNode as g, mergeStaticSignals as h, getBehavior as i, BusName as it, SaveStore as j, readDeviceHints as k, PropSchema as l, LogLevel as lt, getNodeType as m, BehaviorCtor as n, PlayMusicOptions as nt, registeredBehaviors as o, NodeLifecycle as ot, getNodeSignals as p, SFX_PRESETS as q, clearBehaviors as r, AudioBuses as rt, NodeCtor as s, SceneTree as st, Behavior as t, MusicTrack as tt, clearRegistry as u, LogManager as ut, Engine as v, DeviceHints as w, EngineStats as x, EngineOptions as y, VoicePreset as z };

package/dist/{create-game-z5XaB1p5.js → create-game-D2QU5x7S.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { m as diagnose, n as loadScene, o as computeViewport, s as resolveViewport, y as registerBehavior } from "./loader-BlaRQGaA.js";
-import { l as AudioPlayer, u as Engine } from "./register-Dzkd6-os.js";
+import { m as diagnose, n as loadScene, o as computeViewport, s as resolveViewport, y as registerBehavior } from "./loader-Buk8Bu1h.js";
+import { h as Engine, m as AudioPlayer } from "./register-CscIzJEO.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-ByzfDPyu.js";
-import { n as registerGameplayBehaviors } from "./gameplay-BftxM_It.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-tkR_8tWg.js";
+import { n as registerGameplayBehaviors } from "./gameplay-BpQCbABv.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-FIJtNbub.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-D9wquBvK.js";
+import { n as enablePhysics2D } from "./physics-2d-DjXR5DMu.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**
@@ -269,13 +269,16 @@ var Renderer2D = class {
 		this.assets = opts.assets ?? new AssetStore2D(void 0, this.engine);
 		const rendering = resolveRendering(opts.engine.scene?.environment, {
 			antialias: true,
-			pixelRatio: 1
+			pixelRatio: 1,
+			preserveDrawingBuffer: false
 		}, globalThis.devicePixelRatio ?? 1, opts);
 		this.webgl = new WebGLRenderer({
 			canvas: opts.canvas,
-			antialias: rendering.antialias
+			antialias: rendering.antialias,
+			preserveDrawingBuffer: rendering.preserveDrawingBuffer
 		});
 		this.webgl.info.autoReset = false;
+		this.engine.picker = (x, y) => this.pick(x, y);
 		this.webgl.setPixelRatio(rendering.pixelRatio);
 		this.webgl.info.autoReset = false;
 		this.debugLines = new LineSegments(new BufferGeometry(), new LineBasicMaterial({
@@ -483,6 +486,7 @@ var Renderer2D = class {
 		};
 	}
 	dispose() {
+		if (this.engine.picker) this.engine.picker = null;
 		this.disconnect();
 		for (const scene of [this.worldScene, this.uiScene]) scene.traverse((obj) => {
 			const mesh = obj;
@@ -540,6 +544,7 @@ async function createGame2D(opts) {
 	const keyboard = opts.keyboard ?? (typeof window !== "undefined" ? window : false);
 	if (keyboard) engine.input.attachKeyboard(keyboard);
 	cleanups.push(wireAudioUnlock(engine, scene.root, opts.canvas));
+	cleanups.push(engine.settings.bindAudio(engine.audio));
 	const touchMode = opts.touch ?? "auto";
 	if (touchMode !== false) {
 		const host = opts.touchContainer ?? opts.canvas.parentElement ?? null;
@@ -626,6 +631,9 @@ async function createGame2D(opts) {
 		sourceJson,
 		renderer,
 		physics,
+		pick(x, y) {
+			return engine.picker?.(x, y) ?? null;
+		},
 		stats() {
 			return {
 				triangles: 0,

package/dist/{create-game-DqOjMBUS.js → create-game-sFuTLqjD.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { m as diagnose, n as loadScene, y as registerBehavior } from "./loader-BlaRQGaA.js";
-import { l as AudioPlayer, u as Engine } from "./register-Dzkd6-os.js";
+import { m as diagnose, n as loadScene, y as registerBehavior } from "./loader-Buk8Bu1h.js";
+import { h as Engine, m as AudioPlayer } from "./register-CscIzJEO.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as poseFromRenderer, i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-ByzfDPyu.js";
-import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-BftxM_It.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-BpQCbABv.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets--DigHNg4.js";
-import { n as enablePhysics3D } from "./physics-3d-CnPygVGo.js";
+import { E as Camera3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-CQtEGogB.js";
+import { n as enablePhysics3D } from "./physics-3d-DF8npb1O.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
@@ -1554,13 +1554,19 @@ var Renderer3D = class {
 		this.assets = opts.assets ?? new AssetStore3D(this.engine);
 		const rendering = resolveRendering(opts.engine.scene?.environment, {
 			antialias: true,
-			pixelRatio: Math.min(globalThis.devicePixelRatio ?? 1, 2)
-		}, globalThis.devicePixelRatio ?? 1, { pixelRatio: opts.pixelRatio });
+			pixelRatio: Math.min(globalThis.devicePixelRatio ?? 1, 2),
+			preserveDrawingBuffer: false
+		}, globalThis.devicePixelRatio ?? 1, {
+			pixelRatio: opts.pixelRatio,
+			preserveDrawingBuffer: opts.preserveDrawingBuffer
+		});
 		this.webgl = new WebGLRenderer({
 			canvas: opts.canvas,
-			antialias: rendering.antialias
+			antialias: rendering.antialias,
+			preserveDrawingBuffer: rendering.preserveDrawingBuffer
 		});
 		this.webgl.info.autoReset = false;
+		this.engine.picker = (x, y) => this.pick(x, y);
 		this.basePixelRatio = rendering.pixelRatio;
 		this.webgl.setPixelRatio(rendering.pixelRatio);
 		this.adaptive = opts.adaptiveResolution === false ? null : new AdaptiveResolution();
@@ -2077,6 +2083,7 @@ var Renderer3D = class {
 		this.webgl.shadowMap.needsUpdate = true;
 	}
 	dispose() {
+		if (this.engine.picker) this.engine.picker = null;
 		this.disconnect();
 		this.threeScene.traverse((obj) => {
 			const mesh = obj;
@@ -2194,7 +2201,8 @@ async function createGame3D(opts) {
 		canvas: opts.canvas,
 		engine,
 		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {},
-		...opts.adaptiveResolution !== void 0 ? { adaptiveResolution: opts.adaptiveResolution } : {}
+		...opts.adaptiveResolution !== void 0 ? { adaptiveResolution: opts.adaptiveResolution } : {},
+		...opts.preserveDrawingBuffer !== void 0 ? { preserveDrawingBuffer: opts.preserveDrawingBuffer } : {}
 	});
 	await report(.14, "renderer");
 	const wantDebug = opts.debug ?? false;
@@ -2254,6 +2262,7 @@ async function createGame3D(opts) {
 			opts.onProgress?.(.16 + f * .82, "shaders");
 		});
 	} catch {}
+	cleanups.push(engine.settings.bindAudio(engine.audio));
 	await report(1, "ready");
 	function disposeGame() {
 		teardown([
@@ -2274,6 +2283,9 @@ async function createGame3D(opts) {
 		assetErrors() {
 			return renderer.assets?.errors() ?? [];
 		},
+		pick(x, y) {
+			return engine.picker?.(x, y) ?? null;
+		},
 		stats() {
 			return {
 				triangles: 0,

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { C as RendererStats, et as LogLevel, v as Engine } from "./behavior-D_jMpFh8.js";
+import { C as RendererStats, lt as LogLevel, v as Engine } from "./behavior-CKwTCjfR.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */

package/dist/{duplicate-KRPtUtzl.js → duplicate-BgnG1Lqz.js}

@@ -1,4 +1,4 @@
-import { i as serializeNode, t as buildNodeJson } from "./loader-BlaRQGaA.js";
+import { i as serializeNode, t as buildNodeJson } from "./loader-Buk8Bu1h.js";
 //#region src/core/order-groups.ts
 const ORDER_GROUP_BASE = {
 	background: -2e3,

package/dist/editor.js

@@ -1075,6 +1075,41 @@ var dt = {
 				en: "Child of HudLayer. Set text/size/color/background; disabled greys it out. Emits the 'pressed' signal (behaviors: node.on('pressed', ...)); press() triggers it programmatically (gamepad menus, tests).",
 				ko: "HudLayer의 자식. text/size/color/background를 설정하고 disabled로 비활성화합니다. 'pressed' 시그널을 내며(비헤이비어에서 node.on('pressed', ...)), press()로 코드에서도 누를 수 있습니다(게임패드 메뉴, 테스트)."
 			}),
+			F("UiPanel", {
+				en: "A box that holds other widgets — the thing a menu, options screen or inventory actually is.",
+				ko: "다른 위젯을 담는 상자 — 메뉴·설정 화면·인벤토리가 실제로 이것입니다."
+			}, {
+				en: "Child of HudLayer. Widgets under it mount INSIDE it, so tree structure becomes screen structure; panels nest. layout column|row|grid with columns (an inventory is a grid panel, one child per slot), plus gap/padding/background/radius/width/height/border. width or height 0 = size to the contents.",
+				ko: "HudLayer의 자식. 그 아래 위젯들이 이 안에 마운트되어 트리 구조가 화면 구조가 됩니다(중첩 가능). layout은 column|row|grid이고 columns와 함께 씁니다(인벤토리 = grid 패널, 슬롯당 자식 하나). gap/padding/background/radius/width/height/border 지원. width·height가 0이면 내용에 맞춰집니다."
+			}),
+			F("UiImage", {
+				en: "A picture in the HUD — item icons, portraits, a logo.",
+				ko: "HUD 안의 그림 — 아이템 아이콘, 초상화, 로고."
+			}, {
+				en: "src takes a url or a $assetKey (declare the icon once like any other asset). fit contain|cover|fill; tint multiplies through the picture, which is how an unaffordable item greys out in one prop; opacity for disabled states.",
+				ko: "src는 url 또는 $assetKey(아이콘도 다른 에셋처럼 한 번만 선언). fit은 contain|cover|fill, tint는 그림에 곱해져서 살 수 없는 아이템을 프롭 하나로 회색 처리합니다. opacity로 비활성 표현."
+			}),
+			F("UiSlider", {
+				en: "A value the player sets — volume, sensitivity, difficulty.",
+				ko: "플레이어가 조절하는 값 — 볼륨, 감도, 난이도."
+			}, {
+				en: "Emits changed(value). label/value/min/max/step/width/color. Setting .value from a behavior updates the control WITHOUT re-emitting, so restoring a saved setting does not fire the handler that saved it.",
+				ko: "changed(value) 시그널. label/value/min/max/step/width/color. 비헤이비어에서 .value를 설정하면 컨트롤만 갱신되고 changed는 다시 발생하지 않습니다 — 저장된 설정을 복원할 때 저장 핸들러가 다시 도는 것을 막습니다."
+			}),
+			F("UiToggle", {
+				en: "An on/off switch — mute, invert-Y, fullscreen.",
+				ko: "켜기/끄기 스위치 — 음소거, Y축 반전, 전체화면."
+			}, {
+				en: "Emits changed(boolean). label/value. Same no-re-emit rule as UiSlider when set from code.",
+				ko: "changed(boolean) 시그널. label/value. 코드에서 설정할 때 재발생하지 않는 규칙은 UiSlider와 같습니다."
+			}),
+			F("UiSelect", {
+				en: "One of several — quality, resolution, language.",
+				ko: "여러 개 중 하나 — 품질, 해상도, 언어."
+			}, {
+				en: "options is a comma-separated list (\"low,medium,high\"); value is the current one. Emits changed(value).",
+				ko: "options는 쉼표로 구분된 목록(\"low,medium,high\"), value가 현재 선택입니다. changed(value) 시그널."
+			}),
 			F("UiDialogue", {
 				en: "A typewriter dialogue box with a queue and choice buttons — the RPG conversation layer.",
 				ko: "타자기 효과·큐·선택지 버튼을 갖춘 대화창 — RPG 대화 레이어."

package/dist/{environment-presets--DigHNg4.js → environment-presets-CQtEGogB.js}

@@ -1,10 +1,10 @@
-import { t as registerCoreNodes } from "./register-Dzkd6-os.js";
+import { t as registerCoreNodes } from "./register-CscIzJEO.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-CJdGpT2V.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-BftxM_It.js";
+import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-BpQCbABv.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";