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.

16.4 KB
Raw Blame
/**
 * Additive wardrobe — unit tests for src/avatar-garment.js.
 *
 * Builds synthetic avatars and garments in-memory (no GLB fixtures), so the
 * suite is fast and deterministic. The contract under test is that a garment
 * authored against its *own* skeleton, with its own naming convention and its
 * own rest pose, deforms identically to the avatar's body once rebound:
 *
 *   - garment bone indices rewritten into avatar bone order,
 *   - vendor-prefixed / foreign naming still resolves (mixamorig:, VRM, .L/.R),
 *   - helper joints the avatar lacks fall back to their nearest mapped ancestor,
 *   - unresolvable weights are zeroed and the vertex renormalised,
 *   - a divergent rest pose is reconciled, not baked in as an offset,
 *   - a garment that cannot bind is refused rather than attached mangled,
 *   - skin under a garment is culled and the cull is reversible.
 */

import { describe, it, expect } from 'vitest';
import {
	Bone,
	BufferGeometry,
	Float32BufferAttribute,
	Group,
	Matrix4,
	Mesh,
	MeshStandardMaterial,
	Skeleton,
	SkinnedMesh,
	Uint16BufferAttribute,
	Vector3,
} from 'three';
import {
	MIN_BIND_COVERAGE,
	attachGarment,
	bindCoverage,
	buildBoneRemap,
	clampOccludes,
	cullSkinByBones,
	detachSlot,
	extentRejection,
	findAvatarSkeleton,
	occupiedSlots,
	reindexBoneInverses,
	remapSkinAttributes,
	restoreSkin,
	supportsWardrobe,
} from '../src/avatar-garment.js';

/* ── helpers ─────────────────────────────────────────────────────────────── */

/**
 * A minimal humanoid chain: Hips → Spine → Head, plus LeftArm off the spine.
 * `names` lets a caller rename every joint to test foreign conventions, and
 * `spineY` moves the rest pose so divergent-bind-pose cases are expressible.
 */
function buildRig({ prefix = '', spineY = 2, extraBones = [] } = {}) {
	const mk = (n) => { const b = new Bone(); b.name = prefix + n; return b; };
	const hips = mk('Hips');
	const spine = mk('Spine');
	const head = mk('Head');
	const leftArm = mk('LeftArm');

	spine.position.set(0, spineY, 0);
	head.position.set(0, 1, 0);
	leftArm.position.set(0.5, 0.5, 0);

	hips.add(spine);
	spine.add(head);
	spine.add(leftArm);

	const bones = [hips, spine, head, leftArm];
	for (const { name, parent, position } of extraBones) {
		const b = mk(name);
		b.position.copy(position || new Vector3(0, 0.1, 0));
		(bones.find((x) => x.name === prefix + parent) || spine).add(b);
		bones.push(b);
	}

	hips.updateMatrixWorld(true);
	return { bones, hips, spine, head, leftArm, skeleton: new Skeleton(bones) };
}

/** One-vertex-per-entry skinned mesh, each vertex fully weighted to one bone. */
function buildSkinnedMesh(skeleton, verts) {
	const geometry = new BufferGeometry();
	const positions = [];
	const skinIndices = [];
	const skinWeights = [];
	for (const { pos, bone, weights } of verts) {
		positions.push(pos.x, pos.y, pos.z);
		if (weights) {
			skinIndices.push(...weights.map((w) => w[0]), ...Array(4 - weights.length).fill(0));
			skinWeights.push(...weights.map((w) => w[1]), ...Array(4 - weights.length).fill(0));
		} else {
			skinIndices.push(bone, 0, 0, 0);
			skinWeights.push(1, 0, 0, 0);
		}
	}
	geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));
	geometry.setAttribute('skinIndex', new Uint16BufferAttribute(skinIndices, 4));
	geometry.setAttribute('skinWeight', new Float32BufferAttribute(skinWeights, 4));

	const mesh = new SkinnedMesh(geometry, new MeshStandardMaterial());
	mesh.add(skeleton.bones[0]);
	mesh.bind(skeleton);
	mesh.updateMatrixWorld(true);
	return mesh;
}

