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
// Keyframe animation core for the Animation Studio (/pose).
//
// This module is the pure, headless half of Task 2: it owns the editing
// document (keyframes over time), interpolates a pose at any playhead position
// (slerp rotations, lerp root translation), and bakes the result into a
// THREE.AnimationClip whose track names play everywhere on three.ws.
//
// It depends only on `three` (no DOM, no rig) so it is unit-testable in node —
// see tests/pose-animation.test.js. The studio (src/pose-studio.js) drives the
// live preview by calling sampleAtTime() each frame and rig.applyPose(); export
// calls bakeClip() / serializeClip().
//
// Pose shape (the Task 1 rig contract): { bones: { Canonical: [x,y,z,w], … },
// rootPosition: { x, y, z } }. Bones are keyed by CANONICAL names (Hips, Spine,
// LeftArm, …) so a clip baked here binds to standard three.ws avatars.
import {
AnimationClip,
Quaternion,
QuaternionKeyframeTrack,
VectorKeyframeTrack,
} from 'three';
// ── Easing ───────────────────────────────────────────────────────────────────
// Each easing maps a normalized segment fraction [0,1] → eased [0,1]. The easing
// of the OUTGOING keyframe governs the segment that follows it.
export const EASINGS = {
linear: (t) => t,
'ease-in': (t) => t * t,
'ease-out': (t) => t * (2 - t),
'ease-in-out': (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
};
export const DEFAULT_EASING = 'ease-in-out';
function easeFn(name) {
return EASINGS[name] || EASINGS.linear;
}
const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
// ── Editing document ───────────────────────────────────────────────────────
// The in-memory project Task 4 will serialize/save.
// { name, duration /* s */, fps, loop, keyframes: [{ id, time, pose, easing }] }
let _kidSeq = 0;
function nextKeyframeId() {
_kidSeq += 1;
return `kf_${_kidSeq}`;
}
export function createDocument(overrides = {}) {
return {
name: 'animation',
duration: 4,
fps: 30,
loop: true,
keyframes: [],
...overrides,
};
}
export function clonePose(pose) {
if (!pose) return null;
const bones = {};
for (const [key, q] of Object.entries(pose.bones || {})) {
bones[key] = [q[0], q[1], q[2], q[3]];
}
const rp = pose.rootPosition || { x: 0, y: 0, z: 0 };
return { bones, rootPosition: { x: rp.x || 0, y: rp.y || 0, z: rp.z || 0 } };
}
// True when two canonical poses are equal within `eps` — the same quaternion per
// bone and the same root position. Used by the studio's undo stack to skip
// no-op edits (a gizmo click that didn't actually rotate anything).
export function posesEqual(a, b, eps = 1e-4) {
if (!a || !b) return a === b;
const ba = a.bones || {};
const bb = b.bones || {};
const keys = new Set([...Object.keys(ba), ...Object.keys(bb)]);
for (const key of keys) {
const qa = ba[key];
const qb = bb[key];
if (!qa || !qb) return false;
for (let i = 0; i < 4; i++) {
if (Math.abs((qa[i] || 0) - (qb[i] || 0)) > eps) return false;
}
}
const ra = a.rootPosition || { x: 0, y: 0, z: 0 };
const rb = b.rootPosition || { x: 0, y: 0, z: 0 };
return (
Math.abs((ra.x || 0) - (rb.x || 0)) <= eps &&
Math.abs((ra.y || 0) - (rb.y || 0)) <= eps &&
Math.abs((ra.z || 0) - (rb.z || 0)) <= eps
);
}
function sortKeyframes(doc) {
doc.keyframes.sort((a, b) => a.time - b.time);
return doc;
}
// Two keyframes within this many seconds are treated as the same slot, so
// re-dropping at the current playhead updates rather than stacks.
const TIME_EPSILON = 1e-3;
/**
* Capture `pose` at `time`. If a keyframe already sits at ~time, its pose (and
* optionally easing) is updated; otherwise a new keyframe is inserted, sorted.
* @returns the affected keyframe.
*/
export function upsertKeyframe(doc, time, pose, easing = DEFAULT_EASING) {
const t = clamp(time, 0, doc.duration);
const existing = doc.keyframes.find((k) => Math.abs(k.time - t) <= TIME_EPSILON);
if (existing) {
existing.pose = clonePose(pose);
return existing;
}
const kf = { id: nextKeyframeId(), time: t, pose: clonePose(pose), easing };
doc.keyframes.push(kf);
sortKeyframes(doc);
return kf;
}
export function removeKeyframe(doc, id) {
const i = doc.keyframes.findIndex((k) => k.id === id);
if (i === -1) return false;
doc.keyframes.splice(i, 1);
return true;
}
/** Retime a keyframe (drag-to-retime). Keeps the list sorted. */
export function moveKeyframe(doc, id, newTime) {
const kf = doc.keyframes.find((k) => k.id === id);
if (!kf) return null;
kf.time = clamp(newTime, 0, doc.duration);
sortKeyframes(doc);
return kf;
}
export function setKeyframeEasing(doc, id, easing) {
const kf = doc.keyframes.find((k) => k.id === id);
if (kf && EASINGS[easing]) kf.easing = easing;
return kf;
}
/** Clamp every keyframe to the (possibly shortened) duration. */
export function clampKeyframesToDuration(doc) {
for (const kf of doc.keyframes) kf.time = clamp(kf.time, 0, doc.duration);
sortKeyframes(doc);
return doc;
}
// ── Interpolation ────────────────────────────────────────────────────────────
const _qa = new Quaternion();
const _qb = new Quaternion();
const _qOut = new Quaternion();
/**
* Interpolated pose at `time` (seconds). Rotations slerp; root position lerps.
* Returns null when there are no keyframes.
*/
export function sampleAtTime(doc, time) {
const kfs = doc.keyframes;
if (!kfs.length) return null;
if (kfs.length === 1) return clonePose(kfs[0].pose);
const t = clamp(time, 0, doc.duration);
const first = kfs[0];
const last = kfs[kfs.length - 1];
if (t <= first.time) return clonePose(first.pose);
if (t >= last.time) return clonePose(last.pose);
let a = first;
let b = last;
for (let i = 0; i < kfs.length - 1; i++) {
if (kfs[i].time <= t && t < kfs[i + 1].time) {
a = kfs[i];
b = kfs[i + 1];
break;
}
}
const span = b.time - a.time;
let u = span > TIME_EPSILON ? (t - a.time) / span : 0;
u = clamp(easeFn(a.easing)(u), 0, 1);
const aBones = a.pose.bones || {};
const bBones = b.pose.bones || {};
const keys = new Set([...Object.keys(aBones), ...Object.keys(bBones)]);
const bones = {};
for (const key of keys) {
const va = aBones[key] || bBones[key];
const vb = bBones[key] || aBones[key];
_qa.set(va[0], va[1], va[2], va[3]);
_qb.set(vb[0], vb[1], vb[2], vb[3]);
_qOut.copy(_qa).slerp(_qb, u);
bones[key] = [_qOut.x, _qOut.y, _qOut.z, _qOut.w];
}
const ra = a.pose.rootPosition || { x: 0, y: 0, z: 0 };
const rb = b.pose.rootPosition || { x: 0, y: 0, z: 0 };
return {
bones,
rootPosition: {
x: (ra.x || 0) + ((rb.x || 0) - (ra.x || 0)) * u,
y: (ra.y || 0) + ((rb.y || 0) - (ra.y || 0)) * u,
z: (ra.z || 0) + ((rb.z || 0) - (ra.z || 0)) * u,
},
};
}
// ── Baking to a THREE.AnimationClip ────────────────────────────────────────
// We RESAMPLE the document at `fps` and emit linear/slerp tracks. Resampling
// bakes per-keyframe easing into the samples, so the exported clip reproduces
// the exact eased timing under any standard player (AnimationMixer slerps the
// quaternion track), with no easing metadata to carry around.
function uniqueBoneKeys(doc) {
const keys = new Set();
for (const kf of doc.keyframes) {
for (const k of Object.keys(kf.pose?.bones || {})) keys.add(k);
}
return keys;
}
function sampleTimes(duration, fps) {
const safeFps = clamp(Math.round(fps) || 30, 1, 120);
const dt = 1 / safeFps;
const times = [];
for (let t = 0; t < duration - 1e-6; t += dt) times.push(Number(t.toFixed(6)));
times.push(Number(Math.max(duration, dt).toFixed(6)));
return times;
}
/**
* Bake the document into a THREE.AnimationClip.
*
* @param {object} doc the editing document
* @param {object} [opts]
* @param {(canonicalKey:string)=>string|null} [opts.resolveBoneName]
* Maps a canonical bone key to the emitted track bone name. Default:
* identity (canonical names — the cross-platform three.ws clip). Pass a
* function returning the live rig's actual node names to bake a clip that
* binds to a specific GLB/mannequin scene for GLB embedding.
* @param {string} [opts.rootName='Hips'] bone name for the root position track
* @returns {THREE.AnimationClip}
*/
export function bakeClip(doc, { resolveBoneName = (k) => k, rootName = 'Hips' } = {}) {
if (!doc.keyframes.length) {
throw new Error('Add at least one keyframe before baking an animation.');
}
const duration = Math.max(doc.duration, 1 / clamp(doc.fps || 30, 1, 120));
const times = sampleTimes(duration, doc.fps);
const samples = times.map((t) => sampleAtTime(doc, t));
const tracks = [];
for (const key of uniqueBoneKeys(doc)) {
const trackBone = resolveBoneName(key);
if (!trackBone) continue;
const values = new Float32Array(samples.length * 4);
for (let i = 0; i < samples.length; i++) {
const q = samples[i].bones[key] || [0, 0, 0, 1];
values[i * 4] = q[0];
values[i * 4 + 1] = q[1];
values[i * 4 + 2] = q[2];
values[i * 4 + 3] = q[3];
}
tracks.push(new QuaternionKeyframeTrack(`${trackBone}.quaternion`, times, values));
}
if (rootName) {
const posValues = new Float32Array(samples.length * 3);
for (let i = 0; i < samples.length; i++) {
const p = samples[i].rootPosition || { x: 0, y: 0, z: 0 };
posValues[i * 3] = p.x || 0;
posValues[i * 3 + 1] = p.y || 0;
posValues[i * 3 + 2] = p.z || 0;
}
tracks.push(new VectorKeyframeTrack(`${rootName}.position`, times, posValues));
}
const clip = new AnimationClip(doc.name || 'animation', duration, tracks);
clip.resetDuration();
clip.optimize();
return clip;
}
/** Bake + return the documented clip-JSON shape ({ name, duration, tracks }). */
export function serializeClip(doc, opts) {
return AnimationClip.toJSON(bakeClip(doc, opts));
}