create-aura3d 1.1.2 → 1.3.0

package/templates/animation-studio/src/animation-performance.ts

@@ -0,0 +1,556 @@
+/**
+ * animation-performance.ts — the Phase 2.5 KEYSTONE helper for `scene-player.ts`.
+ *
+ * It turns the SHARED, rig-neutral animation library (`@aura3d/animation`'s standard humanoid
+ * clip registry + performance state graph) into per-frame poses that drive ANY character GLB:
+ *
+ *   beat clip intent  ──▶  performance state graph  ──▶  sample standard library clip
+ *                                                          │ (rig-neutral AnimationPose)
+ *                                                          ▼
+ *                                       retargetHumanoidPose(pose, map)   (→ GLB node names)
+ *                                                          │
+ *                                                          ▼
+ *                                       actor.applyRetargetedPose(pose)
+ *
+ * The library + retargeting come from the FRESHLY-BUILT monorepo `dist/animation`. The template's
+ * own published `node_modules/@aura3d/animation` predates Phase 2.4/2.5 (no clip library / rig
+ * inference / state graph), and the render route only aliases a fixed list of `@aura3d/*` specifiers
+ * — NOT `@aura3d/animation`. So we import the in-repo build by relative path (the same monorepo dist
+ * the rest of the route is validated against; vite's workspace fs.allow covers it).
+ */
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore — resolved at runtime to the freshly-built monorepo dist (has co-located .d.ts).
+import {
+  inferHumanoidRig,
+  createHumanoidRetargetingMap,
+  retargetHumanoidPose,
+  createStandardHumanoidClipRegistry,
+  createStandardHumanoidClipDefinitions,
+  createPerformanceStateGraph,
+  AnimationClipRegistry,
+  AnimationTrack,
+  STANDARD_LIBRARY_RIG,
+  STANDARD_CLIP_IDS,
+  PERFORMANCE_GRAPH_PARAMETERS
+} from "@aura3d/animation";
+
+type StandardClipId = (typeof STANDARD_CLIP_IDS)[number];
+
+/**
+ * B1/B3 motion-source provenance. `extracted` = a real catalog-mocap clip from the
+ * universal `public/clip-library/<intent>.json`; `procedural` = the standard-library
+ * synthesized clip; `embedded` = a rich GLB clip shipped by the character itself;
+ * `idle-fallback` = the last-resort idle clip (no usable motion for the intent).
+ */
+export type ClipSource = "extracted" | "procedural" | "embedded" | "idle-fallback";
+
+/** Canonical body bones a downstream gate measures (EXCLUDING mouth morph + caption + camera). */
+export const BODY_BONES = [
+  "hips",
+  "spine",
+  "chest",
+  "upperChest",
+  "neck",
+  "head",
+  "leftShoulder",
+  "leftUpperArm",
+  "leftLowerArm",
+  "rightShoulder",
+  "rightUpperArm",
+  "rightLowerArm"
+] as const;
+export type BodyBoneName = (typeof BODY_BONES)[number];
+
+/**
+ * One character/one-beat clip-decision record (B1). It is emitted per-frame from the
+ * performance rig and bubbled into the route seek proof + the render summary so a
+ * downstream gate can prove the BODY moves (not just the mouth morph).
+ */
+export interface ClipDecision {
+  /** The standard intent that was requested for this beat. */
+  readonly intent: StandardClipId;
+  /** The clip id actually sampled (may differ from intent when the graph auto-returns to idle). */
+  readonly clipId: StandardClipId;
+  /** Where the sampled motion came from (extracted catalog / procedural / embedded / idle fallback). */
+  readonly source: ClipSource;
+  /** Count of canonical body bones whose rotation amplitude this frame exceeds a tiny epsilon. */
+  readonly bonesTouched: number;
+  /** Largest per-body-bone rotation amplitude (radians) applied this frame. */
+  readonly maxRotAmplitudeRad: number;
+  /**
+   * Largest per-body-bone TRANSLATION amplitude (metres) applied this frame across ALL sampled bones
+   * (not just the hips root) — a body bone that physically displaces (weight shift, hip bob, hand
+   * reach) shows up here even when its rotation is small. B1 contract field.
+   */
+  readonly maxTransAmplitude: number;
+  /** Per-body-bone rotation amplitude (radians) keyed by canonical bone (gate input, mouth-free). */
+  readonly bodyBoneRotationRad: Partial<Record<BodyBoneName, number>>;
+  /** Root (hips) translation magnitude applied this frame (locomotion / weight shift). */
+  readonly rootTranslation: number;
+  /**
+   * B1 — did this decision's pose actually reach the GLB skeleton at runtime? The library pose only
+   * proves the LIBRARY moved; this is set true by `scene-player.ts` once the retargeted pose (or an
+   * embedded clip) was applied to ≥1 real skinned skeleton node (`applyRetargetedPose` /
+   * `playClip` reported tracks applied). `poseFor` emits it `false`; the player overwrites it.
+   */
+  readonly reachedGLBRuntime: boolean;
+}
+
+/** The 8 standard performance ids (idle/talk/gesture/point/nod/walk/run/react). */
+export const STANDARD_INTENTS = STANDARD_CLIP_IDS as readonly StandardClipId[];
+
+const INTENT_SET = new Set<string>(STANDARD_INTENTS);
+
+/** Loop-vs-one-shot per standard clip (one-shots auto-return to idle in the graph). */
+const ONE_SHOT = new Set<StandardClipId>(["gesture", "point", "nod", "react"]);
+
+/** Plain pose transform shapes (match `@aura3d/animation`'s AnimationPose). */
+interface PoseTransform {
+  position?: { x: number; y: number; z: number };
+  rotation?: { x: number; y: number; z: number; w: number };
+}
+interface SamplablePose {
+  bones: Record<string, PoseTransform>;
+  morphTargets?: Record<string, number>;
+}
+
+interface SamplableTrack {
+  readonly target: string;
+  readonly valueType: string;
+  sample(time: number): readonly number[];
+}
+interface LibraryClip {
+  readonly id: StandardClipId;
+  readonly duration: number;
+  readonly loop: boolean;
+  readonly tracks: readonly SamplableTrack[];
+}
+
+/**
+ * Map an episode beat's clip field + motion state to one of the standard performance intents.
+ *
+ *  - A director-built document already emits a STANDARD intent (`talk`, `react`, `walk`, …) — use it.
+ *  - An AUTHORED document (e.g. Moon Garden) carries GLB-clip placeholder names (`Loops`, `Run`,
+ *    `Idle`) that are NOT standard intents — derive the intent from speaking/movement so those
+ *    characters still perform from the shared library instead of looping one embedded clip.
+ *  - Movement always wins (walk/run) so a translating character animates its legs.
+ */
+export function resolveIntent(input: {
+  readonly clip: string;
+  readonly moving: boolean;
+  readonly running: boolean;
+  readonly speaking: boolean;
+  readonly anyDialogue: boolean;
+}): StandardClipId {
+  // Locomotion is VELOCITY-GATED, never name-gated: legs cycle ONLY while the root is actually
+  // translating. `moving`/`running` come from the per-frame waypoint velocity (sampleBlocking).
+  if (input.running) return "run";
+  if (input.moving) return "walk";
+  // Stationary now. A shot whose authored clip is walk/run must NOT keep walking in place once the
+  // character has reached its mark — that is the treadmill/moonwalk bug. So when stopped, IGNORE a
+  // locomotion clip name and fall through to the performance/idle state; honor only a non-locomotion
+  // performance clip name (gesture/point/nod/react/talk/idle).
+  const raw = input.clip.trim().toLowerCase();
+  const isLocomotion = raw === "walk" || raw === "run" || /run|sprint|walk|move|loco|jog|stride/.test(raw);
+  if (!isLocomotion) {
+    if (INTENT_SET.has(raw)) return raw as StandardClipId;
+    // Heuristic mapping for common embedded/authored names → standard intent.
+    if (/wave|gesture|emote/.test(raw)) return "gesture";
+    if (/point/.test(raw)) return "point";
+    if (/nod|agree/.test(raw)) return "nod";
+    if (/react|surprise|recoil/.test(raw)) return "react";
+    if (/talk|speak|dialog/.test(raw)) return "talk";
+  }
+  // Locomotion clip but stopped, or no usable name — fall back to the dialogue state.
+  if (input.speaking) return "talk";
+  if (input.anyDialogue) return "react";
+  return "idle";
+}
+
+/** One character's shared-library performance driver (state graph + retarget map + clips). */
+export interface PerformanceRig {
+  /** GLB node names this rig will write to (used to build a clean identity base each frame). */
+  readonly targetNodeNames: readonly string[];
+  /** Retarget map coverage (standard rig → this GLB rig); low coverage = sparse skeleton. */
+  readonly coverage: number;
+  /** True when the GLB's own clips are rich enough to be preferred over retargeting (fallback rule). */
+  readonly preferEmbedded: boolean;
+  /**
+   * Produce the GLB-node-keyed pose for `intent` at episode time `t`. Returns a pose whose `bones`
+   * keys are the GLB's node names — feed straight into `actor.applyRetargetedPose(pose)` — plus a
+   * B1 {@link ClipDecision} measuring the body-bone motion this frame (mouth/caption/camera-free).
+   */
+  poseFor(intent: StandardClipId, t: number, morph?: Record<string, number>): {
+    readonly pose: SamplablePose;
+    readonly decision: ClipDecision;
+  };
+  /** Current state-graph state name (for the proof / debugging). */
+  readonly state: string;
+}
+
+export interface PerformanceRigOptions {
+  /** Flat list of the GLB's skeleton node names (for rig inference). */
+  readonly nodeNames: readonly string[];
+  /** The GLB's own embedded clip names (used by the fallback rule). */
+  readonly embeddedClips: readonly string[];
+  /** B3 per-intent motion source (extracted catalog vs procedural) from {@link loadSharedClipLibrary}. */
+  readonly sources?: Readonly<Record<StandardClipId, "extracted" | "procedural">>;
+}
+
+/** Build the (procedural) shared clip registry once and reuse across characters. */
+export function createSharedClipRegistry(): ReturnType<typeof createStandardHumanoidClipRegistry> {
+  return createStandardHumanoidClipRegistry();
+}
+
+/** A shared registry plus the resolved motion SOURCE per standard intent (B3). */
+export interface SharedClipLibrary {
+  readonly registry: ReturnType<typeof createStandardHumanoidClipRegistry>;
+  /** Per-intent: did the first-choice EXTRACTED catalog clip load, or did we fall to procedural? */
+  readonly sources: Readonly<Record<StandardClipId, "extracted" | "procedural">>;
+}
+
+/** Shape of a `public/clip-library/<id>.json` file (mirrors build-clip-library.ts serialization). */
+interface SerializedClipFile {
+  readonly id: StandardClipId;
+  readonly name: string;
+  readonly duration: number;
+  readonly frameRate: number;
+  readonly loop: boolean;
+  readonly tags?: readonly string[];
+  readonly source?: string;
+  readonly rig?: string;
+  readonly tracks: { target: string; valueType: string; keyframes: unknown[] }[];
+  readonly provenance?: { source?: string };
+}
+
+/**
+ * B3 — load the shared clip registry with the EXTRACTED universal catalog library as the
+ * DEFAULT first choice. Mirrors `loadExtractedClipLibrary` from `scripts/build-clip-library.ts`,
+ * but uses `fetch` (the player runs in the browser, where `node:fs` is unavailable) to read the
+ * SAME `public/clip-library/<intent>.json` files that script writes. We start from the procedural
+ * standard clips and OVERRIDE each intent with its real extracted catalog clip when one exists;
+ * intents with no usable extracted clip keep the procedural baseline (and are logged as such).
+ *
+ * Fallback order per intent (logged): extracted catalog clip → procedural standard clip.
+ * (The embedded-GLB and idle fallbacks live at the per-character decision layer in `poseFor`.)
+ */
+export async function loadSharedClipLibrary(
+  baseUrl = "/clip-library"
+): Promise<SharedClipLibrary> {
+  const registry = new AnimationClipRegistry(createStandardHumanoidClipDefinitions());
+  const sources: Record<StandardClipId, "extracted" | "procedural"> = Object.create(null);
+  for (const id of STANDARD_INTENTS) sources[id] = "procedural";
+
+  // MOTION-SOURCE POLICY (render-verified, TWICE). The extracted catalog mocap DISTORTS the real
+  // 21-joint character rig: with legs it removes/collapses them; even "upper-body only" it stretches
+  // the arms to the floor and compresses the lower body. Both failures were only caught in a real
+  // render (FK overlays + numeric checks passed). So the DEFAULT is the PROCEDURAL baseline — proven
+  // to render clean: natural standing, normal arm length, full intact legs. Extracted is opt-in for
+  // future per-rig validation only.
+  //   - default (off)       → pure procedural baseline (clean, stable) ← DEFAULT
+  //   - AURA_EXTRACTED=upper-body → extracted upper-body + stripped legs (distorts arms; validation only)
+  //   - AURA_EXTRACTED=full → keep leg tracks too (breaks legs; validation only)
+  const extractedMode = (typeof process !== "undefined" && process.env?.AURA_EXTRACTED) || "off";
+  if (extractedMode === "off") {
+    console.info("[animation-performance] extracted clips OFF → procedural baseline (clean rig; mocap distorts this rig).");
+    return { registry, sources };
+  }
+  const STRIP_LEGS = extractedMode !== "full";
+  const LEG_BONE = /(leg|knee|foot|toe|ankle|thigh|shin)/i;
+
+  await Promise.all(
+    STANDARD_INTENTS.map(async (id) => {
+      try {
+        // Locomotion (walk/run) IS the legs — stripping their leg tracks would leave the character
+        // gliding with no step. Keep the PROCEDURAL walk/run (real, stable leg cycle); use extracted
+        // only for the upper-body-dominant intents (talk/gesture/nod/point/react/idle).
+        if (STRIP_LEGS && (id === "walk" || id === "run")) {
+          console.info(`[animation-performance] clip-library/${id}.json → procedural (locomotion keeps its leg cycle).`);
+          return;
+        }
+        const res = await fetch(`${baseUrl}/${id}.json`, { cache: "no-cache" });
+        if (!res.ok) {
+          console.warn(`[animation-performance] clip-library/${id}.json HTTP ${res.status} → procedural baseline.`);
+          return;
+        }
+        const file = (await res.json()) as SerializedClipFile;
+        // Only override with a REAL extracted catalog clip; procedural-fallback files are identical
+        // to the baseline already registered, so registering them would just be noise.
+        if (file.provenance?.source !== "catalog-extracted") {
+          console.warn(`[animation-performance] clip-library/${id}.json is "${file.provenance?.source ?? "unknown"}" (not catalog-extracted) → procedural baseline.`);
+          return;
+        }
+        // SANITY GATE: reject extracted clips whose root (hips) motion is in raw/un-normalized
+        // units or carries a collapsing static offset — those displace the character to the floor.
+        // Clean clips on the standard rig (meters) keep hips translation ≲1m and hips rotation
+        // near identity. Until the extraction pipeline normalizes units + rest pose, fall back to
+        // the (cranked) procedural baseline for any clip that fails this — so the default is never broken.
+        {
+          let maxTrans = 0;
+          let maxHipsRotOffset = 0;
+          // A clip with a baked axis-conversion rest offset (e.g. a constant 90° head/limb
+          // rotation from a Z-up source) is INVISIBLE to a range-based check — the bone never
+          // moves, it just sits rotated, and retargeting bakes that 90° onto the target rig so
+          // the character renders laid-down / contorted. Detect it by the bone that stays
+          // FARTHEST from rest the whole clip: for each rotation track take the MIN offset from
+          // identity across keyframes (the closest it ever gets to rest); genuine motion passes
+          // near rest, a baked offset never does. Reject if any bone's floor exceeds the limit.
+          const REST_FLOOR_LIMIT = 0.15; // ≈ a bone pinned ≥64° from rest for the entire clip
+          let worstRestFloor = 0;
+          let worstRestBone = "";
+          for (const tr of file.tracks) {
+            const isHipsT = /(^|[.\/])hips\.translation$/i.test(tr.target);
+            const isRot = /\.rotation$/i.test(tr.target);
+            const isHipsR = /(^|[.\/])hips\.rotation$/i.test(tr.target);
+            if (isHipsT) {
+              for (const kf of tr.keyframes as { value: number[] }[])
+                for (const c of kf.value ?? []) maxTrans = Math.max(maxTrans, Math.abs(c));
+            }
+            if (isRot) {
+              let restFloor = Infinity;
+              for (const kf of tr.keyframes as { value: number[] }[]) {
+                const v = kf.value ?? [];
+                if (v.length < 4) continue;
+                const offset = 1 - Math.abs(v[3]!); // |w| far from 1 ⇒ large rotation
+                restFloor = Math.min(restFloor, offset);
+                if (isHipsR) maxHipsRotOffset = Math.max(maxHipsRotOffset, offset);
+              }
+              if (restFloor !== Infinity && restFloor > worstRestFloor) {
+                worstRestFloor = restFloor;
+                worstRestBone = tr.target;
+              }
+            }
+          }
+          if (maxTrans > 1.5 || maxHipsRotOffset > 0.25 || worstRestFloor > REST_FLOOR_LIMIT) {
+            console.warn(
+              `[animation-performance] clip-library/${id}.json rejected (hips trans ${maxTrans.toFixed(2)} / hips rotOffset ${maxHipsRotOffset.toFixed(2)} / ${worstRestBone || "—"} rest-floor ${worstRestFloor.toFixed(2)} — un-normalized or baked rest offset) → procedural baseline.`
+            );
+            return;
+          }
+        }
+        // Strip leg/foot/toe tracks by default so the extracted mocap drives only the upper body;
+        // the legs stay at the clean rest pose (built fresh each frame), which keeps them STABLE on
+        // the real character rig. (Hips translation is also a leg-adjacent root signal — drop it too.)
+        const usableTracks = STRIP_LEGS
+          ? file.tracks.filter((tr) => !LEG_BONE.test(tr.target) && !/hips\.translation$/i.test(tr.target))
+          : file.tracks;
+        const tracks = usableTracks.map(
+          (tr) =>
+            new AnimationTrack({
+              target: tr.target,
+              valueType: tr.valueType as never,
+              keyframes: tr.keyframes as never
+            })
+        );
+        registry.register(
+          {
+            id: file.id,
+            name: file.name ?? file.id,
+            duration: file.duration,
+            frameRate: file.frameRate ?? 30,
+            loop: file.loop ?? true,
+            tags: file.tags ?? [file.id, "performance", "extracted"],
+            source: file.source ?? "aura3d.catalog-extracted",
+            tracks: tracks as never,
+            metadata: { rig: file.rig ?? STANDARD_LIBRARY_RIG.id, extracted: true }
+          } as never,
+          { replace: true }
+        );
+        sources[id] = "extracted";
+        console.info(`[animation-performance] clip-library/${id}.json → EXTRACTED catalog clip loaded (${tracks.length} tracks, ${file.duration.toFixed?.(2) ?? file.duration}s).`);
+      } catch (err) {
+        console.warn(`[animation-performance] clip-library/${id}.json fetch failed (${(err as Error).message}) → procedural baseline.`);
+      }
+    })
+  );
+
+  const extractedCount = STANDARD_INTENTS.filter((id) => sources[id] === "extracted").length;
+  console.info(`[animation-performance] shared clip library: ${extractedCount}/${STANDARD_INTENTS.length} intents from EXTRACTED universal catalog, rest procedural.`);
+  return { registry, sources };
+}
+
+/**
+ * Build a {@link PerformanceRig} for one character: infer its humanoid rig from its GLB node names,
+ * build a retarget map from the standard library rig onto it, and hold a performance state graph.
+ *
+ * Fallback rule (Phase 2.5): if the GLB ships rich, named, varied clips of its own (more than one
+ * usable motion clip beyond a single idle), we mark `preferEmbedded` so the caller plays the
+ * embedded clip whenever the intent matches one. Sparse rigs (one idle, or a skeleton too minimal
+ * to retarget well) ALWAYS get retargeted library motion.
+ */
+export function createPerformanceRig(
+  registry: ReturnType<typeof createStandardHumanoidClipRegistry>,
+  options: PerformanceRigOptions
+): PerformanceRig {
+  const rig = inferHumanoidRig(options.nodeNames);
+  const map = createHumanoidRetargetingMap(STANDARD_LIBRARY_RIG, rig);
+  const targetNodeNames = Object.values(map.bindings)
+    .map((b: { target: { name: string } }) => b.target.name)
+    .filter((n): n is string => typeof n === "string" && n.length > 0);
+
+  const graph = createPerformanceStateGraph();
+
+  // Cache sampled clips by id (registry clips are immutable).
+  const clipCache = new Map<StandardClipId, LibraryClip>();
+  const getClip = (id: StandardClipId): LibraryClip | undefined => {
+    const cached = clipCache.get(id);
+    if (cached) return cached;
+    const clip = (registry.get?.(id) ?? registry.require?.(id)) as unknown as LibraryClip | undefined;
+    if (clip) clipCache.set(id, clip);
+    return clip;
+  };
+
+  // Build an identity rest transform for every target node so each frame starts clean — this
+  // prevents a bone touched by a previous intent (e.g. an arm raised in `talk`) from freezing when
+  // the next intent (e.g. `idle`) doesn't move it.
+  const identityBase = (): Record<string, PoseTransform> => {
+    const bones: Record<string, PoseTransform> = {};
+    for (const node of targetNodeNames) bones[node] = { rotation: { x: 0, y: 0, z: 0, w: 1 } };
+    return bones;
+  };
+
+  // Body-bone amplitude is measured on the rig-neutral (canonical) source pose BEFORE retargeting,
+  // so the numbers describe the LIBRARY motion (mouth-morph/caption/camera-free) regardless of how
+  // sparsely the target GLB maps. A quaternion's rotation magnitude is 2*acos(|w|).
+  const rotationAmplitude = (rot?: { x: number; y: number; z: number; w: number }): number => {
+    if (!rot) return 0;
+    const w = Math.min(1, Math.abs(rot.w));
+    return 2 * Math.acos(w);
+  };
+
+  let lastTime = 0;
+  let lastState = graph.currentState as string;
+
+  const poseFor = (
+    intent: StandardClipId,
+    t: number,
+    morph?: Record<string, number>
+  ): { readonly pose: SamplablePose; readonly decision: ClipDecision } => {
+    // Drive the state graph deterministically from the resolved intent. We set every parameter so
+    // the graph crossfades into the requested state (one-shots are pulsed; loops are held).
+    const P = PERFORMANCE_GRAPH_PARAMETERS as Record<string, string>;
+    graph.setParameter(P.talk, intent === "talk");
+    graph.setParameter(P.walk, intent === "walk" || intent === "run");
+    graph.setParameter(P.run, intent === "run");
+    for (const oneShot of ["gesture", "point", "nod", "react"] as const) {
+      graph.setParameter(P[oneShot], intent === oneShot);
+    }
+    const delta = Math.max(0, t - lastTime);
+    lastTime = t;
+    graph.update(delta);
+    lastState = graph.currentState as string;
+
+    // The graph may have auto-returned a one-shot to idle; honor the requested intent for sampling
+    // so a beat that asks for `gesture` actually plays gesture (the graph still governs transitions
+    // for proof/state). For one-shots we sample the requested clip from its local start; for loops
+    // we sample at the wrapped episode time so idle/talk/walk cycle continuously.
+    const clipId: StandardClipId = INTENT_SET.has(graph.currentState) && !ONE_SHOT.has(intent)
+      ? (graph.currentState as StandardClipId)
+      : intent;
+
+    // Sampling fallback order (logged via the decision.source): the requested clip, else idle.
+    let sampledId: StandardClipId = clipId;
+    let clip = getClip(clipId);
+    if (!clip) {
+      sampledId = "idle";
+      clip = getClip("idle");
+    }
+
+    const bones = identityBase();
+    const bodyBoneRotationRad: Partial<Record<BodyBoneName, number>> = {};
+    let rootTranslation = 0;
+    let maxTransAmplitude = 0;
+    if (clip) {
+      const duration = clip.duration > 0 ? clip.duration : 1;
+      const local = clip.loop ? t % duration : Math.min(t, duration);
+      // Sample the standard (rig-neutral) clip into an AnimationPose keyed by canonical bone names.
+      const sourceBones: Record<string, PoseTransform> = {};
+      for (const track of clip.tracks) {
+        const dot = track.target.lastIndexOf(".");
+        if (dot < 0) continue;
+        const bone = track.target.slice(0, dot);
+        const path = track.target.slice(dot + 1);
+        const v = track.sample(local);
+        const slot = (sourceBones[bone] ??= {});
+        if (path === "rotation") slot.rotation = { x: v[0]!, y: v[1]!, z: v[2]!, w: v[3]! };
+        else if (path === "translation") slot.position = { x: v[0]!, y: v[1]!, z: v[2]! };
+      }
+      // B1/B2: measure BODY-bone motion on the rig-neutral source pose (mouth/caption/camera-free).
+      for (const bone of BODY_BONES) {
+        const amp = rotationAmplitude(sourceBones[bone]?.rotation);
+        if (amp > 0) bodyBoneRotationRad[bone] = amp;
+        // B1 maxTransAmplitude: the largest per-body-bone translation magnitude (metres) this frame.
+        const pos = sourceBones[bone]?.position;
+        if (pos) maxTransAmplitude = Math.max(maxTransAmplitude, Math.hypot(pos.x, pos.y, pos.z));
+      }
+      const hipsPos = sourceBones.hips?.position;
+      if (hipsPos) rootTranslation = Math.hypot(hipsPos.x, hipsPos.y, hipsPos.z);
+      // Retarget rig-neutral → this GLB's node names, then overlay onto the clean identity base.
+      const retargeted = retargetHumanoidPose({ bones: sourceBones }, map) as SamplablePose;
+      for (const [node, transform] of Object.entries(retargeted.bones)) bones[node] = transform;
+    }
+
+    const amplitudes = Object.values(bodyBoneRotationRad);
+    // ~0.5° threshold: a bone is "touched" only if it actually rotated this frame (not numeric dust).
+    const EPS = 0.0087;
+    const bonesTouched = amplitudes.filter((a) => a > EPS).length;
+    const maxRotAmplitudeRad = amplitudes.length > 0 ? Math.max(...amplitudes) : 0;
+
+    // B3 source: which library this sampled clip's motion came from. If we had to fall back to idle
+    // (the requested intent had no clip at all) report `idle-fallback`; else the per-intent library
+    // source resolved at load time (extracted catalog vs procedural baseline).
+    const source: ClipSource =
+      sampledId !== clipId ? "idle-fallback" : (options.sources?.[sampledId] ?? "procedural");
+
+    const decision: ClipDecision = {
+      intent,
+      clipId: sampledId,
+      source,
+      bonesTouched,
+      maxRotAmplitudeRad: +maxRotAmplitudeRad.toFixed(5),
+      maxTransAmplitude: +maxTransAmplitude.toFixed(5),
+      bodyBoneRotationRad,
+      rootTranslation: +rootTranslation.toFixed(5),
+      // The library pose has not been applied to a GLB skeleton yet; scene-player flips this true
+      // once it applies the retargeted pose / embedded clip to ≥1 real skinned node.
+      reachedGLBRuntime: false
+    };
+
+    return { pose: { bones, ...(morph ? { morphTargets: morph } : {}) }, decision };
+  };
+
+  // Fallback rule: a GLB with >1 distinct non-idle embedded clip is considered "rich".
+  const nonIdle = options.embeddedClips.filter((c) => !/^idle$/i.test(c.trim()));
+  const preferEmbedded = nonIdle.length >= 2;
+
+  return {
+    targetNodeNames,
+    coverage: map.coverage as number,
+    preferEmbedded,
+    poseFor,
+    get state() {
+      return lastState;
+    }
+  };
+}
+
+/**
+ * Does the GLB ship an embedded clip that satisfies this intent? Returns the matching embedded clip
+ * name (so the caller can `playClip` it) or undefined to fall through to retargeting.
+ */
+export function embeddedClipForIntent(intent: StandardClipId, embeddedClips: readonly string[]): string | undefined {
+  const patterns: Partial<Record<StandardClipId, RegExp>> = {
+    idle: /idle|breath|stand/i,
+    walk: /walk|move/i,
+    run: /run|sprint/i,
+    gesture: /wave|gesture|emote|hello/i,
+    point: /point/i,
+    talk: /talk|speak/i,
+    nod: /nod/i,
+    react: /react|surprise/i
+  };
+  const pat = patterns[intent];
+  if (!pat) return undefined;
+  return embeddedClips.find((c) => pat.test(c));
+}