function buildAvatar({ spineY = 2, prefix = '' } = {}) {
	const rig = buildRig({ prefix, spineY });
	const mesh = buildSkinnedMesh(rig.skeleton, [
		{ pos: new Vector3(0, spineY + 0.5, 0), bone: 1 },   // torso vertex on Spine
		{ pos: new Vector3(0, spineY + 1.0, 0), bone: 2 },   // head vertex
	]);
	const root = new Group();
	root.add(mesh);
	root.updateMatrixWorld(true);
	return { root, mesh, ...rig };
}

/* ── bone remapping ──────────────────────────────────────────────────────── */

describe('buildBoneRemap', () => {
	it('maps identically-named skeletons one-to-one', () => {
		const avatar = buildRig();
		const garment = buildRig();
		const { remap, unresolved } = buildBoneRemap(garment.skeleton, avatar.skeleton);
		expect([...remap]).toEqual([0, 1, 2, 3]);
		expect(unresolved).toEqual([]);
	});

	it('resolves a mixamo-prefixed garment onto a plain avatar', () => {
		const avatar = buildRig();
		const garment = buildRig({ prefix: 'mixamorig:' });
		const { remap, unresolved } = buildBoneRemap(garment.skeleton, avatar.skeleton);
		expect([...remap]).toEqual([0, 1, 2, 3]);
		expect(unresolved).toEqual([]);
	});

	it('falls back to the nearest mapped ancestor for helper joints', () => {
		const avatar = buildRig();
		const garment = buildRig({
			extraBones: [{ name: 'SpineTwist_A', parent: 'Spine' }],
		});
		const { remap, unresolved } = buildBoneRemap(garment.skeleton, avatar.skeleton);
		// The twist joint is unknown to the avatar, so it rides Spine (index 1).
		expect(remap[4]).toBe(1);
		expect(unresolved).toEqual([]);
	});

	it('reports a bone with no mapped ancestor as unresolved', () => {
		const avatar = buildRig();
		const garment = buildRig();
		// An orphan bone parented outside the chain resolves to nothing.
		const orphan = new Bone();
		orphan.name = 'PropHandle';
		const skeleton = new Skeleton([...garment.bones, orphan]);
		const { remap, unresolved } = buildBoneRemap(skeleton, avatar.skeleton);
		expect(remap[4]).toBe(-1);
		expect(unresolved).toEqual(['PropHandle']);
	});
});

describe('bindCoverage', () => {
	it('weights coverage by influence, not by bone count', () => {
		const avatar = buildRig();
		const garment = buildRig();
		const skeleton = new Skeleton([...garment.bones, Object.assign(new Bone(), { name: 'X' })]);
		// One vertex: 90% on Spine (maps), 10% on the orphan (does not).
		const mesh = buildSkinnedMesh(skeleton, [
			{ pos: new Vector3(0, 2, 0), weights: [[1, 0.9], [4, 0.1]] },
		]);
		const { remap } = buildBoneRemap(skeleton, avatar.skeleton);
		expect(bindCoverage(mesh.geometry, remap)).toBeCloseTo(0.9, 5);
	});
});

describe('remapSkinAttributes', () => {
	it('renormalises a vertex after an unresolved weight is dropped', () => {
		const avatar = buildRig();
		const garment = buildRig();
		const skeleton = new Skeleton([...garment.bones, Object.assign(new Bone(), { name: 'X' })]);
		const mesh = buildSkinnedMesh(skeleton, [
			{ pos: new Vector3(0, 2, 0), weights: [[1, 0.5], [4, 0.5]] },
		]);
		const { remap } = buildBoneRemap(skeleton, avatar.skeleton);
		remapSkinAttributes(mesh.geometry, remap);

		const w = mesh.geometry.attributes.skinWeight;
		expect(w.getComponent(0, 0)).toBeCloseTo(1, 5);   // surviving weight scaled to 1
		expect(w.getComponent(0, 1)).toBe(0);
	});
});

