incanto 0.4.2 → 0.5.0

package/dist/2d.d.ts

@@ -1,7 +1,7 @@
 import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { C as RendererStats, S as GameStats, T as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAQq7HGM.js";
-import { t as LoadSceneOptions } from "./loader-Mo0KghCv.js";
-import { t as ParticleSim } from "./particle-sim-CbN4YUuH.js";
+import { C as RendererStats, S as GameStats, T as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CWhW3oa6.js";
+import { t as LoadSceneOptions } from "./loader-D2u0fVW2.js";
+import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -76,7 +76,16 @@ declare class PhysicsBody2D extends Node2D {
   static override readonly props: PropSchema;
   /** The unified collision model: every collider participant can emit these. */
   static override readonly signals: readonly string[];
-  collider: JsonObject;
+  private _collider;
+  /** @internal Physics resync flag — raised when `collider` is REPLACED. */
+  _colliderChanged: boolean;
+  /**
+  * Collider shape prop. Change it by REPLACING the object
+  * (`body.collider = { shape: 'box', size: [...] }`) — physics rebuilds the
+  * body on replacement; in-place mutation of the old object is not watched.
+  */
+  get collider(): JsonObject;
+  set collider(value: JsonObject);
   /** Loader hook: bad collider shapes fail at LOAD, not at physics start. */
   static validateJson(node: Node): void;
   /** @internal Set by Physics2D when the body is created. */
@@ -164,7 +173,27 @@ declare class Physics2D {
   moveAndSlide(node: CharacterBody2D): void;
   /** Rapier debug segments, scaled back to pixels. Null while debugDraw is off. */
   debugLines(): Float32Array | null;
+  /** Create newly-arrived joints; tear down departed ones. */
+  private syncJoints;
+  /**
+  * World-space raycast in PIXELS (y-down). `exclude` skips that body — a
+  * shooter probing from inside its own collider needs it. Sensors (Area2D)
+  * never block rays. Returns distance (px), the surface normal, and the hit
+  * body — or null.
+  */
+  castRay(origin: [number, number], dir: [number, number], maxLen: number, exclude?: PhysicsBody2D, opts?: {
+    staticOnly?: boolean;
+  }): {
+    distance: number;
+    normal: [number, number];
+    node: PhysicsBody2D | null;
+  } | null;
   dispose(): void;
+  private lastStructure;
+  private lastRoot;
+  private readonly jointSet;
+  private readonly joints;
+  private readonly bodySet;
   private syncBodies;
   private ensureEntry;
 }
@@ -409,6 +438,39 @@ declare class ColorRect2D extends Node2D {
   override _syncObject2D(assets: AssetStore2D | null): void;
 }
 //#endregion
+//#region src/2d/nodes/joint-2d.d.ts
+type JointType2D = "fixed" | "revolute" | "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.
+*
+*   { "name": "Hinge", "type": "Joint2D",
+*     "props": { "type": "revolute", "target": "%Anchor", "anchor": [0, -20] } }
+*
+* Types: `fixed` welds the bodies rigidly · `revolute` is a pin/hinge at the
+* anchors · `rope` caps the anchor distance at `length` (px; 0 = measured at
+* creation) · `spring` pulls toward `length` with `stiffness`/`damping`.
+* Anchors are LOCAL pixel offsets on each body.
+*/
+declare class Joint2D extends Node2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  type: JointType2D;
+  target: string;
+  anchor: number[];
+  targetAnchor: number[];
+  /** rope/spring rest length in px; 0 = measure body distance at creation. */
+  length: number;
+  stiffness: number;
+  damping: number;
+  override onEnterTree(): void;
+  /** @internal The two bodies, resolved (throws on a bad target at step time). */
+  _resolveBodies(): {
+    a: PhysicsBody2D;
+    b: PhysicsBody2D;
+  };
+}
+//#endregion
 //#region src/2d/nodes/label.d.ts
 /**
 * CanvasTexture-backed text (zero deps, WebGL-safe). Re-rasterizes only when
@@ -573,6 +635,7 @@ declare class Renderer2D {
   } | null;
   private readonly webgl;
   private readonly worldScene;
+  private readonly syncScratch;
   private readonly uiScene;
   private readonly worldCam;
   private readonly uiCam;
@@ -637,6 +700,11 @@ interface UiSize {
 *
 * Same dirty-push contract as the 3D sync; pure scene-graph math, headless-testable.
 */
-declare function syncTree2D(root: Node, world: Scene, ui: Scene, assets: AssetStore2D | null, uiSize?: UiSize): Sync2DResult;
+/** Per-renderer reusable containers — cleared each frame, never reallocated. */
+interface Sync2DScratch {
+  visited: Set<Object3D>;
+  cameras: Camera2D[];
+}
+declare function syncTree2D(root: Node, world: Scene, ui: Scene, assets: AssetStore2D | null, uiSize?: UiSize, scratch?: Sync2DScratch): Sync2DResult;
 //#endregion
-export { AnimatedSprite2D, type AnimationDef, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, type UIAnchor, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, type AnimationDef, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, type UIAnchor, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CZHROKcT.js";
-import { a as ColorRect2D, c as AnimatedSprite2D, d as CharacterBody2D, f as PhysicsBody2D, h as Node2D, i as Label, l as Sprite2D, m as StaticBody2D, n as UILayer, o as CharacterController2D, p as RigidBody2D, r as Particles2D, s as Camera2D, t as registerNodes2D, u as Area2D } from "./register-DPEV9_9t.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-KuMWPTf6.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BFESHv1X.js";
+import { a as ColorRect2D, c as AnimatedSprite2D, d as Area2D, f as CharacterBody2D, g as Node2D, h as StaticBody2D, i as Label, l as Sprite2D, m as RigidBody2D, n as UILayer, o as CharacterController2D, p as PhysicsBody2D, r as Particles2D, s as Camera2D, t as registerNodes2D, u as Joint2D } from "./register-D71C4rDC.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-KXn1N1jF.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset
@@ -41,4 +41,4 @@ function spriteFromLibraryMeta(meta, opts) {
 	};
 }
 //#endregion
-export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Joint2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
 import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { C as RendererStats, S as GameStats, T as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAQq7HGM.js";
-import { t as LoadSceneOptions } from "./loader-Mo0KghCv.js";
-import { t as ParticleSim } from "./particle-sim-CbN4YUuH.js";
-import { r as SpatialPose } from "./audio-player-DqUR3XFs.js";
-import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, Object3D, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
+import { C as RendererStats, S as GameStats, T as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CWhW3oa6.js";
+import { t as LoadSceneOptions } from "./loader-D2u0fVW2.js";
+import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
+import { r as SpatialPose } from "./audio-player-DkBqRTs4.js";
+import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, 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";
@@ -173,7 +173,16 @@ declare class PhysicsBody3D extends Node3D {
   static override readonly props: PropSchema;
   /** The unified collision model: every collider participant can emit these. */
   static override readonly signals: readonly string[];
-  collider: JsonObject;
+  private _collider;
+  /** @internal Physics resync flag — raised when `collider` is REPLACED. */
+  _colliderChanged: boolean;
+  /**
+  * Collider shape prop. Change it by REPLACING the object
+  * (`body.collider = { shape: 'box', size: [...] }`) — physics rebuilds the
+  * body on replacement; in-place mutation of the old object is not watched.
+  */
+  get collider(): JsonObject;
+  set collider(value: JsonObject);
   /** Loader hook: bad collider shapes fail at LOAD, not at physics start. */
   static validateJson(node: Node): void;
   /** @internal Set by Physics3D when the body is created. */
@@ -260,6 +269,11 @@ declare class Physics3D {
   /** Rapier debug segments (meters). Null while debugDraw is off. */
   debugLines(): Float32Array | null;
   dispose(): void;
+  private lastStructure;
+  private lastRoot;
+  private readonly jointSet;
+  private readonly joints;
+  private readonly bodySet;
   private syncBodies;
   private ensureEntry;
   /** Apply a world-space impulse to a dynamic body (character controllers). */
@@ -268,6 +282,8 @@ declare class Physics3D {
   massOf(node: PhysicsBody3D): 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;
   /**
   * World-space raycast (meters). `exclude` skips that body's collider —
   * ground probes from inside a capsule need it. `opts.staticOnly` hits ONLY the
@@ -415,6 +431,14 @@ interface CloudsEnvironment {
   /** Feature size in world units (bigger = larger, softer cloud masses). */
   scale: number;
 }
+interface BloomEnvironment {
+  /** Linear-HDR luminance above which pixels bloom (the pass runs BEFORE tone
+  * mapping, so emissives/sun glints sit above 1). Default 1 = only
+  * brighter-than-white glows; ~0.8 pulls in bright paint, 1.5+ = emissives only. */
+  threshold: number;
+  /** How strongly the blurred glow is added back (0 = off, ~1.2 = neon). */
+  strength: number;
+}
 interface Environment3DConfig {
   /** Tone-mapping exposure (ACES), default 1. */
   exposure: number;
@@ -424,6 +448,8 @@ interface Environment3DConfig {
   fog: FogEnvironment | null;
   /** Volumetric cloud layer (renderer raymarch composite), or null for none. */
   clouds: CloudsEnvironment | null;
+  /** Bloom post pass (bright-pass → blur → additive composite), or null. */
+  bloom: BloomEnvironment | null;
   /**
   * `null` = not declared (shadow maps stay available, free until a light
   * casts), `false` = force-disabled, object = declared ON with quality knobs
@@ -504,6 +530,8 @@ declare class Environment3D {
   get sunDirection(): [number, number, number] | null;
   /** Parsed volumetric-cloud config, or null when no cloud layer is declared. */
   get clouds(): CloudsEnvironment | null;
+  /** Parsed bloom config, or null when no bloom pass is declared. */
+  get bloom(): BloomEnvironment | null;
   /** The live scene fog (color/near/far) the cloud composite fades into, or null. */
   get sceneFog(): {
     color: Color;
@@ -573,7 +601,7 @@ declare class Billboard3D extends Node3D {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   /** `"screen"` copy the camera orientation (screen-aligned) · `"y"` upright
-  *  yaw-to-camera · `"none"` billboarding off (authored rotation applies). */
+  *  screen-aligned yaw (no off-center roll) · `"none"` off (authored rotation applies). */
   mode: BillboardGroupMode;
   /** Last successfully billboarded WORLD orientation — reapplied on the frames
   *  where `"y"` has no answer (camera dead overhead), because `_syncObject3D`
@@ -965,6 +993,39 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   override free(): void;
 }
 //#endregion
+//#region src/3d/nodes/joint-3d.d.ts
+type JointType3D = "fixed" | "spherical" | "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.
+*
+*   { "name": "Hinge", "type": "Joint3D",
+*     "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.
+*/
+declare class Joint3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  type: JointType3D;
+  target: string;
+  anchor: number[];
+  targetAnchor: number[];
+  /** rope/spring rest length in m; 0 = measure body distance at creation. */
+  length: number;
+  stiffness: number;
+  damping: number;
+  override onEnterTree(): void;
+  /** @internal The two bodies, resolved (throws on a bad target at step time). */
+  _resolveBodies(): {
+    a: PhysicsBody3D;
+    b: PhysicsBody3D;
+  };
+}
+//#endregion
 //#region src/3d/nodes/lights-3d.d.ts
 /** Sun-style light. Direction comes from the node's rotation. */
 declare class DirectionalLight3D extends Node3D {
@@ -1021,6 +1082,14 @@ interface MeshMaterialProps {
   /** 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). */
@@ -1037,7 +1106,8 @@ interface MeshMaterialProps {
 * - `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,
-*   depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat}` —
+*   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
@@ -1067,6 +1137,56 @@ declare class MeshInstance3D extends Node3D {
   override free(): void;
 }
 //#endregion
+//#region src/3d/nodes/loft-mesh-3d.d.ts
+/**
+* One station of a loft: the hull's cross-section at local `z`.
+* Sections are interpolated with a Catmull-Rom spline, so the surface flows
+* SMOOTHLY through every station — this is how real car bodies are modelled.
+*/
+interface LoftSection {
+  /** Station along the hull's local Z (must ascend across `sections`). */
+  z: number;
+  /** Full width of the cross-section at this station. */
+  width: number;
+  /** Full height of the cross-section. */
+  height: number;
+  /** Height of the section CENTRE above the node origin. */
+  y: number;
+  /** 0 = boxy (slab-sided) … 1 = fully elliptical (default 0.7). The lower
+  * half is always kept flatter — vehicle floors are flat. */
+  corner?: number;
+}
+/**
+* A smooth swept hull ("loft"): superellipse cross-sections interpolated
+* along Z with rounded end caps and per-vertex normals — curved highlights
+* and sky reflections sweep across it like sheet metal, which no box/capsule
+* assembly can do. THE node for vehicle bodies, glass canopies, boat hulls,
+* fuselages.
+*
+* - `sections`: ≥2 stations front→back (see LoftSection)
+* - `slices`: vertices around each ring (8..64, default 24)
+* - `smooth`: interpolated rings per section gap (1..16, default 4)
+* - `material`: same object as MeshInstance3D **minus textures** (a loft has
+*   no UVs — map/normalMap/repeat hard-fail). Pair `clearcoat` paint or a
+*   high `envMapIntensity` glass with the smooth normals for the automotive
+*   look.
+*/
+declare class LoftMesh3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  sections: LoftSection[];
+  slices: number;
+  smooth: number;
+  material: MeshMaterialProps;
+  castShadow: boolean;
+  receiveShadow: boolean;
+  /** Loader hook: malformed sections/materials fail at LOAD time. */
+  static validateJson(node: Node): void;
+  private geometryKey;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
+//#endregion
 //#region src/3d/nodes/model-instance-3d.d.ts
 /**
 * A GLB/glTF/VRM model. `model` is a `$key` into the scene's assets header
@@ -1094,6 +1214,12 @@ declare class ModelInstance3D extends Node3D {
   /** Hex colour multiplied into every material — RESKIN one shared GLB into many
   *  variants (e.g. a sickly-green zombie from the base human). '' = untinted. */
   tint: string;
+  /** Override every material's metalness (0..1); -1 keeps the authored value.
+  *  Low-poly kits often ship fully rough — 0.5–0.8 turns flat paint into a
+  *  glinting clear-coat under the scene's IBL. Cloned per instance like tint. */
+  metalness: number;
+  /** Override every material's roughness (0..1); -1 keeps the authored value. */
+  roughness: number;
   private store;
   private entry;
   private mountedRef;
@@ -1107,20 +1233,33 @@ declare class ModelInstance3D extends Node3D {
   *  frames after `this.animation` already moved on). */
   private actionKeys;
   private warnedClaim;
-  /** Per-mesh original (shared) materials, captured at mount so `tint` can always
-  *  re-derive from the source. Our clones are tracked for disposal. */
+  /** Per-mesh original (shared) materials, captured at mount so tint/overrides
+  *  can always re-derive from the source. Our clones are tracked for disposal. */
   private tintTargets;
   private tintedClones;
-  private appliedTint;
+  private appliedMods;
+  /** Named sub-node poses (degrees), re-applied every sync — drive wheels,
+  *  turrets, doors from behaviors without touching three directly. */
+  private nodePoses;
+  /**
+  * Rotate a named sub-node of the loaded model (local Euler XYZ, degrees) —
+  * e.g. spin a GLB car's `wheel-front-left` every frame, aim a turret, swing a
+  * door. Poses persist and re-apply on every sync (safe to set before the
+  * model finishes loading). Unknown names are ignored. `npx incanto-model
+  * <file>` lists a model's node names.
+  */
+  poseNode(name: string, rotation: [number, number, number]): void;
   protected override _createObject3D(): Object3D;
   /** Embedded clip names + the scene's animation `$key`s (editor dropdown). */
   availableAnimations(): string[];
   /** Called by the 3D sync pass with the renderer's asset store. */
   _syncModel(assets: AssetStore3D): void;
-  /** Multiply `tint` into every material — a per-instance reskin of one shared
-  *  GLB (e.g. base human → green zombie). Clones the captured originals (never
-  *  mutates the shared source), disposing prior clones on change. */
-  private applyTint;
+  /** Apply per-instance material mods — `tint` (multiplied into colour) and the
+  *  `metalness`/`roughness` overrides — by cloning the captured originals
+  *  (never mutates the shared source), disposing prior clones on change. */
+  private applyMaterialMods;
+  /** Re-apply every queued named-node pose onto the mounted instance. */
+  private applyPoses;
   private syncAnimation;
   override update(dt: number): void;
   override onExitTree(): void;
@@ -1794,11 +1933,30 @@ declare class Renderer3D {
   private cloudsBlurUniforms;
   private cloudsCompositeScene;
   private cloudsCompositeUniforms;
+  private bloomTarget;
+  private bloomBrightTarget;
+  private bloomBlurTarget;
+  private bloomBrightScene;
+  private bloomBrightUniforms;
+  private bloomBlurScene;
+  private bloomBlurUniforms;
+  private bloomCompositeScene;
+  private bloomCompositeUniforms;
   constructor(opts: Renderer3DOptions);
   private readonly debugLines;
   private syncDebugLines;
   private render;
   /**
+  * Bloom post pass (only when `environment.bloom` is declared). LDR and safe:
+  *   1. scene → full-res offscreen (tone-mapped exactly like direct output)
+  *   2. bright-pass at HALF res (keep pixels above threshold)
+  *   3. separable Gaussian blur (H, V) at half res
+  *   4. composite scene + glow×strength → screen (pure ADD — never re-touches
+  *      the scene's tone; the clouds pipeline taught us that lesson)
+  * Caustics/clouds paths take precedence (composite pipelines don't stack yet).
+  */
+  private renderWithBloom;
+  /**
   * Volumetric cloud pass (only when `environment.clouds` is declared — scenes
   * without it render exactly as before, zero cost). Three steps:
   *   1. scene → full-res offscreen target (color + depth)
@@ -1923,4 +2081,4 @@ interface WalkState {
   alpha: number;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type Heightmap, type HeightmapOptions, 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, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainTheme, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type Heightmap, type HeightmapOptions, 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, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainTheme, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };

package/dist/3d.js

@@ -1,5 +1,5 @@
-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-CMS7DiPi.js";
-import { C as terrainThemeLayers, D as RigidBody3D, E as PhysicsBody3D, F as rigPose, M as cameraRelative, N as keyboardIntensity, O as StaticBody3D, P as movementState, S as TERRAIN_THEMES, T as CharacterBody3D, _ as CharacterController3D, a as VoxelGrid3D, b as Terrain3D, c as ModelInstance3D, d as OmniLight3D, f as Foliage3D, g as FLOWER_VARIETIES, h as resolveFlowerDensity, i as VOXEL_PALETTE, j as QUARTER_PITCH, k as Node3D, l as MeshInstance3D, m as Flowers3D, n as Water3D, o as Tree3D, p as DENSITY_PRESETS, r as WATER_MAX_RIPPLES, s as Particles3D, t as registerNodes3D, u as DirectionalLight3D, v as Camera3D, w as Area3D, x as DEFAULT_TERRAIN_TEXTURE_BASE, y as Billboard3D } from "./register-02aSywx2.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-D8UvwXme.js";
+import { A as StaticBody3D, C as TERRAIN_THEMES, D as CharacterBody3D, E as Area3D, F as keyboardIntensity, I as movementState, L as rigPose, N as QUARTER_PITCH, O as PhysicsBody3D, P as cameraRelative, S as DEFAULT_TERRAIN_TEXTURE_BASE, T as Joint3D, _ as FLOWER_VARIETIES, a as VoxelGrid3D, b as Billboard3D, c as ModelInstance3D, d as DirectionalLight3D, f as OmniLight3D, g as resolveFlowerDensity, h as Flowers3D, i as VOXEL_PALETTE, j as Node3D, k as RigidBody3D, l as LoftMesh3D, m as DENSITY_PRESETS, n as Water3D, o as Tree3D, p as Foliage3D, r as WATER_MAX_RIPPLES, s as Particles3D, t as registerNodes3D, u as MeshInstance3D, v as CharacterController3D, w as terrainThemeLayers, x as Terrain3D, y as Camera3D } from "./register-DvPHJdVj.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CroQPEER.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CXOBOUKG.js";
-export { Area3D, AssetStore3D, Billboard3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-C58oQzTX.js";
+export { Area3D, AssetStore3D, Billboard3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };

package/dist/{audio-player-DqUR3XFs.d.ts → audio-player-DkBqRTs4.d.ts}

@@ -1,4 +1,4 @@
-import { F as Listener, T as Node, l as PropSchema } from "./behavior-BAQq7HGM.js";
+import { F as Listener, T as Node, l as PropSchema } from "./behavior-CWhW3oa6.js";
 
 //#region src/core/nodes/audio-player.d.ts
 /**

package/dist/{behavior-BAQq7HGM.d.ts → behavior-CWhW3oa6.d.ts}

@@ -374,6 +374,34 @@ declare class InputMap {
   * wheel → wheelDelta. `lockOnClick` requests pointer lock on mousedown
   * (the FPS pattern).
   */
+  private readonly padAxesState;
+  private padButtonsDown;
+  /**
+  * Feed one polled gamepad snapshot (standard mapping). Buttons become
+  * codes `Pad0`..`Pad16` in the same space as keys — declare them in input
+  * actions like any key ("jump": ["Space", "Pad0"]). Axes land in
+  * `padAxes()` with a deadzone. Pass null when no pad is connected.
+  */
+  pollGamepad(pad: {
+    buttons: readonly {
+      pressed: boolean;
+    }[];
+    axes: readonly number[];
+  } | null): void;
+  /** Deadzoned analog sticks: 0 = left {x,y}, 1 = right. */
+  padAxes(stick?: 0 | 1): {
+    x: number;
+    y: number;
+  };
+  /**
+  * Poll the browser Gamepad API every frame (the first connected pad).
+  * Wire once at boot: `engine.input.attachGamepad(engine)`. Headless no-op.
+  */
+  attachGamepad(engine: {
+    updated: {
+      connect(fn: () => void): () => void;
+    };
+  }): () => void;
   attachPointer(target: HTMLElement, opts?: {
     lockOnClick?: boolean;
   }): () => void;
@@ -463,6 +491,18 @@ declare class SceneTree {
   private _root;
   private _engine;
   private readonly freeQueue;
+  /**
+  * name → attached nodes with that name. Maintained by Node enter/exit/rename
+  * so `%name` targeting and root-level getNodesByName are O(1) — behaviors
+  * resolve targets every frame and a full-tree walk per chaser melted horde
+  * scenes (N chasers × whole tree, 60×/s).
+  */
+  private readonly _nameIndex;
+  /**
+  * Bumped whenever ANY node attaches or detaches — cheap "did the tree
+  * change shape?" check for per-step body gathers and similar caches.
+  */
+  _structureVersion: number;
   private _frameId;
   /**
   * Monotonic update-frame counter — bumped once per `update()`. Per-frame
@@ -470,6 +510,12 @@ declare class SceneTree {
   * at most once a frame regardless of node visitation order.
   */
   get frameId(): number;
+  /** @internal Node attach hook. */
+  _indexName(node: Node): void;
+  /** @internal Node detach/rename hook (`name` = the entry to remove). */
+  _unindexName(node: Node, name?: string): void;
+  /** @internal Every ATTACHED node named `name` (undefined = none). */
+  _nodesNamed(name: string): ReadonlySet<Node> | undefined;
   /**
   * @internal Opaque per-frame scratch the 3d layer parks its shared moving-body
   * snapshot on (kept here so it is per-tree-instance, never a module global —
@@ -632,6 +678,8 @@ declare class Scene {
   /** Design-resolution viewport (consumed by renderers via resolveViewport). */
   readonly viewport: JsonObject | undefined;
   private readonly connections;
+  /** The full source JSON this scene was loaded from — `restartScene` fuel. */
+  readonly source: SceneJson;
   constructor(source: SceneJson, root: Node, tree: SceneTree);
   /** Lossless export. Note: expanded sub-scene instances serialize as full trees in M1. */
   toJSON(): SceneJson;
@@ -719,6 +767,12 @@ declare class Engine {
   private accumulator;
   private disposeScheduler;
   private readonly frameStats;
+  /**
+  * Game-time multiplier: 1 = realtime, 0.5 = slow motion, 0 = frozen
+  * (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
+  * timers, behaviors all breathe together. See `gameplay` `hitStop()`.
+  */
+  timeScale: number;
   constructor(opts?: EngineOptions);
   get scene(): Scene | null;
   /** Replace the active scene. The previous scene's root is freed. */

package/dist/{create-game-CZHROKcT.js → create-game-BFESHv1X.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { _ as registerBehavior, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-CGs_G-r0.js";
-import { a as Engine } from "./particle-sim-DYuSUxvK.js";
+import { _ as registerBehavior, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-B4OEXDZ8.js";
+import { a as Engine } from "./particle-sim-CFkILGwh.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { r as AudioPlayer } from "./register-BuUV1_KB.js";
+import { s as AudioPlayer } from "./register-Dl_ixIJe.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { n as registerGameplayBehaviors } from "./gameplay-Ccruc3Wd.js";
-import { f as PhysicsBody2D, h as Node2D, n as UILayer, s as Camera2D, t as registerNodes2D } from "./register-DPEV9_9t.js";
+import { n as registerGameplayBehaviors } from "./gameplay-CDFgSG6z.js";
+import { g as Node2D, n as UILayer, p as PhysicsBody2D, s as Camera2D, t as registerNodes2D } from "./register-D71C4rDC.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { n as enablePhysics2D } from "./physics-2d-KuMWPTf6.js";
+import { n as enablePhysics2D } from "./physics-2d-KXn1N1jF.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**
@@ -102,22 +102,29 @@ function worldFromScreen(view, sx, sy) {
 }
 //#endregion
 //#region src/2d/sync.ts
-/**
-* Mirror an Incanto node tree onto two three scenes:
-* - `world`: camera-space drawables
-* - `ui`: everything under a `UILayer` (screen space, ignores the camera);
-*   each layer mounts through its own group, positioned by its `anchor`
-*   against `uiSize` (origin when no size is known — headless).
-*
-* Same dirty-push contract as the 3D sync; pure scene-graph math, headless-testable.
-*/
-function syncTree2D(root, world, ui, assets, uiSize) {
-	const visited = /* @__PURE__ */ new Set();
-	const cameras = [];
-	walk(root, world, ui, false, visited, cameras, assets, uiSize);
-	prune(world, visited);
-	prune(ui, visited);
-	return { activeCamera: cameras.find((c) => c.current) ?? cameras[0] ?? null };
+function createSync2DScratch() {
+	return {
+		visited: /* @__PURE__ */ new Set(),
+		cameras: []
+	};
+}
+function syncTree2D(root, world, ui, assets, uiSize, scratch) {
+	const s = scratch ?? createSync2DScratch();
+	s.visited.clear();
+	s.cameras.length = 0;
+	walk(root, world, ui, false, s.visited, s.cameras, assets, uiSize);
+	prune(world, s.visited);
+	prune(ui, s.visited);
+	let current = null;
+	for (let i = 0; i < s.cameras.length; i++) {
+		const c = s.cameras[i];
+		if (c.current) {
+			current = c;
+			break;
+		}
+	}
+	if (!current) current = s.cameras[0] ?? null;
+	return { activeCamera: current };
 }
 function walk(node, parentObj, ui, inUi, visited, cameras, assets, uiSize) {
 	let nextParent = parentObj;
@@ -144,8 +151,12 @@ function walk(node, parentObj, ui, inUi, visited, cameras, assets, uiSize) {
 	for (const child of node.children) walk(child, nextParent, ui, nextInUi, visited, cameras, assets, uiSize);
 }
 function prune(obj, visited) {
-	for (const child of [...obj.children]) if (child.userData.incantoNode && !visited.has(child)) obj.remove(child);
-	else prune(child, visited);
+	const ch = obj.children;
+	for (let i = ch.length - 1; i >= 0; i--) {
+		const child = ch[i];
+		if (child.userData.incantoNode && !visited.has(child)) obj.remove(child);
+		else prune(child, visited);
+	}
 }
 //#endregion
 //#region src/2d/renderer.ts
@@ -163,6 +174,7 @@ var Renderer2D = class {
 	viewOverride = null;
 	webgl;
 	worldScene = new Scene();
+	syncScratch = createSync2DScratch();
 	uiScene = new Scene();
 	worldCam = new OrthographicCamera(-1, 1, 1, -1, -1e3, 1e3);
 	uiCam = new OrthographicCamera(-1, 1, 1, -1, -1e3, 1e3);
@@ -231,7 +243,7 @@ var Renderer2D = class {
 		const { activeCamera } = syncTree2D(scene.root, this.worldScene, this.uiScene, this.assets, {
 			width: uiW,
 			height: uiH
-		});
+		}, this.syncScratch);
 		let center = vp ? {
 			x: vp.design[0] / 2,
 			y: vp.design[1] / 2