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
/**
* Procedural animation layer (src/procedural/): unit tests.
*
* Everything runs on synthetic in-memory Bone chains, no fixtures. The solver
* tests assert millimetre-level placement; the controller tests assert the
* observable contracts (clamps, fade-out, terrain adaptation, animated-pose
* preservation) rather than exact quaternion values, since the controllers
* damp toward their goals over simulated frames.
*/
import { describe, it, expect } from 'vitest';
import {
Bone,
BufferGeometry,
Float32BufferAttribute,
Group,
Quaternion,
Skeleton,
SkinnedMesh,
Vector3,
} from 'three';
import { solveTwoBoneIK } from '../src/procedural/two-bone-ik.js';
import { LookAtController } from '../src/procedural/look-at.js';
import { FootPlantController } from '../src/procedural/foot-plant.js';
import { canonicalBoneNodes } from '../src/procedural/canonical-bones.js';
// A hip->knee->ankle chain hanging straight down from a root group at hip
// height, knee pre-bent slightly forward (+Z) like every real locomotion pose,
// so the solver has a bend plane to work with.
function makeLeg({ hipY = 1, thigh = 0.5, shin = 0.5, preBend = 0.05 } = {}) {
const root = new Group();
const hip = new Bone();
hip.name = 'RightUpLeg';
hip.position.set(0, hipY, 0);
const knee = new Bone();
knee.name = 'RightLeg';
knee.position.set(0, -thigh, preBend);
const ankle = new Bone();
ankle.name = 'RightFoot';
ankle.position.set(0, -shin, preBend);
root.add(hip);
hip.add(knee);
knee.add(ankle);
root.updateWorldMatrix(true, true);
return { root, hip, knee, ankle };
}
// A minimal humanoid torso + legs, canonical bone names, one metre tall-ish.
function makeHumanoid() {
const model = new Group();
const hips = new Bone();
hips.name = 'Hips';
hips.position.set(0, 0.95, 0);
const spine = new Bone();
spine.name = 'Spine';
spine.position.set(0, 0.1, 0);
const spine2 = new Bone();
spine2.name = 'Spine2';
spine2.position.set(0, 0.2, 0);
const neck = new Bone();
neck.name = 'Neck';
neck.position.set(0, 0.15, 0);
const head = new Bone();
head.name = 'Head';
head.position.set(0, 0.1, 0);
model.add(hips);
hips.add(spine);
spine.add(spine2);
spine2.add(neck);
neck.add(head);
for (const side of ['Left', 'Right']) {
const x = side === 'Left' ? 0.1 : -0.1;
const up = new Bone();
up.name = `${side}UpLeg`;
up.position.set(x, -0.05, 0);
const leg = new Bone();
leg.name = `${side}Leg`;
leg.position.set(0, -0.45, 0.02);
const foot = new Bone();
foot.name = `${side}Foot`;
foot.position.set(0, -0.45, 0.02);
hips.add(up);
up.add(leg);
leg.add(foot);
}
model.updateWorldMatrix(true, true);
return model;
}
function headForwardModelSpace(model) {
const head = model.getObjectByName('Head');
const q = new Quaternion();
head.getWorldQuaternion(q);
const modelQ = new Quaternion();
model.getWorldQuaternion(modelQ);
return new Vector3(0, 0, 1).applyQuaternion(q).applyQuaternion(modelQ.invert());
}
// Run a controller for enough simulated 60fps frames that damping converges.
function settle(controller, frames = 120) {
for (let i = 0; i < frames; i++) controller.update(1 / 60);
}
// A rig whose bones are reachable ONLY through `skeleton.bones` — the armature
// is not parented under the model root. GLBs that export the armature beside
// the mesh, and SkeletonUtils clones, both produce this shape, and it is what
// every NPC in the walkaround world turned out to look like.
function makeDetachedArmatureRig() {
const root = new Group();
const bone = (name) => Object.assign(new Bone(), { name });
const hips = bone('Hips');
const spine = bone('Spine');
const spine2 = bone('Spine2');
const neck = bone('Neck');
const head = bone('Head');
spine.position.y = 0.1;
spine2.position.y = 0.2;
neck.position.y = 0.15;
head.position.y = 0.1;
hips.add(spine);
spine.add(spine2);
spine2.add(neck);
neck.add(head);
const bones = [hips, spine, spine2, neck, head];
for (const side of ['Left', 'Right']) {
const up = bone(`${side}UpLeg`);
const leg = bone(`${side}Leg`);
const foot = bone(`${side}Foot`);
up.position.set(side === 'Left' ? 0.1 : -0.1, -0.05, 0);
leg.position.set(0, -0.45, 0.02);
foot.position.set(0, -0.45, 0.02);
hips.add(up);
up.add(leg);
leg.add(foot);
bones.push(up, leg, foot);
}
hips.position.y = 0.95;
const geo = new BufferGeometry();
geo.setAttribute('position', new Float32BufferAttribute([0, 0, 0], 3));
geo.setAttribute('skinIndex', new Float32BufferAttribute([0, 0, 0, 0], 4));
geo.setAttribute('skinWeight', new Float32BufferAttribute([1, 0, 0, 0], 4));
const mesh = new SkinnedMesh(geo);
mesh.bind(new Skeleton(bones));
root.add(mesh); // the MESH is under root; the bone tree is not
root.updateWorldMatrix(true, true);
return root;
}
describe('canonical bone resolution', () => {
// Regression: the layers used to resolve canonical names to bone *names* and
// then call model.getObjectByName(), which only searches descendants of the
// root. Every rig with a detached armature therefore reported enabled=false
// and silently did nothing — the failure mode that shipped gaze to the walk
// world's NPCs with no effect.
it('finds bones reachable only through skeleton.bones', () => {
const nodes = canonicalBoneNodes(makeDetachedArmatureRig());
expect(nodes.get('Head')?.name).toBe('Head');
expect(nodes.get('LeftFoot')?.name).toBe('LeftFoot');
});
it('getObjectByName cannot find them, which is why node resolution exists', () => {
expect(makeDetachedArmatureRig().getObjectByName('Head')).toBeUndefined();
});
it('LookAtController is enabled on a detached-armature rig', () => {
const ctl = new LookAtController(makeDetachedArmatureRig());
expect(ctl.enabled).toBe(true);
expect(ctl.headBone?.name).toBe('Head');
});
it('FootPlantController is enabled on a detached-armature rig', () => {
expect(new FootPlantController(makeDetachedArmatureRig(), () => 0).enabled).toBe(true);
});
it('and the gaze actually turns that rig', () => {
const root = makeDetachedArmatureRig();
const ctl = new LookAtController(root);
ctl.setTarget(new Vector3(2, 1.5, 2));
settle(ctl);
const head = ctl.headBone;
head.updateWorldMatrix(true, false);
const q = new Quaternion();
head.getWorldQuaternion(q);
const fwd = new Vector3(0, 0, 1).applyQuaternion(q);
expect(fwd.x).toBeGreaterThan(0.25);
});
});
describe('solveTwoBoneIK', () => {
it('places the tip on a reachable target', () => {
const { hip, knee, ankle } = makeLeg();
const target = new Vector3(0.15, 0.35, 0.1);
const ok = solveTwoBoneIK(hip, knee, ankle, target, {
pole: new Vector3(0, 0.5, 1),
});
expect(ok).toBe(true);
const tip = ankle.getWorldPosition(new Vector3());
expect(tip.distanceTo(target)).toBeLessThan(1e-3);
});
it('preserves bone lengths through the solve', () => {
const { hip, knee, ankle } = makeLeg();
const before = {
thigh: hip.getWorldPosition(new Vector3()).distanceTo(knee.getWorldPosition(new Vector3())),
shin: knee.getWorldPosition(new Vector3()).distanceTo(ankle.getWorldPosition(new Vector3())),
};
solveTwoBoneIK(hip, knee, ankle, new Vector3(0.2, 0.5, 0.15), {
pole: new Vector3(0, 0.5, 1),
});
const after = {
thigh: hip.getWorldPosition(new Vector3()).distanceTo(knee.getWorldPosition(new Vector3())),
shin: knee.getWorldPosition(new Vector3()).distanceTo(ankle.getWorldPosition(new Vector3())),
};
expect(after.thigh).toBeCloseTo(before.thigh, 6);
expect(after.shin).toBeCloseTo(before.shin, 6);
});
it('extends toward an out-of-reach target without exploding', () => {
const { hip, knee, ankle } = makeLeg();
const target = new Vector3(0, -5, 0); // 5m below a 1m leg
const ok = solveTwoBoneIK(hip, knee, ankle, target, {
pole: new Vector3(0, 0.5, 1),
});
expect(ok).toBe(true);
const hipPos = hip.getWorldPosition(new Vector3());
const tip = ankle.getWorldPosition(new Vector3());
// Chain is nearly fully extended (softness caps at 98% of 1m reach)...
expect(hipPos.distanceTo(tip)).toBeGreaterThan(0.95);
expect(hipPos.distanceTo(tip)).toBeLessThan(1.0);
// ...and points at the target.
const dir = tip.sub(hipPos).normalize();
const want = target.clone().sub(hipPos).normalize();
expect(dir.dot(want)).toBeGreaterThan(0.999);
});
it('bends the knee toward the pole target', () => {
const { hip, knee, ankle } = makeLeg();
// Crouch: target well above full extension forces a deep bend.
const target = new Vector3(0, 0.4, 0);
const pole = new Vector3(0, 0.7, 2); // knee should point forward (+Z)
solveTwoBoneIK(hip, knee, ankle, target, { pole });
const kneePos = knee.getWorldPosition(new Vector3());
const hipPos = hip.getWorldPosition(new Vector3());
const tip = ankle.getWorldPosition(new Vector3());
// Knee sits forward of the hip-ankle line, on the pole's side.
const mid = hipPos.clone().add(tip).multiplyScalar(0.5);
expect(kneePos.z - mid.z).toBeGreaterThan(0.05);
expect(tip.distanceTo(target)).toBeLessThan(1e-3);
});
it('rejects a degenerate zero-length chain', () => {
const root = new Group();
const a = new Bone();
const b = new Bone();
const c = new Bone();
root.add(a);
a.add(b); // b at a's origin: zero-length bone
b.add(c);
root.updateWorldMatrix(true, true);
expect(solveTwoBoneIK(a, b, c, new Vector3(1, 1, 1))).toBe(false);
});
it('solves from a perfectly straight chain using the pole to pick the bend plane', () => {
const { hip, knee, ankle } = makeLeg({ preBend: 0 });
const target = new Vector3(0, 0.5, 0); // requires bending
const ok = solveTwoBoneIK(hip, knee, ankle, target, {
pole: new Vector3(0, 0.7, 2),
});
expect(ok).toBe(true);
const tip = ankle.getWorldPosition(new Vector3());
expect(tip.distanceTo(target)).toBeLessThan(1e-3);
// Bend went toward the pole (+Z), not backwards.
expect(knee.getWorldPosition(new Vector3()).z).toBeGreaterThan(0);
});
});
describe('LookAtController', () => {
it('is disabled on a rig with no head', () => {
const model = new Group();
const box = new Bone();
box.name = 'RandomProp';
model.add(box);
const ctl = new LookAtController(model);
expect(ctl.enabled).toBe(false);
expect(() => ctl.update(1 / 60)).not.toThrow();
});
it('turns the head toward a side target within the yaw clamp', () => {
const model = makeHumanoid();
const ctl = new LookAtController(model);
expect(ctl.enabled).toBe(true);
// Target off to the avatar's left (+X), slightly above head height.
ctl.setTarget(new Vector3(1.2, 1.6, 1.2));
settle(ctl);
const fwd = headForwardModelSpace(model);
// Head yawed toward +X...
expect(fwd.x).toBeGreaterThan(0.3);
// ...but still mostly forward (chain shares + clamps, never a 90deg snap).
expect(fwd.z).toBeGreaterThan(0.4);
});
it('clamps an extreme side target instead of spinning the neck', () => {
const model = makeHumanoid();
const ctl = new LookAtController(model);
ctl.setTarget(new Vector3(50, 1.4, 1)); // nearly 90deg to the side
settle(ctl);
const fwd = headForwardModelSpace(model);
const yaw = Math.atan2(fwd.x, fwd.z);
expect(yaw).toBeLessThanOrEqual(ctl.maxYaw + 0.02);
});
it('fades out for a target behind the avatar', () => {
const model = makeHumanoid();
const ctl = new LookAtController(model);
ctl.setTarget(new Vector3(0, 1.4, -3)); // directly behind
settle(ctl);
const fwd = headForwardModelSpace(model);
// The layer refused the behind target: still facing forward.
expect(fwd.z).toBeGreaterThan(0.98);
});
it('returns to the base pose after the target clears', () => {
const model = makeHumanoid();
const ctl = new LookAtController(model);
ctl.setTarget(new Vector3(2, 1.4, 1));
settle(ctl);
expect(Math.abs(headForwardModelSpace(model).x)).toBeGreaterThan(0.2);
// The mixer contract: bone locals are rewritten each frame. Simulate by
// restoring rest locals before each update, then let the fade drain.
const head = model.getObjectByName('Head');
const neck = model.getObjectByName('Neck');
const spine2 = model.getObjectByName('Spine2');
ctl.setTarget(null);
for (let i = 0; i < 240; i++) {
head.quaternion.identity();
neck.quaternion.identity();
spine2.quaternion.identity();
ctl.update(1 / 60);
}
const fwd = headForwardModelSpace(model);
expect(Math.abs(fwd.x)).toBeLessThan(0.02);
expect(fwd.z).toBeGreaterThan(0.999);
});
it('respects the model root rotation when aiming', () => {
const model = makeHumanoid();
model.rotation.y = Math.PI / 2; // model already faces +X
model.updateWorldMatrix(true, true);
const ctl = new LookAtController(model);
// Target dead ahead of the ROTATED model: no head turn should remain.
ctl.setTarget(new Vector3(3, 1.4, 0));
settle(ctl);
const fwd = headForwardModelSpace(model);
expect(fwd.z).toBeGreaterThan(0.99); // model-space forward, unturned
});
});
describe('FootPlantController', () => {
it('is disabled without a leg chain or ground sampler', () => {
const model = new Group();
const prop = new Bone();
prop.name = 'Prop';
model.add(prop);
expect(new FootPlantController(model, () => 0).enabled).toBe(false);
expect(new FootPlantController(makeHumanoid(), null).enabled).toBe(false);
});
it('keeps a flat-ground pose untouched', () => {
const model = makeHumanoid();
const ctl = new FootPlantController(model, () => 0);
expect(ctl.enabled).toBe(true);
const before = model.getObjectByName('Hips').position.y;
const footBefore = model
.getObjectByName('LeftFoot')
.getWorldPosition(new Vector3());
settle(ctl);
expect(model.getObjectByName('Hips').position.y).toBeCloseTo(before, 4);
const footAfter = model
.getObjectByName('LeftFoot')
.getWorldPosition(new Vector3());
expect(footAfter.distanceTo(footBefore)).toBeLessThan(1e-3);
});
it('drops the pelvis and reaches the downhill foot on a slope', () => {
const model = makeHumanoid();
// Terrain: left side (x > 0) is 0.15m lower than under the origin.
const ground = (x) => (x > 0.05 ? -0.15 : 0);
const ctl = new FootPlantController(model, ground);
const hipsBefore = model.getObjectByName('Hips').position.y;
const leftBefore = model
.getObjectByName('LeftFoot')
.getWorldPosition(new Vector3());
const rightBefore = model
.getObjectByName('RightFoot')
.getWorldPosition(new Vector3());
// The mixer contract: restore animated locals each frame, then update.
const rest = new Map();
model.traverse((n) => {
if (n.isBone) rest.set(n, { q: n.quaternion.clone(), p: n.position.clone() });
});
for (let i = 0; i < 240; i++) {
for (const [bone, r] of rest) {
bone.quaternion.copy(r.q);
bone.position.copy(r.p);
}
ctl.update(1 / 60);
}
// Pelvis sank toward the downhill delta.
expect(model.getObjectByName('Hips').position.y).toBeLessThan(hipsBefore - 0.1);
model.updateWorldMatrix(true, true);
// Left (downhill) foot followed the pelvis down toward its ground...
const leftAfter = model
.getObjectByName('LeftFoot')
.getWorldPosition(new Vector3());
expect(leftAfter.y).toBeLessThan(leftBefore.y - 0.1);
// ...while the right (level-ground) foot was IK'd back up to its own
// terrain height, not dragged down with the pelvis.
const rightAfter = model
.getObjectByName('RightFoot')
.getWorldPosition(new Vector3());
expect(Math.abs(rightAfter.y - rightBefore.y)).toBeLessThan(0.03);
});
it('preserves the animated foot orientation through the solve', () => {
const model = makeHumanoid();
const foot = model.getObjectByName('RightFoot');
const ground = (x) => (x < -0.05 ? -0.2 : 0);
const ctl = new FootPlantController(model, ground);
const beforeQ = foot.getWorldQuaternion(new Quaternion());
const rest = new Map();
model.traverse((n) => {
if (n.isBone) rest.set(n, { q: n.quaternion.clone(), p: n.position.clone() });
});
for (let i = 0; i < 240; i++) {
for (const [bone, r] of rest) {
bone.quaternion.copy(r.q);
bone.position.copy(r.p);
}
ctl.update(1 / 60);
}
model.updateWorldMatrix(true, true);
const afterQ = foot.getWorldQuaternion(new Quaternion());
expect(Math.abs(beforeQ.angleTo(afterQ))).toBeLessThan(0.03);
});
});