create-aura3d 1.1.2 → 1.3.0

package/templates/animation-studio/scripts/clip-decision-cli.ts

@@ -0,0 +1,51 @@
+/**
+ * clip-decision-cli.ts — B1 standalone proof of the per-beat clip-decision record.
+ *
+ * Builds a real {@link PerformanceRig} for a synthetic full-humanoid skeleton from the shared
+ * standard library and samples a beat, emitting the {@link ClipDecision} so a unit test can assert
+ * the B1 contract fields are present and populated:
+ *   { intent, clipId, source, bonesTouched, maxRotAmplitudeRad, maxTransAmplitude, reachedGLBRuntime }
+ * plus bodyBoneRotationRad + rootTranslation.
+ *
+ * Browser/GPU/Playwright-free: it drives `animation-performance.ts` directly (the same module
+ * scene-player.ts uses), so the proof is of the REAL decision producer, not a re-implementation.
+ *
+ * Usage: tsx scripts/clip-decision-cli.ts --intent talk --t 0.6
+ */
+import { createSharedClipRegistry, createPerformanceRig, resolveIntent } from "../src/animation-performance.js";
+
+function arg(name: string, fallback: string): string {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1]! : fallback;
+}
+
+// A full-humanoid skeleton (so retargeting maps the body bones and the decision carries real motion).
+const HUMANOID_NODES = [
+  "Hips", "Spine", "Chest", "UpperChest", "Neck", "Head",
+  "LeftShoulder", "LeftUpperArm", "LeftLowerArm", "LeftHand",
+  "RightShoulder", "RightUpperArm", "RightLowerArm", "RightHand",
+  "LeftUpperLeg", "LeftLowerLeg", "LeftFoot",
+  "RightUpperLeg", "RightLowerLeg", "RightFoot"
+];
+
+function main(): void {
+  const requestedIntent = arg("intent", "talk");
+  const t = Number(arg("t", "0.6"));
+  const registry = createSharedClipRegistry();
+  const rig = createPerformanceRig(registry, { nodeNames: HUMANOID_NODES, embeddedClips: ["Idle"] });
+  // resolveIntent normally maps a beat → standard intent; here we honor the requested intent directly
+  // unless it is non-standard, in which case resolveIntent derives one.
+  const intent = resolveIntent({
+    clip: requestedIntent,
+    moving: requestedIntent === "walk" || requestedIntent === "run",
+    running: requestedIntent === "run",
+    speaking: requestedIntent === "talk",
+    anyDialogue: true
+  });
+  const { decision } = rig.poseFor(intent, t);
+  // poseFor emits reachedGLBRuntime:false (the player flips it true after applyRetargetedPose). We
+  // assert the FIELD EXISTS here; the gate test below covers the true case from the render summary.
+  console.log(JSON.stringify(decision));
+}
+
+main();

package/templates/animation-studio/scripts/determinism-check.ts