package/templates/animation-studio/src/aura-assets.ts

@@ -0,0 +1,71 @@
+import { defineAuraAssets } from "@aura3d/engine";
+import { AURAVOICE_AURA3D_PROMPT_ANIMATION_CONTRACT_ID } from "./contract";
+
+export const assetContractId = AURAVOICE_AURA3D_PROMPT_ANIMATION_CONTRACT_ID;
+
+export const animationStudioRequiredAssetKeys = ["miko", "luma", "moonGarden"] as const;
+
+export const animationStudioOptionalAudioAssetKeys = [
+  "mikoDialogueStem",
+  "lumaDialogueStem",
+  "moonGardenMusic",
+  "moonGardenChimeSfx"
+] as const;
+
+export const assets = defineAuraAssets({
+  miko: {
+    type: "model",
+    format: "glb",
+    url: "/aura-assets/miko.catalog.glb",
+    bounds: [1.015, 1.95, 0.369],
+    hash: "sha256-fcdc2b7502031e556259dfe942fdfbd7abe41963433f2046ed2522d27bce9d65",
+    metadata: {
+      contractId: assetContractId,
+      role: "animation-character",
+      license: "CC0-1.0",
+      attribution: "Miko — Aura3D-authored CC0 procedural humanoid",
+      source:
+        "Aura3D-authored rigged GLB generated by scripts/build-characters.ts (CC0). Full 21-joint humanoid rig (hips→spine→chest→neck→head, both arms with forearms+hands, both legs with lower-legs+feet+toes; graded-A) with embedded Idle/Wave/Walk/Talk clips and a facial mouthOpen blendshape morph target for lip-sync. Now ships a real UV-mapped 1024×1024 base-colour bitmap texture (skin tone gradients + cheek blush, woven clothing fabric, brushed accent trim, eye/iris falloff, edge ambient occlusion) instead of flat vertex colours.",
+      animationClips: ["Idle", "Wave", "Walk", "Talk"],
+      // Authored rig ships a real face morph (mouthOpen), so lip-sync drives a
+      // blendshape rather than the primitive mouth-card fallback.
+      mouthReadiness: "blendshape",
+      mouthMorphTargets: ["mouthOpen"]
+    }
+  },
+  luma: {
+    type: "model",
+    format: "glb",
+    url: "/aura-assets/luma2.catalog.glb",
+    bounds: [0.99, 1.95, 0.333],
+    hash: "sha256-911c60a074f6d89d0eaeefc1f1eecf4188873880b62aa11b3d02ec2c18a4e036",
+    metadata: {
+      contractId: assetContractId,
+      role: "animation-character",
+      license: "CC0-1.0",
+      attribution: "Luma — Aura3D-authored CC0 procedural humanoid",
+      source:
+        "Aura3D-authored rigged GLB generated by scripts/build-characters.ts (CC0). A warm-gold helper that matches Miko's style (coherent cast). Full 21-joint humanoid rig (graded-A) with embedded Idle/Wave/Walk/Talk clips and a facial mouthOpen blendshape morph target. Now ships a real UV-mapped 1024×1024 base-colour bitmap texture (skin tone gradients + cheek blush, woven clothing fabric, brushed accent trim, eye/iris falloff, edge ambient occlusion) instead of flat vertex colours.",
+      animationClips: ["Idle", "Wave", "Walk", "Talk"],
+      // Authored rig ships a real face morph (mouthOpen), so lip-sync drives a
+      // blendshape rather than the primitive mouth-card fallback.
+      mouthReadiness: "blendshape",
+      mouthMorphTargets: ["mouthOpen"]
+    }
+  },
+  moonGarden: {
+    type: "model",
+    format: "gltf",
+    url: "/aura-assets/moonGarden.gltf",
+    bounds: [3.2, 0.6, 1.2],
+    hash: "sha256-b7b50e37cc4319df21fa2a598aab9e055d54eeb3f5511a3b3f0d4f6c5101c456",
+    metadata: {
+      contractId: assetContractId,
+      role: "animation-set",
+      license: "MIT",
+      source: "Aura3D animation-studio local generated starter set anchor",
+      walkable: true,
+      framingReady: true
+    }
+  }
+} as const);

