incanto 0.74.0 → 0.76.0

package/dist/3d.d.ts

@@ -1,12 +1,12 @@
-import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-BOrk4eQx.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-J1cmVah0.js";
+import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-BRo2uvG6.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-B_245qRy.js";
 import { t as DiagnosticSink } from "./diagnostics-Cu85N3tL.js";
-import { a as SceneJson$1, s as JsonObject } from "./rng-Bb-IutXB.js";
-import { t as EditorSwitchOptions } from "./editor-switch-CFU9mCec.js";
+import { a as SceneJson$1, s as JsonObject } from "./rng-BsXZg3D6.js";
+import { t as EditorSwitchOptions } from "./editor-switch-Bzt0GzVp.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-DNxDAb1w.js";
-import { t as LoadSceneOptions } from "./loader-BAeWMYfF.js";
+import { t as LoadSceneOptions } from "./loader-CbkVdXL8.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 { AnimationClip, AnimationMixer, BufferGeometry, Color, DataTexture, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Quaternion, Scene, ShaderMaterial, Texture, 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";
@@ -451,6 +451,17 @@ declare class RigidBody3D extends PhysicsBody3D {
   friction: number;
   restitution: number;
   /**
+  * How much a `Water3D` lifts this body: `0` (default) = it falls through
+  * water like air, `1` = water's own upthrust — the submerged part of the
+  * collider's volume, at 1000 kg/m³. So `mass` against the collider decides:
+  * a 1 m³ crate at 200 kg floats a fifth under, at 3000 kg it sinks, and a
+  * heavier hull sits deeper. Eight sample points across the collider give a
+  * tilted hull a righting moment, and the water's `drag` slows it. A body with
+  * a `CharacterController3D` under it is never lifted here — the swim spring
+  * owns that one.
+  */
+  buoyancy: number;
+  /**
   * Drag, per second: velocity decays by `e^(-linearDamping·t)`. `0` = none.
   * A body flying through nothing keeps its speed forever otherwise.
   */
@@ -494,6 +505,16 @@ declare class CharacterBody3D extends PhysicsBody3D {
   /** m/s, y-up (up = +y). */
   velocity: number[];
   /**
+  * The mass this body pushes dynamic bodies with, in kg. Rapier's character
+  * controller treats every dynamic body as an OBSTACLE — a character walks
+  * around things — so a beam on a `Patrol` slid up to the player and stopped
+  * dead against them, forever. A piston, a sweeping arm, a moving wall or a
+  * bruiser enemy is a thing that shoves: give it a mass and it pushes what it
+  * meets, and the harder the heavier. `0` (the default) keeps every scene as
+  * it was.
+  */
+  pushes: number;
+  /**
   * Hold the capsule against the surface while it moves, so walking down a
   * slope does not become a series of small falls.
   *
@@ -577,6 +598,94 @@ declare class CharacterBody3D extends PhysicsBody3D {
   isOnFloor(): boolean;
 }
 //#endregion
+//#region src/3d/nodes/vehicle-3d.d.ts
+/** One wheel, as authored in `wheels`. */
+interface WheelSpec {
+  /** Where the spring hangs from, in the CHASSIS's frame (m). */
+  position: [number, number, number];
+  /** Tyre radius (m). */
+  radius: number;
+  /** Spring length at rest (m) — the wheel hangs this far below its mount, less the load. */
+  rest: number;
+  /** Turns with the steer. */
+  steer: boolean;
+  /** Takes the engine force. */
+  drive: boolean;
+}
+/** What one wheel is doing this step. */
+interface WheelState {
+  /** The spring found ground. */
+  contact: boolean;
+  /** Current spring length (m) — the wheel's centre is this far below its mount. */
+  suspension: number;
+  /** Total roll, radians. */
+  rotation: number;
+  /** Current steer, radians. */
+  steering: number;
+}
+/**
+* A car in one node — Rapier's raycast vehicle under a `RigidBody3D` chassis.
+*
+* ```json
+* { "name": "Car", "type": "RigidBody3D",
+*   "props": { "mass": 800, "collider": { "shape": "box", "size": [1.8, 0.6, 4] } },
+*   "children": [
+*     { "name": "Drive", "type": "Vehicle3D", "props": { "wheels": [
+*         { "position": [-0.8, -0.1,  1.4], "steer": true },
+*         { "position": [ 0.8, -0.1,  1.4], "steer": true },
+*         { "position": [-0.8, -0.1, -1.4], "drive": true },
+*         { "position": [ 0.8, -0.1, -1.4], "drive": true } ] } },
+*     { "name": "Wheel0", "type": "Node3D", "props": { "position": [-0.8, -0.1, 1.4] },
+*       "children": [ { "name": "Hub", "type": "Node3D", "children": [ …the tyre mesh… ] } ] }
+*   ] }
+* ```
+*
+* The wheels are springs that never touch anything (a ray each), so a car
+* cannot catch a kerb on a wheel body or disagree with its axle; the throttle,
+* steer and brake come from the `move` vector and the `brake` button (or from
+* code, with `moveAction: ""`). Forward is +z, the +Z-forward rule. A child
+* named `Wheel<i>` is posed every step — it hangs on its spring and turns to
+* steer — and its child `Hub` spins as the wheel rolls.
+*/
+declare class Vehicle3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  wheels: WheelSpec[];
+  suspensionStiffness: number;
+  suspensionCompression: number;
+  suspensionRelaxation: number;
+  maxTravel: number;
+  friction: number;
+  sideFriction: number;
+  maxSteerDeg: number;
+  engineForce: number;
+  brakeForce: number;
+  moveAction: string;
+  brakeAction: string;
+  enabled: boolean;
+  /** Live inputs, −1..1 (throttle, steer) and 0..1 (brake) — the actions write these, or your code does. */
+  throttle: number;
+  steer: number;
+  brake: number;
+  /** Forward speed, m/s (negative in reverse). */
+  speed: number;
+  /** @internal Written by the physics adapter each step. */
+  _states: WheelState[];
+  private reportedActions;
+  /** What wheel `i` is doing. */
+  wheel(i: number): WheelState;
+  /** The wheels with every default filled in. */
+  specs(): WheelSpec[];
+  get body(): RigidBody3D;
+  override onEnterTree(): void;
+  override onExitTree(): void;
+  override fixedUpdate(dt: number): void;
+  /** `Wheel<i>` hangs on its spring and turns to steer; its `Hub` spins. */
+  private poseWheels;
+  /** Full lock, radians. */
+  get maxSteer(): number;
+}
+//#endregion
 //#region src/3d/physics/physics-3d.d.ts
 type Rapier = typeof RapierNs;
 interface Physics3DOptions {
@@ -616,6 +725,11 @@ declare class Physics3D {
   private readonly warnedNoCollider;
   private readonly entries;
   private readonly byColliderHandle;
+  /** Every Water3D in the tree, rescanned when the structure changes. */
+  private readonly waters;
+  private watersStale;
+  /** Raycast vehicles, one per Vehicle3D in the tree, on their chassis entries. */
+  private readonly vehicles;
   private readonly world;
   private readonly events;
   private readonly kcc;
@@ -639,6 +753,15 @@ declare class Physics3D {
   * down to the places where that pair disagrees with a rotated parent.
   */
   private poseFromTree;
+  /**
+  * @internal Called by Vehicle3D.fixedUpdate: push the throttle, steer and
+  * brake into Rapier's raycast vehicle on the chassis and let it apply the
+  * step's forces; read the wheels back. The controller is made on first
+  * use and remade if the chassis body was rebuilt.
+  */
+  _driveVehicle(node: Vehicle3D, dt: number): void;
+  /** @internal The Vehicle3D left the tree: drop its controller. */
+  _freeVehicle(node: Vehicle3D): void;
   /** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
   /**
   * May `candidate` carry `rider`? — see the 2D twin.
@@ -662,6 +785,28 @@ declare class Physics3D {
   private lastRoot;
   private readonly jointSet;
   private readonly joints;
+  /** The two bodies each live joint ties, so a departed joint can be unlinked. */
+  private readonly jointBodies;
+  /** What a hinge's limits/motor were last pushed as, so a write re-applies. */
+  private readonly hingeState;
+  /** Joints refused at creation (bodies that disagree about the axis) — said once. */
+  private readonly refusedJoints;
+  /** A rope's or spring's numbers as last made, so a write REMAKES the joint. */
+  private readonly tetherState;
+  private tetherKey;
+  /**
+  * Who is jointed to whom, and whether that pair's contacts are on.
+  *
+  * A joint's own bodies are not the world to the character controller: a
+  * body jointed to a character with its contacts off is not an obstacle to
+  * its shape-cast (the joint said so, for the contact solver; the cast asks
+  * its own question), and a body jointed to it is never its GROUND — a
+  * chain hanging from a crane hook was the hook's "moving platform", and the
+  * carry dragged the hook along by however far the hook had just moved.
+  */
+  private readonly jointed;
+  private linkJointed;
+  private unlinkJointed;
   /** One fixed body per solid scatter field, carrying a collider per row. */
   private readonly scatterBodies;
   private readonly bodySet;
@@ -714,15 +859,41 @@ declare class Physics3D {
   * meantime. syncBodies runs every step, so the body appears the moment the
   * download lands.
   */
+  /**
+  * Lift every buoyant dynamic body by the water it is in — before the solver
+  * step, so the impulses are part of this step's motion.
+  *
+  * `Water3D.heightAt` had answered "so gameplay can float a raft, bob a
+  * buoy" since the water shipped, and nothing floated anything but the
+  * swimmer: a RigidBody3D dropped into a lake fell through it to the bed,
+  * whatever it weighed. This is Archimedes on eight sample points: each
+  * octant of the collider is an eighth of its volume, lifted by the water's
+  * density times however much of it is under the surface AT THAT POINT, at
+  * that point — so a tilted hull's low corners push harder and it rights
+  * itself, and a wave under one end rocks it. The water's `drag` then bleeds
+  * velocity and spin in proportion to how much is under, which is what stops
+  * a pushed crate and lets a bob die out.
+  */
+  private applyBuoyancy;
+  /** The water whose footprint covers world (x, z), or null. */
+  private waterAt;
   private ensureEntry;
   /** Apply a world-space impulse to a dynamic body (character controllers). */
   applyImpulse(node: PhysicsBody3D, impulse: [number, number, number]): void;
   /** Mass the solver actually uses (collider-derived unless overridden). */
   massOf(node: PhysicsBody3D): number;
+  /** The solver's rotation of a body, as a quaternion `[x, y, z, w]`. */
+  rotationOf(node: PhysicsBody3D): [number, number, number, number];
   /** Current solver velocity (fresher than the node prop mid-step). */
   velocityOf(node: PhysicsBody3D): [number, number, number];
   /** Create newly-arrived joints; tear down departed ones. */
   private syncJoints;
+  /**
+  * Push a hinge's `limits` and motor to the solver — on creation, and again
+  * whenever either changes. Limits and `angle` are this body relative to the
+  * target; Rapier measures the other way round, hence the flip.
+  */
+  private applyHinge;
   /** Who is currently inside each sensor/body, maintained from the event drain. */
   private readonly overlaps;
   private trackOverlap;
@@ -835,6 +1006,19 @@ interface CreateGame3DOptions {
   * to development, e.g. `debug: import.meta.env.VITE_INCANTO_DEBUG === '1'`.
   */
   debug?: boolean;
+  /**
+  * Start the frame loop as soon as the game is built (default `true`).
+  *
+  * `false` hands back a game that has not run a single frame: no
+  * `engine.start()`, and no warm-up tick either. Call `game.engine.start()`
+  * when everything that must exist BEFORE the first frame does — a
+  * `NetworkManager`, whose join takes a moment during which every behaviour
+  * would otherwise run the game OFFLINE. The first race built from the
+  * tarball gridded itself to slot 0 in those frames and sent that pose as
+  * its first replicated state, on top of the other player's car. The shader
+  * warm-up still runs; the canvas stays blank until you start.
+  */
+  autoStart?: boolean;
   /** @internal Test seam — replaces `document` for the debug overlay. */
   _debugDoc?: {
     createElement(tag: string): HTMLElement;
@@ -1465,6 +1649,16 @@ declare class BoneLookAt3D extends Node3D {
   private lookedUpFor;
   /** 0..1 engage blend — eases in/out so tracking never snaps. */
   private engage;
+  /**
+  * How far the head is COMMITTED to the target, 0..1.
+  *
+  * `attachedBone` was a test hook for "did it find the bone"; this is the one
+  * for "is it watching" — the whole observable effect of the node, and it eased
+  * in and out where nothing could read it. A harness asking whether an NPC
+  * tracks the player, and lets go when the player walks behind it, has no other
+  * question to ask.
+  */
+  get engaged(): number;
   /** Test hook. */
   get attachedBone(): Object3D | null;
   _onRender3D(_ctx: RenderContext3D): void;
@@ -1482,9 +1676,20 @@ declare class Camera3D extends Node3D {
   /** A frustum whose planes are the wrong way round draws nothing at all. */
   static validateJson(node: Node): void;
   fov: number;
+  minHorizontalFov: number;
   near: number;
   far: number;
   current: boolean;
+  /**
+  * Make THIS the scene's camera and no other: the renderer takes the first
+  * camera whose `current` is true in tree order, so setting your own without
+  * clearing the gameplay camera's changed nothing visible. A handler a
+  * connection can name — `triggerEnter → DoorCam.makeCurrent`.
+  */
+  makeCurrent(blendSeconds?: number | undefined): void;
+  blendSeconds: number;
+  /** @internal `makeCurrent(seconds)` — read once by the renderer's sync. */
+  _blendRequest: number | undefined;
   lookAt: string;
   /**
   * Aim, every frame, whenever `lookAt` names something — see `aimAt`, which
@@ -1494,6 +1699,15 @@ declare class Camera3D extends Node3D {
   private warnedLookAt;
   override update(_dt: number): void;
   protected override _createObject3D(): Object3D;
+  /**
+  * The vertical fov to actually render with at this aspect.
+  *
+  * Plain `fov` unless `minHorizontalFov` asks for more width than the screen
+  * carries, in which case it is widened until it does. Public because a game
+  * that wants to know what it is really showing — a harness, a debug overlay —
+  * could not otherwise ask, and the answer is not the authored number.
+  */
+  viewFov(aspect: number): number;
   override _syncObject3D(): void;
 }
 //#endregion
@@ -1502,7 +1716,7 @@ declare class Camera3D extends Node3D {
 * The states this controller enters, and therefore the only keys its
 * `animations` map may carry.
 */
-declare const MOVEMENT_STATES: readonly ["idle", "walk", "run", "fastRun", "airborne"];
+declare const MOVEMENT_STATES: readonly ["idle", "walk", "run", "fastRun", "airborne", "swim", "climb", "crouch", "sneak", "dash"];
 /** One of {@link MOVEMENT_STATES}. */
 type MovementState = (typeof MOVEMENT_STATES)[number];
 /**
@@ -1517,6 +1731,7 @@ declare class CharacterController3D extends Node3D {
   static override readonly typeName: string;
   static override readonly signals: readonly string[];
   static override readonly props: PropSchema;
+  enabled: boolean;
   view: RigView;
   camDistance: number;
   eyeHeight: number;
@@ -1543,6 +1758,60 @@ declare class CharacterController3D extends Node3D {
   fallGravity: number;
   floatHeight: number;
   /**
+  * Swimming pace in water too deep to stand in (m/s; `sprint` still
+  * multiplies). `0` turns swimming OFF and the body sinks to the bed, which
+  * is what a drowning pit wants and what every scene got before this.
+  */
+  swimSpeed: number;
+  /**
+  * How far the body's ORIGIN rides below the surface while swimming (m), or
+  * `null` (the default) to take it from the body: deep enough that the head
+  * rides 15 cm clear and the rest is in the water, which is what treading
+  * water looks like.
+  *
+  * The origin is the middle of the capsule, so a fixed number is only ever
+  * right for one character size. The 0.35 m this used to default to left the
+  * head of a standard 1.68 m rig 0.46 m clear of the surface — a person
+  * floating like a boat, chest and shoulders in the air.
+  */
+  swimDepth: number | null;
+  /** Held: swim down at `swimSpeed`. Missing from the input map is fine. */
+  diveAction: string;
+  /**
+  * Ladder pace (m/s). A ladder is any `Area3D` in `ladderGroup`: push UP into
+  * it and the body climbs, gravity off, held to the rungs; at the top it
+  * pulls itself onto the ledge, down steps off at the bottom, `jump` lets go.
+  * `0` = no ladders (every scene before this).
+  */
+  climbSpeed: number;
+  ladderGroup: string;
+  /**
+  * The pull-up, for any jump. A jump that falls a hand short of a ledge is
+  * the most common near-miss in a platformer, and every one handles it the
+  * same way: catch the edge, pull up. On the way down from a jump, a ledge
+  * ahead no higher than this above the capsule's bottom is taken — the same
+  * climb that takes a swimmer out of the water and a climber off a ladder.
+  * `0` (the default) = a jump near a wall feels exactly as it did.
+  */
+  mantleHeight: number;
+  crouchHeight: number;
+  crouchSpeedMultiplier: number;
+  crouchAction: string;
+  dashSpeed: number;
+  dashSeconds: number;
+  dashCooldown: number;
+  dashAction: string;
+  dashBackstep: boolean;
+  private dashLeft;
+  private dashCooldownLeft;
+  private dashDir;
+  /** Read-only: shorter right now — by the key, or by a ceiling. */
+  crouching: boolean;
+  /** The capsule height to stand back up to. */
+  private standingHeight;
+  /** The skin's authored y offset, restored on standing. */
+  private skinRest;
+  /**
   * How high a step the PLAYER walks up without jumping (0 = off).
   *
   * The hover spring holds the capsule a fixed distance above whatever is
@@ -1561,13 +1830,29 @@ declare class CharacterController3D extends Node3D {
   * 200 kg character does not move a seesaw a 70 kg crate tips.
   */
   stepHeight: number;
+  /**
+  * The steepest ground this character STANDS on, in degrees (0-90).
+  *
+  * At or under it the ground is ground: the character holds its place with no
+  * slide at all, however long you leave it there. Over it the ground stops
+  * counting as ground — no hover spring, no `grounded`, no jump reset — and
+  * the body slips off the face, which is what a slope limit means in every
+  * engine that has one.
+  *
+  * 55° is a person. A mountain goat is 80; something on wheels is 25. `90`
+  * turns the limit off — which is what this controller did before it had one,
+  * and why it slid down a 7° hillside.
+  */
+  slopeLimitDeg: number;
   mouseLook: boolean;
   zoomMin: number;
   zoomMax: number;
   pitchMin: number;
   pitchMax: number;
+  pitchStart: number;
   /** Spring-arm: pull the orbit camera in front of walls/ground instead of clipping. */
   cameraCollision: boolean;
+  camera: "drive" | "none";
   /**
   * Ride whatever you are standing on.
   *
@@ -1592,6 +1877,8 @@ declare class CharacterController3D extends Node3D {
   * would fling the player on every step onto one.
   */
   private groundCarry;
+  private carriedRot;
+  private carriedMe;
   turnSpeed: number;
   /** Camera smoothing rate (1-exp(-rate·dt)); side view uses 5. */
   camLerp: number;
@@ -1606,6 +1893,19 @@ declare class CharacterController3D extends Node3D {
   * character facing away from the camera until it first moves).
   */
   skinYawOffset: number;
+  lockOnAction: string;
+  lockGroup: string;
+  lockRange: number;
+  /** What the character is locked onto, or null. */
+  lockTarget: Node | null;
+  /** Lock onto `node`: the camera yaw and the skin follow it from now on. */
+  lock(node: Node): void;
+  /** Let go. */
+  unlock(): void;
+  /** Lock the nearest live, visible member of `lockGroup` within `lockRange` — or let go if locked. */
+  toggleLock(): void;
+  /** Player → target on the ground plane, unit; null when not locked (and lets go when the lock is stale). */
+  private lockDirection;
   /**
   * Movement-state → animation asset map, applied to the `skinPath` model
   * directly — no CharacterAnimator behavior needed:
@@ -1628,9 +1928,33 @@ declare class CharacterController3D extends Node3D {
   /** Camera yaw/pitch in radians (mouse look mutates these). */
   yaw: number;
   pitch: number;
-  /** idle | walk | run | fastRun | airborne — drive animations from this. */
+  /** idle | walk | run | fastRun | airborne | swim — drive animations from this. */
   state: MovementState;
   grounded: boolean;
+  /** Slope of the ground under the character, degrees — 0 when there is none. */
+  groundSlopeDeg: number;
+  /** Its outward normal, or null. `[0, 1, 0]` is flat ground. */
+  groundNormal: [number, number, number] | null;
+  /** In water too deep to stand in — held at the surface by the swim spring. */
+  swimming: boolean;
+  /** The head is under the surface (diving, or a wave over it). */
+  submerged: boolean;
+  /** Pulling up onto a ledge out of the water (see the climb in fixedUpdate). */
+  climbing: boolean;
+  /** On a ladder — an `Area3D` in `ladderGroup` the body overlaps and pushed up into. */
+  onLadder: boolean;
+  private ladders;
+  private ladderScanIn;
+  private ladderLockout;
+  /** Every Water3D in the tree, re-scanned every {@link WATER_SCAN_STEPS}. */
+  private waters;
+  private waterScanIn;
+  /**
+  * A hop out of the water is in progress: the spring may catch a ledge on
+  * the way down (the mantle) — a jump from land never gets that, or the
+  * spring would cushion every landing.
+  */
+  private swimHop;
   /** @internal Feel timers — see the jump block for what each one buys. */
   private coyoteLeft;
   private bufferLeft;
@@ -1640,6 +1964,12 @@ declare class CharacterController3D extends Node3D {
   private jumping;
   /** Seconds of air control still suppressed after a wall kick. */
   private wallLockout;
+  /** What the anti-slide has learned it must keep paying to hold a slope. */
+  private slideHold;
+  /** Where the body stood last step, for the anti-slide's position error. */
+  private slideFrom;
+  /** Seconds since the player last asked this character to move. */
+  private stillFor;
   /** The outward normal of the wall being pressed into this step, if any. */
   private wallNormal;
   private get body();
@@ -1648,6 +1978,25 @@ declare class CharacterController3D extends Node3D {
   /** Actions already reported missing, so a per-frame read says it once. */
   private readonly reportedActions;
   /**
+  * The water over a world point — `[wave surface, still level]` — or null
+  * when no `Water3D`'s footprint covers it. The tree is re-scanned once a
+  * second, so a lake streamed in later is found; the wave height is the CPU
+  * twin of what is drawn, so a swimmer rides the swell the way a raft does.
+  */
+  /** The ladder the body is overlapping, if any — an Area3D in `ladderGroup`. */
+  private ladderUnder;
+  /**
+  * Swap the capsule's height and keep the feet where they are: the body
+  * drops (or rises) by half the difference in the same step, the skin's
+  * authored offset moves the other way so the model's feet stay on the
+  * floor, and the adapter rebuilds the body at the new place next step.
+  */
+  private setHeight;
+  private sceneGravity;
+  /** `swimDepth`, or what it is derived to be for this body (see the prop). */
+  private effectiveSwimDepth;
+  private surfaceAt;
+  /**
   * Read an input action this controller is allowed to be missing.
   *
   * Tolerated because a game may declare no sprint key and no jump; reported
@@ -1663,6 +2012,221 @@ declare class CharacterController3D extends Node3D {
   private findCamera;
 }
 //#endregion
+//#region src/3d/nodes/mesh-instance-3d.d.ts
+type MeshKind = "box" | "sphere" | "capsule" | "plane" | "cylinder" | "gem";
+interface MeshMaterialProps {
+  color?: string;
+  metalness?: number;
+  roughness?: number;
+  emissive?: string;
+  emissiveIntensity?: number;
+  wireframe?: boolean;
+  /** Flat per-face shading — gives faceted meshes (gem!) crisp glints that
+  * sparkle as the mesh turns, instead of a smoothed surface. */
+  flatShading?: boolean;
+  /** 0..1 surface opacity; below 1 turns on transparency (glassy gems, etc.). */
+  opacity?: number;
+  /** Depth-test against the scene (default true). Set false so the mesh ALWAYS
+  * draws on top of geometry behind it — the standard trick for flat ground
+  * decals (AoE telegraphs, selection rings) that must never z-fight with or be
+  * occluded by bumpy terrain. Pair with a high `renderOrder`. */
+  depthTest?: boolean;
+  /** Write to the depth buffer (default true). Set false for additive/overlay
+  * decals so they don't occlude effects drawn after them. */
+  depthWrite?: boolean;
+  /** 0..1 lacquer layer over the base — THE car-paint look: a glossy clear
+  * coat with its own reflection on top of a metallic base. */
+  clearcoat?: number;
+  /** 0..1 roughness of the clearcoat layer alone (default 0 = mirror lacquer). */
+  clearcoatRoughness?: number;
+  /** Reflection strength from the scene's image-based lighting (the PMREM'd
+  * sky / HDRI). 1 = scene default; 2+ makes glass visibly mirror the sky. */
+  envMapIntensity?: number;
+  /** Color texture URL (sampled sRGB, tinted by `color`). */
+  map?: string;
+  /** Tangent-space normal map URL (sampled linear). */
+  normalMap?: string;
+  /** Texture tiling [u, v] across the mesh's UVs (both maps; default [1,1]).
+  * Box/plane UVs span 0–1 per face — scale repeat by the face's world size
+  * for worldspace-ish texel density (e.g. a 6×2.5 m wall at one tile per
+  * meter wants `repeat: [6, 2.5]`). */
+  repeat?: [number, number];
+}
+/**
+* A primitive mesh. Intent-level props only:
+* - `mesh`: box | sphere | capsule | plane | cylinder | gem
+* - `size [x,y,z]`: box extents; sphere/gem radius = x; capsule radius = x,
+*   height = y; plane = x·z ground plane (laid flat); cylinder radius = x, height = y
+* - `material`: `{color, metalness, roughness, wireframe, flatShading, opacity,
+*   clearcoat, clearcoatRoughness, envMapIntensity, depthTest, depthWrite,
+*   emissive, emissiveIntensity, map, normalMap, repeat}` —
+*   `map`/`normalMap` are texture URLs loaded lazily (headless-safe: geometry and
+*   physics never wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading:
+*   true` + a low `roughness` reads as a sparkling faceted jewel (spin it for the
+*   sparkle). `depthTest: false` makes a flat `plane`/`cylinder` an always-on-top
+*   ground decal (AoE telegraph, selection ring) — no z-fighting with terrain.
+*/
+declare class MeshInstance3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  mesh: string;
+  size: number[];
+  material: MeshMaterialProps;
+  castShadow: boolean;
+  receiveShadow: boolean;
+  /** 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;
+  override _syncObject3D(alpha?: number, assets?: AssetStore3D | null): void;
+  /** Lazy texture dressing — same headless guard as Tree3D bark: without a
+  * DOM there is no Image decode, so geometry/colors apply and the maps are
+  * skipped. Re-loads only when a texture-shaping key changes. */
+  private syncTextures;
+  /**
+  * A private CLONE: `repeat` is per-node here (a 1x1 crate and a 8x8 floor
+  * share one tile image), and that is the one field a shared master cannot
+  * carry. The clone shares `texture.source`, so the fetch and the decode are
+  * still done once per url for the whole scene.
+  */
+  private loadTexture;
+  /**
+  * Give the GPU back everything this node OWNS.
+  *
+  * It used to dispose textures and nothing else, so every freed mesh leaked its
+  * geometry and its material — a wave spawner that kills and respawns fifty
+  * enemies a minute leaks fifty of each, forever, and nothing in the game says
+  * so. Both are built here (`_createObject3D` news them, `_syncObject3D`
+  * rebuilds the geometry on a shape change), so both are ours to release.
+  *
+  * The textures are NOT: since the shared texture cache they belong to the
+  * asset store, except the per-node clones this node asked for, which are what
+  * `loadedTextures` holds.
+  */
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/instanced-mesh-3d.d.ts
+/**
+* Hundreds of copies of one mesh in ONE draw call — scattered rocks, fence
+* posts, pillars, crates, gravestones. Same `mesh`/`size`/`material` surface
+* as MeshInstance3D; `transforms` places the copies:
+*
+*   { "name": "Rocks", "type": "InstancedMesh3D",
+*     "props": { "mesh": "gem", "size": [0.7, 0.5, 0.7],
+*       "material": { "color": "#8a8f98", "roughness": 0.9, "flatShading": true },
+*       "transforms": [[12, 0.2, -8, 40, 1.3], [-6, 0.1, 14, 210, 0.8]] } }
+*
+* Each row is `[x, y, z, yawDeg?, scale?]` (yaw 0 and scale 1 when omitted) —
+* dense enough to generate hundreds inline. REPLACE the array to update
+* (mutations are not watched).
+*/
+declare class InstancedMesh3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  mesh: string;
+  size: number[];
+  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[][];
+  set transforms(value: number[][]);
+  private instanced;
+  private builtKey;
+  static validateJson(node: Node): void;
+  /** Test hook: the live instance count. */
+  get instanceCount(): number;
+  override _syncObject3D(alpha?: number): void;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/flock-3d.d.ts
+/** One bird, in WORLD metres and m/s — what `boids()` answers. */
+interface Boid {
+  x: number;
+  y: number;
+  z: number;
+  vx: number;
+  vy: number;
+  vz: number;
+}
+/**
+* A flock — gulls over a harbor, fish under a boat, bats out of a cave — as
+* ONE instanced mesh that flies its own instances.
+*
+* ```json
+* { "name": "Gulls", "type": "Flock3D",
+*   "props": { "position": [0, 14, 0], "count": 40, "radius": 30, "height": 6,
+*              "mesh": "box", "size": [0.5, 0.08, 0.3], "follow": "/root/Boat" } }
+* ```
+*
+* Boids (Reynolds 1987): each instance steers away from neighbours closer
+* than `separation`, toward the average heading of those within `sight`
+* (`alignment`) and toward their centre (`cohesion`), turns back inside an
+* ellipsoid `radius` wide and `height` tall around this node — or around the
+* node at `follow`, offset by this node's position — and never turns faster
+* than `turn`. Every instance flies at `speed`, +z forward, so a mesh that is
+* longer along z reads as a body with a beak.
+*
+* No physics bodies, no behaviour per bird: forty birds cost one draw call
+* and forty-squared distance checks a frame. Seeded from `engine.rng`, so a
+* seeded run flies the same flight. `boids()` answers headless.
+*/
+declare class Flock3D extends InstancedMesh3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  count: number;
+  radius: number;
+  height: number;
+  speed: number;
+  turn: number;
+  separation: number;
+  sight: number;
+  alignment: number;
+  cohesion: number;
+  follow: string;
+  private px;
+  private py;
+  private pz;
+  private vx;
+  private vy;
+  private vz;
+  private rows;
+  static override validateJson(node: Node): void;
+  /** Every bird right now, in world metres and m/s. */
+  boids(): Boid[];
+  override update(dt: number): void;
+  /** The roam centre in this node's local frame: the followed node's offset, or the origin. */
+  private centre;
+  /** Scatter `n` birds through the bound with random headings — engine-seeded. */
+  private seed;
+}
+//#endregion
 //#region src/3d/vegetation/flower-geometry.d.ts
 /**
 * Procedural flower PLANTS for Flowers3D — real plants like the reference
@@ -1999,161 +2563,8 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   override free(): void;
 }
 //#endregion
-//#region src/3d/nodes/mesh-instance-3d.d.ts
-type MeshKind = "box" | "sphere" | "capsule" | "plane" | "cylinder" | "gem";
-interface MeshMaterialProps {
-  color?: string;
-  metalness?: number;
-  roughness?: number;
-  emissive?: string;
-  emissiveIntensity?: number;
-  wireframe?: boolean;
-  /** Flat per-face shading — gives faceted meshes (gem!) crisp glints that
-  * sparkle as the mesh turns, instead of a smoothed surface. */
-  flatShading?: boolean;
-  /** 0..1 surface opacity; below 1 turns on transparency (glassy gems, etc.). */
-  opacity?: number;
-  /** Depth-test against the scene (default true). Set false so the mesh ALWAYS
-  * draws on top of geometry behind it — the standard trick for flat ground
-  * decals (AoE telegraphs, selection rings) that must never z-fight with or be
-  * occluded by bumpy terrain. Pair with a high `renderOrder`. */
-  depthTest?: boolean;
-  /** Write to the depth buffer (default true). Set false for additive/overlay
-  * decals so they don't occlude effects drawn after them. */
-  depthWrite?: boolean;
-  /** 0..1 lacquer layer over the base — THE car-paint look: a glossy clear
-  * coat with its own reflection on top of a metallic base. */
-  clearcoat?: number;
-  /** 0..1 roughness of the clearcoat layer alone (default 0 = mirror lacquer). */
-  clearcoatRoughness?: number;
-  /** Reflection strength from the scene's image-based lighting (the PMREM'd
-  * sky / HDRI). 1 = scene default; 2+ makes glass visibly mirror the sky. */
-  envMapIntensity?: number;
-  /** Color texture URL (sampled sRGB, tinted by `color`). */
-  map?: string;
-  /** Tangent-space normal map URL (sampled linear). */
-  normalMap?: string;
-  /** Texture tiling [u, v] across the mesh's UVs (both maps; default [1,1]).
-  * Box/plane UVs span 0–1 per face — scale repeat by the face's world size
-  * for worldspace-ish texel density (e.g. a 6×2.5 m wall at one tile per
-  * meter wants `repeat: [6, 2.5]`). */
-  repeat?: [number, number];
-}
-/**
-* A primitive mesh. Intent-level props only:
-* - `mesh`: box | sphere | capsule | plane | cylinder | gem
-* - `size [x,y,z]`: box extents; sphere/gem radius = x; capsule radius = x,
-*   height = y; plane = x·z ground plane (laid flat); cylinder radius = x, height = y
-* - `material`: `{color, metalness, roughness, wireframe, flatShading, opacity,
-*   clearcoat, clearcoatRoughness, envMapIntensity, depthTest, depthWrite,
-*   emissive, emissiveIntensity, map, normalMap, repeat}` —
-*   `map`/`normalMap` are texture URLs loaded lazily (headless-safe: geometry and
-*   physics never wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading:
-*   true` + a low `roughness` reads as a sparkling faceted jewel (spin it for the
-*   sparkle). `depthTest: false` makes a flat `plane`/`cylinder` an always-on-top
-*   ground decal (AoE telegraph, selection ring) — no z-fighting with terrain.
-*/
-declare class MeshInstance3D extends Node3D {
-  static override readonly typeName: string;
-  static override readonly props: PropSchema;
-  mesh: string;
-  size: number[];
-  material: MeshMaterialProps;
-  castShadow: boolean;
-  receiveShadow: boolean;
-  /** 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;
-  override _syncObject3D(alpha?: number, assets?: AssetStore3D | null): void;
-  /** Lazy texture dressing — same headless guard as Tree3D bark: without a
-  * DOM there is no Image decode, so geometry/colors apply and the maps are
-  * skipped. Re-loads only when a texture-shaping key changes. */
-  private syncTextures;
-  /**
-  * A private CLONE: `repeat` is per-node here (a 1x1 crate and a 8x8 floor
-  * share one tile image), and that is the one field a shared master cannot
-  * carry. The clone shares `texture.source`, so the fetch and the decode are
-  * still done once per url for the whole scene.
-  */
-  private loadTexture;
-  /**
-  * Give the GPU back everything this node OWNS.
-  *
-  * It used to dispose textures and nothing else, so every freed mesh leaked its
-  * geometry and its material — a wave spawner that kills and respawns fifty
-  * enemies a minute leaks fifty of each, forever, and nothing in the game says
-  * so. Both are built here (`_createObject3D` news them, `_syncObject3D`
-  * rebuilds the geometry on a shape change), so both are ours to release.
-  *
-  * The textures are NOT: since the shared texture cache they belong to the
-  * asset store, except the per-node clones this node asked for, which are what
-  * `loadedTextures` holds.
-  */
-  override free(): void;
-}
-//#endregion
-//#region src/3d/nodes/instanced-mesh-3d.d.ts
-/**
-* Hundreds of copies of one mesh in ONE draw call — scattered rocks, fence
-* posts, pillars, crates, gravestones. Same `mesh`/`size`/`material` surface
-* as MeshInstance3D; `transforms` places the copies:
-*
-*   { "name": "Rocks", "type": "InstancedMesh3D",
-*     "props": { "mesh": "gem", "size": [0.7, 0.5, 0.7],
-*       "material": { "color": "#8a8f98", "roughness": 0.9, "flatShading": true },
-*       "transforms": [[12, 0.2, -8, 40, 1.3], [-6, 0.1, 14, 210, 0.8]] } }
-*
-* Each row is `[x, y, z, yawDeg?, scale?]` (yaw 0 and scale 1 when omitted) —
-* dense enough to generate hundreds inline. REPLACE the array to update
-* (mutations are not watched).
-*/
-declare class InstancedMesh3D extends Node3D {
-  static override readonly typeName: string;
-  static override readonly props: PropSchema;
-  mesh: string;
-  size: number[];
-  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[][];
-  set transforms(value: number[][]);
-  private instanced;
-  private builtKey;
-  static validateJson(node: Node): void;
-  /** Test hook: the live instance count. */
-  get instanceCount(): number;
-  override _syncObject3D(alpha?: number): void;
-  override free(): void;
-}
-//#endregion
 //#region src/3d/nodes/joint-3d.d.ts
-type JointType3D = "fixed" | "spherical" | "rope" | "spring";
+type JointType3D = "fixed" | "spherical" | "revolute" | "prismatic" | "rope" | "spring";
 /**
 * A physics joint linking its PARENT body to `target` (a node path to the
 * other body). Godot-style placement: the joint lives as a child of body A.
@@ -2162,14 +2573,42 @@ type JointType3D = "fixed" | "spherical" | "rope" | "spring";
 *     "props": { "type": "spherical", "target": "%Anchor", "anchor": [0, -20] } }
 *
 * Types: `fixed` welds the bodies rigidly · `spherical` is a ball joint at the
-* anchors · `rope` caps the anchor distance at `length` (m; 0 = measured at
-* creation) · `spring` pulls toward `length` with `stiffness`/`damping`.
-* Anchors are LOCAL meter offsets on each body.
+* anchors · `revolute` is a HINGE about `axis` (a door, a wheel, a lever) with
+* optional `limits` (degrees) and a `motorSpeed` (degrees a second) ·
+* `prismatic` is a SLIDE along `axis` (a portcullis, an elevator, a piston)
+* with `limits` in metres, a `motorSpeed` in metres a second and `travel`
+* read back · `rope`
+* caps the anchor distance at `length` (m; 0 = measured at creation) ·
+* `spring` pulls toward `length` with `stiffness`/`damping`. Anchors are LOCAL
+* meter offsets on each body; `angle` reads the hinge back.
 */
 declare class Joint3D extends Node3D {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   type: JointType3D;
+  /** Hinge axis of a `revolute`, or the line of a `prismatic` (local to this body). */
+  axis: number[];
+  /**
+  * `[min, max]` in degrees for a `revolute` swing; `[]` = no stops. Measured
+  * as `angle` is: this body turned about `axis`, relative to the target.
+  */
+  limits: number[];
+  /** Degrees a second the motor drives the hinge at; `0` = no motor (free). */
+  motorSpeed: number;
+  /** The motor's gain — how quickly it reaches and holds `motorSpeed`. */
+  motorStrength: number;
+  /**
+  * The hinge's current angle in degrees — this body's rotation about `axis`
+  * relative to the target, written by physics every step. `0` when the joint
+  * is not a `revolute` or is not simulated yet.
+  */
+  angle: number;
+  /**
+  * A `prismatic` slide's current travel in metres — this body's anchor along
+  * `axis` relative to the target's, written by physics every step. `0` where
+  * the two anchors coincide, which is where the scene loaded it.
+  */
+  travel: number;
   target: string;
   anchor: number[];
   targetAnchor: number[];
@@ -2558,6 +2997,10 @@ declare class Particles3D extends Node3D {
   maxParticles: number;
   static validateJson(node: Node): void;
   private sim;
+  emitBox: number[];
+  drift: number[];
+  /** @internal Forget the sim so the next update rebuilds it from the props (a preset or kind that changed). */
+  _rebuildSim(): void;
   private bursted;
   private finishedEmitted;
   /** @internal */
@@ -2597,6 +3040,17 @@ declare class Particles3D extends Node3D {
   * list changes (zero per-frame allocation); null when empty so the caller
   * uses the colorStart→colorEnd ramp. */
   private refreshPalette;
+  /**
+  * The stamp every particle is drawn with — a soft round dot.
+  *
+  * A subclass overrides it to look like the thing it IS: `Weather3D`'s rain is
+  * a vertical STREAK, because 2,600 round dots read as a dirty lens and not as
+  * a downpour (measured in a browser at intensity 1). The material is rebuilt
+  * when this changes, so a node may return a different stamp over its life.
+  */
+  protected sprite(): DataTexture;
+  /** The stamp the current material was built with, so a change can rebuild it. */
+  private builtSprite;
   private syncParticles;
   /**
   * Hand the GPU back.
@@ -2609,6 +3063,65 @@ declare class Particles3D extends Node3D {
   override free(): void;
 }
 //#endregion
+//#region src/3d/nodes/ragdoll-3d.d.ts
+/** A bone name → world position, metres — what `activate` takes headless. */
+type RagdollPose = Record<string, [number, number, number]>;
+/** A built limb: its name in {@link RIG} and the RigidBody3D that is it. */
+interface Limb {
+  name: string;
+  body: Node;
+}
+/**
+* A ragdoll for a skinned model — the death that falls.
+*
+* ```json
+* { "name": "Body", "type": "CharacterBody3D", "children": [
+*   { "name": "Skin", "type": "ModelInstance3D", "props": { "model": "$base" } },
+*   { "name": "Ragdoll", "type": "Ragdoll3D", "props": { "target": "../Skin", "lifetime": 8 } }
+* ] }
+* ```
+*
+* Idle it is nothing. `activate()` reads the skeleton at `target` (Mixamo
+* names, forgiving lookup), builds a capsule `RigidBody3D` per limb where the
+* bones are, joins each to its parent with a spherical `Joint3D`, gives them
+* the velocity of the body they fell out of, and from then on writes the
+* bones' world matrices from the limbs every frame — the model crumples,
+* slides, hangs off the ledge. Wire it from `Health.died`; turn the body's
+* collider and its controller off beside it. `reset()` puts the skeleton
+* back under the animation; `lifetime` does that on its own.
+*
+* Headless there is no skeleton: `activate(pose)` takes bone positions, so a
+* test can ask the same questions the game will.
+*/
+declare class Ragdoll3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  static override readonly signals: readonly string[];
+  target: string;
+  mass: number;
+  damping: number;
+  lifetime: number;
+  collide: boolean;
+  /** Read-only: built and driving the bones. */
+  active: boolean;
+  private driven;
+  private limbNodes;
+  private left;
+  /** Every limb built right now, empty while idle. */
+  limbs(): Limb[];
+  /**
+  * Build the ragdoll where the skeleton is (or where `pose` says the bones
+  * are, headless). Returns false when there is nothing to build from.
+  */
+  activate(pose?: RagdollPose | undefined): boolean;
+  /** Free the limbs and hand the skeleton back to the animation. */
+  reset(): void;
+  override update(dt: number): void;
+  override free(): void;
+  /** The velocity of the body this ragdoll falls out of — the first body up the tree. */
+  private hostVelocity;
+}
+//#endregion
 //#region src/3d/terrain/heightmap.d.ts
 /**
 * A smooth radial depression carved into the terrain — a lake/pond bowl. x/z
@@ -3023,15 +3536,27 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private rockScanAt;
   private world;
   private readonly _bodies;
+  private cubeTarget;
+  private cubeCamera;
+  private lastSkyAt;
+  private rippleFft;
+  private rippleSpectrum;
+  private fftUnsupported;
   /** Loader hook: a malformed river fails at LOAD, not as an invisible ribbon. */
   static validateJson(node: Node): void;
   protected override _createObject3D(): Object3D;
   override onReady(): void;
   override onExitTree(): void;
+  /** Said once when the node has no course to be a river along. */
+  private warnedNoPath;
   override update(dt: number): void;
   override _syncObject3D(): void;
   /** Rocks are picked per FRAME (nearest to the eye), scanned on a timer. */
   _onRender3D(ctx: RenderContext3D): void;
+  /** The sky cube: the world beyond the banks, from above the channel's middle. */
+  private syncSky;
+  /** The ripple FFT, advected by the fragment in the ribbon's own frame. */
+  private syncRipple;
   /**
   * @internal Water surface height over a world point, or null where this
   * river does not run — the question scattered vegetation asks before it
@@ -3263,7 +3788,10 @@ declare class Terrain3D extends Node3D {
   * `heightAt`, the drape and the mesh all pick it up on their next rebuild.
   */
   _setExternalChannel(owner: Node, specs: ChannelSpec[] | null): void;
-  /** Authored trenches plus the ones other nodes cut. */
+  /**
+  * Authored trenches plus the ones other nodes cut — every course flattened to
+  * `[x, z]`, whichever spelling it was written in (see `course`).
+  */
   private allChannels;
   /** @internal The pure heightfield (lazily built — physics pulls this). */
   _heightmap(): Heightmap;
@@ -3407,6 +3935,19 @@ declare class Tree3D extends Node3D {
   * it (keeps retrying until a terrain appears), false disables draping.
   */
   drape: boolean | null;
+  /**
+  * Keep trunks out of standing and running water (default true) — a valley a
+  * rill runs through has a grove on its banks, not trees in the current.
+  *
+  * `Foliage3D` and `Flowers3D` have had this since they were written, with the
+  * same default and the same reason; the TREE — the tallest thing in a
+  * landscape and the one that most obviously does not grow midstream — did
+  * not. Measured on a river-valley game: two of twenty-two trunks stood in the
+  * rill.
+  *
+  * `false` is the mangrove, the cypress swamp and the flooded forest.
+  */
+  avoidWater: boolean;
   /** Node path to the Terrain3D to drape onto ('' = auto-find the first one). */
   terrain: string;
   /** Resolved drape target + the grove's world position, set per rebuild. */
@@ -3465,6 +4006,18 @@ declare class Tree3D extends Node3D {
   private buildBarkMaterial;
   private loadBarkTexture;
   /** Per-instance placement + jitter — ONE rng draw order for both paths. */
+  /**
+  * Where every trunk of this grove stands, in WORLD coordinates.
+  *
+  * `drape` is the prop that puts a grove on the ground it grows from, and
+  * nothing could ask whether it had. `UiMinimap.markers()` and
+  * `HudLayer.focusables()` are the same accessor for the same reason: a
+  * feature whose effect no harness can read is a feature nobody checks.
+  *
+  * Recomputed from the seed rather than read back off the InstancedMesh, so it
+  * answers headless too — where there is no mesh at all.
+  */
+  trunks(): Array<[number, number, number]>;
   private scatter;
   private disposeMeshes;
   override free(): void;
@@ -3613,6 +4166,14 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   * as a calm sea; 0.08 = the noisier ported-source look. */
   waveHeight: number;
   waveSpeed: number;
+  /**
+  * How hard this water holds a floating body back, per second at full
+  * submersion — a pushed crate loses `drag` of its velocity each second (and
+  * its spin likewise), scaled by how much of it is under. `0` is ice; `1.5`
+  * lets a boat coast a few lengths; `6` is syrup. Only bodies with `buoyancy`
+  * feel it (see `RigidBody3D.buoyancy`).
+  */
+  drag: number;
   /** 'fancy' shader water (default) | 'simple' cheap CPU sine material. */
   quality: string;
   /** Fancy ramp overrides: `{trough?, surface?, peak?}` hex strings. */
@@ -3628,6 +4189,16 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   */
   mirror: boolean;
   /**
+  * Screen-space reflections (fancy only, default on): the scene ABOVE the
+  * waterline is rendered once at half resolution and every water pixel
+  * marches its reflected ray through that image — so a rock, a pier, a
+  * wader or a boat is mirrored on the water WITHOUT the planar `mirror`
+  * pass. What the screen cannot see (behind the camera, off its edges)
+  * falls back to the sky cube, which is why a mirror-calm lake still wants
+  * `mirror: true`; with `mirror` on this is skipped as redundant.
+  */
+  ssr: boolean;
+  /**
   * Milliseconds between planar-mirror re-renders. A reflection seen through a
   * rippling surface does not need 60 Hz — 33 ms halves the pass's cost and
   * nobody can tell. 0 re-renders every frame.
@@ -3688,6 +4259,30 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   /** Primary swell wavelength in meters (the two crossing trains derive). */
   swellWavelength: number;
   /**
+  * The bottom under this water: a node path to a Terrain3D (fancy only). With
+  * it the swell KNOWS the beach — waves slow and rise as the bottom comes up
+  * (Green's law), their crests peak, and at 0.78× the depth they BREAK into
+  * foam, with spray sprites bursting where the foam fronts pass. Sampled
+  * once into a 256² depth grid over the terrain's footprint; beyond it the
+  * water is assumed deep. Pair with `swell` (the waves that shoal) and
+  * `shoreWaves` (the foam fronts the spray rides).
+  */
+  bed: string;
+  /**
+  * Wind speed in m/s — THE realistic-sea dial (fancy only; 0 = off). Above 0
+  * the surface stops being a noise field and becomes a JONSWAP spectrum:
+  * thousands of waves at every wavelength and heading, each moving at the
+  * speed deep water gives it, inverse-FFT'd on the GPU every frame into a
+  * tiling patch with real crest shapes, choppy horizontal drag and whitecaps
+  * born where the surface folds. The wind blows toward `swellDirectionDeg`.
+  * 4 = a light breeze (ripples, 20 cm), 7 = a fresh breeze (1 m waves),
+  * 12 = rough. The CPU twin (buoyancy, waders) sums the same spectrum.
+  */
+  wind: number;
+  /** Horizontal drag of the FFT sea toward its crests, 0..~1.5 — narrow
+  * crests, broad troughs; past ~1.2 the surface folds and foams everywhere. */
+  choppiness: number;
+  /**
   * GERSTNER pinch on the swell: 0 keeps the legacy height-only trains, 1 is
   * maximum trochoid (crests narrow to a peak, troughs go broad). It also
   * decides where whitecaps break — the surface's Jacobian collapses on a
@@ -3750,6 +4345,26 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   /** Per-frame scene pre-pass: depth (absorption/foam) + color grab (refraction). */
   private scenePassTarget;
   private mirrorTarget;
+  /** Half-res render of the scene ABOVE the waterline — what SSR reflects. */
+  private aboveTarget;
+  private readonly ssrViewProj;
+  /** The FFT sea (wind > 0): the GPU passes, and the CPU spectrum they share. */
+  private seaFft;
+  private seaFftUnsupported;
+  private spectrum;
+  private spectrumKey;
+  private uploadedSpectrumKey;
+  private rippleFft;
+  private rippleSpectrum;
+  private rippleKey;
+  private uploadedRippleKey;
+  /** The bed depth grid (see `bed`), its footprint, and the spray that rides it. */
+  private bedTexture;
+  private bedRect;
+  private bedKey;
+  private spray;
+  /** Vertex spacing of the fancy grid — the mip the vertex shader reads at. */
+  private fancySegments;
   private readonly mirrorCamera;
   private readonly mirrorMatrix;
   private lastMirrorAt;
@@ -3864,6 +4479,11 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   private renderCutoutMasks;
   private syncFancy;
   /**
+  * The bed depth grid and the spray that rides it. Built once per `bed`
+  * (terrain heights are static); torn down when the path is cleared.
+  */
+  private syncBed;
+  /**
   * @internal Environment-sky sun hand-off (see {@link SunConsumer3D}): the
   * sky's sun drives the glint ONLY while the `sunDirection` prop sits at its
   * schema default — an explicitly authored prop always wins. Runs right
@@ -3884,6 +4504,22 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   */
   heightAt(x: number, z: number): number;
   /**
+  * How far below THIS water's surface a world point is, in metres — `0` when
+  * it is above the surface, and `0` when it is outside the pool's footprint.
+  *
+  * `heightAt` answers the surface height everywhere, including a hundred
+  * metres inland, so the obvious spelling of "am I under water"
+  * (`y < water.heightAt(x, z)`) says yes for a player standing in a cellar
+  * well below sea level. The footprint-aware version lived inside
+  * `CharacterController3D`'s swim spring and nothing else could reach it —
+  * and every underwater game needs it for a breath meter, muffled audio, a
+  * "you surfaced" banner, or an enemy that only strikes below.
+  *
+  * The WAVE is included: a point just under a trough is out, and the same
+  * point under a crest is in, which is what a swimmer feels.
+  */
+  depthAt(x: number, y: number, z: number): number;
+  /**
   * @internal Water surface height over a world point, or null outside this
   * surface's footprint — what scattered vegetation asks before it plants a
   * blade (see {@link WetSurface}). The STILL level, not the wave: grass does
@@ -3892,6 +4528,19 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   _waterYAt(x: number, z: number): number | null;
   /** Base wave height at world (x, z) — the CPU twin of the active shader.
   * Ripples are excluded on purpose: a splash must not re-trigger itself. */
+  /**
+  * The sea's spectrum, or null when there is no wind (or the tier collapsed
+  * the surface to the simple shader, whose CPU waves are its own). Built on
+  * the CPU once per (wind, heading, choppiness) and shared by the GPU upload
+  * and the headless twin — one sea, two evaluators.
+  */
+  private seaSpectrum;
+  /**
+  * The ripple layer's spectrum: the sea's own wind when it blows, else the
+  * breeze that puts wind ripple on a pool — its ENERGY is irrelevant (the
+  * layer is normalized to `detailStrength` by rms slope), only its shape.
+  */
+  private rippleSpectrumFor;
   private waveOffsetAt;
 }
 //#endregion
@@ -3948,6 +4597,29 @@ declare class WaterCutout3D extends Node3D {
 /** How many cutouts one Water3D reads (the nearest ones win). */
 declare const WATER_CUTOUT_MAX = 4;
 //#endregion
+//#region src/3d/nodes/weather-3d.d.ts
+declare class Weather3D extends Particles3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  kind: string;
+  intensity: number;
+  radius: number;
+  height: number;
+  wind: number[];
+  follow: string;
+  /** Rain is a streak; snow keeps the soft flake the particle system draws. */
+  protected override sprite(): DataTexture;
+  private tunedFor;
+  private camera;
+  private cameraScanIn;
+  override onEnterTree(): void;
+  /** Set the inherited particle props from `kind` — once, and again if it changes. */
+  private tune;
+  private tuning;
+  private followed;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/3d/register.d.ts
 /**
 * Register the 3D node taxonomy (and the core nodes). Call once in your game
@@ -4287,9 +4959,31 @@ interface SyncScratch {
     parent: Object3D;
   }>;
   state: WalkState;
+  blend: CameraBlend;
+}
+/**
+* The picture's flight from one camera to the next. `lastPos/Quat/Fov` is the
+* pose the picture was LAST drawn from — a blend already flying included, so a
+* second switch mid-blend starts from where the picture is, not from a camera
+* it never reached.
+*/
+interface CameraBlend {
+  cam: PerspectiveCamera;
+  active: boolean;
+  t: number;
+  seconds: number;
+  fromPos: Vector3;
+  fromQuat: Quaternion;
+  fromFov: number;
+  lastNode: Camera3D | null;
+  lastPos: Vector3;
+  lastQuat: Quaternion;
+  lastFov: number;
 }
 interface SyncOptions {
   assets?: AssetStore3D;
+  /** Real seconds since the last frame — what a camera blend flies on. */
+  dt?: number;
   /** Sync `static: true` subtrees every frame anyway (the editor's edit mode). */
   ignoreStatic?: boolean;
   /**
@@ -4400,4 +5094,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, SpotLight3D, 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, isWebGLAvailable, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, showBootFailure, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };
+export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, type Boid, 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, Flock3D, 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, type Limb, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, Ragdoll3D, type RagdollPose, 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, SpotLight3D, 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, Vehicle3D, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, Weather3D, type WheelSpec, type WheelState, acquireOwnTexture, acquireTexture, applyQualityTier3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, isWebGLAvailable, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, showBootFailure, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };