Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

feat(kiln/imposter): clip-resolver utility

Matt Kissinger283af457d503
diff --git a/imposter/__tests__/clip-resolver.test.ts b/imposter/__tests__/clip-resolver.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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;
+}