incanto 0.71.0 → 0.73.0

package/bin/incanto-check.mjs

@@ -86,7 +86,7 @@ function collectScenes(entry) {
  * not. A WARNING, not an error: a url can legitimately be produced at runtime,
  * and refusing to load a scene over a guess would be worse than the bug.
  */
-function missingArt(file, json) {
+async function missingArt(file, json) {
   const assets = json && typeof json === 'object' ? json.assets : null;
   const sceneDir = dirname(file);
   const root = projectRoot(sceneDir);
@@ -112,9 +112,17 @@ function missingArt(file, json) {
       url: u.url,
     })),
   ];
+  const remote = [];
   for (const { what, kind, url } of named) {
     if (typeof url !== 'string' || url === '') continue;
-    // Remote and inline are not this command's business to guess about.
+    // A remote url is not guessed about — it is ASKED. A melee arena built from
+    // the tarball named a model at a path that does not exist on the CDN, and
+    // `incanto-verify` printed "its assets resolve" over a 404 only the browser
+    // ever reported. Inline (`data:`) and protocol-relative urls stay unchecked.
+    if (/^https?:\/\//i.test(url)) {
+      remote.push({ what, kind, url });
+      continue;
+    }
     if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) continue;
     const rel = url.replace(/^\//, '');
     const candidates = [
@@ -139,6 +147,68 @@ function missingArt(file, json) {
         `, and beside the scene). It will ${kind === 'audio' ? 'be silent' : 'draw nothing'}.`,
     );
   }
+  out.push(...(await missingRemoteArt(remote)));
+  return out;
+}
+
+/** One answer per url per run — a corpus names the same model in every scene. */
+const probed = new Map();
+
+/**
+ * Does the server have it? A HEAD with a short deadline; servers that refuse
+ * HEAD get one ranged GET. Only the answer "no" (404/410) is a warning: an
+ * unreachable host is a NOTE on stdout and nothing else, because a check that
+ * fails offline is a check people turn off.
+ */
+async function probeUrl(url) {
+  if (probed.has(url)) return probed.get(url);
+  const ask = async (method) => {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), 4000);
+    try {
+      const res = await fetch(url, {
+        method,
+        redirect: 'follow',
+        signal: ctl.signal,
+        headers: method === 'GET' ? { range: 'bytes=0-0' } : {},
+      });
+      if (method === 'GET') await res.body?.cancel?.();
+      return { status: res.status };
+    } catch (e) {
+      return {
+        error:
+          e?.name === 'AbortError'
+            ? 'timed out after 4 s'
+            : (e?.cause?.code ?? e?.message ?? String(e)),
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  let answer = await ask('HEAD');
+  if (answer.status === 405 || answer.status === 403 || answer.status === 501)
+    answer = await ask('GET');
+  probed.set(url, answer);
+  return answer;
+}
+
+async function missingRemoteArt(remote) {
+  const answers = await Promise.all(
+    remote.map(async (r) => ({ ...r, ...(await probeUrl(r.url)) })),
+  );
+  const out = [];
+  for (const { what, kind, url, status, error } of answers) {
+    if (status === 404 || status === 410) {
+      out.push(
+        `${what} → ${url} is not found on its server (HTTP ${status}). It will ` +
+          `${kind === 'audio' ? 'be silent' : 'draw nothing'}.`,
+      );
+    } else if (error !== undefined) {
+      console.log(
+        `      note: ${what} → ${url} could not be reached from here (${error}) — not checked.`,
+      );
+    }
+  }
   return out;
 }
 
@@ -266,49 +336,51 @@ for (const file of files) {
 
 const instanced = instancedScenes(corpus, (from, ref) => resolve(dirname(from), ref));
 
-const results = files.map((file) => {
-  let json;
-  try {
-    json = readJson(file);
-  } catch (e) {
-    return { file, ok: false, code: 'BAD_JSON', message: String(e?.message ?? e) };
-  }
-  const res = validateScene(json, {
-    strictBehaviors: args.strict,
-    /*
-     * `validateScene` has always taken `behaviors`; this bin had no way to pass
-     * any. So `--strict-behaviors` could only ever FAIL on a project with a
-     * behaviour of its own — which is every project past its first hour:
-     *
-     *   [UNKNOWN_BEHAVIOR] Unknown behavior 'Hunter'. … Did you forget
-     *   registerBehavior('Hunter', Hunter)?
-     *   0/1 scene(s) valid                                        EXIT=1
-     *
-     * A flag whose only outcome is failure is a flag nobody uses, and the check
-     * it gates — a script name that resolves nowhere — is worth having.
-     */
-    behaviors,
-    declaredAssets,
-    resolveScene: (p) => readJson(resolve(dirname(file), p)),
-  });
-  if (res.ok) {
+const results = await Promise.all(
+  files.map(async (file) => {
+    let json;
+    try {
+      json = readJson(file);
+    } catch (e) {
+      return { file, ok: false, code: 'BAD_JSON', message: String(e?.message ?? e) };
+    }
+    const res = validateScene(json, {
+      strictBehaviors: args.strict,
+      /*
+       * `validateScene` has always taken `behaviors`; this bin had no way to pass
+       * any. So `--strict-behaviors` could only ever FAIL on a project with a
+       * behaviour of its own — which is every project past its first hour:
+       *
+       *   [UNKNOWN_BEHAVIOR] Unknown behavior 'Hunter'. … Did you forget
+       *   registerBehavior('Hunter', Hunter)?
+       *   0/1 scene(s) valid                                        EXIT=1
+       *
+       * A flag whose only outcome is failure is a flag nobody uses, and the check
+       * it gates — a script name that resolves nowhere — is worth having.
+       */
+      behaviors,
+      declaredAssets,
+      resolveScene: (p) => readJson(resolve(dirname(file), p)),
+    });
+    if (res.ok) {
+      return {
+        file,
+        ok: true,
+        warnings: [
+          ...auditScene(json, { declaredElsewhere, instanced: instanced.has(resolve(file)) }),
+          ...(await missingArt(file, json)),
+        ],
+      };
+    }
     return {
       file,
-      ok: true,
-      warnings: [
-        ...auditScene(json, { declaredElsewhere, instanced: instanced.has(resolve(file)) }),
-        ...missingArt(file, json),
-      ],
+      ok: false,
+      code: res.error?.code,
+      message: res.error?.message,
+      details: res.error?.details,
     };
-  }
-  return {
-    file,
-    ok: false,
-    code: res.error?.code,
-    message: res.error?.message,
-    details: res.error?.details,
-  };
-});
+  }),
+);
 
 const failed = results.filter((r) => !r.ok);
 const warned = results.reduce((n, r) => n + (r.warnings?.length ?? 0), 0);

package/bin/incanto-editor.mjs

@@ -30,7 +30,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { readJson } from './_read-json.mjs';
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -463,7 +463,7 @@ const server = createServer((req, res) => {
       if (!originAllowed(req)) {
         return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
       }
-      readBody(req, res, (body) => {
+      readBody(req, res, async (body) => {
         // a path with no extension means the usual thing, so `levels/arena` works
         const wanted =
           typeof body?.path === 'string' && body.path && !body.path.endsWith('.json')
@@ -495,14 +495,20 @@ const server = createServer((req, res) => {
          */
         const asked = body?.dimension === '3d' || body?.dimension === '2d' ? body.dimension : null;
         const dimension = asked ?? projectDimension() ?? '2d';
-        const scene = {
-          format: 1,
-          type: 'scene',
-          dimension,
-          name,
-          root: { name, type: dimension === '3d' ? 'Node3D' : 'Node2D' },
-        };
         try {
+          // uid at CREATION, like every node the editor makes: without it the
+          // first save backfills one and the diff carries a line nobody wrote.
+          // Imported here rather than at the top so starting the editor never
+          // pays for `dist` it may not otherwise need — inside the try, so a
+          // missing build is a 400 and not a dead server.
+          const { newUid } = await import(pathToFileURL(join(PKG_ROOT, 'dist', 'index.js')).href);
+          const scene = {
+            format: 1,
+            type: 'scene',
+            dimension,
+            name,
+            root: { name, type: dimension === '3d' ? 'Node3D' : 'Node2D', uid: newUid() },
+          };
           mkdirSync(dirname(abs), { recursive: true });
           writeFileSync(abs, formatSceneJson(scene));
           return send(res, 201, JSON.stringify({ rel: relative(ROOT, abs), abs }));

package/bin/incanto-feel.mjs

@@ -60,7 +60,17 @@ if (args.help || !args.scene) {
                     pushed +x/-y/+y/-x until the player moves)
   --jump ACTION     the button to jump with (default: "jump")
   --json            the report as JSON instead of prose`);
-  process.exit(!args.invalid && args.help && args.scene !== undefined ? 0 : 1);
+  /*
+   * `--help` is a REQUEST, and the answer is the text above.
+   *
+   * The rule used to be "0 only if a scene was also named", so the exact thing
+   * an agent types first — `incanto-playtest --help` — printed the usage and
+   * exited 1, while thirteen sibling bins exited 0 for the same input. A
+   * non-zero exit says "you did it wrong" to someone who did the documented
+   * thing, and under `set -e` it stops the script. A typo still exits 1
+   * (`invalid`), and so does a missing scene when help was not asked for.
+   */
+  process.exit(args.help && !args.invalid ? 0 : 1);
 }
 
 const { facingReport, facingText, feelReport, feelText } = await import(

package/bin/incanto-play.mjs

@@ -69,7 +69,17 @@ if (args.help || !args.scene) {
 
 Headless play: stdin commands (step/press/release/vector/key/mouse/pointer/
 wheel/capture/describe/framing/logs/quit), JSON-line responses on stdout.`);
-  process.exit(!args.invalid && args.help && args.scene !== undefined ? 0 : 1);
+  /*
+   * `--help` is a REQUEST, and the answer is the text above.
+   *
+   * The rule used to be "0 only if a scene was also named", so the exact thing
+   * an agent types first — `incanto-playtest --help` — printed the usage and
+   * exited 1, while thirteen sibling bins exited 0 for the same input. A
+   * non-zero exit says "you did it wrong" to someone who did the documented
+   * thing, and under `set -e` it stops the script. A typo still exits 1
+   * (`invalid`), and so does a missing scene when help was not asked for.
+   */
+  process.exit(args.help && !args.invalid ? 0 : 1);
 }
 
 const out = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);

package/bin/incanto-playtest.mjs

@@ -92,7 +92,17 @@ if (args.help || !args.scene) {
 Exits 1 when a run THREW or left the world, or when a win is declared and no
 run reached it. A scene that declares no win, or has nobody to drive, exits 0 —
 the report marks those · rather than ✗, and the exit code says the same.`);
-  process.exit(!args.invalid && args.help && args.scene !== undefined ? 0 : 1);
+  /*
+   * `--help` is a REQUEST, and the answer is the text above.
+   *
+   * The rule used to be "0 only if a scene was also named", so the exact thing
+   * an agent types first — `incanto-playtest --help` — printed the usage and
+   * exited 1, while thirteen sibling bins exited 0 for the same input. A
+   * non-zero exit says "you did it wrong" to someone who did the documented
+   * thing, and under `set -e` it stops the script. A typo still exits 1
+   * (`invalid`), and so does a missing scene when help was not asked for.
+   */
+  process.exit(args.help && !args.invalid ? 0 : 1);
 }
 
 const { playtest, playtestText, playtestFailed, failingReplays } = await import(

package/bin/incanto-verify.mjs

@@ -4,6 +4,7 @@
  *
  *   bunx incanto-verify                      # finds your scene
  *   bunx incanto-verify src/game.scene.json --behaviors src/behaviors.ts
+ *   bunx incanto-verify src/game.scene.json --runs 16      # more seeds for the plays rung
  *
  * The rungs already existed and were used one at a time, because using them
  * together means knowing three things nobody writes down: the order, that the
@@ -31,8 +32,14 @@ const { feelsRung, firstLine, ladderText, ladderVerdict, saysRung, unmeasuredPla
 
 const argv = process.argv.slice(2);
 const asJson = argv.includes('--json');
+// `--runs N` for the plays rung. Eight seeds see a one-in-eight event 64% of
+// the time; a starter is where a rare fall costs the most, so the sweep asks
+// the six that ship for sixteen. The default stays 8 — every example, every
+// campaign, and the sweep's seven minutes are the reason.
+const runsAt = argv.indexOf('--runs');
+const RUNS = runsAt >= 0 && /^\d+$/.test(argv[runsAt + 1] ?? '') ? argv[runsAt + 1] : '8';
 if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE[,FILE...]] [--json]
+  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE[,FILE...]] [--runs N] [--json]
 
 Walks the whole ladder and tells you the ONE thing to do next:
 
@@ -223,7 +230,7 @@ let botPlayed = true;
 
 // ---- plays ---------------------------------------------------------------
 if (rungs[0].status === 'pass') {
-  const args = [scene, '--json', '--runs', '8'];
+  const args = [scene, '--json', '--runs', RUNS];
   if (behaviors) args.push('--behaviors', behaviors);
   const r = run('playtest', args);
   const out = safeJson(r.stdout);

package/dist/2d.d.ts

@@ -1,10 +1,10 @@
-import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-L8yccdMP.js";
-import { 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-Dcz0fr1S.js";
+import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-BOrk4eQx.js";
+import { 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 { t as DiagnosticSink } from "./diagnostics-Cu85N3tL.js";
 import { a as SceneJson, s as JsonObject } from "./rng-Bb-IutXB.js";
 import { t as EditorSwitchOptions } from "./editor-switch-CFU9mCec.js";
 import { r as FrameStats } from "./frame-report-DNxDAb1w.js";
-import { t as LoadSceneOptions } from "./loader-8-IHvbKD.js";
+import { t as LoadSceneOptions } from "./loader-BAeWMYfF.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -159,9 +159,24 @@ declare class PhysicsBody2D extends Node2D {
   /** @internal Set by Physics2D when the body is created. */
   _physics: Physics2D | null;
 }
-/** Immovable collider (ground, walls, platforms). */
+/**
+* Immovable collider (ground, walls, platforms).
+*
+* It also carries the SURFACE it is: `friction` and `restitution` used to
+* live on `RigidBody2D` alone, so a trampoline, an ice patch or a sticky
+* landing could not be written in scene JSON, and Rapier's AVERAGE rule
+* halved whatever a ball brought to a plain floor. A static body's authored
+* value WINS the pair — restitution above 0 combines by Max, friction below
+* the default by Min and above it by Max — so the pad decides, whatever lands
+* on it. Left at the defaults, nothing changes for any existing scene.
+*/
 declare class StaticBody2D extends PhysicsBody2D {
   static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** 0.5 plain · 0 ice (slides on and on) · 1+ glue. Away from 0.5 it wins the pair. */
+  friction: number;
+  /** 0 dead · 1 trampoline. Above 0 it wins the pair: a dead ball still bounces. */
+  restitution: number;
 }
 /**
 * Sensor volume. Emits `triggerEnter(other)` / `triggerExit(other)` — the
@@ -184,6 +199,10 @@ declare class RigidBody2D extends PhysicsBody2D {
   fixedRotation: boolean;
   friction: number;
   restitution: number;
+  /** Drag, per second: velocity decays by `e^(-linearDamping·t)`. `0` = none. */
+  linearDamping: number;
+  /** Rolling resistance, per second, on the spin — see `RigidBody3D.angularDamping`. */
+  angularDamping: number;
   /** px/s, y-down. Read back every step; write to launch. */
   linearVelocity: number[];
   /**
@@ -250,6 +269,8 @@ declare class CharacterBody2D extends PhysicsBody2D {
   * `0` restores the old behaviour.
   */
   stepHeight: number;
+  /** See CharacterBody3D.collideWithCharacters — off, a crowd ignores itself and costs nothing. */
+  collideWithCharacters: boolean;
   /** @internal Updated by Physics2D.moveAndSlide. */
   _grounded: boolean;
   moveAndSlide(): void;
@@ -359,6 +380,10 @@ declare class Physics2D {
   */
   /** Drop one node from the overlap map, both as a key and as a member. */
   private forgetOverlaps;
+  /** Every overlap `node` is in ends now — the exits Rapier does not send for a disabled collider. */
+  private releaseOverlaps;
+  /** Every body the armed sensor is inside of RIGHT NOW enters it — the starts Rapier does not send for a re-enabled collider. */
+  private armOverlaps;
   private pruneOverlaps;
   /** The bodies currently overlapping `node`. Freed nodes are dropped on read. */
   overlapping(node: PhysicsBody2D): PhysicsBody2D[];

package/dist/2d.js

@@ -1,9 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
 import { t as isWebGLAvailable } from "./webgl-unavailable-C8aDbGmR.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CH4kt78v.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-BYQCBySi.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-FhrXUc6B.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CbTLFjis.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-CY9QCCZs.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CovokK7s.js";
 //#region src/2d/library-sprite.ts
 /**
 * What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in

package/dist/3d.d.ts

@@ -1,10 +1,10 @@
-import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-L8yccdMP.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-Dcz0fr1S.js";
+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 { 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 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-8-IHvbKD.js";
+import { t as LoadSceneOptions } from "./loader-BAeWMYfF.js";
 import { n as PathGrid } from "./pathfinding-_fGrCFmH.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
@@ -391,9 +391,24 @@ declare class PhysicsBody3D extends Node3D {
   /** @internal Set by Physics3D when the body is created. */
   _physics: Physics3D | null;
 }
-/** Immovable collider (ground, walls, platforms). */
+/**
+* Immovable collider (ground, walls, platforms).
+*
+* It also carries the SURFACE it is: `friction` and `restitution` used to
+* live on `RigidBody3D` alone, so a trampoline, an ice patch or a sticky
+* landing could not be written in scene JSON, and Rapier's AVERAGE rule
+* halved whatever a ball brought to a plain floor. A static body's authored
+* value WINS the pair — restitution above 0 combines by Max, friction below
+* the default by Min and above it by Max — so the pad decides, whatever lands
+* on it. Left at the defaults, nothing changes for any existing scene.
+*/
 declare class StaticBody3D extends PhysicsBody3D {
   static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** 0.5 plain · 0 ice (slides on and on) · 1+ glue. Away from 0.5 it wins the pair. */
+  friction: number;
+  /** 0 dead · 1 trampoline. Above 0 it wins the pair: a dead ball still bounces. */
+  restitution: number;
 }
 /** Sensor volume emitting `triggerEnter(other)` / `triggerExit(other)`. */
 declare class Area3D extends PhysicsBody3D {
@@ -435,6 +450,17 @@ declare class RigidBody3D extends PhysicsBody3D {
   fixedRotation: boolean;
   friction: number;
   restitution: number;
+  /**
+  * Drag, per second: velocity decays by `e^(-linearDamping·t)`. `0` = none.
+  * A body flying through nothing keeps its speed forever otherwise.
+  */
+  linearDamping: number;
+  /**
+  * Rolling resistance, per second, on the spin. Rapier has none by itself:
+  * friction only converts slip into spin, so a rolling ball is a wheel and a
+  * golf ball rolled to the edge of the world. `1`–`3` stops a ball on a green.
+  */
+  angularDamping: number;
   /** m/s, y-up. Read back every step; write to launch. */
   linearVelocity: number[];
   /**
@@ -481,6 +507,16 @@ declare class CharacterBody3D extends PhysicsBody3D {
   /** Max climbable slope angle. */
   slopeLimitDeg: number;
   /**
+  * Whether OTHER characters are obstacles to this one. On (default), a
+  * character is a wall to every other character — Godot's answer, and what a
+  * few enemies want. Off, the controller ignores every other kinematic body
+  * and a crowd costs what the floor and the walls cost: eighty chasers around
+  * a player cost 64–286 ms a step with this on (each slide shape-casts
+  * against every neighbour, O(n²) in the crowd) and under a millisecond off.
+  * A survivor's horde overlaps itself and nobody minds.
+  */
+  collideWithCharacters: boolean;
+  /**
   * How high a step this body walks UP without jumping (0 = none).
   *
   * Rapier's character controller does not autostep unless asked, and nothing
@@ -637,7 +673,12 @@ declare class Physics3D {
   * off ONE fixed body — they never move, so there is nothing to step — and the
   * whole set is rebuilt only when the tree's shape changes.
   */
-  /** Where each live scatter field was when its colliders were built. */
+  /**
+  * Where each live scatter field was when its colliders were built — and what
+  * they were built FROM. Rows and place were remembered from the start; the
+  * stone itself (`mesh`, `size`, the `collider` spec) was not, so a field
+  * grown at runtime, or resized in the inspector, collided as the old stones.
+  */
   private readonly scatterState;
   /**
   * Has any scatter field moved, or had its rows replaced, since the build?
@@ -650,6 +691,24 @@ declare class Physics3D {
   private syncScatters;
   private syncBodies;
   /**
+  * The stamp an auto body is compared against, reused across every body and
+  * step: the walk writes here instead of returning an object, because it runs
+  * once per auto body per step and a village of crates must not allocate.
+  */
+  private readonly stamp;
+  /** An auto body whose carried mesh (or mounted model) is not what it was built from. */
+  private autoReshaped;
+  private rememberAutoShape;
+  /**
+  * The same choice `meshesUnder` makes — the FIRST carried mesh in tree
+  * order, else the first mounted model — reduced to the numbers the collider
+  * was built from, so a change in any of them is visible without a rebuild.
+  */
+  private stampAutoShape;
+  private walkAutoShape;
+  /** A heightfield body whose Terrain3D regenerated its grid since the build. */
+  private heightfieldReshaped;
+  /**
   * Null while a `{"shape":"auto"}` body is waiting on its model — the shape
   * lives in the model's triangles, and there is nothing honest to guess in the
   * meantime. syncBodies runs every step, so the body appears the moment the
@@ -676,6 +735,10 @@ declare class Physics3D {
   */
   /** Drop one node from the overlap map, both as a key and as a member. */
   private forgetOverlaps;
+  /** Every overlap `node` is in ends now — the exits Rapier does not send for a disabled collider. */
+  private releaseOverlaps;
+  /** Every body the armed sensor is inside of RIGHT NOW enters it — the starts Rapier does not send for a re-enabled collider. */
+  private armOverlaps;
   private pruneOverlaps;
   /**
   * The bodies currently overlapping `node` — the standing answer behind
@@ -1424,12 +1487,8 @@ declare class Camera3D extends Node3D {
   current: boolean;
   lookAt: string;
   /**
-  * Aim, every frame, whenever `lookAt` names something.
-  *
-  * In `update` and not `_syncObject3D`: the second is the renderer's copy pass
-  * and a static node is pruned from it, which silently freezes anything driven
-  * there. `rotation` is written as an ordinary prop, so the editor, the
-  * serializer and `describeFraming` all see what the camera is actually doing.
+  * Aim, every frame, whenever `lookAt` names something — see `aimAt`, which
+  * the spot light shares.
   */
   /** The `lookAt` path already reported as unlookable — cleared by a new one. */
   private warnedLookAt;
@@ -1470,6 +1529,17 @@ declare class CharacterController3D extends Node3D {
   jumpCutMultiplier: number;
   maxJumps: number;
   airControl: number;
+  /**
+  * `[away, up]` m/s: airborne and pressing into a wall, `jump` kicks off it —
+  * away along the wall's normal, up. `[0, 0]` (default) = no wall-jumps.
+  * The controller owns this because a kick written from outside lasted three
+  * frames: the jump cut halved its rise on release and air control steered
+  * the horizontal straight back into the wall. After a kick, air control
+  * stands down for `WALL_LOCKOUT` so the kick lands.
+  */
+  wallJumpImpulse: number[];
+  /** Max fall speed (m/s) while pressing into a wall; 0 = no wall slide. */
+  wallSlideSpeed: number;
   fallGravity: number;
   floatHeight: number;
   /**
@@ -1568,6 +1638,10 @@ declare class CharacterController3D extends Node3D {
   private rising;
   /** Between the jump impulse and the landing — the animation's clock. */
   private jumping;
+  /** Seconds of air control still suppressed after a wall kick. */
+  private wallLockout;
+  /** The outward normal of the wall being pressed into this step, if any. */
+  private wallNormal;
   private get body();
   override onEnterTree(): void;
   override fixedUpdate(dt: number): void;
@@ -2169,6 +2243,44 @@ declare class OmniLight3D extends Node3D {
   protected override _createObject3D(): Object3D;
   override _syncObject3D(): void;
 }
+/**
+* A cone of light — a flashlight, a searchlight, a car's headlights, a stage
+* spot, a guard's torch.
+*
+* It AIMS down the node's local −Z, exactly like a camera: at rest it points
+* along −Z, `rotation: [-90, 0, 0]` points it at the floor, and a headlamp
+* mounted on a +Z-forward skin wants `rotation: [0, 180, 0]`. `coneDeg` is the
+* FULL angle of the cone (a "30° beam" is 30), converted to three's half-angle
+* here so nobody has to halve it by hand. `intensity` is in the same physical
+* units as `OmniLight3D` — tens, not ones. Shadows are a perspective map from
+* the cone's apex, so `castShadow` costs one extra render per frame per light.
+*/
+declare class SpotLight3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  color: string;
+  intensity: number;
+  /** 0 = unlimited (three `distance` semantics). */
+  range: number;
+  /** Full cone angle in degrees, exclusive of 0 and 180. */
+  coneDeg: number;
+  /** 0 = hard edge, 1 = the whole cone is falloff. */
+  penumbra: number;
+  castShadow: boolean;
+  shadowMapSize: number;
+  /**
+  * A node path to AIM at, every frame — the camera's prop, for the same
+  * reason: a searchlight that tracks the player, a stage spot on the boss.
+  * Aiming by hand is Euler arithmetic in XYZ order, where a yaw on the same
+  * node as a pitch swings the cone sideways (at yaw 180 a −55° pitch points
+  * UP). Empty = the authored `rotation` is the aim.
+  */
+  lookAt: string;
+  private warnedLookAt;
+  override update(_dt: number): void;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
 //#endregion
 //#region src/3d/nodes/loft-mesh-3d.d.ts
 /**
@@ -3395,9 +3507,19 @@ declare class VoxelGrid3D extends Node3D {
   * hard-fails at load; this one silently truncated.
   */
   static validateJson(node: Node): void;
-  /** JSON-authored blocks as [x, y, z, tile] tuples (generated terrains bake these). */
-  voxels: number[][];
-  private appliedVoxels;
+  private _voxels;
+  /**
+  * JSON-authored blocks as [x, y, z, tile] tuples (generated terrains bake
+  * these). The seed lands WHEN THE PROP DOES — at load, before the tree
+  * readies — not on the first `update()` as it used to: a sibling that
+  * builds chunk colliders from `blocks()` at ready (the minecraft template's
+  * Builder) saw an empty map and a baked hut was walked through, and the
+  * late `setBlocks` then WIPED whatever a generator had built at ready.
+  * Now a generator calling `setBlocks` after load is the author replacing
+  * the seed, never the seed replacing the author.
+  */
+  get voxels(): number[][];
+  set voxels(rows: number[][]);
   /** Said once per node: a runtime overflow must not spam a frame loop. */
   private reportedOverflow;
   private readonly map;
@@ -4278,4 +4400,4 @@ declare function createNavDebugNode(nav: TerrainNav, opts?: {
   name?: string;
 }): InstancedMesh3D;
 //#endregion
-export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type Rig, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type SceneJson, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, 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, 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 };