Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

12.1 KB
Raw Blame
// Rig report tests — run against the real GLBs shipped in public/avatars rather
// than synthetic fixtures. Those files are the exact rigs the platform serves,
// so a regression here is a regression a user would actually hit, and the suite
// covers every verdict level without anyone having to hand-author a broken rig.

import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import {
	analyzeGlb,
	detectConvention,
	readGlbJson,
	manifestFromReport,
	formatBytes,
	MIN_CANONICAL_BONES,
	CANONICAL_TOTAL,
	CONVENTION_COUNT,
	LIMB_GROUPS,
	CONVENTIONS,
} from '../src/rig-report.js';

const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');

function load(name) {
	const buf = readFileSync(join(ROOT, 'public/avatars', `${name}.glb`));
	return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
}

function report(name) {
	return analyzeGlb(load(name), { fileName: `${name}.glb` });
}

function documentedRigConventions() {
	const doc = readFileSync(join(ROOT, 'docs/rig-doctor.md'), 'utf8');
	const rows = [];
	for (const match of doc.matchAll(/^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*`([^`]+)`\s*\|$/gm)) {
		const convention = match[1].trim();
		if (convention === 'Convention' || /^-+$/.test(convention)) continue;
		rows.push({ convention, detectedBy: match[2].trim(), schema: match[3].trim() });
	}
	return rows;
}

describe('readGlbJson', () => {
	it('rejects a file that is not a GLB with a message a creator can act on', () => {
		const notGlb = new TextEncoder().encode('this is plainly not a binary glTF file');
		expect(() => readGlbJson(notGlb.buffer)).toThrow(/Export as \.glb/);
	});

	it('rejects a truncated buffer instead of reading past its end', () => {
		expect(() => readGlbJson(new ArrayBuffer(8))).toThrow(/too small/);
	});

	it('reports a truncated JSON chunk rather than throwing a RangeError', () => {
		// Valid header claiming a 4 KB JSON chunk in a 40-byte file.
		const buf = new ArrayBuffer(40);
		const v = new DataView(buf);
		v.setUint32(0, 0x46546c67, true);
		v.setUint32(4, 2, true);
		v.setUint32(8, 40, true);
		v.setUint32(12, 4096, true);
		v.setUint32(16, 0x4e4f534a, true);
		expect(() => readGlbJson(buf)).toThrow(/runs past the end/);
	});
});

describe('detectConvention fingerprints', () => {
	const ctx = (joints, meshNames = []) => ({ joints, meshNames, json: {} });

	it('keeps documented rig conventions in sync with the detector', () => {
		const implemented = CONVENTIONS.filter((c) => c.id !== 'unknown');
		const docs = documentedRigConventions();
		const implementedLabels = implemented.map((c) => c.label);
		const documentedLabels = docs.map((row) => row.convention);

		expect(documentedLabels).toEqual(implementedLabels);
		for (const convention of implemented) {
			expect(convention.evidence, `${convention.label} evidence`).toEqual(expect.any(String));
			expect(convention.evidence.trim(), `${convention.label} evidence`).not.toBe('');
		}
	});

	it('identifies an MMD rig from its Japanese PMX bone names', () => {
		const c = detectConvention(ctx(['センター', '上半身', '左腕', '左ひじ', '右ひざ']));
		expect(c.id).toBe('mmd');
		expect(c.label).toBe('MikuMikuDance (PMX/PMD)');
	});

	it('identifies a Source engine rig and ranks it above plain Biped', () => {
		const c = detectConvention(ctx(['ValveBiped.Bip01_Pelvis', 'ValveBiped.Bip01_L_UpperArm', 'ValveBiped.Bip01_Head1']));
		expect(c.id).toBe('source');
		expect(detectConvention(ctx(['ValveBipedBip01_Pelvis'])).id).toBe('source');
		expect(detectConvention(ctx(['Bip01 Pelvis', 'Bip01 L UpperArm'])).id).toBe('biped');
	});

	it('does not claim MMD for a Latin-named rig', () => {
		expect(detectConvention(ctx(['Hips', 'Spine', 'LeftArm', 'RightArm'])).id).not.toBe('mmd');
	});

	it('identifies Apple joint-suffixed rigs', () => {
		const c = detectConvention(ctx(['hips_joint', 'spine_joint', 'left_arm_joint', 'right_arm_joint']));
		expect(c.id).toBe('apple-joint');
	});

	it('identifies Kinect rigs without confusing SpineShoulder for a limb', () => {
		const c = detectConvention(ctx(['SpineBase', 'SpineMid', 'SpineShoulder', 'ShoulderLeft', 'KneeRight']));
		expect(c.id).toBe('kinect');
	});

	it('identifies MediaPipe Pose from its unique foot landmarks', () => {
		const c = detectConvention(ctx(['left_hip', 'left_knee', 'left_heel', 'right_foot_index']));
		expect(c.id).toBe('mediapipe');
	});

	it('reports unknown rather than guessing when nothing fingerprints', () => {
		expect(detectConvention(ctx(['bone_a', 'bone_b', 'bone_c'])).id).toBe('unknown');
	});
});

describe('analyzeGlb verdicts', () => {
	it('passes the canonical Avaturn reference rig with every joint mapped', () => {
		const r = report('cz');
		expect(r.verdict.level).toBe('pass');
		expect(r.skeleton.convention.id).toBe('avaturn');
		expect(r.skeleton.mapped).toBe(CANONICAL_TOTAL);
		expect(r.skeleton.groups.every((g) => g.driven)).toBe(true);
	});

	it('passes a Mixamo rig and names the convention from its joint prefix', () => {
		const r = report('michelle');
		expect(r.verdict.level).toBe('pass');
		expect(r.skeleton.convention.id).toBe('mixamo');
		expect(r.skeleton.renames.length).toBeGreaterThan(0);
		expect(r.skeleton.renames[0].from).toMatch(/^mixamorig/i);
	});

	it('identifies Ready Player Me from its Wolf3D mesh nodes, not its bone names', () => {
		const r = report('default');
		expect(r.skeleton.convention.id).toBe('rpm');
		expect(r.skeleton.convention.schema).toBe('rpm');
	});

	it('fails a model with no skinned mesh and says so plainly', () => {
		const r = report('mannequin');
		expect(r.skeleton.skinned).toBe(false);
		expect(r.verdict.level).toBe('fail');
		expect(r.verdict.drivable).toBe(false);
		expect(r.verdict.headline).toMatch(/no skinned mesh/i);
	});

	it('fails a skinned but non-humanoid rig for lack of canonical joints', () => {
		const r = report('fox');
		expect(r.skeleton.skinned).toBe(true);
		expect(r.skeleton.jointCount).toBeGreaterThan(0);
		expect(r.skeleton.mapped).toBeLessThan(MIN_CANONICAL_BONES);
		expect(r.verdict.level).toBe('fail');
		expect(r.verdict.headline).toMatch(/canonical skeleton/i);
	});

	it('reports per-vertex skin-weight health for a non-humanoid rig, same verdict as before', () => {
		// fox.glb has no canonical bone names at all (UniRig/SkinTokens/AniGen
		// output looks the same way), so canonical coverage can never answer
		// "is this skin sound" for it; maxInfluences/unweightedVertices can.
		const r = report('fox');
		expect(r.skeleton.skinnedVertices).toBeGreaterThan(0);
		expect(r.skeleton.maxInfluences).toBeGreaterThan(0);
		expect(r.skeleton.maxInfluences).toBeLessThanOrEqual(8);
		expect(r.skeleton.unweightedVertices).toBeGreaterThanOrEqual(0);
		expect(r.skeleton.unweightedVertices).toBeLessThanOrEqual(r.skeleton.skinnedVertices);
		// The new fields are informational: they must not change the verdict
		// this rig already got.
		expect(r.verdict.drivable).toBe(false);
		expect(r.verdict.level).toBe('fail');
		expect(r.verdict.notes.some((n) => /skinned vertices?/i.test(n))).toBe(true);
	});

	it('reports zero skin-weight stats for an unskinned model rather than throwing', () => {
		const r = report('mannequin');
		expect(r.skeleton.skinned).toBe(false);
		expect(r.skeleton.maxInfluences).toBe(0);
		expect(r.skeleton.unweightedVertices).toBe(0);
		expect(r.skeleton.skinnedVertices).toBe(0);
	});

	it('warns on a halfbody rig and names exactly which groups stay frozen', () => {
		const r = report('realistic-halfbody');
		expect(r.verdict.level).toBe('warn');
		expect(r.verdict.drivable).toBe(true);
		const legs = r.skeleton.groups.find((g) => g.id === 'legs');
		expect(legs.driven).toBe(false);
		expect(legs.missingKey).toContain('LeftUpLeg');
		// Hands are fully rigged on this avatar, so the warning must not smear
		// the failure across every group.
		expect(r.skeleton.groups.find((g) => g.id === 'hands').driven).toBe(true);
	});

	it('mirrors the runtime gate: skinned plus MIN_CANONICAL_BONES decides drivability', () => {
		for (const name of ['cz', 'michelle', 'fox', 'mannequin', 'realistic-halfbody']) {
			const r = report(name);
			const expected = r.skeleton.skinned && r.skeleton.mapped >= MIN_CANONICAL_BONES;
			expect(r.verdict.drivable).toBe(expected);
		}
	});
});

describe('analyzeGlb inventory', () => {
	it('counts triangles, materials, and joints for a real avatar', () => {
		const r = report('michelle');
		expect(r.geometry.triangles).toBeGreaterThan(1000);
		expect(r.geometry.vertices).toBeGreaterThan(1000);
		expect(r.counts.materials).toBeGreaterThan(0);
		expect(r.skeleton.jointCount).toBeGreaterThanOrEqual(CANONICAL_TOTAL);
		expect(r.bytes).toBe(r.jsonBytes + r.binBytes + 28);
	});

	it('finds the full Oculus viseme set on an avatar that ships lip-sync', () => {
		const r = report('realistic-female');
		expect(r.morphs.visemeCount).toBe(15);
		expect(r.morphs.visemeComplete).toBe(true);
		expect(r.morphs.lipSync).toBe(true);
		expect(r.verdict.notes.some((n) => /lip-sync/i.test(n))).toBe(true);
	});

	it('reports no lip-sync, and suggests visemes, on a rig with none', () => {
		const r = report('cz');
		expect(r.morphs.visemeCount).toBe(0);
		expect(r.morphs.lipSync).toBe(false);
		expect(r.verdict.fixes.some((f) => /viseme/i.test(f))).toBe(true);
	});

	it('lists every limb group exactly once, in body order', () => {
		const r = report('cz');
		expect(r.skeleton.groups.map((g) => g.id)).toEqual(LIMB_GROUPS.map((g) => g.id));
	});

	it('surfaces unmapped joint names so they can become new canonicalizer rules', () => {
		const r = report('cesium-man');
		expect(r.skeleton.unmapped.length).toBeGreaterThan(0);
		expect(r.skeleton.unmapped.every((n) => typeof n === 'string' && n.length)).toBe(true);
	});
});

describe('manifestFromReport', () => {
	it('produces a manifest that satisfies every required schema-v1 field', () => {
		const r = report('michelle');
		const m = manifestFromReport(r, {
			id: 'avatar-test',
			name: 'Michelle',
			meshUri: 'https://three.ws/avatars/michelle.glb',
			owner: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
			sha256: 'a'.repeat(64),
			createdAt: '2026-07-31T00:00:00.000Z',
		});
		for (const key of ['schemaVersion', 'id', 'name', 'mesh', 'skeleton', 'owner', 'createdAt']) {
			expect(m[key], `missing required field ${key}`).toBeDefined();
		}
		expect(m.schemaVersion).toBe(1);
		expect(m.mesh.format).toBe('glb');
		expect(m.mesh.kBytes).toBeGreaterThan(0);
		expect(m.owner.chain).toBe('solana');
	});

	it('declares a skeleton value the schema enum actually accepts', () => {
		const allowed = ['avaturn', 'mixamo', 'rpm', 'vrm-humanoid', 'custom'];
		for (const name of ['cz', 'michelle', 'default', 'fox', 'cesium-man']) {
			const m = manifestFromReport(report(name), {
				id: 'x', name: 'x', meshUri: 'https://example.com/x.glb', owner: 'x', createdAt: '2026-07-31T00:00:00.000Z',
			});
			expect(allowed).toContain(m.skeleton);
		}
	});
});

describe('formatBytes', () => {
	it('scales through B, KB, and MB', () => {
		expect(formatBytes(0)).toBe('0 B');
		expect(formatBytes(512)).toBe('512 B');
		expect(formatBytes(2048)).toBe('2.0 KB');
		expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MB');
	});
});

// The /rig-doctor hero advertises "N rig conventions recognised" and "52
// canonical joints scored". The page rewrites both from this module at runtime,
// but the markup still carries them for a reader with JavaScript off, and that
// static copy had already gone stale by one convention. These assertions fail
// the moment the two disagree again.
describe('the /rig-doctor hero facts match the analyser', () => {
	const html = readFileSync(join(ROOT, 'pages/rig-doctor.html'), 'utf8');

	it('states the number of conventions the fingerprinter actually implements', () => {
		const m = html.match(/<strong id="rd-fact-conventions">(\d+)<\/strong>/);
		expect(m, 'pages/rig-doctor.html lost its #rd-fact-conventions element').not.toBeNull();
		expect(Number(m[1])).toBe(CONVENTION_COUNT);
	});

	it('states the size of the canonical skeleton it actually scores against', () => {
		const m = html.match(/<strong id="rd-fact-joints">(\d+)<\/strong>/);
		expect(m, 'pages/rig-doctor.html lost its #rd-fact-joints element').not.toBeNull();
		expect(Number(m[1])).toBe(CANONICAL_TOTAL);
	});
});