@@ -0,0 +1,48 @@
+/**
+ * determinism-check.ts — renders the same document + range TWICE and verifies the
+ * frames are byte-identical, proving the render is deterministic given a document.
+ *
+ * Run: pnpm exec tsx --tsconfig tsconfig.base.json packages/create-aura3d/templates/animation-studio/scripts/determinism-check.ts
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(__dirname, "..", "..", "..", "..", "..");
+const TEMPLATE_ROOT = resolve(__dirname, "..");
+
+function render(outDir: string): void {
+  const r = spawnSync(
+    "pnpm",
+    ["exec", "tsx", "--tsconfig", "tsconfig.base.json", "packages/create-aura3d/templates/animation-studio/scripts/render-live.ts"],
+    { cwd: REPO, stdio: "ignore", env: { ...process.env, AURA_OUTPUT_DIR: outDir, AURA_PREVIEW_RANGE: "4-6" } }
+  );
+  if (r.status !== 0) throw new Error(`render to ${outDir} failed (status ${r.status})`);
+}
+
+function hashFrame(outDir: string): string | null {
+  const p = resolve(TEMPLATE_ROOT, outDir, "frames", "first.png");
+  if (!existsSync(p)) return null;
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+
+function main(): void {
+  console.log("rendering pass A (range 4-6) ...");
+  render("dist/episodes/determinism-a");
+  console.log("rendering pass B (range 4-6) ...");
+  render("dist/episodes/determinism-b");
+
+  const a = hashFrame("dist/episodes/determinism-a");
+  const b = hashFrame("dist/episodes/determinism-b");
+  console.log(`A first.png sha256 = ${a?.slice(0, 16)}…`);
+  console.log(`B first.png sha256 = ${b?.slice(0, 16)}…`);
+  const ok = a !== null && a === b;
+  console.log(`\nDETERMINISM ${ok ? "PASS" : "FAIL"} — same document ${ok ? "→ byte-identical frame." : "produced different frames."}`);
+  if (!ok) process.exitCode = 1;
+}
+
+main();

package/templates/animation-studio/scripts/generate-scene.ts

@@ -0,0 +1,95 @@
+/**
+ * generate-scene.ts — the SECOND-SCENE test (heuristic Director).
+ *
+ * Builds a DIFFERENT scene input (different shots/dialogue/blocking intent), runs it
+ * through the deterministic Director → EpisodeDocument → validates it → writes the
+ * document JSON. Then `AURA_DOCUMENT=<that json> ... render-live.ts` renders it through
+ * the SAME generic player — proving the renderer + Director generalize beyond Moon Garden.
+ *
+ * HONEST SCOPE: it reuses the Moon Garden cast + set assets (so no catalog resolution is
+ * needed here) but generates entirely NEW direction (blocking, camera, shots, prop
+ * scatter, world-state). The captions still come from the Moon Garden dialogue track
+ * (dialogue-in-document is a follow-up). This proves the Director produces a *valid,
+ * renderable, distinct* scene — NOT that arbitrary prompts are "watchable" (the human
+ * rubric / watchability gate covers that, and remains the open risk).
+ *
+ * Run: pnpm exec tsx --tsconfig tsconfig.base.json packages/create-aura3d/templates/animation-studio/scripts/generate-scene.ts
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compileEpisodeDocument } from "../src/director/compile-episode-document.js";
+import type { DirectorSceneInput } from "../src/director/director-heuristics.js";
+import { validateEpisodeDocument } from "../src/animation-episode-validator.js";
+import { moonGardenDocument } from "../src/examples/moon-garden.example.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUT_DIR = resolve(__dirname, "..", "dist", "generated");
+const OUT_PATH = resolve(OUT_DIR, "second-scene.document.json");
+
+// A different scene: both characters ENTER from the sides, CONVERGE through the middle
+// beats, and the speaker alternates — completely different staging from Moon Garden.
+const secondScene: DirectorSceneInput = {
+  duration: 60,
+  characters: [
+    { id: "miko", entersFrom: "left" },
+    { id: "luma", entersFrom: "right" }
+  ],
+  shots: [
+    { shotId: "open", startTime: 0, endTime: 15 },
+    { shotId: "approach", startTime: 15, endTime: 32 },
+    { shotId: "together", startTime: 32, endTime: 48 },
+    { shotId: "close", startTime: 48, endTime: 60 }
+  ],
+  dialogue: [
+    { lineId: "l1", speakerId: "miko", startTime: 1, endTime: 14 },
+    { lineId: "l2", speakerId: "luma", startTime: 16, endTime: 31 },
+    { lineId: "l3", speakerId: "miko", startTime: 33, endTime: 47 },
+    { lineId: "l4", speakerId: "luma", startTime: 49, endTime: 59 }
+  ],
+  walkableBounds: { min: [-3.6, 0, -2], max: [3.6, 0, 2] },
+  props: [{ propId: "mushroom", count: 7, scaleRange: [0.06, 0.16], feetOffset: 2.8 }],
+  clips: { idle: "idle", walk: "walk", gesture: "wave" }
+};
+
+async function main(): Promise<void> {
+  const result = await compileEpisodeDocument({
+    id: "second-scene-001",
+    duration: 60,
+    assets: moonGardenDocument.assets,
+    set: moonGardenDocument.set,
+    scene: secondScene
+  });
+
+  const validation = validateEpisodeDocument(result.document, {
+    availableClipsByCharacter: {
+      miko: ["Loops"],
+      luma: ["Armature|ArmatureAction", "Armature|Armature.001Action", "Armature|PoseLib"]
+    }
+  });
+
+  mkdirSync(OUT_DIR, { recursive: true });
+  writeFileSync(OUT_PATH, `${JSON.stringify(result.document, null, 2)}\n`);
+
+  console.log("=== Director second-scene test (heuristics-only) ===");
+  console.log(`document: ${OUT_PATH}`);
+  console.log(`shots: ${result.document.shots.map((s) => `${s.shotId}[${s.startTime}-${s.endTime}] ${s.presetId}`).join(", ")}`);
+  console.log(
+    `blocking: ${result.document.blocking
+      .map((b) => `${b.characterId} (${b.shots.map((s) => `${s.shotId}:${s.waypoints.length}wp/${s.clip}`).join(", ")})`)
+      .join(" | ")}`
+  );
+  console.log(`setDressing: ${result.document.setDressing.length} props`);
+  console.log(`shape-valid: ${result.validation.ok}  coherence-valid: ${validation.ok}`);
+  if (validation.errors.length) console.log("ERRORS:\n - " + validation.errors.join("\n - "));
+  if (validation.warnings.length) console.log("warnings:\n - " + validation.warnings.join("\n - "));
+  console.log(
+    `\nrender it:\n  AURA_DOCUMENT=${OUT_PATH} AURA_OUTPUT_DIR=dist/episodes/second-scene \\\n` +
+      `    pnpm exec tsx --tsconfig tsconfig.base.json packages/create-aura3d/templates/animation-studio/scripts/render-live.ts`
+  );
+
+  if (!result.validation.ok || !validation.ok) process.exitCode = 1;
+}
+
+void main();