package/templates/animation-studio/src/character.ts

@@ -0,0 +1,40 @@
+// Typed character definition for Animation Studio. Pure data + types (no engine import) so the
+// profile pipeline (plan/profile/package/verify) runs in plain Node.
+
+export type LocomotionAction = "idle" | "walk" | "run";
+
+export interface AnimationStudioIkChain {
+  readonly id: string;
+  readonly root: string;
+  readonly mid: string;
+  readonly tip: string;
+}
+
+export interface AnimationStudioCharacter {
+  readonly id: string;
+  readonly name: string;
+  /** Typed asset key resolved from aura.assets.json (never a raw URL). */
+  readonly assetKey: string;
+  /** Locomotion clip map: action -> embedded GLB clip name. */
+  readonly clipMap: Readonly<Record<LocomotionAction, string>>;
+  /** Speeds (units/sec) at which walk and run clips reach full weight. */
+  readonly walkSpeed: number;
+  readonly runSpeed: number;
+  /** Two-bone IK chains the studio can solve (feet/hands). */
+  readonly ikChains: readonly AnimationStudioIkChain[];
+}
+
+export const requiredLocomotionActions: readonly LocomotionAction[] = ["idle", "walk", "run"];
+
+export const heroCharacter: AnimationStudioCharacter = {
+  id: "hero",
+  name: "Hero",
+  assetKey: "hero",
+  clipMap: { idle: "Idle", walk: "Walk", run: "Run" },
+  walkSpeed: 1.6,
+  runSpeed: 4.4,
+  ikChains: [
+    { id: "left-leg", root: "LeftUpLeg", mid: "LeftLeg", tip: "LeftFoot" },
+    { id: "right-leg", root: "RightUpLeg", mid: "RightLeg", tip: "RightFoot" }
+  ]
+};