Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(kiln/imposter): clip-resolver utility
Matt Kissinger283af457d503
diff --git a/imposter/__tests__/clip-resolver.test.ts b/imposter/__tests__/clip-resolver.test.tsnew file mode 100644index 00000000..fe9e9e8c--- /dev/null+++ b/imposter/__tests__/clip-resolver.test.ts@@ -0,0 +1,150 @@+/**+ * Clip resolver tests — uses realistic clip lists pulled from the Quaternius+ * soldier set so behavior is validated against real-world naming, not toys.+ */++import { describe, expect, test } from 'bun:test';++import {+ applyClipFallbacks,+ normalizeClipName,+ resolveClips,+} from '../clip-resolver';++// Real clip lists from CHARACTERS_MANIFEST.json (Poly Pizza / Quaternius set).+const HERO_CLIPS = [+ 'CharacterArmature|Attacking_Idle',+ 'CharacterArmature|Dagger_Attack',+ 'CharacterArmature|Death',+ 'CharacterArmature|Idle',+ 'CharacterArmature|PickUp',+ 'CharacterArmature|Punch',+ 'CharacterArmature|RecieveHit',+ 'CharacterArmature|Roll',+ 'CharacterArmature|Run',+ 'CharacterArmature|Walk',+];++const NVA_MATT_CLIPS = [+ 'CharacterArmature|Death',+ 'CharacterArmature|Idle',+ 'CharacterArmature|Idle_Gun',+ 'CharacterArmature|Punch',+ 'CharacterArmature|Run',+ 'CharacterArmature|Run_Gun',+ 'CharacterArmature|Run_Slash',+ 'CharacterArmature|Slash',+ 'CharacterArmature|Stab',+ 'CharacterArmature|Walk',+ 'CharacterArmature|Walk_Gun',+];++const US_SOLDIER_CLIPS = [+ 'CharacterArmature|Death',+ 'CharacterArmature|Idle',+ 'CharacterArmature|Idle_Shoot',+ 'CharacterArmature|Run',+ 'CharacterArmature|Run_Gun',+];++describe('normalizeClipName', () => {+ test('strips single armature prefix', () => {+ expect(normalizeClipName('CharacterArmature|Walk')).toBe('Walk');+ });+ test('strips repeated prefixes', () => {+ expect(normalizeClipName('CharacterArmature|CharacterArmature|Idle')).toBe('Idle');+ });+ test('preserves un-prefixed names', () => {+ expect(normalizeClipName('Run')).toBe('Run');+ });+});++describe('resolveClips — hero (Quaternius Character_Animated)', () => {+ test('resolves idle + walking + running from exact + alias matches', () => {+ const r = resolveClips(HERO_CLIPS, ['idle', 'walking', 'running']);+ expect(r.clips.idle?.resolved).toBe('Idle');+ expect(r.clips.idle?.matchedBy).toBe('exact');+ expect(r.clips.walking?.resolved).toBe('Walk');+ expect(r.clips.running?.resolved).toBe('Run');+ expect(r.missing).toHaveLength(0);+ });++ test('shoot falls through to Punch (melee fallback in alias list)', () => {+ const r = resolveClips(HERO_CLIPS, ['shoot']);+ expect(r.clips.shoot?.resolved).toBe('Punch');+ expect(r.clips.shoot?.matchedBy).toBe('alias');+ expect(r.missing).toHaveLength(0);+ });++ test('returns raw clip name (with armature prefix) for AnimationMixer', () => {+ const r = resolveClips(HERO_CLIPS, ['idle']);+ expect(r.clips.idle?.rawName).toBe('CharacterArmature|Idle');+ });++ test('unmapped clips are surfaced for debugging', () => {+ const r = resolveClips(HERO_CLIPS, ['idle', 'walking']);+ expect(r.unmapped).toContain('CharacterArmature|Death');+ expect(r.unmapped).toContain('CharacterArmature|Roll');+ });+});++describe('resolveClips — NVA (Matt)', () => {+ test('idle + walking match directly', () => {+ const r = resolveClips(NVA_MATT_CLIPS, ['idle', 'walking']);+ expect(r.clips.idle?.resolved).toBe('Idle');+ expect(r.clips.walking?.resolved).toBe('Walk');+ });++ test('shoot falls through to Slash (no Gun_Shoot / Shoot clip)', () => {+ const r = resolveClips(NVA_MATT_CLIPS, ['shoot']);+ expect(r.clips.shoot?.resolved).toBe('Slash');+ expect(r.clips.shoot?.matchedBy).toBe('alias');+ });+});++describe('resolveClips — US Soldier (PpLF4rt4ah)', () => {+ test('walking falls through to Run when Walk is absent', () => {+ // US Soldier has no Walk clip; the alias list for 'walking' includes only+ // Walk / Walk_Gun / Walking. Expect missing (no Run substitution yet).+ const r = resolveClips(US_SOLDIER_CLIPS, ['walking']);+ expect(r.clips.walking?.resolved).toBeNull();+ expect(r.missing).toContain('walking');+ });++ test('Idle_Shoot resolves shoot via alias', () => {+ const r = resolveClips(US_SOLDIER_CLIPS, ['shoot']);+ expect(r.clips.shoot?.resolved).toBe('Idle_Shoot');+ });+});++describe('applyClipFallbacks', () => {+ test('promotes running -> walking when walking is missing', () => {+ const initial = resolveClips(US_SOLDIER_CLIPS, ['idle', 'walking', 'running']);+ expect(initial.missing).toContain('walking');++ const after = applyClipFallbacks(initial, { walking: 'running' });+ expect(after.clips.walking?.resolved).toBe('Run');+ expect(after.clips.walking?.matchedBy).toBe('fallback');+ expect(after.clips.walking?.fallbackFor).toBe('running');+ expect(after.missing).not.toContain('walking');+ });++ test('no-op when donor target is also missing', () => {+ const initial = resolveClips(['Idle'], ['idle', 'walking']);+ const after = applyClipFallbacks(initial, { walking: 'running' });+ // running was never resolved -> walking stays null.+ expect(after.clips.walking?.resolved).toBeNull();+ expect(after.missing).toContain('walking');+ });++ test('does not overwrite an already-resolved target', () => {+ const initial = resolveClips(HERO_CLIPS, ['idle', 'walking', 'running']);+ const after = applyClipFallbacks(initial, { walking: 'running' });+ // Target "walking" does not exact-match clip "Walk" (different words);+ // it resolves via the "Walk" alias. The fallback must not overwrite an+ // already-populated slot regardless of whether it was exact or alias.+ expect(after.clips.walking?.resolved).toBe('Walk');+ expect(after.clips.walking?.matchedBy).toBe('alias');+ expect(after.clips.walking?.fallbackFor).toBeUndefined();+ });+});diff --git a/imposter/clip-resolver.ts b/imposter/clip-resolver.tsnew file mode 100644index 00000000..39d694d3--- /dev/null+++ b/imposter/clip-resolver.ts@@ -0,0 +1,210 @@+/**+ * Animation-clip resolver for animated imposters.+ *+ * Real character GLBs use inconsistent clip names — a soldier might call+ * its stand-still pose "Idle", "Attacking_Idle", "Idle_Gun", "Idle_Neutral",+ * and a Blender export typically prefixes them with "CharacterArmature|".+ * The baker needs a deterministic way to pick ONE clip per logical target.+ *+ * Resolution rules (per target):+ * 1. Exact case-insensitive match on the normalized (no armature prefix) name.+ * 2. First alias in the target's priority list that matches any clip.+ * 3. null — clip is missing; caller decides whether to skip or fall back.+ *+ * This module is pure — no Three.js import, no file I/O. Consumers pass in+ * a flat list of clip names (from gltf.animations) and get back a map of+ * target -> resolved clip name.+ */++/** Logical clip targets the animated imposter baker cares about. */+export type ClipTarget = 'idle' | 'walking' | 'running' | 'shoot' | 'death';++/** Priority-ordered candidate names for each target. First match wins. */+export const CLIP_ALIASES: Record<ClipTarget, string[]> = {+ idle: [+ 'Idle',+ 'Idle_Gun',+ 'Idle_Neutral',+ 'Attacking_Idle',+ 'Idle_Shoot',+ 'Idle_Hold',+ ],+ walking: [+ 'Walk',+ 'Walk_Gun',+ 'Walking',+ 'Walk_Forward',+ ],+ running: [+ 'Run',+ 'Run_Gun',+ 'Running',+ ],+ shoot: [+ // Prefer dedicated shoot clips, then stationary gun-ready, then melee.+ 'Gun_Shoot',+ 'Shoot',+ 'Idle_Gun_Shoot',+ 'Run_Shoot',+ 'Idle_Shoot',+ 'Attack',+ 'Slash',+ 'Stab',+ 'Punch',+ 'Punch_Right',+ 'Idle_Gun_Pointing',+ ],+ death: [+ 'Death',+ 'Die',+ 'HitRecieve', // Quaternius misspells "Receive"+ 'HitReact',+ ],+};++export interface ResolvedClip {+ target: ClipTarget;+ /** Actual clip name in the GLB (post armature-prefix strip). Null = missing. */+ resolved: string | null;+ /** The raw clip name with any armature prefix kept, for AnimationMixer.clipAction lookup. */+ rawName: string | null;+ /** Which alias matched. "exact" = exact case-insensitive target name. */+ matchedBy: 'exact' | 'alias' | 'fallback' | 'missing';+ /** If the matcher fell through to a best-guess, note what target was missing and what was used. */+ fallbackFor?: ClipTarget;+}++export interface ClipResolutionReport {+ /** Map from logical target -> resolved clip (or null). */+ clips: Partial<Record<ClipTarget, ResolvedClip>>;+ /** Targets that had no match at all, after aliases were exhausted. */+ missing: ClipTarget[];+ /** Clip names present in the GLB that we did NOT map. Useful for debugging. */+ unmapped: string[];+}++/**+ * Normalize a clip name by stripping common exporter prefixes.+ * "CharacterArmature|Walk" -> "Walk"+ * "CharacterArmature|CharacterArmature|Idle" -> "Idle"+ */+export function normalizeClipName(raw: string): string {+ let s = raw;+ // Strip repeated "Name|" prefixes until none left.+ while (s.includes('|')) s = s.slice(s.indexOf('|') + 1);+ return s;+}++/**+ * Resolve the requested targets against a GLB's clip list.+ *+ * @param clipNames - flat list of clip names from gltf.animations (raw, including any "Armature|" prefixes).+ * @param targets - which logical clips the caller wants.+ */+export function resolveClips(clipNames: string[], targets: ClipTarget[]): ClipResolutionReport {+ const report: ClipResolutionReport = {+ clips: {},+ missing: [],+ unmapped: [],+ };++ // Build a lookup { normalized-lower: raw-name } for case-insensitive match.+ // Last-write-wins on duplicates — Quaternius exports often have the same+ // clip twice (with and without armature prefix). Either form works for+ // AnimationMixer.clipAction once you have the raw.+ const byNorm = new Map<string, string>();+ for (const raw of clipNames) {+ const norm = normalizeClipName(raw).toLowerCase();+ if (!byNorm.has(norm)) byNorm.set(norm, raw);+ }++ const consumed = new Set<string>();++ for (const target of targets) {+ const aliases = CLIP_ALIASES[target];+ let resolved: ResolvedClip | null = null;++ // 1. Exact target name (e.g. target='idle' matches clip 'Idle').+ const exactHit = byNorm.get(target.toLowerCase());+ if (exactHit) {+ resolved = {+ target,+ resolved: normalizeClipName(exactHit),+ rawName: exactHit,+ matchedBy: 'exact',+ };+ }++ // 2. Alias hits (preserves priority order).+ if (!resolved) {+ for (const alias of aliases) {+ const hit = byNorm.get(alias.toLowerCase());+ if (hit) {+ resolved = {+ target,+ resolved: normalizeClipName(hit),+ rawName: hit,+ matchedBy: 'alias',+ };+ break;+ }+ }+ }++ if (resolved) {+ report.clips[target] = resolved;+ consumed.add(resolved.resolved!.toLowerCase());+ } else {+ report.missing.push(target);+ report.clips[target] = {+ target,+ resolved: null,+ rawName: null,+ matchedBy: 'missing',+ };+ }+ }++ for (const [norm, raw] of byNorm) {+ if (!consumed.has(norm)) report.unmapped.push(raw);+ }++ return report;+}++/**+ * Apply a fallback strategy to a resolution report — promotes a different+ * target's clip into a missing slot. Common pattern: 'shoot' fell through+ * but 'idle' was found -> use idle as a stationary-pose stand-in for the+ * shoot target.+ *+ * Returns a NEW report with the fallbacks applied. Original report is+ * not mutated.+ */+export function applyClipFallbacks(+ report: ClipResolutionReport,+ fallbacks: Partial<Record<ClipTarget, ClipTarget>>,+): ClipResolutionReport {+ const next: ClipResolutionReport = {+ clips: { ...report.clips },+ missing: [...report.missing],+ unmapped: [...report.unmapped],+ };+ for (const [targetStr, donorTarget] of Object.entries(fallbacks) as [ClipTarget, ClipTarget][]) {+ const target = targetStr;+ const current = next.clips[target];+ if (current && current.resolved) continue;+ const donor = next.clips[donorTarget];+ if (!donor || !donor.resolved) continue;+ next.clips[target] = {+ target,+ resolved: donor.resolved,+ rawName: donor.rawName,+ matchedBy: 'fallback',+ fallbackFor: donorTarget,+ };+ const mIdx = next.missing.indexOf(target);+ if (mIdx >= 0) next.missing.splice(mIdx, 1);+ }+ return next;+}