incanto 0.28.0 → 0.30.0

package/dist/3d.d.ts

@@ -1,9 +1,10 @@
-import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CPibUfnH.js";
-import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
+import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
+import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAc0erXF.js";
+import { t as EditorSwitchOptions } from "./editor-switch-B0wB_DSr.js";
+import { t as LoadSceneOptions } from "./loader-B242FF6N.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-RWYkNKx9.js";
-import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Vector3, WebGLRenderer } from "three";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-BwD974Ss.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";
 import * as RapierNs from "@dimforge/rapier3d-compat";
@@ -124,13 +125,6 @@ interface SunConsumer3D {
   /** @internal Called by syncTree when `environment.sky` declares a sun. */
   _applySunDirection(dir: readonly [number, number, number]): void;
 }
-/**
-* Base of every 3D node: a JSON-prop transform backed by a `THREE.Object3D`.
-*
-* Props stay plain JSON (registry/serializer compatible); the renderer layer
-* pushes them onto the backing object once per frame (`_syncObject3D`).
-* Rotation is in DEGREES in JSON — friendlier for agents and humans.
-*/
 declare class Node3D extends Node {
   static override readonly typeName: string;
   static readonly props: PropSchema;
@@ -154,6 +148,23 @@ declare class Node3D extends Node {
   renderOrder: number;
   /** Named draw-order band; `renderOrder` is the fine offset inside it. */
   orderGroup: string;
+  /**
+  * PUT THIS ON THE GROUND. `true` sets the node's Y from the terrain under it
+  * at load; a number does the same and lifts it by that many metres (a post
+  * whose origin sits at its middle wants half its height).
+  *
+  * Computing a Y by hand is the single most repeated mistake in scene
+  * authoring, and it is not a careless one: the number is right when it is
+  * written and wrong the moment anything reshapes the ground — a river carving
+  * its bed, a basin, a different seed, a generator that mirrors the carve
+  * slightly differently. Every "floating boulder", "buried player" and
+  * "bridge posts in mid-air" in this engine's history is that drift.
+  *
+  * With this the ground is asked at load, in the same frame the terrain is
+  * built, and there is nothing to drift from. `null` (default) leaves `y`
+  * exactly as authored — for anything that genuinely hangs in the air.
+  */
+  snapToGround: number | boolean | null;
   /** What three actually sorts by: band base + renderOrder. */
   get effectiveRenderOrder(): number;
   private _object3D;
@@ -165,6 +176,22 @@ declare class Node3D extends Node {
   */
   _interpPrev: number[] | null;
   _interpCurr: number[] | null;
+  override onReady(): void;
+  /**
+  * Resolve {@link snapToGround} against the terrain under this node.
+  *
+  * Ancestor transforms are translation-only here, the same contract heightAt
+  * and the physics heightfield already follow, so the world height converts
+  * back to a local Y by subtracting the parents' offset.
+  */
+  applyGroundSnap(): void;
+  /**
+  * @internal The backing object IF it has been built — never builds one.
+  *
+  * `_ensureObject3D()` is the wrong call during teardown: it allocates a mesh
+  * for a node that never rendered, purely so the next line can dispose it.
+  */
+  protected get _builtObject3D(): Object3D | null;
   /** @internal The backing three object (lazily created). */
   _ensureObject3D(): Object3D;
   /** @internal Override point for subclasses (mesh, camera, light…). */
@@ -249,6 +276,20 @@ type Rapier = typeof RapierNs;
 interface Physics3DOptions {
   /** m/s², y-up. Default: scene `physics.gravity`, else [0, -9.81, 0]. */
   gravity?: [number, number, number];
+  /**
+  * Build the colliders and keep them on the tree, but never advance the world
+  * (default: `true`, i.e. simulate).
+  *
+  * This exists for the scene editor. "Show colliders" there used to hand-draw
+  * wireframes from the `collider` JSON — which cannot show what the engine
+  * actually creates, because the shape is not always in the JSON (a mesh-fitted
+  * body, a scatter's hulls, a character capsule) and the drawing ignored
+  * rotation and scale. With `simulate: false` the editor gets the SAME lines
+  * play mode gets, from the same Rapier world, without anything falling over
+  * the moment you look at it: bodies are posed FROM the tree each tick and the
+  * solver never runs.
+  */
+  simulate?: boolean;
 }
 /**
 * Enable 3D physics for an engine. Dynamically imports Rapier (compat build)
@@ -259,9 +300,11 @@ declare function enablePhysics3D(engine: Engine, opts?: Physics3DOptions): Promi
 /** Per-engine 3D physics world. Same contract as Physics2D. */
 declare class Physics3D {
   private readonly R;
-  private readonly engine;
+  readonly engine: Engine;
   /** Render collider outlines in the GAME view (renderers pick this up). */
   debugDraw: boolean;
+  /** Narrow those outlines to one node's subtree (see DebugLineSource). */
+  debugScope: object | null;
   readonly dimension = "3d";
   private readonly unregisterDebug;
   private readonly warnedNoCollider;
@@ -275,19 +318,54 @@ declare class Physics3D {
   private readonly optsGravity;
   private lastScene;
   constructor(R: Rapier, engine: Engine, opts?: Physics3DOptions);
+  /** Whether the solver runs at all. False = collider outlines only. */
+  private readonly simulate;
   /** @internal Driven by engine.fixedUpdated. */
   step(dt: number): void;
+  /**
+  * Move every body to its node's current transform.
+  *
+  * Only used in outline mode: normally physics owns the pose and writes it
+  * INTO the node, so nothing re-reads the tree. Deliberately computed the same
+  * way `ensureEntry` computes a body's initial pose — world position, node-local
+  * euler — so an outline in the editor is the outline the game will draw, right
+  * down to the places where that pair disagrees with a rotated parent.
+  */
+  private poseFromTree;
   /** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
   moveAndSlide(node: CharacterBody3D): void;
   /** Rapier debug segments (meters). Null while debugDraw is off. */
   debugLines(): Float32Array | null;
+  /**
+  * The Rapier bodies a selected node stands for: its own, its descendants',
+  * and — when it owns none — the nearest body ABOVE it, so clicking the visual
+  * mesh child of a StaticBody3D shows that body's collider rather than nothing.
+  */
+  private scopedBodies;
   dispose(): void;
   private lastStructure;
   private lastRoot;
   private readonly jointSet;
   private readonly joints;
+  /** One fixed body per solid scatter field, carrying a collider per row. */
+  private readonly scatterBodies;
   private readonly bodySet;
+  /**
+  * Give every row of a scatter field its own static collider.
+  *
+  * A stone field is one node with fifty transforms in it, and a player walking
+  * through all fifty is what gives a world away as scenery. All of them hang
+  * off ONE fixed body — they never move, so there is nothing to step — and the
+  * whole set is rebuilt only when the tree's shape changes.
+  */
+  private syncScatters;
   private syncBodies;
+  /**
+  * Null while a `{"shape":"auto"}` body is waiting on its model — the shape
+  * lives in the model's triangles, and there is nothing honest to guess in the
+  * meantime. syncBodies runs every step, so the body appears the moment the
+  * download lands.
+  */
   private ensureEntry;
   /** Apply a world-space impulse to a dynamic body (character controllers). */
   applyImpulse(node: PhysicsBody3D, impulse: [number, number, number]): void;
@@ -374,6 +452,20 @@ interface CreateGame3DOptions {
   _debugDoc?: {
     createElement(tag: string): HTMLElement;
   };
+  /**
+  * LIVE EDITING: the ☰ debug menu gains "edit this scene", which turns this
+  * page into the scene editor — same window, no reload — and the editor's play
+  * button turns it back into the game. The scene and the camera survive both
+  * crossings.
+  *
+  * DEFAULTS TO `debug`: a build with the debug overlay is a build someone is
+  * working on, and "the scene I am looking at, open in the editor" is what
+  * working on it means. It costs nothing until clicked — the editor is a lazy
+  * chunk. `false` opts out; `{ open }` loads it yourself (apps that alias
+  * incanto to source); `{ save }` makes the editor's save button write your
+  * file. Never reachable without `debug` — the ☰ menu is its only entrance.
+  */
+  editor?: boolean | EditorSwitchOptions;
   seed?: number;
   fixedHz?: number;
   pixelRatio?: number;
@@ -381,6 +473,19 @@ interface CreateGame3DOptions {
   * (default ON). `false` pins the resolution — screenshots, capture, tests. */
   adaptiveResolution?: boolean;
   resolveScene?: LoadSceneOptions["resolveScene"];
+  /**
+  * Boot progress, for the loading screen an app already has.
+  *
+  * Assets are only the FIRST half of a boot: building a dressed scene and
+  * compiling its GPU programs takes as long again, and a bar that hits 100%
+  * on the last downloaded byte then sits there while the world is built is
+  * worse than no bar — the player reads "done" and waits anyway.
+  *
+  * `fraction` runs 0 → 1 across everything this call does, and `label` names
+  * the phase ('scene', 'physics', 'renderer', 'shaders', 'ready'). Feed the
+  * asset preload into the first half and this into the second.
+  */
+  onProgress?: (fraction: number, label: string) => void;
   /** @internal Test seam — replaces the Renderer3D construction. */
   _rendererFactory?: (engine: Engine, canvas: HTMLCanvasElement) => GameRenderer;
   /** @internal Test seam — replaces the rAF scheduler. */
@@ -394,10 +499,32 @@ interface GameRenderer {
 interface Game3D {
   engine: Engine;
   scene: Scene$1;
+  /**
+  * The AUTHORED scene this game booted from — the JSON, not the live tree.
+  *
+  * A running tree has moved: physics has stepped it, behaviors have spawned
+  * into it, the player is somewhere else. Handing that to an editor would
+  * make "edit the scene" mean "edit wherever the simulation happens to be",
+  * so the source is kept beside the game and handed over unchanged.
+  */
+  sourceJson: SceneJson;
   renderer: GameRenderer;
   physics: Physics3D | null;
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
+  /**
+  * Turn this page into the scene editor, right where the player is standing —
+  * what the ☰ debug menu's "edit this scene" calls. Bind it to your own key or
+  * button if you want the switch without the overlay.
+  *
+  * Resolves once the editor has taken the page. The game is disposed on the
+  * way out and rebooted when the editor hands it back, so the `Game3D` this
+  * was called on is DEAD afterwards — take the new one from the editor's
+  * `play` path if you need a handle.
+  *
+  * `null` when the game was booted with `editor: false` — nothing to open.
+  */
+  openEditor: (() => Promise<void>) | null;
   dispose(): void;
 }
 /**
@@ -1269,6 +1396,23 @@ declare class InstancedMesh3D extends Node3D {
   material: MeshMaterialProps;
   castShadow: boolean;
   receiveShadow: boolean;
+  /**
+  * Make the scatter SOLID: `{}` gives every row a collider shaped like the
+  * mesh itself — a faceted `gem` stone collides as that stone's own hull, not
+  * as a ball tucked inside it — sized from `size` × the row's scale.
+  *
+  * A field of fifty boulders a player walks straight through is the tell that
+  * a world is a picture. One fixed body carries all the colliders, so the cost
+  * is a handful of shapes and no per-frame work — these never move.
+  *
+  * `{ shape: 'sphere' | 'box' }` (with `radius`/`size`) opts out into a
+  * cheaper approximation when a rough blocker is genuinely all you want.
+  */
+  collider: {
+    shape?: string;
+    radius?: number;
+    size?: number[];
+  } | null;
   private _transforms;
   private transformsDirty;
   get transforms(): number[][];
@@ -1423,6 +1567,23 @@ declare class ModelInstance3D extends Node3D {
   /** false = play the clip once, then emit `animationFinished`. */
   animationLoop: boolean;
   /**
+  * Playback rate of BOTH animation layers. 1 is the speed the clip was
+  * authored at; 0.5 halves it, 2 doubles it, 0 freezes on the current pose.
+  * Negative plays backwards (a closing door is an opening one reversed).
+  *
+  * Live: changing it retimes the clip already playing, no restart.
+  */
+  animationSpeed: number;
+  /**
+  * Seconds into the clip to start at.
+  *
+  * A row of identical torches all starting at 0 flickers in lockstep and the
+  * eye reads it instantly as "copies". Give each a different offset and the
+  * same clip becomes a crowd. Applied when a clip STARTS (a restart re-seeks),
+  * wrapped into the clip's duration, so any number is legal.
+  */
+  animationOffset: number;
+  /**
   * Two-layer animation: play this clip on the UPPER BODY ONLY (the
   * `upperBodyRoot` bone subtree) while `animation` keeps driving the rest —
   * attack while running, wave while walking. One-shot by default
@@ -1447,7 +1608,21 @@ declare class ModelInstance3D extends Node3D {
   private mountedRef;
   private fittedHeight;
   private fitGroup;
+  /**
+  * @internal The mounted model, or null while the asset is still loading.
+  * Physics reads this to shape a `{"shape":"auto"}` collider on the real
+  * triangles — nothing else may reach into the loaded three graph.
+  */
+  _mountedObject3D(): Group | null;
   private mixer;
+  /** The offset the playing clip was seeked to — re-seek when the prop moves. */
+  private appliedOffset;
+  /** @internal Test seam — the mixer driving this model's clips. */
+  get _mixer(): AnimationMixer | null;
+  /** @internal Test seam — which `animation` key is actually playing. */
+  get _playingClip(): string;
+  /** @internal Test seam — where the base clip currently is, in seconds. */
+  get _currentActionTime(): number;
   private playing;
   private currentAction;
   private playingUpper;
@@ -1733,6 +1908,30 @@ interface PathSample {
   /** Meters from the source. */
   along: number;
 }
+/** One reach where the ribbon could not cover the ground its water stands on. */
+interface RiverCoverageGap {
+  /** Metres from the source. */
+  along: number;
+  /** What the terrain says is under water at this station. */
+  wettedHalfWidth: number;
+  /** What a ribbon can carry through the bend here. */
+  carriedHalfWidth: number;
+}
+/**
+* Where a river's ribbon falls short of the water it is standing in.
+*
+* A swept ribbon has a hard geometric ceiling — it cannot be wider than the
+* bend it is taking, or its inner edge folds through itself. When the ground
+* under the surface is wetter than that ceiling allows, the ribbon leaves BARE
+* CHANNEL FLOOR beside the water, and to a player the creek simply stops in
+* the middle of its own bed. No amount of shader work fixes it: the surface
+* really is missing.
+*
+* This reports those reaches so a caller can act on them instead of shipping
+* them. River3D calls it at build time and warns; `incanto/test` exposes it so
+* a game can gate on it headlessly.
+*/
+declare function findRiverCoverageGaps(rings: readonly RiverRing[], tolerance?: number): RiverCoverageGap[];
 /** A cross-section station: where the water is, how wide, how fast. */
 interface RiverRing extends PathSample {
   /** The width the author ASKED for (half of it) — nominal, drives current. */
@@ -1740,6 +1939,9 @@ interface RiverRing extends PathSample {
   /** Wetted half-width to the left of the flow: where the ground rises to the
   * surface. This, not {@link halfWidth}, is where the water actually ends. */
   halfLeft: number;
+  /** What the terrain scan asked for before the bend capped it (fit only). */
+  wettedLeft?: number;
+  wettedRight?: number;
   /** Wetted half-width to the right of the flow. */
   halfRight: number;
   /** No bank on that side: the ground never came up to the surface, so the
@@ -1754,6 +1956,26 @@ interface RiverRing extends PathSample {
   /** Surface current in m/s. */
   speed: number;
 }
+interface RiverRingOptions {
+  path: readonly (readonly number[])[];
+  /** One entry = constant width; several = a profile lerped source→mouth. */
+  widths: readonly number[];
+  /** Water column at the centerline, in meters. */
+  depth: number;
+  /** Reference current in m/s (the mean over the river). */
+  flowSpeed: number;
+  /** Centerline sampling step in meters. */
+  step: number;
+  bedAt: BedSampler;
+  /**
+  * Fit the surface to the ground across the channel — the surface may not
+  * stand above the rim that holds it, and the ribbon ends where the ground
+  * comes up to meet it. Default OFF, because it is meaningful only when
+  * `bedAt` is REAL ground: a river with no terrain under it invents a bed one
+  * `depth` below itself, and there is nothing there to contain or spill it.
+  */
+  fit?: boolean;
+}
 interface RiverHit {
   /** In the channel: inside the banks AND between source and mouth. */
   inside: boolean;
@@ -1768,11 +1990,57 @@ interface RiverHit {
   speed: number;
   halfWidth: number;
 }
+/**
+* Make a traced course fit to carry a river of a given width.
+*
+* `traceDownhillPath` follows the steepest descent, which on real terrain
+* zigzags, kinks and sometimes hooks back within a few metres of a reach it
+* already ran. A ribbon on such a course cannot be well formed at any width
+* worth looking at: tight corners fold its inner edge, and a hook stacks two
+* sheets of water on the same ground. Every symptom of that is a rendering
+* artifact with no rendering fix.
+*
+* So the course is conditioned first, in three steps that are all about the
+* WIDTH the river will be:
+*  1. Laplacian passes relax the trace toward a curve whose bends a ribbon of
+*     `halfWidth` can take.
+*  2. Points closer together than the width are dropped — they only encode
+*     noise at that scale.
+*  3. The course is CUT where it comes back within two widths of itself: a
+*     creek does not flow over its own reach, and ending is a better answer
+*     than two stacked sheets or a strangled trickle.
+*
+* Use it on anything `traceDownhillPath` produces before handing it to River3D.
+*/
+declare function smoothCourse(path: readonly (readonly number[])[], halfWidth: number, passes?: number): number[][];
+/**
+* The centerline station spacing River3D itself uses — EXPORTED so a generator
+* placing things against the water calls the same derivation. A hardcoded step
+* puts the generator's stations in different places than the node's; on a
+* smooth reach nobody notices, on a tight tail the two snap to different rings
+* and rocks grown for one water stand beside the other.
+*/
+declare function riverStepFor(widths: readonly number[], depth: number): number;
+declare function buildRiverRings(opts: RiverRingOptions): RiverRing[];
+declare function projectToRiver(rings: readonly RiverRing[], x: number, z: number): RiverHit | null;
 /** A place where the river stops flowing and starts falling. */
 interface RiverFall {
   /** Where the water LANDS (local frame) — the plunge point. */
   x: number;
   z: number;
+  /** Where it LEAVES: the lip. A falling sheet hangs from here, not from the
+  * plunge — hanging it downstream is how a curtain ends up floating in the
+  * air past the cliff it should be pouring over. */
+  lipX: number;
+  lipZ: number;
+  /** Water half-width AT THE LIP — a fall is as wide as the water going over
+  * the edge, not as wide as the pool it lands in. */
+  lipHalfWidth: number;
+  /** Downstream direction at the lip. */
+  lipDirX: number;
+  lipDirZ: number;
+  /** Current at the lip — what throws the sheet forward. */
+  lipSpeed: number;
   /** Water surface at the lip and at the base. */
   topY: number;
   baseY: number;
@@ -1891,6 +2159,8 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private bedAt;
   /** Whether the last course was fitted to real ground (see buildRiverRings). */
   private fitted;
+  private bounds;
+  private boundsKey;
   /** Everything standing in the current, rescanned on a slow timer. */
   private rocks;
   private rockScanAt;
@@ -1911,6 +2181,9 @@ declare class River3D extends Node3D implements SunConsumer3D {
   * plants a blade (see {@link WetSurface}).
   */
   _waterYAt(x: number, z: number): number | null;
+  /** XZ bounds of the wetted channel, padded by its widest reach. Rebuilt with
+  * the course (the key is the same one the course is derived under). */
+  private ringBounds;
   /**
   * Where a WORLD point sits in the channel — the query gameplay scripts run
   * (steer a raft, drown a torch, decide a ford is too fast to cross). `null`
@@ -1953,6 +2226,18 @@ declare class River3D extends Node3D implements SunConsumer3D {
   * Pure CPU work — no three objects — so gameplay can call it any time.
   */
   private ensureCourse;
+  /**
+  * Say so when the course cannot carry the water standing in it.
+  *
+  * A swept ribbon may not be wider than the bend it takes (its inner edge
+  * would fold through itself), so where the ground is wetter than that ceiling
+  * the surface leaves BARE CHANNEL FLOOR — the creek visibly stops in the
+  * middle of its own bed. That is a course/width mismatch the author has to
+  * decide about, and it is invisible from the JSON, so it is said out loud
+  * with the three things that fix it.
+  */
+  private warnUncoveredWater;
+  private warnedCoverage;
   private rebuildIfNeeded;
   private buildMaterial;
   /**
@@ -2062,6 +2347,10 @@ declare class Terrain3D extends Node3D {
   * dug", and re-loading the scene digs it again.
   */
   private readonly externalChannels;
+  /** Bumped whenever an external channel is cut or released. */
+  private externalRev;
+  /** What the cached heightmap was built from (see shapeUnchanged). */
+  private shapeStamp;
   /**
   * WET SAND band: `{ y, band? }` darkens + glosses the splat in a noisy,
   * breathing band just above height `y` (a waterline) — the trace of the
@@ -2097,6 +2386,9 @@ declare class Terrain3D extends Node3D {
   private allChannels;
   /** @internal The pure heightfield (lazily built — physics pulls this). */
   _heightmap(): Heightmap;
+  /** Cheap guard for the heightmap cache: scalars by value, arrays by identity. */
+  private shapeUnchanged;
+  private rememberShape;
   /** The splat layers in effect — theme preset, or `layers` for 'custom'. */
   resolvedLayers(): TerrainLayer[];
   override _syncObject3D(): void;
@@ -2404,6 +2696,16 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   reflectionInterval: number;
   /** Depth-texture shoreline foam — rides the always-on fancy scene pass. */
   foam: boolean;
+  /**
+  * How much sky the surface throws back at grazing angles, 0..1 — `null`
+  * keeps the preset's own ceiling.
+  *
+  * Turn it DOWN when the sky is blown out: a bright overcast reflected at 0.78
+  * is a sheet of white, and a pool doing that next to a River3D (which paints
+  * an AUTHORED sky palette and so never blows out) reads as two unrelated
+  * materials meeting at a line. Turn it up for a mirror-calm lake.
+  */
+  reflectivity: number | null;
   /** Bodies crossing the surface emit signals and raise ripples. */
   interaction: boolean;
   /** Splash WHITEWATER: the shaders paint expanding surface foam where bodies
@@ -2510,6 +2812,9 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   private readonly mirrorCamera;
   private readonly mirrorMatrix;
   private lastMirrorAt;
+  /** Camera pose the current mirror image was rendered from (see redraw). */
+  private readonly lastMirrorEye;
+  private readonly lastMirrorQuat;
   protected override _createObject3D(): Object3D;
   override update(dt: number): void;
   override _syncObject3D(): void;
@@ -2691,6 +2996,11 @@ declare class Renderer3D {
   private readonly loadedAssetScenes;
   /** The scene whose GPU programs have been pre-compiled (warm-up, see render). */
   private compiledScene;
+  /** The camera the last frame drew with — what warmUp compiles against. */
+  private warmCamera;
+  /** Set while a caller intends to run {@link warmUp} instead: the first frame
+  * then compiles only what it actually draws, and the rest goes async. */
+  private deferCompile;
   /** Reused per-frame walk scratch (instance-scoped — never a module global). */
   private readonly syncScratch;
   /** Editors set this: keep syncing `static: true` subtrees every frame. */
@@ -2740,6 +3050,20 @@ declare class Renderer3D {
   * grab, the mirror and the bloom chain follow automatically.
   */
   private governResolution;
+  /**
+  * Compile the scene's GPU programs off the critical path.
+  *
+  * The compile itself is unavoidable — a dressed outdoor scene is 40+ programs
+  * and a driver takes hundreds of milliseconds each (measured: SEVEN SECONDS
+  * for this engine's creek template on macOS/Metal). What is avoidable is
+  * doing it in ONE synchronous block, which freezes the tab and leaves a
+  * loading bar with nothing to say.
+  *
+  * Called by `createGame3D` behind the app's loading screen.
+  */
+  /** @internal Tell the next frame to leave the bulk compile to {@link warmUp}. */
+  deferFirstCompile(): void;
+  warmUp(onProgress?: (fraction: number) => void): Promise<void>;
   private render;
   /**
   * Bloom post pass (only when `environment.bloom` is declared). LDR and safe:
@@ -2785,10 +3109,23 @@ declare class Renderer3D {
   */
   pick(sx: number, sy: number): Node | null;
   /**
-  * GPU counters for the LAST rendered frame, straight from three's
-  * per-frame-maintained `renderer.info` (render pass + GPU memory).
+  * GPU counters for the last rendered frame — EVERY pass of it, summed (see
+  * the `info.reset()` in `render`), plus GPU memory.
   */
   stats(): RendererStats;
+  /**
+  * Where the last rendered frame was seen FROM.
+  *
+  * Paired with {@link cameraBasis} this is the view on screen — a third-person
+  * rig, a cutscene camera and the editor's free-fly all answer here, which is
+  * what a mode switch needs to carry across so the cut does not read as a
+  * page load.
+  */
+  lastCameraPosition(): {
+    x: number;
+    y: number;
+    z: number;
+  } | null;
   /** The last rendered camera's world-space basis (for screen-plane dragging). */
   cameraBasis(): {
     right: Vector3;
@@ -2941,4 +3278,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 Game3D, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverHit, type RiverRing, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+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 Game3D, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, findRiverCoverageGaps, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

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-DEG-TP7D.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-BRgWpNsa.js";
-import { A as Joint3D, C as BoneLookAt3D, D as DEFAULT_TERRAIN_TEXTURE_BASE, E as Terrain3D, F as rigPose, M as cameraRelative, N as keyboardIntensity, O as TERRAIN_THEMES, P as movementState, S as Camera3D, T as Billboard3D, _ as DENSITY_PRESETS, a as Trail3D, b as FLOWER_VARIETIES, c as traceDownhillPath, d as LoftMesh3D, f as DirectionalLight3D, g as Foliage3D, h as MeshInstance3D, i as Tree3D, j as QUARTER_PITCH, k as terrainThemeLayers, l as Particles3D, m as InstancedMesh3D, n as VOXEL_PALETTE, o as River3D, p as OmniLight3D, r as VoxelGrid3D, s as riverCarveChannels, t as registerNodes3D, u as ModelInstance3D, v as Flowers3D, w as BoneAttachment3D, x as CharacterController3D, y as resolveFlowerDensity } from "./register-6R75AC7-.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-Cfr6aFZ1.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-DuBTv2zI.js";
+import { A as DEFAULT_TERRAIN_TEXTURE_BASE, B as movementState, C as FLOWER_VARIETIES, D as BoneAttachment3D, E as BoneLookAt3D, F as MeshInstance3D, L as QUARTER_PITCH, M as terrainThemeLayers, N as Joint3D, O as Billboard3D, P as InstancedMesh3D, R as cameraRelative, S as resolveFlowerDensity, T as Camera3D, V as rigPose, _ as DirectionalLight3D, a as Trail3D, b as DENSITY_PRESETS, c as findRiverCoverageGaps, d as riverStepFor, f as smoothCourse, g as LoftMesh3D, h as ModelInstance3D, i as Tree3D, j as TERRAIN_THEMES, k as Terrain3D, l as projectToRiver, m as Particles3D, n as VOXEL_PALETTE, o as River3D, p as traceDownhillPath, r as VoxelGrid3D, s as buildRiverRings, t as registerNodes3D, u as riverCarveChannels, v as OmniLight3D, w as CharacterController3D, x as Flowers3D, y as Foliage3D, z as keyboardIntensity } from "./register-DJ0SByQg.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d--y5clE2j.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CeRH-Ff_.js";
 //#region src/3d/environment-runtime.ts
 /**
 * Live environment editing — the renderer re-applies `scene.environment`
@@ -142,4 +142,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, StaticBody3D, TERRAIN_THEMES, Terrain3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+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, StaticBody3D, TERRAIN_THEMES, Terrain3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, findRiverCoverageGaps, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

package/dist/{behavior-CPibUfnH.d.ts → behavior-BAc0erXF.d.ts}

@@ -791,6 +791,16 @@ declare class Engine {
   *  `engine.music.play(src)` / `crossfadeTo(src, secs)` / `stop(fadeOut)`;
   *  routes through the music bus and is advanced each frame by the loop. */
   readonly music: MusicManager;
+  /**
+  * Where nodes that build DOM (HudLayer and its widgets) mount their elements.
+  *
+  * `null` — the default — means `document.body` with `position: fixed`, i.e. a
+  * game's HUD covers the window, which is what a game wants. A host that only
+  * OWNS PART of the page sets this to its own (positioned) container so the
+  * HUD stays inside it: the scene editor points it at the viewport pane, which
+  * is why an edited scene's HUD no longer floats over the inspector.
+  */
+  uiHost: HTMLElement | null;
   private readonly fixedStep;
   private readonly maxFixedSteps;
   private readonly scheduler;
@@ -870,6 +880,17 @@ interface PropDef {
   /** For enum-like string props: the valid values. Drives editor/debug
   * dropdowns and the generated JSON-Schema enum — keep it exhaustive. */
   options?: readonly string[];
+  /**
+  * For an OBJECT-valued prop shaped as a tagged union — `collider`, whose
+  * `shape` decides which other keys are required. One declaration gives an
+  * inspector both the dropdown AND something valid to write when the tag
+  * changes: switching `box` → `sphere` must not leave a `size` and no
+  * `radius`, which is a hard load error.
+  */
+  variants?: {
+    /** The key that picks the variant (e.g. `'shape'`). */tag: string; /** Tag value → a COMPLETE, valid value for the prop. */
+    byTag: Record<string, JsonValue>;
+  };
 }
 type PropSchema = Record<string, PropDef>;
 interface NodeCtor {