incanto 0.66.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-BXNLfIJk.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-Cga7FVP4.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-_UAcHxnC.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;
@@ -578,6 +603,16 @@ declare class Physics3D {
   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`.
   *
@@ -683,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
@@ -732,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.
   *
@@ -1028,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
 /**
@@ -1792,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;
@@ -4034,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 { 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-D1RADWu3.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-BlPsEmq6.js";
-import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-DYJCIzO0.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-BkHjwJgI.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-_UAcHxnC.d.ts → audio-player-BNUHo0JF.d.ts}

@@ -1,4 +1,4 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-BXNLfIJk.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-BXNLfIJk.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`

package/dist/{create-game-Dd7H4bJV.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-BmuqYTiY.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-byR9USax.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-D1RADWu3.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-D0CxCveZ.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-Cji5A6sX.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,

package/dist/{create-game-DYJCIzO0.js → create-game-FAXdHta3.js}

@@ -1,14 +1,15 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { c as parseEnvironment3D, k as diagnose, n as loadScene, s as horizonColorFromSky, u as sunDirectionFromSky, z as registerBehavior } from "./loader-lQDCwNag.js";
-import { C as qualityRendering, _ as AudioPlayer, v as Engine, x as qualityCaps } from "./register-BmuqYTiY.js";
+import { c as parseEnvironment3D, k as diagnose, n as loadScene, s as horizonColorFromSky, u as sunDirectionFromSky, z as registerBehavior } from "./loader-KZESOZmE.js";
+import { C as qualityRendering, _ as AudioPlayer, v as Engine, x as qualityCaps } 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, o as poseFromRenderer, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-byR9USax.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, o as poseFromRenderer, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-LB9cTnXJ.js";
 import { o as frameStats } from "./frame-report-BSMny7oe.js";
-import { J as createCausticsQuad, K as Node3D, U as PhysicsBody3D, n as registerGameplayBehaviors } from "./gameplay-D1RADWu3.js";
+import { J as createCausticsQuad, K as Node3D, U as PhysicsBody3D, n as registerGameplayBehaviors } from "./gameplay-CGSv-9XR.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-BlPsEmq6.js";
-import { n as enablePhysics3D } from "./physics-3d-BkHjwJgI.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-C-5g2pMh.js";
+import { n as enablePhysics3D } from "./physics-3d-i1IeAY0F.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";
@@ -27,6 +28,31 @@ import { Sky } from "three/examples/jsm/objects/Sky.js";
 */
 var AssetStore3D = class {
 	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.
+	*/
+	meshGeometries = /* @__PURE__ */ new Map();
+	meshMaterials = /* @__PURE__ */ new Map();
 	models = /* @__PURE__ */ new Map();
 	animations = /* @__PURE__ */ new Map();
 	modelKeys = /* @__PURE__ */ new Map();
@@ -253,10 +279,27 @@ function yieldToFrame(maxWaitMs = DEFAULT_MAX_WAIT_MS, raf = typeof requestAnima
 * - hard-validates the merged result NOW (in your call stack), so a bad patch
 *   throws where you wrote it — never inside the render loop
 */
-function setEnvironment3D(engine, patch) {
+/**
+* The environment stages a quality tier is allowed to touch.
+*
+* These are the ones `qualityEnvironment` names, and the ones that must snap
+* back to what the scene file says rather than accumulating.
+*/
+const TIER_KEYS = [
+	"shadows",
+	"bloom",
+	"post",
+	"clouds"
+];
+function setEnvironment3D(engine, patch, opts) {
 	const scene = engine.scene;
 	if (!scene) throw new IncantoError("BAD_FORMAT", "setEnvironment3D: the engine has no scene.");
 	const merged = { ...scene.environment ?? {} };
+	if (opts?.rebaseTierKeys) {
+		const authored = scene.source?.environment ?? {};
+		for (const key of TIER_KEYS) if (key in authored) merged[key] = authored[key];
+		else delete merged[key];
+	}
 	for (const [key, value] of Object.entries(patch)) if (value === null) delete merged[key];
 	else if (typeof value === "object" && !Array.isArray(value) && typeof merged[key] === "object" && merged[key] !== null && !Array.isArray(merged[key])) merged[key] = {
 		...merged[key],
@@ -266,6 +309,24 @@ function setEnvironment3D(engine, patch) {
 	parseEnvironment3D(merged);
 	scene.environment = merged;
 }
+/**
+* Apply a quality tier — the only caller that may RESET as well as patch.
+*
+* 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.*
+*
+* 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}`.
+*/
+function applyQualityTier3D(engine, patch) {
+	setEnvironment3D(engine, patch, { rebaseTierKeys: true });
+}
 //#endregion
 //#region src/3d/adaptive-resolution.ts
 const DEFAULTS = {
@@ -2180,6 +2241,7 @@ async function createGame3D(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);
@@ -2294,7 +2356,7 @@ async function createGame3D(opts) {
 	cleanups.push(engine.settings.bindAudio(engine.audio));
 	cleanups.push(engine.settings.bindLocale(engine.locale));
 	cleanups.push(engine.settings.bindQuality((patch) => {
-		setEnvironment3D(engine, patch);
+		applyQualityTier3D(engine, patch);
 	}));
 	cleanups.push(engine.settings.bindFrameCap((fps) => {
 		engine.maxFps = fps;
@@ -2368,7 +2430,11 @@ async function createGame3D(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,
@@ -2454,4 +2520,4 @@ function wireAudioUnlock(engine, root, canvas) {
 	return detachAll;
 }
 //#endregion
-export { Environment3D as a, syncTree as i, create_game_exports as n, setEnvironment3D as o, Renderer3D as r, AssetStore3D as s, createGame3D as t };
+export { Environment3D as a, AssetStore3D as c, syncTree as i, create_game_exports as n, applyQualityTier3D as o, Renderer3D as r, setEnvironment3D as s, createGame3D as t };

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { Ft as LogLevel, T as RendererStats, b as Engine } from "./behavior-BXNLfIJk.js";
+import { Ft as LogLevel, T as RendererStats, b as Engine } from "./behavior-ZnfzKDo3.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */

package/dist/debug.js

@@ -1,5 +1,6 @@
 import { t as jsonClone } from "./json-CwwhxQgb.js";
 import { s as mergeStaticProps } from "./registry-CF70EArN.js";
+import { r as capturePointer } from "./touch-DEAmqGdf.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
 //#region src/debug/capture.ts
 /**
@@ -369,7 +370,7 @@ var FloatingPanel = class {
 			active = e.pointerId;
 			lastX = e.clientX;
 			lastY = e.clientY;
-			grip.setPointerCapture?.(e.pointerId);
+			capturePointer(grip, e.pointerId);
 		});
 		grip.addEventListener("pointermove", (e) => {
 			if (e.pointerId !== active) return;
@@ -565,7 +566,7 @@ function openRegionSelect(opts) {
 		applyStyle(popup, { display: "none" });
 		applyStyle(box, { cursor: next === "move" ? "grabbing" : "crosshair" });
 		const id = event.pointerId;
-		if (id !== void 0) layer.setPointerCapture?.(id);
+		if (id !== void 0) capturePointer(layer, id);
 		render();
 	}
 	function render() {

package/dist/{duplicate-CqSAtdrh.js → duplicate-B8QnX2-r.js}

@@ -1,4 +1,4 @@
-import { a as serializeNode, t as buildNodeJson } from "./loader-lQDCwNag.js";
+import { a as serializeNode, t as buildNodeJson } from "./loader-KZESOZmE.js";
 //#region src/core/scene/duplicate.ts
 function stripUids(json) {
 	const { uid: _uid, ...rest } = json;

package/dist/editor.js

@@ -2380,7 +2380,8 @@ var Vn = [
 	"connections",
 	"input",
 	"multiplayer",
-	"strings"
+	"strings",
+	"environment"
 ];
 function Hn(e, t, n) {
 	e.appendChild(Tr("scene")), e.appendChild(Ar("name", String(t.working.name ?? ""), (e) => {
@@ -7842,6 +7843,10 @@ var ss = class {
 			return !0;
 		}) === !0;
 	}
+	resume(e) {
+		let t = this.original;
+		this.reset(e), this.original = t;
+	}
 	reset(e) {
 		this.working = e, this.working.root && cs(this.working.root), this.original = JSON.stringify(this.working), this.undoStack = [], this.selection = [], this.emit();
 	}
@@ -9794,7 +9799,7 @@ async function xc(e = {}) {
 		let t = e.target.matches("input, textarea, select");
 		(e.metaKey || e.ctrlKey) && e.key === "z" ? (e.preventDefault(), u.undo()) : (e.metaKey || e.ctrlKey) && e.key === "s" ? (e.preventDefault(), p.disabled || p.click()) : !t && e.code === "KeyF" ? P.zoomToFit() : !t && (e.code === "Digit0" || e.code === "Numpad0") ? P.gameView() : !t && e.code === "KeyW" ? P.setMode("move") : !t && e.code === "KeyE" ? P.setMode("rotate") : !t && e.code === "KeyR" && P.setMode("scale");
 	};
-	return window.addEventListener("keydown", Me), n.push(() => window.removeEventListener("keydown", Me)), F(), e.camera && P.setEditCamera(e.camera.position, e.camera.target), kt.ready(C, w, o.version), {
+	return window.addEventListener("keydown", Me), n.push(() => window.removeEventListener("keydown", Me)), F(), e.scene && u.resume(e.scene), e.camera && P.setEditCamera(e.camera.position, e.camera.target), kt.ready(C, w, o.version), {
 		working: () => u.working,
 		camera: () => P.editCamera(),
 		showError: O,

package/dist/{environment-presets-BlPsEmq6.js → environment-presets-C-5g2pMh.js}

@@ -1,11 +1,11 @@
-import { k as diagnose } from "./loader-lQDCwNag.js";
-import { L as translateOn, t as registerCoreNodes } from "./register-BmuqYTiY.js";
+import { k as diagnose } from "./loader-KZESOZmE.js";
+import { L as translateOn, t as registerCoreNodes } from "./register-Cs53CY7s.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-CF70EArN.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CY-mrr1L.js";
-import { B as rejectScale, G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, X as colliderFootDrop, w as tolerateUnknownAction, z as WaterCutout3D } from "./gameplay-D1RADWu3.js";
+import { B as rejectScale, G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, X as colliderFootDrop, w as tolerateUnknownAction, z as WaterCutout3D } from "./gameplay-CGSv-9XR.js";
 import { t as checkSheetGrid } from "./sheet-grid-BT6N_Bjs.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
@@ -387,6 +387,10 @@ var MeshInstance3D = class extends Node3D {
 		validateMeshMaterial(node.material, node.name);
 	}
 	geometryKey = "";
+	materialKey = "";
+	/** True while this node is using a cache entry it must not dispose. */
+	sharedGeometry = false;
+	sharedMaterial = false;
 	textureKey = "";
 	loadedTextures = [];
 	_createObject3D() {
@@ -395,12 +399,48 @@ var MeshInstance3D = class extends Node3D {
 	_syncObject3D(alpha = 1, assets = null) {
 		super._syncObject3D(alpha, assets);
 		const m = this._ensureObject3D();
-		const key = `${this.mesh}:${JSON.stringify(this.size)}`;
+		const key = `${this.mesh}:${this.size.join(",")}`;
 		if (key !== this.geometryKey) {
-			m.geometry.dispose();
-			m.geometry = buildMeshGeometry(this.mesh, this.size);
+			if (!this.sharedGeometry) m.geometry.dispose();
+			const cached = assets?.meshGeometries.get(key);
+			if (cached) {
+				m.geometry = cached;
+				this.sharedGeometry = true;
+			} else {
+				const built = buildMeshGeometry(this.mesh, this.size);
+				m.geometry = built;
+				this.sharedGeometry = Boolean(assets);
+				assets?.meshGeometries.set(key, built);
+			}
 			this.geometryKey = key;
 		}
+		const look = JSON.stringify(this.material);
+		if (assets && look !== this.materialKey) {
+			const shared = assets.meshMaterials.get(look);
+			if (shared) {
+				if (!this.sharedMaterial) m.material.dispose();
+				m.material = shared;
+				this.sharedMaterial = true;
+				this.materialKey = look;
+				this.textureKey = "shared";
+				m.castShadow = this.castShadow;
+				m.receiveShadow = this.receiveShadow;
+				return;
+			}
+			if (this.sharedMaterial) {
+				m.material = new MeshPhysicalMaterial();
+				this.sharedMaterial = false;
+				this.textureKey = "";
+			}
+			this.materialKey = look;
+			const mine = m.material;
+			applyMeshMaterial(mine, this.material);
+			this.syncTextures(mine, assets);
+			assets.meshMaterials.set(look, mine);
+			m.castShadow = this.castShadow;
+			m.receiveShadow = this.receiveShadow;
+			return;
+		}
 		const mat = m.material;
 		applyMeshMaterial(mat, this.material);
 		this.syncTextures(mat, assets);