incanto 0.48.0 → 0.50.0

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-play.mjs

@@ -62,8 +62,11 @@ wheel/capture/describe/framing/logs/quit), JSON-line responses on stdout.`);
 }
 
 const out = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
-const fail = (cmd, e) =>
+let failures = 0;
+const fail = (cmd, e) => {
+  failures += 1;
   out({ ok: false, cmd, error: { code: e?.code ?? 'ERROR', message: e?.message ?? String(e) } });
+};
 
 const { createPlaySession } = await import(pathToFileURL(join(PKG, 'dist', 'test.js')).href);
 const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
@@ -204,21 +207,43 @@ function handle(line) {
 }
 
 if (args.commands) {
-  for (const line of readFileSync(resolve(args.commands), 'utf-8').split('\n')) {
-    if (!handle(line)) process.exit(0);
+  const text = readFileSync(resolve(args.commands), 'utf-8');
+  // A REPLAY, not a command script. `incanto-playtest` writes its failing runs
+  // as ReplayJson and the docs point this flag at them; reading one as text
+  // rejected every line as UNKNOWN_COMMAND and still exited 0, so the tool's
+  // whole payoff — "the failure comes back as a file you can watch" — silently
+  // did nothing.
+  const recording = text.trimStart().startsWith('{') ? JSON.parse(text) : null;
+  if (recording?.replay) {
+    incanto.replay(session.engine, recording);
+    out({
+      ok: true,
+      cmd: 'replay',
+      frames: recording.ticks.length,
+      events: recording.events.length,
+    });
+    out({ ok: true, cmd: 'describe', text: session.describe() });
+    session.dispose();
+    process.exitCode = 0;
+  } else {
+    for (const line of text.split('\n')) {
+      if (!handle(line)) break;
+    }
+    session.dispose();
+    // A script whose every line was rejected must not report success: that is
+    // exactly how a replay pointed at the wrong reader stayed invisible.
+    process.exitCode = failures > 0 ? 1 : 0;
   }
-  session.dispose();
-  process.exit(0);
-}
-
-const rl = createInterface({ input: process.stdin });
-rl.on('line', (line) => {
-  if (!handle(line)) {
-    rl.close();
+} else {
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', (line) => {
+    if (!handle(line)) {
+      rl.close();
+      process.exit(0);
+    }
+  });
+  rl.on('close', () => {
+    session.dispose();
     process.exit(0);
-  }
-});
-rl.on('close', () => {
-  session.dispose();
-  process.exit(0);
-});
+  });
+}

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

@@ -50,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;

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-BLDjy_PW.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-_9VBOHn6.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;

package/dist/3d.js

@@ -1,9 +1,9 @@
-import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-BQOeAid6.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-D1b0ydTS.js";
-import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-akjPkFv5.js";
+import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-DbaI313d.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-XFuqu5jv.js";
+import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-DqqxEax1.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-njybhZon.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CSoGjM8P.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DrpF5hcG.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;
@@ -25,6 +25,115 @@ function rigOf(facts) {
 	if (facts.nodes.some((n) => MIXAMO.test(n.name))) return "mixamorig";
 	return facts.skins > 0 ? "other" : "none";
 }
+/**
+* The locomotion clips every mixamorig character can play as they are.
+*
+* They are not art you go looking for — they are the rig's vocabulary, they
+* retarget onto anything mixamo-shaped (and through the humanoid map onto a
+* VRM), and this repo's own examples reference them 29 times. Nothing shipped
+* ever told an agent where they live, so a character found through an asset MCP
+* arrived with no way to walk.
+*
+* Keyed by the states `CharacterController3D` emits, so the map below IS the
+* controller's `animations` prop.
+*/
+const CLIP_BASE = "https://agent8-games.verse8.io/assets/3d/animations/mixamorig";
+const LOCOMOTION_CLIPS = {
+	idle: `${CLIP_BASE}/idle-00.glb`,
+	walk: `${CLIP_BASE}/walk.glb`,
+	run: `${CLIP_BASE}/run-medium.glb`,
+	fastRun: `${CLIP_BASE}/run-fast.glb`,
+	airborne: `${CLIP_BASE}/jump.glb`
+};
+/** The capsule the shipped templates use, and the skin fitted to it. */
+const BODY = {
+	radius: .34,
+	height: 1
+};
+/**
+* A found character, as a thing that walks.
+*
+* The model alone draws a statue: `CharacterController3D` must sit under a
+* dynamic body, the skin has to be sized to the capsule and dropped to its
+* feet, the clips have to be declared, and the input actions have to exist or
+* nothing reads the keyboard. Every one of those is a documented step and all
+* of them are needed at once, which is exactly the shape of thing worth
+* printing rather than describing.
+*/
+function characterJson(target) {
+	const assets = { [target.key]: {
+		type: "model",
+		url: target.url
+	} };
+	const animations = {};
+	for (const [state, url] of Object.entries(LOCOMOTION_CLIPS)) {
+		const key = `anims/${state}`;
+		assets[key] = {
+			type: "animation",
+			url
+		};
+		animations[state] = `$${key}`;
+	}
+	return {
+		assets,
+		input: {
+			move: {
+				type: "vector2",
+				keys: {
+					up: ["KeyW"],
+					down: ["KeyS"],
+					left: ["KeyA"],
+					right: ["KeyD"]
+				}
+			},
+			jump: {
+				type: "button",
+				keys: ["Space"]
+			},
+			sprint: {
+				type: "button",
+				keys: ["ShiftLeft"]
+			}
+		},
+		node: {
+			name: "Player",
+			type: "RigidBody3D",
+			groups: ["player"],
+			props: {
+				fixedRotation: true,
+				friction: 0,
+				collider: {
+					shape: "capsule",
+					radius: BODY.radius,
+					height: BODY.height
+				}
+			},
+			children: [{
+				name: "Controller",
+				type: "CharacterController3D",
+				props: {
+					view: "free",
+					coyoteSeconds: .12,
+					jumpBufferSeconds: .15,
+					animations
+				}
+			}, {
+				name: "Skin",
+				type: "ModelInstance3D",
+				props: {
+					model: `$${target.key}`,
+					targetHeight: BODY.height + 2 * BODY.radius,
+					position: [
+						0,
+						-(BODY.height / 2 + BODY.radius),
+						0
+					],
+					castShadow: true
+				}
+			}]
+		}
+	};
+}
 function modelVerdict(facts, target) {
 	const rig = rigOf(facts);
 	const kind = facts.meshes === 0 && facts.animations.length > 0 ? "animation" : "model";
@@ -51,6 +160,7 @@ function modelVerdict(facts, target) {
 		originOffset: offset,
 		groundedAtOrigin: grounded,
 		embeddedClips: facts.animations.map((a) => a.name),
+		characterJson: target && kind === "model" && (rig === "mixamorig" || rig === "vrm-humanoid") ? characterJson(target) : null,
 		sceneJson: target ? {
 			assets: { [target.key]: {
 				type: kind,

package/dist/{create-game-CniOiWzN.js → create-game-BLDjy_PW.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
-import { h as Engine, m as AudioPlayer } from "./register-BSXV8T9F.js";
+import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-DwazzlQb.js";
+import { h as Engine, m as AudioPlayer } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
-import { n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-R2JTnIMw.js";
+import { n as registerGameplayBehaviors } from "./gameplay-DbaI313d.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-BNPZYJmd.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-BmgXBNDB.js";
+import { n as enablePhysics2D } from "./physics-2d-_9VBOHn6.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
 /**

package/dist/{create-game-akjPkFv5.js → create-game-DqqxEax1.js}

@@ -1,15 +1,15 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
-import { _ as qualityCaps, h as Engine, m as AudioPlayer, y as qualityRendering } from "./register-BSXV8T9F.js";
+import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-DwazzlQb.js";
+import { _ as qualityCaps, h as Engine, m as AudioPlayer, y as qualityRendering } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { r as parseDrive, t as logReport } from "./log-report-lxrQY9cH.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
-import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-DbaI313d.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-D1b0ydTS.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-XFuqu5jv.js";
 import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-njybhZon.js";
-import { n as enablePhysics3D } from "./physics-3d-CSoGjM8P.js";
+import { n as enablePhysics3D } from "./physics-3d-DrpF5hcG.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

package/dist/{duplicate-CRtihGmC.js → duplicate-CI9WF_bg.js}

@@ -1,4 +1,4 @@
-import { i as serializeNode, t as buildNodeJson } from "./loader-r49nDwB4.js";
+import { i as serializeNode, t as buildNodeJson } from "./loader-DwazzlQb.js";
 //#region src/core/scene/duplicate.ts
 function stripUids(json) {
 	const { uid: _uid, ...rest } = json;

package/dist/{environment-presets-D1b0ydTS.js → environment-presets-XFuqu5jv.js}

@@ -1,10 +1,10 @@
-import { t as registerCoreNodes } from "./register-BSXV8T9F.js";
+import { t as registerCoreNodes } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-IyWCGe4q.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
-import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-BQOeAid6.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-D_p28jwU.js";
+import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-DbaI313d.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
@@ -2112,13 +2112,19 @@ var AnimatedSprite3D = class extends Sprite3D {
 	frameList = [];
 	frameIndex = 0;
 	frameTime = 0;
+	currentDef = null;
 	sheetTexture = null;
 	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) {
-		const def = this.animations[name];
-		if (!def) throw new IncantoError("UNKNOWN_ANIMATION", `No animation '${name}' on '${this.name}'. Available: [${Object.keys(this.animations).join(", ")}].`);
-		this.currentAnimation = name;
-		this.frameList = resolveFrames(def.frames, name);
+		const { name: resolved, def } = resolveAnimation(this.animations, name, this.name);
+		this.currentAnimation = resolved;
+		this.currentDef = def;
+		this.frameList = resolveFrames(def.frames, resolved);
 		this.frameIndex = 0;
 		this.currentFrame = this.frameList[0] ?? 0;
 		this.frameTime = 0;
@@ -2128,11 +2134,12 @@ var AnimatedSprite3D = class extends Sprite3D {
 		this.playing = false;
 	}
 	onReady() {
+		validateAnimationAliases(this.animations, this.name);
 		if (this.autoplay) this.play(this.autoplay);
 	}
 	update(dt) {
 		if (!this.playing || this.currentAnimation === "") return;
-		const def = this.animations[this.currentAnimation];
+		const def = this.currentDef;
 		if (!def || !Number.isFinite(def.fps) || def.fps <= 0) return;
 		const perFrame = 1 / def.fps;
 		this.frameTime += dt;
@@ -2173,18 +2180,6 @@ var AnimatedSprite3D = class extends Sprite3D {
 		super.free();
 	}
 };
-function resolveFrames(frames, name) {
-	if (!Array.isArray(frames) || frames.length === 0) throw new IncantoError("BAD_FORMAT", `Animation '${name}': "frames" must be a non-empty array.`);
-	if (frames.length === 2) {
-		const [start, end] = frames;
-		if (end >= start) {
-			const out = [];
-			for (let f = start; f <= end; f++) out.push(f);
-			return out;
-		}
-	}
-	return [...frames];
-}
 //#endregion
 //#region src/3d/nodes/billboard-3d.ts
 const _parentQ = new Quaternion();