describe('reindexBoneInverses', () => {
	it("keeps the garment's own inverse for bones it referenced", () => {
		const avatar = buildRig({ spineY: 3 });
		const garment = buildRig({ spineY: 2 });
		const { remap } = buildBoneRemap(garment.skeleton, avatar.skeleton);
		const out = reindexBoneInverses(garment.skeleton, avatar.skeleton, remap);
		// Avatar Spine sits at y=3, garment Spine at y=2; the reindexed inverse
		// must be the garment's (translate -2), not the avatar's (translate -3).
		expect(out[1].elements[13]).toBeCloseTo(-2, 5);
	});
});

/* ── attach ──────────────────────────────────────────────────────────────── */

describe('attachGarment', () => {
	it('binds a foreign-named garment so it deforms with the avatar', () => {
		const avatar = buildAvatar({ spineY: 2 });
		const garment = buildRig({ prefix: 'mixamorig:', spineY: 2 });
		const garmentMesh = buildSkinnedMesh(garment.skeleton, [
			{ pos: new Vector3(0, 2.5, 0), bone: 1 },   // shirt vertex over the spine
		]);
		const garmentRoot = new Group();
		garmentRoot.add(garmentMesh);
		garmentRoot.updateMatrixWorld(true);

		const res = attachGarment(avatar.root, garmentRoot, { slot: 'top' });
		expect(res.ok).toBe(true);
		expect(res.coverage).toBeCloseTo(1, 5);

		// Rotate the avatar's spine; body and garment must land together.
		avatar.spine.rotation.z = Math.PI / 4;
		avatar.root.updateMatrixWorld(true);
		res.meshes[0].skeleton.update();
		avatar.mesh.skeleton.update();

		const bodyPoint = avatar.mesh.applyBoneTransform(0, new Vector3().fromBufferAttribute(
			avatar.mesh.geometry.attributes.position, 0));
		const garmentPoint = res.meshes[0].applyBoneTransform(0, new Vector3().fromBufferAttribute(
			res.meshes[0].geometry.attributes.position, 0));

		expect(garmentPoint.x).toBeCloseTo(bodyPoint.x, 5);
		expect(garmentPoint.y).toBeCloseTo(bodyPoint.y, 5);
		expect(garmentPoint.z).toBeCloseTo(bodyPoint.z, 5);
	});

	it('reconciles a divergent rest pose instead of baking in an offset', () => {
		// Garment authored on a rig whose spine sits at y=2; avatar's is at y=3.
		// The vertex sat 0.5 above its own spine and must still sit 0.5 above the
		// avatar's, i.e. y=3.5 — not y=2.5 (offset ignored) and not y=4.5 (double).
		const avatar = buildAvatar({ spineY: 3 });
		const garment = buildRig({ spineY: 2 });
		const garmentMesh = buildSkinnedMesh(garment.skeleton, [
			{ pos: new Vector3(0, 2.5, 0), bone: 1 },
		]);
		const garmentRoot = new Group();
		garmentRoot.add(garmentMesh);
		garmentRoot.updateMatrixWorld(true);

		const res = attachGarment(avatar.root, garmentRoot, { slot: 'top' });
		expect(res.ok).toBe(true);

		avatar.root.updateMatrixWorld(true);
		res.meshes[0].skeleton.update();
		const p = res.meshes[0].applyBoneTransform(0, new Vector3().fromBufferAttribute(
			res.meshes[0].geometry.attributes.position, 0));
		expect(p.y).toBeCloseTo(3.5, 5);
	});

	it('refuses a garment whose skin cannot reach the avatar skeleton', () => {
		const avatar = buildAvatar();
		const alien = new Skeleton([
			Object.assign(new Bone(), { name: 'tentacle_root' }),
			Object.assign(new Bone(), { name: 'tentacle_tip' }),
		]);
		const garmentMesh = buildSkinnedMesh(alien, [
			{ pos: new Vector3(0, 1, 0), bone: 0 },
		]);
		const garmentRoot = new Group();
		garmentRoot.add(garmentMesh);

		const res = attachGarment(avatar.root, garmentRoot, { slot: 'top' });
		expect(res.ok).toBe(false);
		expect(res.coverage).toBeLessThan(MIN_BIND_COVERAGE);
		expect(res.reason).toMatch(/binds only/);
		// Nothing was left behind in the scene.
		expect(occupiedSlots(avatar.root)).toEqual([]);
	});

	it('tracks slot occupancy and detaches cleanly', () => {
		const avatar = buildAvatar();
		const garment = buildRig();
		const garmentRoot = new Group();
		garmentRoot.add(buildSkinnedMesh(garment.skeleton, [
			{ pos: new Vector3(0, 2.5, 0), bone: 1 },
		]));

		const res = attachGarment(avatar.root, garmentRoot, { slot: 'top' });
		expect(res.ok).toBe(true);
		expect(occupiedSlots(avatar.root)).toEqual(['top']);

		expect(detachSlot(avatar.root, 'top')).toBe(1);
		expect(occupiedSlots(avatar.root)).toEqual([]);
	});

	it('rejects an avatar with no skinned mesh', () => {
		const res = attachGarment(new Group(), new Group(), { slot: 'top' });
		expect(res.ok).toBe(false);
		expect(res.reason).toMatch(/no skinned mesh/);
	});
});

