incanto 0.46.0 → 0.48.0

package/bin/incanto-verify.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * incanto-verify — the whole ladder, one command, one next action.
+ *
+ *   bunx incanto-verify                      # finds your scene
+ *   bunx incanto-verify src/game.scene.json --behaviors src/behaviors.ts
+ *
+ * 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
+ * first red rung makes the ones above it meaningless, and that "no dev server"
+ * is a question unasked rather than a failing game.
+ *
+ *   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.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { ladderText, ladderVerdict } = await import(
+  pathToFileURL(join(PKG, 'dist', 'test.js')).href
+);
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const flag = (name) => {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : null;
+};
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`Usage: incanto-verify [scene.json] [--behaviors FILE] [--json]
+
+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
+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. */
+function findScene() {
+  const named = argv.find((a) => !a.startsWith('-') && a.endsWith('.json'));
+  if (named) return named;
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 4 || found.length > 8) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (entry.name.endsWith('.scene.json')) found.push(full);
+    }
+  };
+  try {
+    walk(process.cwd(), 0);
+  } catch {
+    /* unreadable tree — the caller can always name the file */
+  }
+  return { scene: found.length === 1 ? found[0] : null, candidates: found };
+}
+
+const bin = (name) => join(PKG, 'bin', `incanto-${name}.mjs`);
+const run = (name, args) =>
+  spawnSync(process.execPath, [bin(name), ...args], {
+    encoding: 'utf-8',
+    timeout: 180_000,
+    // A playtest report carries a replay per losing run; the 1MB default
+    // truncates it and a truncated report is indistinguishable from a tool
+    // that would not start.
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+const { scene, candidates } = findScene();
+if (!scene) {
+  const report = ladderVerdict([], { candidates });
+  console.log(asJson ? JSON.stringify(report, null, 2) : ladderText(report));
+  process.exit(0);
+}
+if (!existsSync(scene) || !statSync(scene).isFile()) {
+  console.error(`no such scene: ${scene}`);
+  process.exit(1);
+}
+
+const behaviors = flag('--behaviors');
+const rungs = [];
+
+// ---- loads ---------------------------------------------------------------
+{
+  const r = run('check', [scene, '--json']);
+  const out = safeJson(r.stdout);
+  const problems = out?.files?.flatMap((f) => f.problems ?? []) ?? [];
+  rungs.push(
+    r.status === 0
+      ? { name: 'loads', status: 'pass', summary: 'the scene is legal and its assets resolve' }
+      : {
+          name: 'loads',
+          status: 'fail',
+          summary: problems[0]?.why ?? firstLine(r.stdout || r.stderr) ?? 'incanto-check failed',
+          fix: `fix that, then run again — nothing above this rung means anything until it is green (\`incanto-check ${scene}\` for the detail)`,
+        },
+  );
+}
+
+// ---- plays ---------------------------------------------------------------
+if (rungs[0].status === 'pass') {
+  const args = [scene, '--json', '--runs', '8'];
+  if (behaviors) args.push('--behaviors', behaviors);
+  const r = run('playtest', args);
+  const out = safeJson(r.stdout);
+  const won = out?.runs?.filter((x) => x.outcome === 'won').length ?? 0;
+  const total = out?.runs?.length ?? 0;
+  // A scene that declares no win is not a scene that cannot be won: a
+  // walkabout template has no end, and calling that a failure sends its author
+  // hunting a bug that was never there.
+  const noGoal = out && out.declaresWin === false;
+  rungs.push(
+    r.status === 0
+      ? { name: 'plays', status: 'pass', summary: `${won} of ${total} seeded runs finished it` }
+      : noGoal
+        ? {
+            name: 'plays',
+            status: 'unmeasured',
+            summary: `nothing declares a win — ${total} runs played without error, and there was no end to reach`,
+            fix: 'if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)',
+          }
+        : {
+            name: 'plays',
+            status: 'fail',
+            summary:
+              total > 0 ? `no run finished it (${total} tried)` : 'the playtest could not run',
+            fix: behaviors
+              ? `see which runs stalled and where: \`incanto-playtest ${scene} --behaviors ${behaviors}\``
+              : `run it with your behaviours — without them the structure plays and your game logic does not: \`incanto-playtest ${scene} --behaviors src/behaviors.ts\``,
+          },
+  );
+} else {
+  rungs.push({ name: 'plays', status: 'skipped', summary: 'not run — the scene does not load' });
+}
+
+// ---- draws ---------------------------------------------------------------
+{
+  const r = run('frame', ['--json']);
+  const out = safeJson(r.stdout);
+  const report = out?.report;
+  if (!report) {
+    rungs.push({
+      name: 'draws',
+      status: 'unmeasured',
+      summary: firstLine(r.stderr) ?? 'no dev server with a page open',
+      fix: /not drawing/.test(r.stderr ?? '')
+        ? 'bring the preview window to the front — a hidden tab does not render, and a frame is captured inside a render'
+        : 'start your dev server, open the page, and run this again — the pixels are in the browser',
+    });
+  } else if (report.black) {
+    rungs.push({
+      name: 'draws',
+      status: 'fail',
+      summary: 'BLACK SCREEN — nothing was drawn',
+      fix: 'no light, no current camera, or nothing in view: `incanto-frame --out shot.png` and look',
+    });
+  } else if (!report.subject) {
+    rungs.push({
+      name: 'draws',
+      status: 'fail',
+      summary: 'nothing but background — the camera is pointed away from the scene',
+      fix: 'check the camera: `incanto-frame --out shot.png` and look at what it is aimed at',
+    });
+  } else {
+    rungs.push({
+      name: 'draws',
+      status: 'pass',
+      summary: `subject fills ${(report.subject.coverage * 100).toFixed(1)}% of the frame`,
+    });
+  }
+}
+
+/**
+ * The JSON in `text`, past whatever a dependency printed first. Rapier's
+ * 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('{');
+  if (start < 0) return null;
+  try {
+    return JSON.parse(raw.slice(start));
+  } catch {
+    return null;
+  }
+}
+function firstLine(text) {
+  const line = (text ?? '').split('\n').find((l) => l.trim());
+  return line ? line.trim() : null;
+}
+
+const verdict = ladderVerdict(rungs);
+console.log(asJson ? JSON.stringify({ scene, ...verdict }, null, 2) : ladderText(verdict));
+// `exitCode`, never `process.exit()`: stdout to a PIPE is written
+// asynchronously, and exiting discards whatever has not flushed. A --json
+// report read by another program came back truncated — silently, and only
+// when piped, which is the only way a program reads it.
+process.exitCode = verdict.ok ? 0 : 1;

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
 import { D as QualityCaps, Et as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-62q0HWBO.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
-import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
+import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
 import { t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.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-Ct8XgsmV.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-DZ70IY26.js";
 import { n as PathGrid, s as SpatialPose } from "./pathfinding-C49JSNNq.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";
@@ -633,7 +633,7 @@ interface Game3D {
   * make "edit the scene" mean "edit wherever the simulation happens to be",
   * so the source is kept beside the game and handed over unchanged.
   */
