incanto 0.65.0 → 0.67.0

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-CmMuQ6CL.js";
+import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats, x as EngineOptions } from "./behavior-ZnfzKDo3.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
 import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-CTB441z4.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BrEHwbK1.js";
+import { t as LoadSceneOptions } from "./loader-DyT30ArB.js";
+import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BNUHo0JF.js";
 import { n as PathGrid } from "./pathfinding-_fGrCFmH.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
@@ -133,6 +133,31 @@ interface AnimationEntry {
 */
 declare class AssetStore3D {
   private readonly engine;
+  /**
+  * One geometry and one material per distinct SHAPE and per distinct look.
+  *
+  * `MeshInstance3D._createObject3D` used to `new BoxGeometry()` and
+  * `new MeshPhysicalMaterial()` for every node, even when byte-identical.
+  * Three identical nodes reported `geometry shared? false false / material
+  * shared? false false`, with distinct uuids. Measured at 3,200 units, all
+  * three runs at identical 3,209 draw calls / 1,741,932 triangles and an
+  * identical screenshot:
+  *
+  * ```
+  * per-node geometry + material   31.0 ms wall   (renderMs 27.3)
+  * share one geometry             27.0 ms
+  * + share two materials          15.4 ms        <- 2x the headroom
+  * ```
+  *
+  * 13.1 ms of that 26.5 ms cliff was GPU state churn from per-node objects,
+  * and none of it was visible headlessly: with no renderer `_syncObject3D`
+  * never runs, so the bench measured 55 ns/node instead of ~2,000.
+  *
+  * Renderer-scoped, deliberately — module-level state is the predecessor's
+  * fatal flaw and two games in one page must not share a cache.
+  */
+  readonly meshGeometries: Map<string, unknown>;
+  readonly meshMaterials: Map<string, unknown>;
   private readonly models;
   private readonly animations;
   private readonly modelKeys;
@@ -358,6 +383,33 @@ declare class StaticBody3D extends PhysicsBody3D {
 /** Sensor volume emitting `triggerEnter(other)` / `triggerExit(other)`. */
 declare class Area3D extends PhysicsBody3D {
   static override readonly typeName: string;
+  /**
+  * Who is inside RIGHT NOW — the standing answer behind the enter/exit pair.
+  *
+  * Enter and exit tell you about crossings; a pressure plate, a capture point,
+  * a "how many enemies are in the blast" count and a shop trigger all want
+  * OCCUPANCY. Without this every one of them kept a private `Set` fed by the
+  * two signals, and had to guard it, because a body that is teleported or
+  * freed inside a sensor does not reliably announce its exit. Physics already
+  * knows; now it says.
+  *
+  * ```ts
+  * const load = this.area.overlapping()
+  *   .reduce((kg, b) => kg + ((b as RigidBody3D).mass ?? 0), 0);
+  * door.open = load >= 60;
+  * ```
+  *
+  * It reports everything the solver says is inside, STATIC WORLD INCLUDED — a
+  * plate laid into the floor genuinely contains the floor. Pass a group to ask
+  * the question you usually mean:
+  *
+  * ```ts
+  * area.overlapping('crate')   // only things tagged `crate`
+  * ```
+  *
+  * Empty in a scene with no physics world.
+  */
+  overlapping(group?: string): PhysicsBody3D[];
 }
 /** Dynamic simulated body. */
 declare class RigidBody3D extends PhysicsBody3D {
@@ -370,6 +422,14 @@ declare class RigidBody3D extends PhysicsBody3D {
   restitution: number;
   /** m/s, y-up. Read back every step; write to launch. */
   linearVelocity: number[];
+  /**
+  * rad/s about each world axis. Read back every step; write to spin.
+  *
+  * A puzzle builder could neither launch a spinning body nor read how fast a
+  * lever was swinging — only its angle, differenced by hand — because this had
+  * no counterpart to `linearVelocity`. `fixedRotation` pins it at zero.
+  */
+  angularVelocity: number[];
   /** @internal set by Physics3D */
   _physics3d: Physics3D | null;
   /** World-space impulse (kg·m/s) — the floating-capsule controller's verb. */
@@ -539,6 +599,27 @@ declare class Physics3D {
   velocityOf(node: PhysicsBody3D): [number, number, number];
   /** Create newly-arrived joints; tear down departed ones. */
   private syncJoints;
+  /** Who is currently inside each sensor/body, maintained from the event drain. */
+  private readonly overlaps;
+  private trackOverlap;
+  /**
+  * Forget every overlap whose node has left the tree.
+  *
+  * The lazy drop inside `overlapping()` only cleans the SETS of a key someone
+  * asks about, and only when they ask. This clears the KEYS, which is where the
+  * dead nodes were pinned.
+  */
+  /** Drop one node from the overlap map, both as a key and as a member. */
+  private forgetOverlaps;
+  private pruneOverlaps;
+  /**
+  * The bodies currently overlapping `node` — the standing answer behind
+  * `triggerEnter`/`triggerExit`.
+  *
+  * Freed nodes are dropped on read rather than tracked, so a hazard that
+  * despawns inside a plate cannot leave a ghost holding a door open.
+  */
+  overlapping(node: PhysicsBody3D): PhysicsBody3D[];
   /**
   * World-space raycast (meters). `exclude` skips that body's collider —
   * ground probes from inside a capsule need it. `opts.staticOnly` hits ONLY the
@@ -637,6 +718,18 @@ interface CreateGame3DOptions {
   */
   editor?: boolean | EditorSwitchOptions;
   seed?: number;
+  /**
+  * Namespace this game's persisted settings — volume, language, quality tier.
+  *
+  * They are keyed `incanto:<namespace>:<key>` in the browser's storage and
+  * defaulted to `settings` for everyone, so two Incanto games on one domain
+  * shared one options screen. Measured: game A's player sets `renderScale
+  * 0.25, muted, quality low`; game B, whose source never mentions settings,
+  * boots at a 480x232 drawing buffer and silent.
+  *
+  * `SaveSlots(namespace)` already takes one for exactly this reason.
+  */
+  settings?: EngineOptions["settings"];
   fixedHz?: number;
   pixelRatio?: number;
   /** Keep the frame rate by rendering fewer pixels while frames run slow
@@ -686,7 +779,22 @@ interface GameRenderer {
 }
 interface Game3D {
   engine: Engine;
-  scene: Scene$1;
+  /**
+  * The LIVE scene — a getter over `engine.scene`, not a snapshot.
+  *
+  * This used to be the scene captured at boot. `Engine.setScene` calls
+  * `this._scene?.root.free()`, so after any swap the old handle was not merely
+  * stale, it was EMPTIED — and a single-scene game reaches that through
+  * `flow.restart()`, which `incanto-hud.md` wires to a Start button. Measured:
+  *
+  *   before swap  game.scene.root.children = 2   engine.scene = 2
+  *   after  swap  game.scene.root.children = 0   engine.scene = 2
+  *   game.scene.root.getNode('Flow')  ->  No node at 'Flow'. Children here: [].
+  *
+  * `game.engine.scene` always worked and three skills use it, so there were
+  * two handles with one name and no note saying which was which.
+  */
+  get scene(): Scene$1;
   /**
   * The AUTHORED scene this game booted from — the JSON, not the live tree.
   *
@@ -982,19 +1090,25 @@ declare class Environment3D {
 }
 //#endregion
 //#region src/3d/environment-runtime.d.ts
+declare function setEnvironment3D(engine: Engine, patch: JsonObject, opts?: {
+  rebaseTierKeys?: boolean;
+}): void;
 /**
-* Live environment editing — the renderer re-applies `scene.environment`
-* every frame (cheap when unchanged), so changing the LOOK at runtime is
-* just writing that object. This helper does it safely:
+* Apply a quality tier — the only caller that may RESET as well as patch.
 *
-*   setEnvironment3D(engine, { sky: { elevationDeg: 4 }, exposure: 0.8 });
-*   setEnvironment3D(engine, { fog: null });          // null DELETES a key
+* A tier is re-applied every time the player moves the slider, so it cannot
+* compose with what the last one left behind: `low` strips the author's bloom,
+* and `high` then has nothing to put back. This re-derives the four tier-owned
+* stages from the scene FILE first, so every tier is reversible, and so a stage
+* the author never wrote can never appear — the contract `settings.ts` states
+* and `incanto-performance.md` promises: *the tier can only take things away.*
 *
-* - one-level deep merge (patching `sky.elevationDeg` keeps the other sky keys)
-* - hard-validates the merged result NOW (in your call stack), so a bad patch
-*   throws where you wrote it — never inside the render loop
+* Measured before this, on a scene with no `bloom` and no `post` in its JSON:
+* `high` and `medium` both rendered five GL passes at 3.3 ms where `low`
+* rendered one at 1.24 ms — 62% of the frame on a chain the game never asked
+* for, and `environment.bloom` read back `{strength: 0.8, threshold: 1}`.
 */
-declare function setEnvironment3D(engine: Engine, patch: JsonObject): void;
+declare function applyQualityTier3D(engine: Engine, patch: JsonObject): void;
 //#endregion
 //#region src/3d/model-verdict.d.ts
 /**
@@ -1264,6 +1378,25 @@ declare class CharacterController3D extends Node3D {
   airControl: number;
   fallGravity: number;
   floatHeight: number;
+  /**
+  * How high a step the PLAYER walks up without jumping (0 = off).
+  *
+  * The hover spring holds the capsule a fixed distance above whatever is
+  * DIRECTLY below it, so a vertical face stopped the player dead at about
+  * 0.2 m — while `CharacterBody3D.stepHeight` let every enemy climb 0.35 m.
+  * The docs said the player did not need this ("it floats over small ledges
+  * already"); it floats over 18 cm ones.
+  *
+  * This probes just AHEAD of the capsule in the direction of travel: if the
+  * ground there is higher, but by no more than `stepHeight`, the spring aims
+  * at THAT surface and lifts the character onto it. A wall taller than the
+  * step is not a step and still stops you.
+  *
+  * Do not reach for `floatHeight` instead. It does raise the character over
+  * ledges, and it silently makes it WEIGHTLESS: at `floatHeight: 0.28` a
+  * 200 kg character does not move a seesaw a 70 kg crate tips.
+  */
+  stepHeight: number;
   mouseLook: boolean;
   zoomMin: number;
   zoomMax: number;
@@ -1727,6 +1860,10 @@ declare class MeshInstance3D extends Node3D {
   /** Loader hook: malformed materials fail at LOAD time, not at render. */
   static validateJson(node: Node): void;
   private geometryKey;
+  private materialKey;
+  /** True while this node is using a cache entry it must not dispose. */
+  private sharedGeometry;
+  private sharedMaterial;
   private textureKey;
   private loadedTextures;
   protected override _createObject3D(): Object3D;
@@ -1836,6 +1973,31 @@ declare class Joint3D extends Node3D {
   length: number;
   stiffness: number;
   damping: number;
+  /**
+  * Do the two linked bodies still collide with EACH OTHER?
+  *
+  * `null` (default) decides from the joint type, because the two families want
+  * opposite answers:
+  *
+  * - **pivots** (`fixed`, `spherical`, `revolute`) → **off**. A hinge's bodies
+  *   overlap at the pivot by construction, so the contact solver fights the
+  *   joint and flings them. A puzzle builder's first hinge produced a bar that
+  *   spun chaotically forever and threw a 40 kg box thirty metres, and they
+  *   nearly filed "spherical joints inject energy":
+  *
+  *   ```
+  *   t=   0  Plank r=[0,0,0]      Box [ 0.00, 5.50,  2.40]
+  *   t=3000  Plank r=[-66,24,64]  Box [-29.70, 0.40, -4.91]
+  *   ```
+  *
+  * - **tethers** (`rope`, `spring`) → **on**. These anchor a thing to the world,
+  *   and the thing has to rest on what it is tethered to. Defaulting these off
+  *   drops a barrel roped to the floor straight through it — measured, in this
+  *   repo's own conformance room.
+  *
+  * Set `true`/`false` to say it outright.
+  */
+  collide: boolean | null;
   override onEnterTree(): void;
   /** @internal The two bodies, resolved (throws on a bad target at step time). */
   _resolveBodies(): {
@@ -3719,6 +3881,43 @@ declare class Renderer3D {
     behind: boolean;
   };
   /**
+  * The WORLD POINT under canvas pixel (sx, sy) — the other half of
+  * `screenFromWorld`, and the call `incanto-web-integration.md` has always
+  * offered "for taps and clicks".
+  *
+  * It did not exist in 3D. `Renderer2D` has had it since the beginning, the
+  * doc covers both runtimes, and an agent building a tower defense went looking
+  * for it and measured `typeof game.renderer.worldFromScreen === "undefined"`.
+  * `pick()` gives you the NODE under a pixel but never the POINT, so "put the
+  * thing where the player clicked on the ground" was not expressible and that
+  * game discretised its whole map into clickable pads instead.
+  *
+  * A pixel in 3D is a RAY, not a point, so this needs a surface to land on and
+  * takes the horizontal plane at `planeY` (default 0 — the ground). Returns
+  * null when the ray runs parallel to that plane or would only meet it behind
+  * the camera, which is what "the sky" looks like from here.
+  *
+  * For anything not flat — terrain, a hillside, a stack of crates — raycast
+  * physics instead: `rayFromScreen` gives you the origin and direction to feed
+  * `physics.castRay`.
+  */
+  worldFromScreen(sx: number, sy: number, planeY?: number): {
+    x: number;
+    y: number;
+    z: number;
+  } | null;
+  /**
+  * The camera ray through canvas pixel (sx, sy) — origin and unit direction,
+  * ready for `physics.castRay(origin, dir, maxLen)`.
+  *
+  * This is the honest 3D answer to "where did the player click": on uneven
+  * ground the only thing that knows is the collision world.
+  */
+  rayFromScreen(sx: number, sy: number): {
+    origin: [number, number, number];
+    dir: [number, number, number];
+  } | null;
+  /**
   * The node rendered under canvas pixel (sx, sy), or null — raycasts the last
   * rendered camera into the scene and resolves the hit up to its `incantoNode`
   * (every Node3D stamps that in `_ensureObject3D`). 3D depth-sorts, so the
@@ -3907,4 +4106,4 @@ declare function createNavDebugNode(nav: TerrainNav, opts?: {
   name?: string;
 }): InstancedMesh3D;
 //#endregion
-export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type Rig, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type SceneJson, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };
+export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type Rig, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type SceneJson, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, applyQualityTier3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };

package/dist/3d.js

@@ -1,10 +1,10 @@
-import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-lQDCwNag.js";
+import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-KZESOZmE.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-BSMny7oe.js";
-import { B as CharacterBody3D, F as Water3D, H as RigidBody3D, I as WATER_CUTOUT_MAX, L as WaterCutout3D, U as StaticBody3D, V as PhysicsBody3D, W as Node3D, q as WATER_MAX_RIPPLES, z as Area3D } from "./gameplay-D-H986A4.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, 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, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ 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-BvHs6HEk.js";
-import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-W2xzTJhs.js";
+import { G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, R as WATER_CUTOUT_MAX, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, Y as WATER_MAX_RIPPLES, z as WaterCutout3D } from "./gameplay-CGSv-9XR.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, 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, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ 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-C-5g2pMh.js";
+import { a as Environment3D, c as AssetStore3D, i as syncTree, o as applyQualityTier3D, r as Renderer3D, s as setEnvironment3D, t as createGame3D } from "./create-game-FAXdHta3.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DULB1lD1.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-i1IeAY0F.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;
@@ -317,4 +317,4 @@ function createNavDebugNode(nav, opts) {
 	return node;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };
+export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, applyQualityTier3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };

package/dist/{audio-player-BrEHwbK1.d.ts → audio-player-BNUHo0JF.d.ts}

@@ -1,4 +1,4 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-CmMuQ6CL.js";
+import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-ZnfzKDo3.js";
 import { a as Rng } from "./schema-CFeioQRE.js";
 
 //#region src/core/particle-sim.d.ts

package/dist/{behavior-CmMuQ6CL.d.ts → behavior-ZnfzKDo3.d.ts}

@@ -16,6 +16,15 @@ declare class Signal<Args extends unknown[] = unknown[]> {
   }): () => void;
   disconnect(fn: SignalListener<Args>): void;
   disconnectAll(): void;
+  /**
+  * How many listeners are attached.
+  *
+  * A leak is a SLOPE, and a game had no way to see one: every check in this
+  * engine is a snapshot. A handler connected per frame and never disconnected,
+  * or a `once` that armed and never fired, accumulates invisibly and is
+  * perfectly healthy for the first thirty seconds of every playthrough.
+  */
+  get count(): number;
   emit(...args: Args): void;
   get connectionCount(): number;
 }
@@ -247,6 +256,14 @@ declare class Node implements NodeLifecycle {
     once?: boolean;
   }): () => void;
   off(signal: string, fn: SignalListener<unknown[]>): void;
+  /**
+  * How many listeners this node has on `signal` — 0 for one nobody watches.
+  *
+  * The engine's own leak test reads it, and so can a game: a handler connected
+  * every frame and never disconnected is invisible to every other check here,
+  * because every other check is a snapshot and a leak is a slope.
+  */
+  listenerCount(signal: string): number;
   emit(signal: string, ...args: unknown[]): void;
   /**
   * Defer destruction to the end of the current update pass (flushed by the
@@ -1220,7 +1237,8 @@ interface RestoreReport {
 declare function captureBehaviors(root: Node, source?: JsonValue): {
   state: BehaviorState; /** Paths of nodes that had state to save and no uid to save it under. */
   unaddressable: string[]; /** Behaviors in this tree that have something to save — addressable or not. */
-  saveable: number;
+  saveable: number; /** Authored nodes this run consumed that the `#freed` ledger cannot record. */
+  unrecordable: string[];
 };
 /**
 * Hand each behavior its state back.
@@ -1600,6 +1618,26 @@ interface EngineOptions {
   seed?: number;
   /** Frame cap in fps; 0 (default) runs at whatever the display offers. */
   maxFps?: number;
+  /**
+  * Which SETTINGS this game owns — its own, or the origin's.
+  *
+  * Persisted settings are keyed `incanto:<namespace>:<key>` in the browser's
+  * storage, and this defaulted to `settings` with no way to change it. So two
+  * Incanto games served from one domain shared one volume slider, one language
+  * and one quality tier. Measured: game A's player sets
+  * `renderScale 0.25, muted, quality low`; game B — whose source never mentions
+  * settings — boots at a 480×232 drawing buffer, silent.
+  *
+  * `SaveSlots(namespace)` and `createSaveStore(namespace)` have always taken
+  * one and document it as "keeps two games on one origin apart". This is the
+  * third sibling finally saying the same thing.
+  *
+  * Pass a `Settings` instance instead when a game wants to share deliberately
+  * (a launcher and its titles), or drive them from its own store.
+  */
+  settings?: Settings | {
+    namespace: string;
+  };
 }
 /**
 * The game loop: drives a Scene's tree with fixed-timestep `fixedUpdate`
@@ -1649,6 +1687,25 @@ declare class Engine {
   * and cleared on dispose; null when nothing renders (headless).
   */
   picker: ((x: number, y: number) => Node | null) | null;
+  /** Frames the engine has stepped — monotonic, and the pick cache's key. */
+  frameNumber: number;
+  /** @internal frame number + answer, so N Clickables cost ONE raycast. */
+  private pickCacheFrame;
+  private pickCacheKey;
+  private pickCacheHit;
+  /**
+  * The node under (x, y), answered at most ONCE per frame per cursor position.
+  *
+  * `Clickable` asks every frame, and a board game has one per cell: 42 pads
+  * measured **420 picker calls over ten frames** — one GPU raycast per pad per
+  * frame, all answering the same question about the same pixel. At 60 fps that
+  * is ~2500 raycasts a second to find out what the cursor is on, and a 200-tile
+  * board was unusable.
+  *
+  * Cached on (frame, x, y), so a game that picks at two different points in one
+  * frame still gets two real answers.
+  */
+  pickAt(x: number, y: number): Node | 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;

package/dist/{create-game-DIyh5Zy9.js → create-game-DMetd3vR.js}

@@ -1,14 +1,15 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { d as computeViewport, f as resolveViewport, k as diagnose, n as loadScene, z as registerBehavior } from "./loader-lQDCwNag.js";
-import { _ as AudioPlayer, v as Engine } from "./register-CgeR4ckF.js";
+import { d as computeViewport, f as resolveViewport, k as diagnose, n as loadScene, z as registerBehavior } from "./loader-KZESOZmE.js";
+import { _ as AudioPlayer, v as Engine } from "./register-Cs53CY7s.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
-import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-BordHL9o.js";
+import { n as attachTouchControls } from "./touch-DEAmqGdf.js";
+import { t as resolveRendering } from "./rendering-options-ByAdi8PF.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-LB9cTnXJ.js";
 import { o as frameStats } from "./frame-report-BSMny7oe.js";
-import { n as registerGameplayBehaviors } from "./gameplay-D-H986A4.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DO5_Qp0Q.js";
+import { n as registerGameplayBehaviors } from "./gameplay-CGSv-9XR.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-vIxU3Xbv.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-CmnunaR2.js";
+import { n as enablePhysics2D } from "./physics-2d-_B6zj3zU.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
 /**
@@ -756,6 +757,7 @@ async function createGame2D(opts) {
 	const engine = new Engine({
 		seed: opts.seed,
 		fixedHz: opts.fixedHz,
+		...opts.settings ? { settings: opts.settings } : {},
 		...opts._scheduler ? { scheduler: opts._scheduler } : {}
 	});
 	const sourceJson = cloneSceneJson(opts.scene);
@@ -918,7 +920,11 @@ async function createGame2D(opts) {
 	}
 	return {
 		engine,
-		scene,
+		get scene() {
+			const live = engine.scene;
+			if (!live) throw new IncantoError("TREE_VIOLATION", "game.scene: the engine has no scene.");
+			return live;
+		},
 		sourceJson,
 		renderer,
 		physics,