/* ── occlusion ───────────────────────────────────────────────────────────── */

describe('cullSkinByBones', () => {
	it('drops triangles fully covered by the garment and restores them', () => {
		const rig = buildRig();
		const mesh = buildSkinnedMesh(rig.skeleton, [
			{ pos: new Vector3(0, 2, 0), bone: 1 },   // spine
			{ pos: new Vector3(1, 2, 0), bone: 1 },   // spine
			{ pos: new Vector3(0, 3, 0), bone: 1 },   // spine  → triangle 0 covered
			{ pos: new Vector3(0, 3, 1), bone: 2 },   // head   → triangle 1 survives
		]);
		mesh.geometry.setIndex([0, 1, 2, 0, 1, 3]);

		const dropped = cullSkinByBones(mesh.geometry, new Set([1]), 0.5);
		expect(dropped).toBe(1);
		expect(mesh.geometry.getIndex().count).toBe(3);

		expect(restoreSkin(mesh.geometry)).toBe(true);
		expect(mesh.geometry.getIndex().count).toBe(6);
	});
});

/* ── gating ──────────────────────────────────────────────────────────────── */

describe('supportsWardrobe', () => {
	it('accepts a humanoid rig', () => {
		expect(supportsWardrobe(buildAvatar().root)).toBe(true);
	});

	it('accepts a foreign-named humanoid rig', () => {
		expect(supportsWardrobe(buildAvatar({ prefix: 'mixamorig:' }).root)).toBe(true);
	});

	it('rejects a non-humanoid prop', () => {
		const bone = Object.assign(new Bone(), { name: 'root' });
		const skeleton = new Skeleton([bone]);
		const mesh = buildSkinnedMesh(skeleton, [{ pos: new Vector3(0, 0, 0), bone: 0 }]);
		const root = new Group();
		root.add(mesh);
		expect(supportsWardrobe(root)).toBe(false);
	});
});