-  sourceJson: SceneJson;
+  sourceJson: SceneJson$1;
   renderer: GameRenderer;
   physics: Physics3D | null;
   /**
@@ -931,6 +931,91 @@ declare class Environment3D {
 */
 declare function setEnvironment3D(engine: Engine, patch: JsonObject): void;
 //#endregion
+//#region src/3d/model-verdict.d.ts
+/**
+* What a GLB will DO in an incanto scene, judged from what is in the file.
+*
+* Finding an asset is somebody else's job and they do it better: the agent8
+* service has a vector search over the same library, and matching "a stocky
+* dwarf blacksmith" to a URL is not something a filename filter should attempt.
+* What no search can answer is whether the thing it found will work HERE —
+*
+*   will the library's animation clips play on it? (bone NAMES decide, and a
+*     rig that does not match keeps its bind pose with only a console warning)
+*   how tall is it? (a model authored in centimetres dwarfs the scene)
+*   does it stand on its own origin? (`monster_trumble_mega` sits ten units
+*     above its root, so a node at [0,0,0] puts it in the sky — `targetHeight`
+*     normalises SIZE, not position, which cost a day of this repo's time)
+*
+* Every one of those is in the file, and every one of them was learned the
+* expensive way. Pure arithmetic over an already-parsed report: no three, no
+* network, no GPU.
+*/
+/** The parts of `incanto-model`'s report this judges. */
+interface ModelFacts {
+  nodes: Array<{
+    name: string;
+  }>;
+  bbox: {
+    size: [number, number, number];
+    center: [number, number, number];
+    min: [number, number, number];
+    max: [number, number, number];
+  } | null;
+  animations: Array<{
+    name: string;
+    duration: number;
+  }>;
+  /** Meshes in the file. Zero means there is nothing to draw — see `kind`. */
+  meshes: number;
+  /** glTF skins. Zero means a prop, not a character. */
+  skins: number;
+  vrm: {
+    humanBones: number;
+  } | null;
+}
+type Rig = "mixamorig" | "vrm-humanoid" | "other" | "none";
+interface SceneJson {
+  assets: Record<string, {
+    type: "model" | "animation";
+    url: string;
+  }>;
+  /** Null for a clip: it is played BY a model, it is not one. */
+  node: {
+    name: string;
+    type: "ModelInstance3D";
+    props: Record<string, unknown>;
+  } | null;
+}
+interface ModelVerdict {
+  /**
+  * What the file IS. A clip is a `.glb` with a rig and no mesh — declared as a
+  * model it renders nothing at all, with no error, and every other signal
+  * about it says "character".
+  */
+  kind: "model" | "animation";
+  rig: Rig;
+  /** The `3d/animations` shelf plays on this as-is. */
+  takesLibraryClips: boolean;
+  /** Height in the file's own units (0 when there is no geometry to measure). */
+  height: number;
+  /** Where the model sits relative to its own origin: bottom-centre, in units. */
+  originOffset: [number, number, number];
+  /** Standing on its own origin — a node at [0,0,0] puts its feet on the floor. */
+  groundedAtOrigin: boolean;
+  /** Clip names baked into the file itself (playable by name, no asset entry). */
+  embeddedClips: string[];
+  sceneJson: SceneJson | null;
+}
+interface VerdictTarget {
+  url: string;
+  /** Scene asset key. Also names the node. */
+  key: string;
+}
+declare function modelVerdict(facts: ModelFacts, target?: VerdictTarget): ModelVerdict;
+/** The verdict as sentences: what to do, and what will bite if you do not. */
+declare function verdictText(v: ModelVerdict): string;
+//#endregion
 //#region src/3d/nodes/billboard-3d.d.ts
 /** Valid `Billboard3D.mode` values — drives the prop options AND validateJson. */
 declare const BILLBOARD_GROUP_MODES: readonly ["screen", "y", "none"];
