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
/**
* Preset application across rig backends (src/pose-rig.js).
*
* The pose presets are authored as mannequin-local Euler rotations where rest
* is identity (arms at the sides). Applying those raw local quaternions to a
* loaded GLB avatar REPLACED each bone's bind rotation and garbled every
* preset (arms-up read as a T-pose, salute pointed sideways, hands-on-hips
* threw the arms in the air). The fix expresses a preset as world-frame
* rotation deltas composed down the mannequin hierarchy and replays them on
* top of the target rig's captured rest pose — the same world-delta
* convention animation-retarget.js uses for clips.
*
* These tests pin:
* 1. Mannequin equivalence — the world-delta path reproduces the preset's
* local Eulers exactly on the mannequin (identity rest), for every preset.
* 2. GLB correctness — on a rig with non-identity bind rotations, each posed
* bone's world rotation is delta · restWorld (bind preserved, not wiped).
* 3. FK slider semantics on GLB — an untouched bone reads 0°/0°/0° (not its
* raw bind angles) and zeroing a bone restores rest instead of erasing it.
* 4. localTargetsForPose — returns targets for exactly the posed bones and
* leaves the rig's live transforms untouched (agent-screen tween path).
*/
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { Bone, Euler, Group, Object3D, Quaternion, Vector3 } from 'three';
import { describe, it, expect } from 'vitest';
import { MannequinRig, makeGltfRig, poseFromMannequinPreset } from '../src/pose-rig.js';
import { PRESETS, getPresetById } from '../src/pose-presets.js';
import { loadBoneGraph } from './_helpers/glb-bone-graph.js';
const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const avatarPath = (n) => path.join(REPO, 'public/avatars', `${n}.glb`);
const MANNEQUIN_TO_CANONICAL = {
pelvis: 'Hips', spine: 'Spine', chest: 'Spine2', neck: 'Neck', head: 'Head',
shoulderL: 'LeftArm', elbowL: 'LeftForeArm', wristL: 'LeftHand',
shoulderR: 'RightArm', elbowR: 'RightForeArm', wristR: 'RightHand',
hipL: 'LeftUpLeg', kneeL: 'LeftLeg', ankleL: 'LeftFoot',
hipR: 'RightUpLeg', kneeR: 'RightLeg', ankleR: 'RightFoot',
};
function quatFromEuler(rot) {
return new Quaternion().setFromEuler(new Euler(rot.x || 0, rot.y || 0, rot.z || 0, 'XYZ'));
}
// A miniature humanoid GLB scene whose bones carry non-identity bind
// rotations, like a real exported avatar (a Mixamo-style rig binds the right
// shoulder near 94° pitch / 90° roll — the values the studio's sliders showed
// raw before the fix).
function makeBoundScene() {
const scene = new Group();
const mk = (name, rot, parent) => {
const b = new Bone();
b.name = name;
b.quaternion.setFromEuler(new Euler(rot.x || 0, rot.y || 0, rot.z || 0, 'XYZ'));
b.position.set(0, 0.2, 0);
parent.add(b);
return b;
};
const armature = new Object3D();
armature.name = 'Armature';
armature.quaternion.setFromEuler(new Euler(Math.PI / 2, 0, 0)); // FBX-style +90°X
scene.add(armature);
const hips = mk('Hips', { x: -Math.PI / 2 }, armature);
const spine = mk('Spine', { x: 0.05 }, hips);
const spine2 = mk('Spine2', { x: -0.05 }, spine);
const rShoulder = mk('RightShoulder', { x: 1.64, z: 1.57 }, spine2);
const rArm = mk('RightArm', { z: -0.3 }, rShoulder);
const rForeArm = mk('RightForeArm', { z: -0.1 }, rArm);
mk('RightHand', {}, rForeArm);
const lShoulder = mk('LeftShoulder', { x: 1.64, z: -1.57 }, spine2);
const lArm = mk('LeftArm', { z: 0.3 }, lShoulder);
const lForeArm = mk('LeftForeArm', { z: 0.1 }, lArm);
mk('LeftHand', {}, lForeArm);
return scene;
}
function worldQuat(node) {
node.updateWorldMatrix(true, false);
return node.getWorldQuaternion(new Quaternion());
}
// A positional T-pose rig: arms extend along ±X (like a Mixamo bind), legs
// straight down, spine up. Presets are authored against an arms-at-sides
// stance, so this rig exercises the reference-stance alignment: a preset that
// keeps the arms down must bring a T-bound arm DOWN, not leave it horizontal.
function makeTPoseScene() {
const scene = new Group();
const mk = (name, pos, parent) => {
const b = new Bone();
b.name = name;
b.position.set(...pos);
parent.add(b);
return b;
};
const hips = mk('Hips', [0, 1, 0], scene);
const spine = mk('Spine', [0, 0.15, 0], hips);
const spine2 = mk('Spine2', [0, 0.25, 0], spine);
const neck = mk('Neck', [0, 0.15, 0], spine2);
mk('Head', [0, 0.12, 0], neck);
for (const [side, sign] of [['Left', 1], ['Right', -1]]) {
const sh = mk(`${side}Shoulder`, [sign * 0.08, 0.12, 0], spine2);
const arm = mk(`${side}Arm`, [sign * 0.12, 0, 0], sh);
const fore = mk(`${side}ForeArm`, [sign * 0.28, 0, 0], arm);
mk(`${side}Hand`, [sign * 0.26, 0, 0], fore);
const up = mk(`${side}UpLeg`, [sign * 0.1, -0.05, 0], hips);
const leg = mk(`${side}Leg`, [0, -0.45, 0], up);
const foot = mk(`${side}Foot`, [0, -0.45, 0], leg);
mk(`${side}ToeBase`, [0, -0.06, 0.14], foot);
}
return scene;
}
// World-space direction from a bone to its child bone (the limb direction).
function limbDir(rig, from, to) {
rig.root.updateMatrixWorld(true);
const a = rig.getNode(from).getWorldPosition(new Vector3());
const b = rig.getNode(to).getWorldPosition(new Vector3());
return b.sub(a).normalize();
}
describe('poseFromMannequinPreset world deltas', () => {
it('emits a world delta for every posed joint, composed down the chain', () => {
const pose = poseFromMannequinPreset(getPresetById('hands-up').pose);
expect(pose.worldDeltas.RightArm).toBeDefined();
expect(pose.worldDeltas.RightForeArm).toBeDefined();
// Forearm delta = shoulder delta · elbow local.
const s = new Quaternion(...pose.worldDeltas.RightArm);
const e = quatFromEuler({ x: -0.10 });
const expected = s.clone().multiply(e);
const got = new Quaternion(...pose.worldDeltas.RightForeArm);
expect(got.angleTo(expected)).toBeLessThan(1e-6);
});
});
describe('presets on the mannequin (regression)', () => {
it('the world-delta path reproduces every preset joint local exactly', () => {
const rig = new MannequinRig();
for (const preset of PRESETS) {
rig.applyPose(poseFromMannequinPreset(preset.pose));
for (const [joint, rot] of Object.entries(preset.pose)) {
if (joint === 'rootPosition') continue;
const canonical = MANNEQUIN_TO_CANONICAL[joint];
const node = rig.getNode(canonical);
expect(node, `${preset.id}.${joint}`).toBeTruthy();
const angle = node.quaternion.angleTo(quatFromEuler(rot));
expect(angle, `${preset.id}.${joint}`).toBeLessThan(1e-6);
}
}
});
});
describe('presets on a T-pose-bound GLB rig (reference-stance alignment)', () => {
it('T-pose preset keeps a T-bound arm horizontal', () => {
const rig = makeGltfRig(makeTPoseScene());
expect(rig).toBeTruthy();
rig.applyPose(poseFromMannequinPreset(getPresetById('tpose').pose));
const dir = limbDir(rig, 'RightArm', 'RightForeArm');
expect(dir.dot(new Vector3(-1, 0, 0))).toBeGreaterThan(0.99);
});
it('arms-up preset raises a T-bound arm near vertical', () => {
const rig = makeGltfRig(makeTPoseScene());
rig.applyPose(poseFromMannequinPreset(getPresetById('hands-up').pose));
for (const side of ['Left', 'Right']) {
const dir = limbDir(rig, `${side}Arm`, `${side}ForeArm`);
// z = ±PI·0.92 from hanging ⇒ 14.4° short of straight up, tilted out.
expect(dir.y, side).toBeGreaterThan(0.9);
}
});
it('salute preset drops the non-saluting arm to the side (not left at T)', () => {
const rig = makeGltfRig(makeTPoseScene());
rig.applyPose(poseFromMannequinPreset(getPresetById('salute').pose));
const dir = limbDir(rig, 'LeftArm', 'LeftForeArm');
// shoulderL z = 0.09 ⇒ hanging nearly straight down.
expect(dir.y).toBeLessThan(-0.95);
});
it('relaxed stand brings both T-bound arms down with a soft elbow bend', () => {
const rig = makeGltfRig(makeTPoseScene());
rig.applyPose(poseFromMannequinPreset(getPresetById('relaxed').pose));
for (const side of ['Left', 'Right']) {
expect(limbDir(rig, `${side}Arm`, `${side}ForeArm`).y, side).toBeLessThan(-0.9);
expect(limbDir(rig, `${side}ForeArm`, `${side}Hand`).y, side).toBeLessThan(-0.85);
}
});
it('legs already bound straight stay put under standing presets', () => {
const rig = makeGltfRig(makeTPoseScene());
rig.applyPose(poseFromMannequinPreset(getPresetById('hands-up').pose));
expect(limbDir(rig, 'LeftUpLeg', 'LeftLeg').y).toBeLessThan(-0.99);
});
it('resetPose restores the bind pose after a preset (no skinned mesh needed)', () => {
const rig = makeGltfRig(makeBoundScene());
const bind = {};
for (const { key, node } of rig.getBones()) bind[key] = node.quaternion.clone();
rig.applyPose(poseFromMannequinPreset(getPresetById('salute').pose));
rig.resetPose();
for (const { key, node } of rig.getBones()) {
expect(node.quaternion.angleTo(bind[key]), key).toBeLessThan(1e-6);
}
});
it('applying one preset after another never compounds (applyPose resets first)', () => {
const rig = makeGltfRig(makeBoundScene());
rig.applyPose(poseFromMannequinPreset(getPresetById('hands-on-hips').pose));
const once = worldQuat(rig.getNode('RightArm'));
rig.applyPose(poseFromMannequinPreset(getPresetById('salute').pose));
rig.applyPose(poseFromMannequinPreset(getPresetById('hands-on-hips').pose));
expect(worldQuat(rig.getNode('RightArm')).angleTo(once)).toBeLessThan(1e-6);
});
});
describe('GLB FK slider semantics (delta from rest)', () => {
it('an untouched bone reads 0/0/0 even with a large bind rotation', () => {
const rig = makeGltfRig(makeBoundScene());
const e = rig.getBoneEuler('RightShoulder');
expect(Math.abs(e.x)).toBeLessThan(1e-6);
expect(Math.abs(e.y)).toBeLessThan(1e-6);
expect(Math.abs(e.z)).toBeLessThan(1e-6);
});
it('setBoneEuler(0,0,0) restores rest instead of erasing the bind rotation', () => {
const rig = makeGltfRig(makeBoundScene());
const node = rig.getNode('RightArm');
const bind = node.quaternion.clone();
rig.setBoneEuler('RightArm', { x: 0.5, y: -0.2, z: 0.8 });
expect(node.quaternion.angleTo(bind)).toBeGreaterThan(0.1);
rig.setBoneEuler('RightArm', { x: 0, y: 0, z: 0 });
expect(node.quaternion.angleTo(bind)).toBeLessThan(1e-6);
});
it('get/setBoneEuler round-trip through the world-delta frame', () => {
const rig = makeGltfRig(makeBoundScene());
rig.setBoneEuler('LeftForeArm', { x: -1.2, y: 0.3, z: 0.1 });
const e = rig.getBoneEuler('LeftForeArm');
expect(e.x).toBeCloseTo(-1.2, 5);
expect(e.y).toBeCloseTo(0.3, 5);
expect(e.z).toBeCloseTo(0.1, 5);
});
});
describe('presets on committed real avatars', () => {
// michelle.glb / xbot.glb are Mixamo-derived: their skins' inverse-bind
// matrices are in a cm-scale frame, so a resetPose built on skeleton.pose()
// collapses the avatar to 1% scale (it vanished in the studio). Rest must
// come from the node transforms at load, never from the skin's bind frame.
for (const name of ['michelle', 'cz', 'xbot', 'realistic-male']) {
it(`${name}.glb keeps its size and raises its arms for the cheer preset`, () => {
const { root } = loadBoneGraph(avatarPath(name));
const rig = makeGltfRig(root);
expect(rig, name).toBeTruthy();
root.updateMatrixWorld(true);
const hipsBefore = rig.getNode('Hips').getWorldPosition(new Vector3());
rig.applyPose(poseFromMannequinPreset(getPresetById('hands-up').pose));
root.updateMatrixWorld(true);
const hipsAfter = rig.getNode('Hips').getWorldPosition(new Vector3());
// The figure must stay where (and how big) it was — no bind-frame collapse.
expect(hipsAfter.distanceTo(hipsBefore), name).toBeLessThan(0.05 * Math.max(1, hipsBefore.length()));
for (const side of ['Left', 'Right']) {
expect(limbDir(rig, `${side}Arm`, `${side}ForeArm`).y, `${name} ${side}`).toBeGreaterThan(0.85);
}
// And resetPose returns to the loaded stance, same scale.
rig.resetPose();
root.updateMatrixWorld(true);
expect(rig.getNode('Hips').getWorldPosition(new Vector3()).distanceTo(hipsBefore), name)
.toBeLessThan(1e-6 + 0.001 * hipsBefore.length());
});
}
});
describe('localTargetsForPose', () => {
it('returns targets only for posed bones and leaves the rig unposed', () => {
const rig = makeGltfRig(makeBoundScene());
const before = {};
for (const { key, node } of rig.getBones()) before[key] = node.quaternion.clone();
const pose = poseFromMannequinPreset(getPresetById('wave').pose);
const targets = rig.localTargetsForPose(pose);
// wave poses LeftArm, RightArm, RightForeArm, RightHand and Head; this
// test rig has no Head bone, so it must be skipped, not invented.
expect(new Set(targets.keys())).toEqual(
new Set(['LeftArm', 'RightArm', 'RightForeArm', 'RightHand']),
);
for (const { key, node } of rig.getBones()) {
expect(node.quaternion.angleTo(before[key]), key).toBeLessThan(1e-6);
}
// And the targets match what applyPose would produce.
rig.applyPose(pose);
for (const [key, to] of targets) {
expect(rig.getNode(key).quaternion.angleTo(to), key).toBeLessThan(1e-6);
}
});
});