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 three.ws motion library and the text to animation lane.
//
// The library is 2,800+ clips baked onto the canonical humanoid skeleton, the
// same clips the /animations gallery and the <agent-3d> embed play. A clip is a
// three.js AnimationClip serialised as JSON, so the viewer parses it with
// AnimationClip.parse and retargets it onto whatever rig is open with the
// platform's own retargeter. Text to animation samples a motion model on the
// three.ws GPU fleet and returns a clip in the same format.
import { normalizeOrigin } from './studio.js';
import { slugFromPrompt } from './naming.js';
const PAGE = 1000;
const MOTION_POLL_MS = 3000;
const MOTION_TIMEOUT_MS = 6 * 60_000;
/**
* @typedef {object} LibraryClip
* @property {string} name stable id, e.g. "mx-happy-idle-c9cd...";
* @property {string} label human title, e.g. "Happy Idle"
* @property {boolean} loop whether the clip is meant to cycle
* @property {number} duration seconds
* @property {string} url the clip JSON on the CDN
* @property {string|null} thumb preview image
*/
/**
* Every clip in the library. Pages through the manifest so a growing catalogue
* never produces one oversized response.
*
* @param {string} origin
* @param {{ signal?: AbortSignal }} [opts]
* @returns {Promise<LibraryClip[]>}
*/
export async function listLibrary(origin, { signal } = {}) {
const base = normalizeOrigin(origin);
const clips = [];
let offset = 0;
for (let page = 0; page < 20; page++) {
const url = new URL('/api/animations/library', base);
url.searchParams.set('limit', String(PAGE));
url.searchParams.set('offset', String(offset));
const body = await getJson(url.href, { signal, what: 'the animation library' });
for (const row of Array.isArray(body?.clips) ? body.clips : []) {
const clip = normalizeClip(row);
if (clip) clips.push(clip);
}
if (body?.next_offset === null || body?.next_offset === undefined) break;
offset = Number(body.next_offset);
if (!Number.isFinite(offset)) break;
}
return clips;
}
/** One manifest row, validated. Rows without a fetchable clip URL are dropped. */
export function normalizeClip(row) {
const url = row?.url;
if (typeof url !== 'string' || !/^https?:\/\//.test(url)) return null;
const label = String(row.label || row.name || '').trim();
if (!label) return null;
return {
name: String(row.name || label),
label,
loop: Boolean(row.loop),
duration: Number(row.duration) || 0,
url,
thumb: typeof row.thumb === 'string' ? row.thumb : null,
};
}
/**
* Fetch one clip's JSON.
* @param {string} url
* @param {{ signal?: AbortSignal }} [opts]
*/
export async function fetchClip(url, { signal } = {}) {
const clip = await getJson(url, { signal, what: 'the animation clip' });
if (!Array.isArray(clip?.tracks) || !clip.tracks.length) {
throw new Error('the clip has no animation tracks');
}
return clip;
}
/** A file-safe stem for a clip: "Happy Idle" -> "happy-idle". */
export function clipSlug(label) {
return slugFromPrompt(String(label || '').replace(/^mx-/, ''), 'clip').replace(/-[0-9a-f]{12}(-\d+)?$/, '');
}
/**
* Generate an animation clip from a text prompt.
*
* POST /api/forge-motion starts the job; GET ?job= polls it. Resolves with the
* finished clip JSON plus its URL.
*
* @param {string} origin
* @param {string} prompt
* @param {{ signal?: AbortSignal, durationSeconds?: number, onStatus?: (message: string) => void, pollMs?: number }} [opts]
* @returns {Promise<{ clipUrl: string, clip: object }>}
*/
export async function generateMotion(origin, prompt, { signal, durationSeconds = 4, onStatus, pollMs = MOTION_POLL_MS } = {}) {
const base = normalizeOrigin(origin);
const start = await fetch(new URL('/api/forge-motion', base).href, {
method: 'POST',
headers: { 'content-type': 'application/json', accept: 'application/json' },
body: JSON.stringify({ prompt, duration_seconds: durationSeconds }),
signal,
}).catch((err) => {
throw new Error(`could not reach the motion lane: ${err?.message || err}`);
});
const started = await start.json().catch(() => null);
if (start.status === 503) {
throw new Error(started?.message || 'text to animation is not available on this origin right now');
}
if (!start.ok || !started?.job_id) {
throw new Error(started?.message || `the motion lane returned HTTP ${start.status}`);
}
const deadline = Date.now() + MOTION_TIMEOUT_MS;
const poll = new URL('/api/forge-motion', base);
poll.searchParams.set('job', started.job_id);
while (Date.now() < deadline) {
await sleep(pollMs, signal);
const status = await getJson(poll.href, { signal, what: 'the motion job' });
if (status?.status === 'failed') {
throw new Error(status.error || 'the motion model could not animate that prompt');
}
if (status?.clip_url) {
onStatus?.('retargeting the clip…');
const clip = await fetchClip(status.clip_url, { signal });
return { clipUrl: status.clip_url, clip };
}
onStatus?.(status?.status === 'running' ? 'the motion model is sampling…' : 'queued on the GPU fleet…');
}
throw new Error('the motion job did not finish within six minutes');
}
async function getJson(url, { signal, what }) {
let res;
try {
res = await fetch(url, { headers: { accept: 'application/json' }, signal });
} catch (err) {
if (signal?.aborted) throw new Error('cancelled');
throw new Error(`could not reach ${what}: ${err?.message || err}`);
}
if (!res.ok) throw new Error(`${what} returned HTTP ${res.status}`);
const body = await res.json().catch(() => null);
if (body === null) throw new Error(`${what} returned a non-JSON body`);
return body;
}
function sleep(ms, signal) {
return new Promise((resolve, reject) => {
if (signal?.aborted) return reject(new Error('cancelled'));
const timer = setTimeout(() => {
signal?.removeEventListener('abort', onAbort);
resolve();
}, ms);
const onAbort = () => {
clearTimeout(timer);
reject(new Error('cancelled'));
};
signal?.addEventListener('abort', onAbort, { once: true });
});
}