@@ -3621,4 +3706,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, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, 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, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+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, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };

package/dist/3d.js

@@ -1,9 +1,96 @@
 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-BtCNdkjI.js";
-import { a as frameStats, i as frameSignature, n as diffSignatures, o as frameText, r as diffText, t as SIGNATURE_GRID } from "./frame-report-Lr3VO24R.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 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";
+//#region src/3d/model-verdict.ts
+/** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
+const MIXAMO = /^mixamorig[:_]?/i;
+/**
+* Anything outside this is not a character at this scale, and the fix is one
+* prop. Wide on purpose: a 2.4m ogre is a design choice, a 40m one is
+* centimetres.
+*/
+const CHARACTER_HEIGHT = {
+	min: .4,
+	max: 4
+};
+/** What `targetHeight` gets set to when a model is plainly the wrong scale. */
+const DEFAULT_TARGET_HEIGHT = 1.7;
+/** Fraction of the model's own height that its origin may drift before it matters. */
+const ORIGIN_TOLERANCE = .25;
+function rigOf(facts) {
+	if (facts.vrm && facts.vrm.humanBones > 0) return "vrm-humanoid";
+	if (facts.nodes.some((n) => MIXAMO.test(n.name))) return "mixamorig";
+	return facts.skins > 0 ? "other" : "none";
+}
+function modelVerdict(facts, target) {
+	const rig = rigOf(facts);
+	const kind = facts.meshes === 0 && facts.animations.length > 0 ? "animation" : "model";
+	const height = facts.bbox ? facts.bbox.size[1] : 0;
+	const offset = facts.bbox ? [
+		facts.bbox.center[0],
+		facts.bbox.min[1],
+		facts.bbox.center[2]
+	] : [
+		0,
+		0,
+		0
+	];
+	const slack = Math.max(height * ORIGIN_TOLERANCE, .05);
+	const grounded = !facts.bbox || Math.abs(offset[0]) <= slack && Math.abs(offset[1]) <= slack && Math.abs(offset[2]) <= slack;
+	const oddSize = height > 0 && (height < CHARACTER_HEIGHT.min || height > CHARACTER_HEIGHT.max);
+	const props = { model: `$${target?.key ?? "model"}` };
+	if (oddSize) props.targetHeight = DEFAULT_TARGET_HEIGHT;
+	return {
+		kind,
+		rig,
+		takesLibraryClips: kind === "model" && (rig === "mixamorig" || rig === "vrm-humanoid"),
+		height,
+		originOffset: offset,
+		groundedAtOrigin: grounded,
+		embeddedClips: facts.animations.map((a) => a.name),
+		sceneJson: target ? {
+			assets: { [target.key]: {
+				type: kind,
+				url: target.url
+			} },
+			node: kind === "animation" ? null : {
+				name: titleCase(target.key),
+				type: "ModelInstance3D",
+				props
+			}
+		} : null
+	};
+}
+const titleCase = (key) => key.split(/[-_\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("") || "Model";
+const round = (n) => String(Math.round(n * 100) / 100);
+/** The verdict as sentences: what to do, and what will bite if you do not. */
+function verdictText(v) {
+	const lines = [];
+	if (v.kind === "animation") {
+		lines.push("an animation CLIP — no mesh of its own. It plays ON a character: declare it as {\"type\":\"animation\"} and point a ModelInstance3D's `animation` at it. Used as a `model` it draws nothing at all, with no error");
+		if (v.embeddedClips.length > 0) lines.push(`clip: ${v.embeddedClips.join(", ")}`);
+		return lines.join("\n");
+	}
+	if (v.rig === "mixamorig") lines.push("mixamorig rig — the 3d/animations clips play on this as they are");
+	else if (v.rig === "vrm-humanoid") lines.push("VRM humanoid — clips are retargeted onto it automatically");
+	else if (v.rig === "other") lines.push("skinned, but NOT a mixamorig rig — the 3d/animations clips will not bind to it (bones are matched by name; a mismatch keeps the bind pose and only warns)");
+	else lines.push("no skeleton — a prop, not a character; `animation` does nothing here");
+	if (v.height > 0) {
+		const odd = v.height < CHARACTER_HEIGHT.min || v.height > CHARACTER_HEIGHT.max;
+		lines.push(`stands ${round(v.height)} units tall` + (odd ? ` — not a character's size; set targetHeight (${DEFAULT_TARGET_HEIGHT}) to fix it` : ""));
+	}
+	if (!v.groundedAtOrigin) {
+		const [x, y, z] = v.originOffset;
+		const where = Math.abs(y) > Math.abs(x) && Math.abs(y) > Math.abs(z) ? `${round(Math.abs(y))} units ${y > 0 ? "above" : "below"} the origin` : `off-centre by [${round(x)}, ${round(y)}, ${round(z)}]`;
+		lines.push(`does NOT stand on its own origin — it sits ${where}. A node at [0,0,0] puts it there too; offset the node, or expect an empty-looking frame`);
+	}
+	if (v.embeddedClips.length > 0) lines.push(`clips in the file: ${v.embeddedClips.join(", ")} (play by name, no asset needed)`);
+	return lines.join("\n");
+}
+//#endregion
 //#region src/3d/terrain-nav.ts
 function buildTerrainNav(terrain, opts) {
 	const cellSize = opts?.cellSize ?? 2;
@@ -115,4 +202,4 @@ function createNavDebugNode(nav, opts) {
 	return node;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };

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

@@ -2,12 +2,13 @@ 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 { 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 { 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 { a as frameStats, i as frameSignature } from "./frame-report-Lr3VO24R.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 { 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";
@@ -1545,6 +1546,12 @@ function prune(obj, visited) {
 //#endregion
 //#region src/3d/renderer.ts
 /**
+* How long a capture waits for the game's own loop before drawing its own
+* frame. Long enough that a running game answers from its normal loop (16ms),
+* short enough that a paused or occluded tab still answers promptly.
+*/
+const CAPTURE_NUDGE_MS = 120;
+/**
 * WebGL presentation layer: subscribes to `engine.updated`, mirrors the active
 * scene's node tree onto a three.js scene, applies the scene `environment`
 * header (ambient/background/sky/fog/shadows/exposure — see Environment3D),
@@ -1890,6 +1897,14 @@ var Renderer3D = class {
 				resolve,
 				reject
 			});
+			setTimeout(() => {
+				if (this.pendingCaptures.length > 0) try {
+					this.render();
+				} catch (error) {
+					const e = error instanceof Error ? error : new Error(String(error));
+					for (const w of this.pendingCaptures.splice(0)) w.reject(e);
+				}
+			}, CAPTURE_NUDGE_MS);
 		});
 	}
 	pendingCaptures = [];
@@ -2441,16 +2456,73 @@ async function createGame3D(opts) {
 		if (!capture) throw new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames");
 		return capture.call(renderer);
 	};
+	/**
+	* Run a drive script against the LIVE game, in real time.
+	*
+	* `step` waits on the wall clock rather than advancing a fixed timestep: this
+	* is the running game, with its own loop, its own physics and its own
+	* animation. Stepping it by hand would fight all three.
+	*/
+	const applyDrive = async (steps) => {
+		let frames = 0;
+		let watching = true;
+		const tick = () => {
+			if (!watching) return;
+			frames += 1;
+			requestAnimationFrame(tick);
+		};
+		requestAnimationFrame(tick);
+		for (const s of steps) switch (s.kind) {
+			case "press":
+				engine.input.pressAction(s.action);
+				break;
+			case "release":
+				engine.input.releaseAction(s.action);
+				break;
+			case "vector":
+				engine.input.setActionVector(s.action, s.x, s.y);
+				break;
+			case "key":
+				engine.input.handleKey(s.code, s.down);
+				break;
+			case "pointer":
+				engine.input.handlePointerMove(s.dx, s.dy);
+				break;
+			case "step":
+				await new Promise((r) => setTimeout(r, s.ms));
+				break;
+		}
+		watching = false;
+		return frames;
+	};
 	const hot = import.meta.hot;
 	if (hot) {
 		const onFrameRequest = (data) => {
 			const request = data;
 			const id = request?.id;
-			captureFramePixels().then((shot) => hot.send("incanto:frame-report", {
+			hot.send("incanto:frame-ack", { id });
+			const drive = request?.drive ? parseDrive(request.drive) : null;
+			if (drive?.error) {
+				hot.send("incanto:frame-report", {
+					id,
+					report: { error: drive.error }
+				});
+				return;
+			}
+			let droveFrames = null;
+			(drive ? applyDrive(drive.steps) : Promise.resolve(null)).then((frames) => {
+				droveFrames = frames;
+				return captureFramePixels();
+			}).then((shot) => hot.send("incanto:frame-report", {
 				id,
 				report: {
 					...frameStats(shot.pixels, shot.width, shot.height, { grid: request?.grid }),
-					signature: frameSignature(shot.pixels, shot.width, shot.height)
+					signature: frameSignature(shot.pixels, shot.width, shot.height),
+					...droveFrames === null ? {} : { droveFrames },
+					...request?.image ? { image: frameImage(shot.pixels, shot.width, shot.height, (w, h) => Object.assign(document.createElement("canvas"), {
+						width: w,
+						height: h
+					}), request.image) } : {}
 				}
 			})).catch((error) => hot.send("incanto:frame-report", {
 				id,
@@ -2459,6 +2531,30 @@ async function createGame3D(opts) {
 		};
 		hot.on("incanto:frame-request", onFrameRequest);
 		cleanups.push(() => hot.off?.("incanto:frame-request", onFrameRequest));
+		const onLogsRequest = (data) => {
+			const id = data?.id;
+			try {
+				hot.send("incanto:logs-report", {
+					id,
+					report: logReport({
+						entries: engine.log.entries(),
+						stats: {
+							...engine.stats(),
+							...renderer.stats?.() ?? {}
+						},
+						assetErrors: renderer.assets?.errors() ?? [],
+						hidden: typeof document !== "undefined" && document.hidden
+					})
+				});
+			} catch (error) {
+				hot.send("incanto:logs-report", {
+					id,
+					report: { error: error instanceof Error ? error.message : String(error) }
+				});
+			}
+		};
+		hot.on("incanto:logs-request", onLogsRequest);
+		cleanups.push(() => hot.off?.("incanto:logs-request", onLogsRequest));
 	}
 	cleanups.push(pauseWhenHidden(engine));
 	await report(1, "ready");

package/dist/{frame-report-Ct8XgsmV.d.ts → frame-report-DZ70IY26.d.ts}

@@ -28,6 +28,31 @@ interface FrameStats {
   meanLuma: number;
   /** Coarse mean colour per cell, rows top to bottom. */
   grid: GridCell[][];
+  /** What the frame is OF, or null when it is all background. */
+  subject: Subject | null;
+}
+/**
+* The thing in the shot: everything that is not the background.
+*
+* `black` and `uniform` answer "did anything render at all". They do not answer
+* the question that actually goes wrong — "is the thing IN the shot, and can
+* you see it" — and every visual defect reported against the editor's model
+* previews walked straight past them. A white square with a faint sky gradient
+* is neither black nor uniform; a character drawn as a speck in the corner has
+* a perfectly ordinary mean luminance.
+*/
+interface Subject {
+  /** Bounding box in pixels, origin top-left. */
+  box: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  };
+  /** Share of the frame's pixels that are subject, 0..1. */
+  coverage: number;
+  /** Touching an edge — the shot is a crop, and something is outside it. */
+  clipped: boolean;
 }
 interface FrameStatsOptions {
   /** Cells across and down. Default 16x9 — 144 cells, printable. */