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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Tests for the server-side avatar appearance baker.
//
// These exercise bakeAppearance() directly (no DB, no R2) using:
// - a base GLB built in-memory containing a Head bone-style node and a mesh
// with named morph targets we can verify get baked.
// - the real public/accessories/*.glb files generated by
// scripts/generate-accessory-glbs.mjs.
//
// Verifies:
// 1. Morph weights from outfit.morphBinding are baked into node.weights
// so a downstream loader sees the dressed pose without runtime work.
// 2. A bone-attached accessory GLB ends up parented under the matching bone.
// 3. appearanceHash() is order-invariant: { outfit: a, accessories: [b, c] }
// hashes identically to { accessories: [b, c], outfit: a }.
// 4. isBakeable() is false for null / empty appearance.
import { describe, it, expect, beforeAll } from 'vitest';
import { Document, NodeIO } from '@gltf-transform/core';
import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
import { MeshoptDecoder } from 'meshoptimizer';
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import {
bakeAppearance,
appearanceHash,
isBakeable,
bakedStorageKeyFor,
} from '../api/_lib/bake.js';
// ── In-memory test base GLB ────────────────────────────────────────────────
// Builds a tiny skeleton-shaped GLB with:
// - a "Hips" → "Spine" → "Head" node chain (the bone names AccessoryManager
// and bake.findBone() look for)
// - a single triangle mesh under the root with two morph targets named
// "Outfit_Casual" and "Outfit_Formal" so we can verify weight baking
async function buildTestBaseGlb() {
const doc = new Document();
doc.createBuffer();
doc.getRoot().getAsset().generator = 'avatar-bake.test fixture';
// Bone chain
const hips = doc.createNode('Hips');
const spine = doc.createNode('Spine');
const head = doc.createNode('Head');
hips.addChild(spine);
spine.addChild(head);
// One triangle, three morph targets that displace the apex vertex.
const basePositions = new Float32Array([
0, 0, 0,
1, 0, 0,
0.5, 1, 0,
]);
const baseNormals = new Float32Array([
0, 0, 1,
0, 0, 1,
0, 0, 1,
]);
const indices = new Uint16Array([0, 1, 2]);
const posAccessor = doc.createAccessor('positions').setType('VEC3').setArray(basePositions);
const norAccessor = doc.createAccessor('normals').setType('VEC3').setArray(baseNormals);
const idxAccessor = doc.createAccessor('indices').setType('SCALAR').setArray(indices);
// Morph targets are stored as Primitive targets; each target is an
// {attribute → accessor} mapping describing the delta from base.
const targetCasualPos = doc
.createAccessor('outfit_casual_pos_delta')
.setType('VEC3')
.setArray(new Float32Array([0, 0, 0, 0, 0, 0, 0, 0.5, 0]));
const targetFormalPos = doc
.createAccessor('outfit_formal_pos_delta')
.setType('VEC3')
.setArray(new Float32Array([0, 0, 0, 0, 0, 0, 0, 1.0, 0]));
const prim = doc
.createPrimitive()
.setAttribute('POSITION', posAccessor)
.setAttribute('NORMAL', norAccessor)
.setIndices(idxAccessor)
.setMaterial(doc.createMaterial('base').setBaseColorFactor([0.5, 0.5, 0.5, 1]));
const targetCasual = doc.createPrimitiveTarget('Outfit_Casual').setAttribute('POSITION', targetCasualPos);
const targetFormal = doc.createPrimitiveTarget('Outfit_Formal').setAttribute('POSITION', targetFormalPos);
prim.addTarget(targetCasual);
prim.addTarget(targetFormal);
const mesh = doc.createMesh('body').addPrimitive(prim);
// Target names live on mesh.extras.targetNames per the KHR convention.
mesh.setExtras({ targetNames: ['Outfit_Casual', 'Outfit_Formal'] });
const bodyNode = doc.createNode('body').setMesh(mesh);
const scene = doc.createScene('root').addChild(hips).addChild(bodyNode);
doc.getRoot().setDefaultScene(scene);
const io = new NodeIO();
return io.writeBinary(doc);
}
let BASE_GLB = null;
let BASEBALL_GLB = null;
beforeAll(async () => {
BASE_GLB = await buildTestBaseGlb();
BASEBALL_GLB = await readFile(
path.resolve(process.cwd(), 'public/accessories/hat-baseball.glb'),
);
});
// ── Helpers ────────────────────────────────────────────────────────────────
async function inspect(glbBytes) {
// bakeAppearance now ships meshopt-compressed buffers, so the test reader
// must register the meshopt decoder dependency to round-trip them.
await MeshoptDecoder.ready;
const io = new NodeIO()
.registerExtensions(ALL_EXTENSIONS)
.registerDependencies({ 'meshopt.decoder': MeshoptDecoder });
return io.readBinary(new Uint8Array(glbBytes));
}
function findNode(doc, name) {
return doc.getRoot().listNodes().find((n) => n.getName() === name) || null;
}
// ── Tests ──────────────────────────────────────────────────────────────────
describe('isBakeable', () => {
it('rejects null / undefined / empty', () => {
expect(isBakeable(null)).toBe(false);
expect(isBakeable(undefined)).toBe(false);
expect(isBakeable({})).toBe(false);
expect(isBakeable({ accessories: [] })).toBe(false);
expect(isBakeable({ morphs: {} })).toBe(false);
});
it('accepts any non-empty field', () => {
expect(isBakeable({ outfit: 'outfit-casual' })).toBe(true);
expect(isBakeable({ accessories: ['hat-baseball'] })).toBe(true);
expect(isBakeable({ morphs: { Smile: 0.5 } })).toBe(true);
expect(isBakeable({ colors: { outfit: '#ff0000' } })).toBe(true);
expect(isBakeable({ hidden: ['outfit'] })).toBe(true);
expect(isBakeable({ garments: [{ slot: 'top', id: 'oxford-shirt-white' }] })).toBe(true);
expect(isBakeable({ colors: {} })).toBe(false);
expect(isBakeable({ hidden: [] })).toBe(false);
expect(isBakeable({ garments: [] })).toBe(false);
});
});
describe('appearanceHash', () => {
it('is stable across key order', () => {
const a = appearanceHash({ outfit: 'outfit-casual', accessories: ['hat-baseball'] });
const b = appearanceHash({ accessories: ['hat-baseball'], outfit: 'outfit-casual' });
expect(a).toBe(b);
});
it('differs when content differs', () => {
const a = appearanceHash({ outfit: 'outfit-casual' });
const b = appearanceHash({ outfit: 'outfit-formal' });
expect(a).not.toBe(b);
});
it('is 64 hex chars (sha256)', () => {
expect(appearanceHash({ outfit: 'outfit-casual' })).toMatch(/^[a-f0-9]{64}$/);
});
});
describe('bakedStorageKeyFor', () => {
it('keeps the user/slug prefix and embeds a hash slice', () => {
const key = bakedStorageKeyFor({
baseStorageKey: 'u/abc123/dancer/xyz.glb',
hash: 'a'.repeat(64),
});
expect(key.startsWith('u/abc123/dancer/baked-')).toBe(true);
expect(key.endsWith('.glb')).toBe(true);
});
});
describe('bakeAppearance — morph weights', () => {
it('bakes outfit morphBinding into the mesh weights so downstream loaders see the pose', async () => {
const baked = await bakeAppearance(BASE_GLB, {
outfit: 'outfit-casual', // public/accessories/presets.json → { Outfit_Casual: 1.0 }
});
const doc = await inspect(baked);
const bodyNode = findNode(doc, 'body');
expect(bodyNode).toBeTruthy();
// Either node-level weights or mesh-level weights should carry the bake.
const weights = bodyNode.getWeights();
expect(weights.length).toBe(2);
// Outfit_Casual is target #0 in our fixture.
expect(weights[0]).toBeCloseTo(1.0, 3);
expect(weights[1]).toBeCloseTo(0.0, 3);
});
it('applies appearance.morphs overrides on top of preset bindings', async () => {
const baked = await bakeAppearance(BASE_GLB, {
outfit: 'outfit-casual',
morphs: { Outfit_Casual: 0.25, Outfit_Formal: 0.75 },
});
const doc = await inspect(baked);
const bodyNode = findNode(doc, 'body');
const weights = bodyNode.getWeights();
expect(weights[0]).toBeCloseTo(0.25, 3);
expect(weights[1]).toBeCloseTo(0.75, 3);
});
});
// Builds a GLB with two separate meshes carrying named Wolf3D materials, so we
// can verify colour tints land on the right material and hidden layers drop the
// right node — the garment-layer (wardrobe) bake path.
async function buildLayeredGlb() {
const doc = new Document();
doc.createBuffer();
const positions = () =>
doc.createAccessor().setType('VEC3').setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0.5, 1, 0]));
const normals = () =>
doc.createAccessor().setType('VEC3').setArray(new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]));
const indices = () => doc.createAccessor().setType('SCALAR').setArray(new Uint16Array([0, 1, 2]));
const meshNode = (name, materialName) => {
const prim = doc
.createPrimitive()
.setAttribute('POSITION', positions())
.setAttribute('NORMAL', normals())
.setIndices(indices())
.setMaterial(doc.createMaterial(materialName).setBaseColorFactor([1, 1, 1, 1]));
const mesh = doc.createMesh(name).addPrimitive(prim);
return doc.createNode(name).setMesh(mesh);
};
const top = meshNode('OutfitTopNode', 'Wolf3D_Outfit_Top');
const skin = meshNode('SkinNode', 'Wolf3D_Skin');
const scene = doc.createScene('root').addChild(top).addChild(skin);
doc.getRoot().setDefaultScene(scene);
return new NodeIO().writeBinary(doc);
}
function findMaterial(doc, name) {
return doc.getRoot().listMaterials().find((m) => m.getName() === name) || null;
}
describe('bakeAppearance — garment layers (colors + hidden)', () => {
it('tints the slot material baseColorFactor and leaves other slots untouched', async () => {
const base = await buildLayeredGlb();
const baked = await bakeAppearance(base, { colors: { outfit: '#ff0000' } });
const doc = await inspect(baked);
const top = findMaterial(doc, 'Wolf3D_Outfit_Top');
expect(top).toBeTruthy();
const [r, g, b] = top.getBaseColorFactor();
// #ff0000 sRGB → linear ≈ [1, 0, 0].
expect(r).toBeCloseTo(1.0, 2);
expect(g).toBeCloseTo(0.0, 2);
expect(b).toBeCloseTo(0.0, 2);
// Skin was not in the colors map — its factor stays white.
const skin = findMaterial(doc, 'Wolf3D_Skin');
expect(skin.getBaseColorFactor().slice(0, 3)).toEqual([1, 1, 1]);
});
it('drops the meshes of a hidden slot but keeps the rest of the body', async () => {
const base = await buildLayeredGlb();
const baked = await bakeAppearance(base, { hidden: ['outfit'] });
const doc = await inspect(baked);
// The outfit node (and its now-orphaned material) are pruned away.
expect(findNode(doc, 'OutfitTopNode')).toBeNull();
expect(findMaterial(doc, 'Wolf3D_Outfit_Top')).toBeNull();
// The base body remains.
expect(findNode(doc, 'SkinNode')).toBeTruthy();
});
});
describe('bakeAppearance — bone-attached accessories', () => {
it('parents the hat-baseball mesh under the Head bone after baking', async () => {
const baked = await bakeAppearance(BASE_GLB, {
accessories: ['hat-baseball'],
});
const doc = await inspect(baked);
const head = findNode(doc, 'Head');
expect(head).toBeTruthy();
// After bake, Head should have at least one child that came from the
// hat-baseball.glb root (named "HatBaseball" by the generator).
const headChildren = head.listChildren();
const hatRoot = headChildren.find((n) => n.getName() === 'HatBaseball');
expect(hatRoot).toBeTruthy();
});
});