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
// The Motion Score: the wire format between whatever decided what should happen
// and the solver that makes a body do it.
//
// A score is a list of beats. A beat is a body at one instant plus how long it
// takes to get there and how long it stays. Everything in it is anatomy and
// timing, nothing is a bone name or a quaternion, which is what lets a language
// model author one, a person edit one by hand, and a diff of two of them be
// readable.
//
// Validation is deliberately forgiving in one direction and strict in the
// other. Anything a caller can reasonably mean is accepted and normalized
// (a bare string where an object is allowed, degrees out of range, beats out of
// order); anything ambiguous is an error with the path that caused it, because
// a score that half-parses produces a body that half-moves, and that is worse
// than a rejection.
import {
EASES,
EFFORTS,
ELBOW_POLES,
EXPRESSIONS,
GAZES,
HAND_SHAPES,
POSTURES,
STANCES,
} from './vocabulary.js';
import { ANCHOR_NAMES, DIRECTIONS } from './rig/anchors.js';
import { PLANT_TILT } from './rig/ik.js';
/** The score format version this build reads and writes. */
export const MOTION_SCORE_VERSION = 1;
/** Hard bounds, so a malformed score cannot ask for an hour-long clip. */
export const LIMITS = Object.freeze({
maxBeats: 64,
/**
* A clip shorter than this has nowhere to put the idle layer and nothing for
* a mixer to interpolate, so a score of one held beat is extended to it.
*/
minDuration: 0.8,
maxDuration: 60,
maxBeatSeconds: 12,
minBeatSeconds: 0.02,
maxNameLength: 120,
maxOffset: 1.2,
maxAngle: 180,
});
const SIDES = ['left', 'right'];
const PLANTS = Object.keys(PLANT_TILT);
const num = (v) => typeof v === 'number' && Number.isFinite(v);
const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
class ScoreError extends Error {
constructor(path, message) {
super(`${path}: ${message}`);
this.path = path;
this.name = 'ScoreError';
}
}
/**
* Validate and normalize a score. Returns the normalized score, or throws a
* ScoreError naming the exact path that failed.
*
* Normalizing means: every beat carries an absolute `at`, an `in`, a `hold` and
* a resolved `effort`; every shorthand is expanded to its object form; every
* angle and offset is inside its limit. After this, the solver never has to ask
* whether a field is present.
*
* @param {object} input
* @returns {object} the normalized score
*/
export function normalizeScore(input) {
if (!input || typeof input !== 'object') throw new ScoreError('score', 'must be an object');
const version = input.version ?? MOTION_SCORE_VERSION;
if (version !== MOTION_SCORE_VERSION) {
throw new ScoreError('score.version', `unsupported version ${version}, this build reads ${MOTION_SCORE_VERSION}`);
}
const name = typeof input.name === 'string' && input.name.trim()
? input.name.trim().slice(0, LIMITS.maxNameLength)
: 'motion';
const beatsIn = Array.isArray(input.beats) ? input.beats : null;
if (!beatsIn || !beatsIn.length) throw new ScoreError('score.beats', 'must be a non-empty array');
if (beatsIn.length > LIMITS.maxBeats) {
throw new ScoreError('score.beats', `at most ${LIMITS.maxBeats} beats, got ${beatsIn.length}`);
}
const defaultEffort = resolveEffort(input.effort, 'score.effort') ?? { ...EFFORTS.neutral };
let clock = 0;
const beats = beatsIn.map((raw, i) => {
const path = `score.beats[${i}]`;
if (!raw || typeof raw !== 'object') throw new ScoreError(path, 'must be an object');
const effort = resolveEffort(raw.effort, `${path}.effort`) ?? defaultEffort;
// A sudden beat is quicker than a sustained one by default, so timing
// follows effort unless the beat states its own.
const travel = num(raw.in)
? clamp(raw.in, LIMITS.minBeatSeconds, LIMITS.maxBeatSeconds)
: (i === 0 ? 0 : defaultTravel(effort));
const hold = num(raw.hold) ? clamp(raw.hold, 0, LIMITS.maxBeatSeconds) : 0;
const at = num(raw.at) ? Math.max(clock, raw.at) : clock + travel;
clock = at + hold;
if (clock > LIMITS.maxDuration) {
throw new ScoreError(path, `score runs past the ${LIMITS.maxDuration}s limit`);
}
return {
at,
in: travel,
hold,
ease: pickEase(raw.ease, effort, path),
effort,
posture: pickPosture(raw.posture, path),
root: normalizeRoot(raw.root, path),
torso: normalizeTorso(raw.torso, path),
gaze: normalizeGaze(raw.gaze, path),
arms: normalizeArms(raw.arms, path),
legs: normalizeLegs(raw.legs, path),
face: normalizeFace(raw.face, path),
label: typeof raw.label === 'string' ? raw.label.slice(0, LIMITS.maxNameLength) : null,
};
});
// A single beat, or a last beat with no hold, would compile to a clip with no
// length: hold the final shape long enough to be worth playing.
const last = beats[beats.length - 1];
const played = last.at + last.hold;
if (played < LIMITS.minDuration) last.hold += LIMITS.minDuration - played;
return {
version: MOTION_SCORE_VERSION,
name,
seed: typeof input.seed === 'string' && input.seed ? input.seed : name,
loop: input.loop === true,
effort: defaultEffort,
beats,
duration: last.at + last.hold,
};
}
/**
* Validate without throwing. Returns `{ ok, score, error }`, which is what an
* HTTP handler and an LLM repair loop both actually want.
* @param {object} input
*/
export function validateScore(input) {
try {
return { ok: true, score: normalizeScore(input), error: null };
} catch (err) {
return { ok: false, score: null, error: { path: err.path ?? 'score', message: err.message } };
}
}
// A sudden effort covers ground fast. The curve is deliberately not linear in
// `time`: the interesting range for a gesture is the middle.
function defaultTravel(effort) {
return 0.9 - 0.62 * effort.time ** 0.8;
}
function resolveEffort(spec, path) {
if (spec == null) return null;
if (typeof spec === 'string') {
const preset = EFFORTS[spec];
if (!preset) throw new ScoreError(path, `unknown effort "${spec}"`);
return { ...preset };
}
if (typeof spec !== 'object') throw new ScoreError(path, 'must be a name or an object');
const base = spec.preset ? EFFORTS[spec.preset] : EFFORTS.neutral;
if (spec.preset && !base) throw new ScoreError(`${path}.preset`, `unknown effort "${spec.preset}"`);
return {
weight: clamp(num(spec.weight) ? spec.weight : base.weight, 0, 1),
time: clamp(num(spec.time) ? spec.time : base.time, 0, 1),
flow: clamp(num(spec.flow) ? spec.flow : base.flow, 0, 1),
};
}
// With no ease named, effort picks one: sudden and bound snaps, sudden and free
// overshoots, sustained settles.
function pickEase(spec, effort, path) {
if (spec == null) {
if (effort.time > 0.75) return effort.flow > 0.6 ? 'overshoot' : 'snap';
if (effort.time < 0.25) return 'settle';
return 'smooth';
}
if (typeof spec !== 'string' || !EASES[spec]) {
throw new ScoreError(`${path}.ease`, `unknown ease "${spec}"`);
}
return spec;
}
function pickPosture(spec, path) {
if (spec == null) return null;
if (typeof spec !== 'string' || !POSTURES[spec]) {
throw new ScoreError(`${path}.posture`, `unknown posture "${spec}"`);
}
return spec;
}
function normalizeRoot(spec, path) {
if (spec == null) return {};
if (typeof spec !== 'object') throw new ScoreError(`${path}.root`, 'must be an object');
const out = {};
if (spec.height != null) out.height = boundedNumber(spec.height, 0.28, 1.15, `${path}.root.height`);
if (spec.forward != null) out.forward = offset(spec.forward, `${path}.root.forward`);
if (spec.side != null) out.side = offset(spec.side, `${path}.root.side`);
if (spec.rise != null) out.rise = offset(spec.rise, `${path}.root.rise`);
if (spec.turn != null) out.turn = angle(spec.turn, `${path}.root.turn`);
return out;
}
function normalizeTorso(spec, path) {
if (spec == null) return {};
if (typeof spec !== 'object') throw new ScoreError(`${path}.torso`, 'must be an object');
const out = {};
for (const key of ['lean', 'twist', 'sideBend']) {
if (spec[key] != null) out[key] = angle(spec[key], `${path}.torso.${key}`);
}
return out;
}
function normalizeGaze(spec, path) {
if (spec == null) return null;
if (typeof spec === 'string') {
if (!GAZES[spec]) throw new ScoreError(`${path}.gaze`, `unknown gaze "${spec}"`);
return { preset: spec };
}
if (typeof spec !== 'object') throw new ScoreError(`${path}.gaze`, 'must be a name or an object');
const out = {};
if (spec.preset != null) {
if (!GAZES[spec.preset]) throw new ScoreError(`${path}.gaze.preset`, `unknown gaze "${spec.preset}"`);
out.preset = spec.preset;
}
for (const key of ['yaw', 'pitch', 'roll']) {
if (spec[key] != null) out[key] = angle(spec[key], `${path}.gaze.${key}`);
}
return out;
}
function normalizeArms(spec, path) {
if (spec == null) return {};
if (typeof spec !== 'object') throw new ScoreError(`${path}.arms`, 'must be an object');
const out = {};
for (const side of SIDES) {
if (spec[side] == null) continue;
out[side] = normalizeArm(spec[side], `${path}.arms.${side}`);
}
return out;
}
function normalizeArm(spec, path) {
if (typeof spec === 'string') return { at: anchorName(spec, path) };
if (typeof spec !== 'object') throw new ScoreError(path, 'must be an anchor name or an object');
const out = {};
if (spec.at != null) {
if (Array.isArray(spec.at)) {
if (spec.at.length !== 3 || !spec.at.every(num)) {
throw new ScoreError(`${path}.at`, 'an explicit point must be three finite numbers');
}
out.at = [...spec.at];
} else {
out.at = anchorName(spec.at, `${path}.at`);
}
}
for (const key of ['out', 'up', 'forward']) {
if (spec[key] != null) out[key] = offset(spec[key], `${path}.${key}`);
}
if (spec.palm != null) out.palm = directionName(spec.palm, `${path}.palm`);
if (spec.point != null) out.point = directionName(spec.point, `${path}.point`);
if (spec.elbow != null) {
if (typeof spec.elbow !== 'string' || !ELBOW_POLES[spec.elbow]) {
throw new ScoreError(`${path}.elbow`, `unknown elbow "${spec.elbow}"`);
}
out.elbow = spec.elbow;
}
if (spec.hand != null) out.hand = normalizeHand(spec.hand, `${path}.hand`);
return out;
}
function normalizeHand(spec, path) {
if (typeof spec === 'string') {
if (!HAND_SHAPES[spec]) throw new ScoreError(path, `unknown hand shape "${spec}"`);
return { shape: spec };
}
if (typeof spec !== 'object') throw new ScoreError(path, 'must be a shape name or an object');
const out = {};
if (spec.shape != null) {
if (!HAND_SHAPES[spec.shape]) throw new ScoreError(`${path}.shape`, `unknown hand shape "${spec.shape}"`);
out.shape = spec.shape;
}
for (const key of ['curl', 'thumb']) {
if (spec[key] != null) out[key] = boundedNumber(spec[key], 0, 1, `${path}.${key}`);
}
if (spec.spread != null) out.spread = boundedNumber(spec.spread, -1, 1, `${path}.spread`);
return out;
}
function normalizeLegs(spec, path) {
if (spec == null) return {};
if (typeof spec === 'string') return { stance: stanceName(spec, `${path}.legs`) };
if (typeof spec !== 'object') throw new ScoreError(`${path}.legs`, 'must be a stance name or an object');
const out = {};
if (spec.stance != null) out.stance = stanceName(spec.stance, `${path}.legs.stance`);
for (const side of SIDES) {
if (spec[side] == null) continue;
out[side] = normalizeFoot(spec[side], `${path}.legs.${side}`);
}
return out;
}
function normalizeFoot(spec, path) {
if (typeof spec !== 'object' || spec === null) throw new ScoreError(path, 'must be an object');
const out = {};
for (const key of ['out', 'forward', 'lift']) {
if (spec[key] != null) out[key] = offset(spec[key], `${path}.${key}`);
}
if (spec.heading != null) out.heading = angle(spec.heading, `${path}.heading`);
if (spec.plant != null) {
if (typeof spec.plant !== 'string' || !PLANTS.includes(spec.plant)) {
throw new ScoreError(`${path}.plant`, `unknown plant "${spec.plant}", expected one of ${PLANTS.join(', ')}`);
}
out.plant = spec.plant;
}
return out;
}
function normalizeFace(spec, path) {
if (spec == null) return null;
if (typeof spec === 'string') {
if (!EXPRESSIONS[spec]) throw new ScoreError(`${path}.face`, `unknown expression "${spec}"`);
return { [spec]: 1 };
}
if (typeof spec !== 'object') throw new ScoreError(`${path}.face`, 'must be an expression name or an object');
const out = {};
for (const [key, value] of Object.entries(spec)) {
if (!num(value)) throw new ScoreError(`${path}.face.${key}`, 'must be a number');
out[key] = clamp(value, 0, 1);
}
return out;
}
function anchorName(value, path) {
if (typeof value !== 'string' || !ANCHOR_NAMES.includes(value)) {
throw new ScoreError(path, `unknown anchor "${value}"`);
}
return value;
}
function directionName(value, path) {
if (typeof value !== 'string' || !DIRECTIONS[value]) {
throw new ScoreError(path, `unknown direction "${value}"`);
}
return value;
}
function stanceName(value, path) {
if (typeof value !== 'string' || !STANCES[value]) {
throw new ScoreError(path, `unknown stance "${value}"`);
}
return value;
}
function boundedNumber(value, lo, hi, path) {
if (!num(value)) throw new ScoreError(path, 'must be a finite number');
return clamp(value, lo, hi);
}
function offset(value, path) {
return boundedNumber(value, -LIMITS.maxOffset, LIMITS.maxOffset, path);
}
function angle(value, path) {
return boundedNumber(value, -LIMITS.maxAngle, LIMITS.maxAngle, path);
}
/**
* The JSON Schema for a score, for tool-calling and for editors. Generated from
* the same vocabulary the solver reads, so the enums a model is offered can
* never drift from the ones the solver accepts.
* @returns {object}
*/
export function scoreSchema() {
const offsetProp = (description) => ({ type: 'number', minimum: -LIMITS.maxOffset, maximum: LIMITS.maxOffset, description });
const angleProp = (description) => ({ type: 'number', minimum: -LIMITS.maxAngle, maximum: LIMITS.maxAngle, description });
const armProp = {
type: 'object',
additionalProperties: false,
properties: {
at: { type: 'string', enum: [...ANCHOR_NAMES], description: 'anatomical place the wrist goes' },
out: offsetProp('metres away from the midline, on this hand\'s side'),
up: offsetProp('metres above the anchor'),
forward: offsetProp('metres in front of the anchor'),
palm: { type: 'string', enum: Object.keys(DIRECTIONS), description: 'where the palm faces' },
point: { type: 'string', enum: Object.keys(DIRECTIONS), description: 'where the fingers point' },
elbow: { type: 'string', enum: Object.keys(ELBOW_POLES), description: 'where the elbow is pushed' },
hand: { type: 'string', enum: Object.keys(HAND_SHAPES), description: 'hand shape' },
},
};
return {
$schema: 'https://json-schema.org/draft/2020-12/schema',
title: 'Motion Score',
type: 'object',
required: ['beats'],
additionalProperties: false,
properties: {
version: { const: MOTION_SCORE_VERSION },
name: { type: 'string', maxLength: LIMITS.maxNameLength },
seed: { type: 'string', description: 'stable seed; the same seed and score always compile to the same clip' },
loop: { type: 'boolean', description: 'true when the last beat should flow back into the first' },
effort: { type: 'string', enum: Object.keys(EFFORTS), description: 'default performance quality for every beat' },
beats: {
type: 'array',
minItems: 1,
maxItems: LIMITS.maxBeats,
items: {
type: 'object',
additionalProperties: false,
properties: {
label: { type: 'string', description: 'what this beat is, for a human reading the score' },
in: { type: 'number', minimum: LIMITS.minBeatSeconds, maximum: LIMITS.maxBeatSeconds, description: 'seconds to travel into this beat' },
hold: { type: 'number', minimum: 0, maximum: LIMITS.maxBeatSeconds, description: 'seconds to stay here once arrived' },
ease: { type: 'string', enum: Object.keys(EASES) },
effort: { type: 'string', enum: Object.keys(EFFORTS) },
posture: { type: 'string', enum: Object.keys(POSTURES), description: 'whole-body shape this beat starts from' },
root: {
type: 'object',
additionalProperties: false,
properties: {
height: { type: 'number', minimum: 0.28, maximum: 1.15, description: 'hip height as a fraction of standing' },
forward: offsetProp('metres the body travels forward'),
side: offsetProp('metres the body travels to its left'),
rise: offsetProp('metres the whole body leaves the floor'),
turn: angleProp('degrees the body turns toward its left'),
},
},
torso: {
type: 'object',
additionalProperties: false,
properties: {
lean: angleProp('degrees forward, negative leans back'),
twist: angleProp('degrees toward the body\'s left'),
sideBend: angleProp('degrees leaning left, negative right'),
},
},
gaze: { type: 'string', enum: Object.keys(GAZES) },
arms: {
type: 'object',
additionalProperties: false,
properties: { left: armProp, right: armProp },
},
legs: {
type: 'object',
additionalProperties: false,
properties: {
stance: { type: 'string', enum: Object.keys(STANCES) },
left: { type: 'object', additionalProperties: false, properties: footSchema(offsetProp, angleProp) },
right: { type: 'object', additionalProperties: false, properties: footSchema(offsetProp, angleProp) },
},
},
face: { type: 'string', enum: Object.keys(EXPRESSIONS) },
},
},
},
},
};
}
function footSchema(offsetProp, angleProp) {
return {
out: offsetProp('metres from the midline'),
forward: offsetProp('metres in front of the hips'),
lift: offsetProp('metres the ankle is raised off the floor'),
heading: angleProp('degrees the foot turns toward the body\'s left'),
plant: { type: 'string', enum: PLANTS, description: 'how the foot meets the floor' },
};
}
/**
* A one-line human summary of a score: how long it runs, how many beats, and
* what it does. Used by the CLI, the API response, and anything logging one.
* @param {object} score a normalized score
* @returns {string}
*/
export function describeScore(score) {
const beats = score.beats.length;
const labels = score.beats.map((b) => b.label || b.posture).filter(Boolean);
const shape = labels.length ? `: ${[...new Set(labels)].slice(0, 6).join(' > ')}` : '';
return `${score.name}, ${score.duration.toFixed(2)}s, ${beats} beat${beats === 1 ? '' : 's'}${score.loop ? ', looping' : ''}${shape}`;
}