describe('findAvatarSkeleton', () => {
	it('picks the skeleton driving the most vertices, not the first found', () => {
		const root = new Group();
		const prop = buildRig({ prefix: 'prop_' });
		root.add(buildSkinnedMesh(prop.skeleton, [{ pos: new Vector3(0, 0, 0), bone: 0 }]));
		const body = buildRig();
		const bodyMesh = buildSkinnedMesh(body.skeleton, Array.from({ length: 10 }, () => (
			{ pos: new Vector3(0, 2, 0), bone: 1 }
		)));
		root.add(bodyMesh);

		expect(findAvatarSkeleton(root).mesh).toBe(bodyMesh);
	});
});

describe('clampOccludes', () => {
	it('keeps evidenced regions a slot may plausibly cover', () => {
		expect(clampOccludes('top', ['torso', 'upperArms'])).toEqual(['torso', 'upperArms']);
		expect(clampOccludes('bottom', ['hips', 'upperLegs', 'lowerLegs']))
			.toEqual(['hips', 'upperLegs', 'lowerLegs']);
	});

	it('drops regions outside the slot (waistband graze cannot hide legs)', () => {
		expect(clampOccludes('footwear', ['torso', 'hips', 'feet'])).toEqual(['feet']);
	});

	it('never lets headwear or hair occlude scalp: Head-bone culling would take the face', () => {
		expect(clampOccludes('headwear', ['scalp'])).toEqual([]);
		expect(clampOccludes('hair', ['scalp'])).toEqual([]);
	});

	it('is safe on unknown slots and malformed occludes', () => {
		expect(clampOccludes('nonsense', ['torso'])).toEqual([]);
		expect(clampOccludes('top', undefined)).toEqual([]);
		expect(clampOccludes('top', 'torso')).toEqual([]);
	});
});

describe('extentRejection', () => {
	// Measured against the avatar being worn, so the verdict is scale
	// invariant: identical in metres or centimetres.
	function bodyRoot(height = 1.667) {
		const root = new Group();
		const geo = new BufferGeometry();
		geo.setAttribute('position', new Float32BufferAttribute(
			[-0.2, 0, -0.1, 0.2, 0, -0.1, 0, height, 0.1], 3));
		root.add(new Mesh(geo, new MeshStandardMaterial()));
		return root;
	}
	function boxRoot(w, h, d) {
		const root = new Group();
		const geo = new BufferGeometry();
		geo.setAttribute('position', new Float32BufferAttribute(
			[-w / 2, -h / 2, -d / 2, w / 2, h / 2, d / 2, 0, 0, 0], 3));
		root.add(new Mesh(geo, new MeshStandardMaterial()));
		return root;
	}

	it('accepts a normally proportioned garment', () => {
		// A full-length coat on a 1.667m body.
		expect(extentRejection(boxRoot(0.5, 0.9, 0.35), bodyRoot())).toBeNull();
	});

	it('rejects the malformed 1.43m-deep hair curtain that shipped', () => {
		const reason = extentRejection(boxRoot(0.30, 0.896, 1.431), bodyRoot());
		expect(reason).toMatch(/depth/);
		expect(reason).toMatch(/malformed/);
	});

	it('is scale invariant (centimetre-unit avatar behaves identically)', () => {
		expect(extentRejection(boxRoot(30, 89.6, 143.1), bodyRoot(166.7))).toMatch(/depth/);
		expect(extentRejection(boxRoot(50, 90, 35), bodyRoot(166.7))).toBeNull();
	});

	it('abstains when the avatar has no measurable height', () => {
		expect(extentRejection(boxRoot(9, 9, 9), new Group())).toBeNull();
	});

	it('refuses to attach an oversized garment through attachGarment', () => {
		const avatar = buildRig();
		const root = new Group();
		root.add(buildSkinnedMesh(avatar.skeleton, [
			{ pos: new Vector3(0, 0, 0), bone: 0 },
			{ pos: new Vector3(0, 1.667, 0), bone: 2 },
		]));
		root.updateMatrixWorld(true);
		const res = attachGarment(root, boxRoot(0.3, 0.9, 1.5), { slot: 'hair' });
		expect(res.ok).toBe(false);
		expect(res.reason).toMatch(/malformed/);
	});
});