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
// Anatomical anchors: the places on a body a motion can be written against.
//
// A score says "the right hand goes to the chest, a hand's width out and a
// little forward", never an XYZ. Two reasons that matters. It is the only form
// a language model can author reliably, and it survives the body moving: an
// anchor is measured once on the rest skeleton, then carried by whichever bone
// owns it, so "at the chin" is still at the chin after the torso has turned
// forty degrees and the hips have dropped into a crouch.
import { qConj, qRotate, vAdd, vLerp, vScale, vSub } from './math.js';
import {
ARM_REACH,
BODY_FORWARD,
BODY_LEFT,
BODY_UP,
GROUND_Y,
SHOULDER_SPAN,
hasBone,
restPos,
restWorld,
} from './skeleton.js';
const head = restPos('Head');
const neck = restPos('Neck');
const chest = restPos('Spine2');
const waist = restPos('Spine');
const hips = restPos('Hips');
const shoulderL = restPos('LeftArm');
const shoulderR = restPos('RightArm');
const chinY = neck[1] + (head[1] - neck[1]) * 0.55;
// Half the shoulder span: the lateral unit every side-aware anchor is placed in.
const halfSpan = SHOULDER_SPAN / 2;
// How far below the shoulder a wrist hangs on a relaxed arm: not quite the full
// reach, so the elbow keeps a soft bend instead of locking.
const hang = ARM_REACH * 0.94;
const lateral = (metres) => vScale(BODY_LEFT, metres);
const ahead = (metres) => vScale(BODY_FORWARD, metres);
const above = (metres) => vScale(BODY_UP, metres);
/**
* Every anchor, in model space on the reference rig. Side-aware anchors are an
* object keyed by side; `anchorPoint` picks the one matching the acting limb.
*/
export const ANCHORS = Object.freeze({
head,
forehead: vAdd(head, above(0.07)),
crown: vAdd(head, above(0.14)),
temple: { Left: vAdd(head, vAdd(lateral(0.09), above(0.03))), Right: vAdd(head, vAdd(lateral(-0.09), above(0.03))) },
nose: vAdd(head, vAdd(above(0.02), ahead(0.05))),
mouth: vAdd([0, chinY + 0.04, head[2]], ahead(0.04)),
chin: vAdd([0, chinY, head[2]], ahead(0.03)),
neck,
// Upper chest, where most gesturing lives. Measured up from the chest bone
// toward the neck: the bone itself sits at mid-torso, and anchoring there
// hangs every gesture at belly height.
sternum: vAdd([0, chest[1] + (neck[1] - chest[1]) * 0.6, chest[2]], ahead(0.02)),
chest: [0, chest[1], chest[2]],
heart: vAdd([0, chest[1] + (neck[1] - chest[1]) * 0.4, chest[2]], lateral(0.06)),
belly: [0, (chest[1] + hips[1]) / 2, waist[2]],
waist: [0, waist[1], waist[2]],
hips,
shoulder: { Left: shoulderL, Right: shoulderR },
/**
* Hands on hips. Placed at the iliac crest rather than the hip joint, which
* is both where hands actually go and inside the arm's reach; the joint
* itself is a few centimetres past a wrist's range on a real skeleton.
*/
hip: {
Left: vAdd(hips, vAdd(lateral(halfSpan * 0.6), above(0.06))),
Right: vAdd(hips, vAdd(lateral(-halfSpan * 0.6), above(0.06))),
},
/**
* Arms hanging: where a relaxed wrist sits beside the thigh. Measured DOWN
* FROM THE SHOULDER by the arm's own length, not up from the hips, so it is
* always a place the arm can actually reach.
*/
side: {
Left: vAdd(shoulderL, vAdd(above(-hang), vAdd(lateral(0.02), ahead(0.02)))),
Right: vAdd(shoulderR, vAdd(above(-hang), vAdd(lateral(-0.02), ahead(0.02)))),
},
/** Straight out in front at chest height: the offering, pointing, handshake zone. */
front: vAdd([0, chest[1] + 0.06, chest[2]], ahead(0.34)),
/** Out to the side at shoulder height: the presenting, shrugging zone. */
wide: {
Left: vAdd(shoulderL, vAdd(lateral(0.3), ahead(0.08))),
Right: vAdd(shoulderR, vAdd(lateral(-0.3), ahead(0.08))),
},
/** Arm raised: hailing, waving, celebrating. */
overhead: {
Left: vAdd(shoulderL, vAdd(above(0.42), lateral(0.06))),
Right: vAdd(shoulderR, vAdd(above(0.42), lateral(-0.06))),
},
/** Behind the hip: reaching back, hands clasped behind. */
behind: {
Left: vAdd(shoulderL, vAdd(above(-hang * 0.86), vAdd(lateral(-0.02), ahead(-hang * 0.42)))),
Right: vAdd(shoulderR, vAdd(above(-hang * 0.86), vAdd(lateral(0.02), ahead(-hang * 0.42)))),
},
/**
* On the thigh, a little under a third of the way from hip to knee: where a hand actually
* rests when someone sits down or leans on their legs. The knee itself is
* past a wrist's reach on a human skeleton, which is why hands go here.
*/
thigh: {
Left: vLerp(restPos('LeftUpLeg'), restPos('LeftLeg'), 0.28),
Right: vLerp(restPos('RightUpLeg'), restPos('RightLeg'), 0.28),
},
/** The knee joint itself: a place to look at, or to reach for in a crouch. */
knee: {
Left: vAdd(restPos('LeftLeg'), ahead(0.12)),
Right: vAdd(restPos('RightLeg'), ahead(0.12)),
},
/** On the floor in front of the feet. */
floor: vAdd([0, GROUND_Y + 0.05, 0], ahead(0.28)),
});
// Which bone carries each anchor, so the anchor follows the body. Anything not
// listed rides the chest, which is the right default for gesture space.
const ANCHOR_BONE = Object.freeze({
head: 'Head',
forehead: 'Head',
crown: 'Head',
temple: 'Head',
nose: 'Head',
mouth: 'Head',
chin: 'Head',
neck: 'Neck',
sternum: 'Spine2',
chest: 'Spine2',
heart: 'Spine2',
front: 'Spine2',
wide: 'Spine2',
overhead: 'Spine2',
belly: 'Spine',
waist: 'Spine',
hips: 'Hips',
hip: 'Hips',
side: 'Spine2',
behind: 'Spine2',
knee: { Left: 'LeftLeg', Right: 'RightLeg' },
thigh: { Left: 'LeftUpLeg', Right: 'RightUpLeg' },
shoulder: 'Spine2',
// The floor does not follow the body: that is what makes it the floor.
floor: null,
});
/** Every anchor name a score may use. */
export const ANCHOR_NAMES = Object.freeze(Object.keys(ANCHORS).sort());
/**
* Resolve an anchor plus a body-relative offset to a point on the REST
* skeleton. Offsets are in metres: `out` moves away from the body's midline on
* the acting side, `up` and `forward` do what they say.
*
* @param {string|number[]} anchor an ANCHORS key, or an explicit model-space point
* @param {{ out?: number, up?: number, forward?: number, side?: 'Left'|'Right' }} [offset]
* @returns {number[]} model-space point on the rest skeleton
*/
export function restAnchor(anchor, offset = {}) {
const side = offset.side ?? 'Right';
let base = Array.isArray(anchor) ? anchor : ANCHORS[anchor];
if (base && !Array.isArray(base)) base = base[side];
if (!base) throw new Error(`unknown motion anchor "${anchor}"`);
const out = side === 'Left' ? (offset.out ?? 0) : -(offset.out ?? 0);
return vAdd(
base,
vAdd(lateral(out), vAdd(above(offset.up ?? 0), ahead(offset.forward ?? 0))),
);
}
/**
* The same anchor, but placed on a POSED body: the rest point is expressed in
* its carrier bone's frame and re-read through that bone's current rotation and
* position. This is what keeps a hand target at the chin when the head turns.
*
* @param {import('./pose.js').Pose} pose
* @param {string|number[]} anchor
* @param {{ out?: number, up?: number, forward?: number, side?: 'Left'|'Right' }} [offset]
* @returns {number[]} model-space point on the posed skeleton
*/
export function anchorPoint(pose, anchor, offset = {}) {
const rest = restAnchor(anchor, offset);
let bone = Array.isArray(anchor) ? null : ANCHOR_BONE[anchor];
// A side-keyed carrier: the knee anchor rides whichever knee it belongs to.
if (bone && typeof bone === 'object') bone = bone[offset.side ?? 'Right'];
if (!bone || !hasBone(bone)) {
// An unattached anchor still rides the root, so a body that walks forward
// carries its gesture space with it, but a floor anchor stays on the floor.
if (anchor === 'floor') return vAdd(rest, [pose.rootOffset[0], 0, pose.rootOffset[2]]);
return vAdd(rest, pose.rootOffset);
}
const local = qRotate(qConj(restWorld(bone)), vSub(rest, restPos(bone)));
return vAdd(pose.worldPos(bone), qRotate(pose.worldQuat(bone), local));
}
/**
* A body-relative direction resolved against the POSED chest, so "palm forward"
* means forward for the body rather than forward for the world.
*
* @param {import('./pose.js').Pose} pose
* @param {string} name one of the DIRECTION keys
* @param {'Left'|'Right'} [side]
* @returns {number[]} unit world direction
*/
export function bodyDirection(pose, name, side = 'Right') {
const local = DIRECTIONS[name];
if (!local) throw new Error(`unknown motion direction "${name}"`);
const bone = hasBone('Spine2') ? 'Spine2' : 'Hips';
const mirrored = side === 'Right' && MIRRORED_DIRECTIONS.has(name)
? vScale(local, -1)
: local;
return qRotate(pose.worldQuat(bone), qRotate(qConj(restWorld(bone)), mirrored));
}
/** Named directions in the body's own frame, for palms, gaze, and pointing. */
export const DIRECTIONS = Object.freeze({
forward: BODY_FORWARD,
back: vScale(BODY_FORWARD, -1),
up: BODY_UP,
down: vScale(BODY_UP, -1),
/** Across the body toward the other side. Mirrored per acting hand. */
in: BODY_LEFT,
/** Away from the body on the acting side. Mirrored per acting hand. */
out: vScale(BODY_LEFT, -1),
left: BODY_LEFT,
right: vScale(BODY_LEFT, -1),
});
// `in` and `out` are relative to the acting hand; the rest are absolute for the
// body, so a score can say "palm left" and mean the body's left on either hand.
const MIRRORED_DIRECTIONS = new Set(['in', 'out']);
/** A hand's width on the reference rig: the unit small offsets are written in. */
export const HAND_WIDTH = SHOULDER_SPAN * 0.22;