incanto 0.47.0 → 0.49.0

package/bin/incanto-frame.mjs

@@ -26,6 +26,7 @@ const { listeningPorts, parseProcNetTcp } = await import(
   pathToFileURL(join(PKG, 'dist', 'vite.js')).href
 );
 const { frameText, diffText } = await import(pathToFileURL(join(PKG, 'dist', '3d.js')).href);
+const { parseDrive } = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
 
 const args = process.argv.slice(2);
 const asJson = args.includes('--json');
@@ -39,6 +40,8 @@ const flag = (name) => {
 const gridArg = flag('--grid');
 const outArg = flag('--out');
 const sizeArg = flag('--size');
+const driveArg = flag('--do');
+const driveFile = flag('--do-file');
 const remember = flag('--remember');
 const diff = flag('--diff');
 const threshold = flag('--threshold');
@@ -49,6 +52,8 @@ if (args.includes('--help') || args.includes('-h')) {
   --grid WxH      cells across and down (default 16x9)
   --out FILE      also write the frame as a PNG you can look at
   --size N        longest side of that PNG (default 512)
+  --do SCRIPT     drive the game first, THEN capture (see below)
+  --do-file FILE  the same script, from a file
   --port N        skip discovery and use this port
 
   --remember [L]  keep this frame as the baseline named L (default "last")
@@ -64,6 +69,17 @@ the frame it fills. When that is not enough, look:
 
   incanto-frame --out shot.png    # then open it, or read it
 
+Every interesting state in a game is downstream of input, so --do drives the
+running game before capturing — the same words incanto-play takes:
+
+  incanto-frame --do "vector move 0 1; step 3000; vector move 0 0" --out bridge.png
+  incanto-frame --do "press jump; step 400" --out midair.png
+
+  press/release ACTION · vector ACTION X Y · key CODE down|up
+  pointer DX DY · step MS        (semicolons or newlines separate)
+
+step waits on the real clock: this is the live game, with its own loop.
+
 
 The report of ONE frame has a floor: a one-pixel seam is a fraction of a level
 once a cell is averaged, and nothing can tell it apart from a thin rope in the
@@ -111,6 +127,24 @@ function bsdListeningPorts() {
   }
 }
 
+/** The script to run before capturing, from `--do` or `--do-file`. */
+const driveScript = driveFile ? read(driveFile) : driveArg;
+if (driveFile && driveScript === null) {
+  console.error(`cannot read ${driveFile}`);
+  process.exit(1);
+}
+if (driveScript) {
+  const parsed = parseDrive(driveScript);
+  if (parsed.error) {
+    // Refuse here rather than in the page: a bad command that ran nothing would
+    // hand back the boot screen, and nothing about that frame would say so.
+    console.error(
+      `${parsed.error}\n  commands: press/release ACTION · vector ACTION X Y · key CODE down|up · pointer DX DY · step MS`,
+    );
+    process.exit(1);
+  }
+}
+
 const explicit = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : null;
 const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
@@ -150,12 +184,20 @@ if (!found) {
 const params = new URLSearchParams();
 if (gridArg !== null) params.set('grid', gridArg);
 if (outArg) params.set('image', sizeArg || '512');
+if (driveScript) {
+  params.set('drive', driveScript);
+  // Tell the server how long to wait: the script runs in real time.
+  const totalMs = parseDrive(driveScript).totalMs;
+  params.set('driveMs', String(totalMs));
+}
 if (remember !== null) params.set('remember', remember);
 if (diff !== null) params.set('diff', diff);
 if (threshold) params.set('threshold', threshold);
 const q = params.toString();
 const res = await fetch(`http://${found.host}:${found.port}/__incanto/frame${q ? `?${q}` : ''}`, {
-  signal: AbortSignal.timeout(10_000),
+  // Outlast the server's own budget, or the CLI gives up on an answer that
+  // was on its way.
+  signal: AbortSignal.timeout(15_000 + (driveScript ? parseDrive(driveScript).totalMs * 2 : 0)),
 });
 const body = await res.json().catch(() => null);
 
@@ -184,6 +226,18 @@ if (!res.ok || !body?.report) {
 }
 
 const report = body.report;
+// A drive that advanced no frames moved nothing: the inputs landed on a game
+// the browser had frozen, and the frame that came back is the one from before.
+// Saying nothing here would be handing over a picture that quietly lies.
+if (driveScript && report.droveFrames === 0) {
+  console.error(
+    'the drive ran but the game never advanced — 0 frames drawn.\n' +
+      '  The page is hidden (a window covered by another counts) and the browser\n' +
+      '  stops animating it, so the inputs landed on a frozen game and this frame\n' +
+      '  is unchanged. Bring the preview to the front and try again.',
+  );
+  process.exit(1);
+}
 if (report.error) {
   console.error(`the page could not capture a frame: ${report.error}`);
   process.exit(1);
@@ -215,6 +269,9 @@ if (asJson) {
   );
 } else {
   const lines = [frameText(report)];
+  if (typeof report.droveFrames === 'number') {
+    lines.push(`drove ${report.droveFrames} frames before capturing`);
+  }
   if (wroteImage) lines.push(`wrote ${wroteImage} — open it, or read it`);
   if (body.diffError === 'no-baseline') {
     lines.push(

package/bin/incanto-logs.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * incanto-logs — what the RUNNING game is saying.
+ *
+ *   bunx incanto-logs
+ *   bunx incanto-logs --json
+ *
+ * `incanto-frame` gets the pixels out of the browser; this gets the WORDS. The
+ * engine writes diagnostics for exactly this purpose — a model whose fit came
+ * out at 934x, an asset that 404'd, a node that quarantined itself — and until
+ * now every one of them reached a human only, in the debug overlay's logs
+ * panel. An agent could see a game and not hear it.
+ *
+ * Unlike a frame this needs no render, so it answers from a tab the browser has
+ * stopped drawing.
+ *
+ * Exit 1 when the game reports something wrong: an error logged, an error
+ * swallowed to keep it alive, or an asset that never loaded.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { listeningPorts } = await import(pathToFileURL(join(PKG, 'dist', 'vite.js')).href);
+const { logText } = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+if (args.includes('--help') || args.includes('-h')) {
+  console.error(`Usage: incanto-logs [--json] [--port N]
+
+What the running game is saying: its warnings and errors, the errors it
+swallowed to keep going, the assets that never loaded, and its frame rate.
+
+Run your game's dev server and open the page first — the log buffer is in the
+browser, not in the dev server. This needs no render, so a page the browser has
+stopped drawing still answers.
+
+Exit 1 when something is wrong.`);
+  process.exit(0);
+}
+
+const read = (path) => {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+};
+
+/** Ports listening on a machine with no `/proc` (macOS, BSD) — see incanto-frame. */
+function bsdListeningPorts() {
+  try {
+    const { execFileSync } = createRequire(import.meta.url)('node:child_process');
+    const out = execFileSync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN'], {
+      encoding: 'utf-8',
+      timeout: 1500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const ports = new Set();
+    for (const line of out.split('\n')) {
+      const m = line.match(/:(\d+)\s*\(LISTEN\)/);
+      if (m) ports.add(Number(m[1]));
+    }
+    return [...ports];
+  } catch {
+    return [];
+  }
+}
+
+const explicit = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : null;
+const discovered = explicit ? [explicit] : await listeningPorts({ read });
+const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
+
+let found = null;
+outer: for (const port of ports) {
+  for (const host of ['localhost', '127.0.0.1']) {
+    try {
+      const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
+        signal: AbortSignal.timeout(300),
+      });
+      if (!res.ok) continue;
+      const body = await res.json();
+      if (body?.incanto) {
+        found = { host, port };
+        break outer;
+      }
+    } catch {
+      // not listening, not ours, or not answering — next
+    }
+  }
+}
+
+if (!found) {
+  console.error(
+    'no incanto dev server found.\n' +
+      '  Start your game (the dev server) and try again — the log buffer lives in\n' +
+      '  the running page, so there has to be one.',
+  );
+  process.exit(1);
+}
+
+const res = await fetch(`http://${found.host}:${found.port}/__incanto/logs`, {
+  signal: AbortSignal.timeout(10_000),
+});
+const body = await res.json().catch(() => null);
+
+if (res.status === 504 || body?.error === 'no-page-connected') {
+  console.error(
+    `the dev server is running on :${found.port}, but no page answered.\n` +
+      '  Open the preview in a browser — the log buffer is there, not in the server.',
+  );
+  process.exit(1);
+}
+if (!res.ok || !body?.report || body.report.error) {
+  console.error(
+    `could not read the game's logs: ${body?.report?.error ?? body?.error ?? res.status}`,
+  );
+  process.exit(1);
+}
+
+console.log(asJson ? JSON.stringify(body.report, null, 2) : logText(body.report));
+// `exitCode`, never `process.exit()` — stdout to a pipe is written
+// asynchronously and exiting discards what has not flushed.
+process.exitCode = body.report.ok ? 0 : 1;

package/bin/incanto-model.mjs

@@ -353,7 +353,19 @@ if (args.json) {
   // The verdict is the part you act on, so it goes last — closest to the
   // prompt, where a reader stops.
   out.push('', verdictText(verdict));
-  if (verdict.sceneJson) {
+  // A rig that takes the library clips gets the WHOLE character: the model on
+  // its own is a statue, and the steps from there (a dynamic body under the
+  // controller, the skin fitted to the capsule and dropped to its feet, the
+  // clips declared, the input actions that make anything read the keyboard)
+  // are documented in four different places and all needed at once.
+  if (verdict.characterJson) {
+    const { assets, input, node } = verdict.characterJson;
+    out.push(
+      '',
+      'paste a playable character into your scene:',
+      JSON.stringify({ assets, input, node }, null, 2),
+    );
+  } else if (verdict.sceneJson) {
     const { assets, node } = verdict.sceneJson;
     out.push(
       '',

package/bin/incanto-playtest.mjs

@@ -34,6 +34,8 @@ function parseArgs(argv) {
     else if (a === '--runs') args.runs = Number(argv[++i]);
     else if (a === '--seconds') args.seconds = Number(argv[++i]);
     else if (a === '--seed') args.seed = Number(argv[++i]);
+    else if (a === '--fall-below') args.fallBelow = Number(argv[++i]);
+    else if (a === '--reach-radius') args.reachRadius = Number(argv[++i]);
     else if (a === '--out') args.out = argv[++i];
     else if (a === '--no-replays') args.noReplays = true;
     else if (a === '--json') args.json = true;
@@ -53,6 +55,9 @@ if (args.help || !args.scene) {
   --runs N          independent seeded runs (default 20)
   --seconds N       simulated seconds per run before calling it stuck (default 60)
   --seed N          first seed; run i uses seed+i (default 1)
+  --fall-below Y    left the world past this y (default: 50 under the spawn in
+                    3D, 1000 px under it in 2D — 2D counts DOWN the screen)
+  --reach-radius R  how close counts as "reached" (default 2 in 3D, 32 px in 2D)
   --behaviors FILE  your Behavior subclasses (.ts works on node >= 23.6 / bun)
   --out DIR         where failing replays go (default .incanto/playtest)
   --no-replays      report only, write nothing
@@ -101,6 +106,8 @@ try {
     seed: args.seed,
     behaviors,
     stubMissingBehaviors: !args.behaviors,
+    ...(Number.isFinite(args.fallBelow) ? { fallBelow: args.fallBelow } : {}),
+    ...(Number.isFinite(args.reachRadius) ? { reachRadius: args.reachRadius } : {}),
     // sub-scenes resolve relative to the scene file, as the loader does
     resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
   });

package/bin/incanto-verify.mjs

@@ -13,6 +13,7 @@
  *   loads   incanto-check     the scene is legal and every asset resolves
  *   plays   incanto-playtest  a seeded run can actually finish it
  *   draws   incanto-frame     the GPU drew something, and the subject is in shot
+ *   says    incanto-logs      what the running game is complaining about
  *
  * Exit 1 when a rung FAILED. An unmeasured rung is not a failure — it prints
  * what to arrange, and says so in the summary.
@@ -41,6 +42,7 @@ Walks the whole ladder and tells you the ONE thing to do next:
   loads   the scene is legal and every asset resolves       (incanto-check)
   plays   a seeded run can actually finish it               (incanto-playtest)
   draws   the GPU drew something and the subject is in shot (incanto-frame)
+  says    the running game logs no errors and lost no assets (incanto-logs)
 
 Without a scene it looks for one *.scene.json under the current directory.
 "draws" needs a dev server with the page open; without one it is reported as
@@ -48,10 +50,18 @@ NOT MEASURED rather than failed — a missing measurement is not a broken game.`
   process.exit(0);
 }
 
-/** The scene to verify: the one named, or the only one that can be found. */
+/**
+ * The scene to verify: the one named, or the only one that can be found.
+ *
+ * ALWAYS the same shape. It used to return a bare string for a named scene and
+ * an object for a search, and the caller destructures — so `{ scene } = "a.json"`
+ * was `undefined` and naming your scene was the one way to make the whole
+ * ladder do nothing. It only ever worked when you named nothing, which is how
+ * it was run while being written.
+ */
 function findScene() {
   const named = argv.find((a) => !a.startsWith('-') && a.endsWith('.json'));
-  if (named) return named;
+  if (named) return { scene: named, candidates: [named] };
   const found = [];
   const walk = (dir, depth) => {
     if (depth > 4 || found.length > 8) return;
@@ -190,6 +200,35 @@ if (rungs[0].status === 'pass') {
  * deprecation notice lands on stdout ahead of the report, and treating that as
  * "the tool could not run" is how this reported a healthy scene as broken.
  */
+// ---- says ---------------------------------------------------------------
+{
+  const r = run('logs', ['--json']);
+  const report = safeJson(r.stdout);
+  if (!report) {
+    rungs.push({
+      name: 'says',
+      status: 'unmeasured',
+      summary: firstLine(r.stderr) ?? 'no page to ask',
+      fix: 'open the preview page and run this again — the log buffer is in the browser',
+    });
+  } else if (report.ok) {
+    rungs.push({ name: 'says', status: 'pass', summary: 'no errors, no failed assets' });
+  } else {
+    const asset = report.assetErrors?.[0];
+    rungs.push({
+      name: 'says',
+      status: 'fail',
+      // A game whose grass and water are fine still fails here when its player
+      // never loaded — which is the case this rung exists for, and the one
+      // `draws` calls healthy.
+      summary: asset
+        ? `asset ${asset.ref} never loaded: ${asset.error}`
+        : (report.worst?.message ?? `${report.stats?.errors ?? 0} errors were swallowed`),
+      fix: 'read it in full: `incanto-logs`',
+    });
+  }
+}
+
 function safeJson(text) {
   const raw = text ?? '';
   const start = raw.indexOf('{');

package/dist/2d.d.ts

@@ -2,6 +2,7 @@ import { Et as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engi
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
 import { t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
+import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -135,10 +136,16 @@ declare class RigidBody2D extends PhysicsBody2D {
 declare class CharacterBody2D extends PhysicsBody2D {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
+  /**
+  * Renamed to match the 3D body, where `snapToGround` had to give the name
+  * back to `Node3D`'s PLACEMENT prop. 2D has no placement prop, so nothing is
+  * ambiguous here and old scenes keep loading unchanged.
+  */
+  static readonly propAliases: Record<string, string>;
   /** px/s, y-down (up = -y). */
   velocity: number[];
   /** Keep contact on slopes/steps while not moving upward. */
-  snapToGround: boolean;
+  stickToGround: boolean;
   /** Max climbable slope angle. */
   slopeLimitDeg: number;
   /** @internal Updated by Physics2D.moveAndSlide. */
@@ -373,6 +380,11 @@ interface SpriteFromLibraryResult {
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset
 * declaration + AnimatedSprite2D props. `autoplay` defaults to the first
 * LOOPING animation (idle-like), falling back to the first one.
+*
+* The animation map also gets ALIASES for the movement states a character
+* controller emits but the sheet does not name (`run` → `move`, `fall` →
+* `idle`), so the converted props and the documented
+* `movementStateChanged → play` wiring work together out of the box.
 */
 declare function spriteFromLibraryMeta(meta: unknown, opts: {
   url: string;
@@ -411,15 +423,6 @@ declare class Sprite2D extends Node2D {
 }
 //#endregion
 //#region src/2d/nodes/animated-sprite-2d.d.ts
-interface AnimationDef {
-  /**
-  * Two numbers = inclusive [start, end] frame RANGE.
-  * Any other length = explicit frame list.
-  */
-  frames: number[];
-  fps: number;
-  loop?: boolean;
-}
 /**
 * Spritesheet animation: pure-JSON animation map, frame selection via a UV
 * window on the node's own texture clone. Frames advance in `update(dt)` —
@@ -431,7 +434,7 @@ declare class AnimatedSprite2D extends Sprite2D {
   static override readonly props: PropSchema;
   /** `'$assetKey'` of a spritesheet asset. */
   sheet: string;
-  animations: Record<string, AnimationDef>;
+  animations: Record<string, AnimationEntry>;
   autoplay: string;
   playing: boolean;
   /** Absolute frame index within the sheet. */
@@ -440,8 +443,14 @@ declare class AnimatedSprite2D extends Sprite2D {
   private frameList;
   private frameIndex;
   private frameTime;
+  private currentDef;
   private ownTexture;
   private loadedSheetRef;
+  /**
+  * `currentAnimation` reports the clip that is RUNNING, not the name asked
+  * for: an alias is a rename, and a state machine that reads back `fall` while
+  * the idle frames play is describing something that is not happening.
+  */
   play(name: string): void;
   stop(): void;
   override onReady(): void;
@@ -920,4 +929,4 @@ declare function parseCells(cells: readonly (string | readonly number[])[], lege
 */
 declare function mergeSolidRects(grid: readonly (readonly number[])[], solid: Set<number>): TileRect[];
 //#endregion
-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, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, 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, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };

package/dist/2d.js

@@ -1,12 +1,65 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CniOiWzN.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-R2JTnIMw.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BmgXBNDB.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BgV6UbVA.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-BNPZYJmd.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-vyCBfACH.js";
 //#region src/2d/library-sprite.ts
 /**
+* What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in
+* a library sheet that answers for it.
+*
+* The two vocabularies never met: the controller emits `run`, every library
+* sheet calls it `move`, and no sheet anywhere ships a `fall` — so the wiring
+* the 2D skill documents in one line (`movementStateChanged → play`) asked for
+* animations that do not exist, on artwork from the engine's own catalog.
+*
+* These are ALIASES, so they read as what they are, and the author can point
+* any of them somewhere better.
+*/
+const CONTROLLER_STATES = [
+	["run", [
+		"run",
+		"move",
+		"walk"
+	]],
+	["jump", ["jump", "idle"]],
+	["fall", [
+		"fall",
+		"jump",
+		"idle"
+	]],
+	["wallSlide", ["wallSlide", "idle"]],
+	["dash", [
+		"dash",
+		"run",
+		"move",
+		"idle"
+	]]
+];
+/**
+* Fill in the states the sheet does not name, and touch nothing it does.
+*
+* Silent when there is no `idle` to fall back on: a spinning-coin sheet is not
+* a character, and inventing movement states for it would put clips in the map
+* that mean nothing.
+*/
+function addControllerStates(animations) {
+	const real = new Set(Object.keys(animations));
+	if (!real.has("idle")) return;
+	for (const [state, candidates] of CONTROLLER_STATES) {
+		if (real.has(state)) continue;
+		const target = candidates.find((c) => c !== state && real.has(c));
+		if (target) animations[state] = target;
+	}
+}
+/**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset
 * declaration + AnimatedSprite2D props. `autoplay` defaults to the first
 * LOOPING animation (idle-like), falling back to the first one.
+*
+* The animation map also gets ALIASES for the movement states a character
+* controller emits but the sheet does not name (`run` → `move`, `fall` →
+* `idle`), so the converted props and the documented
+* `movementStateChanged → play` wiring work together out of the box.
 */
 function spriteFromLibraryMeta(meta, opts) {
 	const m = meta;
@@ -25,6 +78,7 @@ function spriteFromLibraryMeta(meta, opts) {
 		firstName ??= name;
 		if (loop && firstLooping === null) firstLooping = name;
 	}
+	addControllerStates(animations);
 	const autoplay = opts.autoplay ?? firstLooping ?? firstName;
 	return {
 		asset: {

package/dist/3d.d.ts

@@ -370,9 +370,27 @@ declare class CharacterBody3D extends PhysicsBody3D {
   static override readonly props: PropSchema;
   /** m/s, y-up (up = +y). */
   velocity: number[];
-  snapToGround: boolean;
+  /**
+  * Hold the capsule against the surface while it moves, so walking down a
+  * slope does not become a series of small falls.
+  *
+  * Named apart from `Node3D.snapToGround` (which PLACES a node on the ground
+  * at load) because sharing the name silently broke both: the boolean shadowed
+  * the placement prop, its `true` default made the placement pass teleport
+  * every character body in a terrain scene, and a lift value was rejected
+  * outright — so the only escape from the teleport also turned this off.
+  */
+  stickToGround: boolean;
   /** Max climbable slope angle. */
   slopeLimitDeg: number;
+  /**
+  * `snapToGround` on a character body is ambiguous, so it is refused.
+  *
+  * A boolean here used to mean the ground-stick, and as placement it means
+  * "leave y alone" — which is already the default. Rather than pick one and
+  * silently do the other thing to an existing scene, say which prop was meant.
+  */
+  override onReady(): void;
   /** @internal Updated by Physics3D.moveAndSlide. */
   _grounded: boolean;
   moveAndSlide(): void;
@@ -1006,6 +1024,25 @@ interface ModelVerdict {
   /** Clip names baked into the file itself (playable by name, no asset entry). */
   embeddedClips: string[];
   sceneJson: SceneJson | null;
+  /**
+  * The whole playable character — body, controller, skin, clips and input —
+  * for a rig that can take the library's locomotion clips. Null for a prop.
+  *
+  * The model on its own is a statue, and every step from there is documented
+  * somewhere different: the controller must sit under a dynamic body, the skin
+  * must be sized to the capsule and dropped to its feet, the clips must be
+  * declared, and the input actions must exist or nothing reads the keyboard.
+  */
+  characterJson: CharacterJson | null;
+}
+interface CharacterJson {
+  assets: Record<string, {
+    type: string;
+    url: string;
+  }>;
+  /** The actions `CharacterController3D` reads — without them it never moves. */
+  input: Record<string, unknown>;
+  node: Record<string, unknown>;
 }
 interface VerdictTarget {
   url: string;