Skip to content

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.

feat(motion): expose the rig through a package entry point and a CLI

nirholasec509730b509
diff --git a/packages/motion/bin/motion.js b/packages/motion/bin/motion.js
new file mode 100755
index 000000000..161b8d4fd
--- /dev/null
+++ b/packages/motion/bin/motion.js
@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// three-ws-motion: compile a prompt or a Motion Score into an AnimationClip.
+//
+// three-ws-motion "wave hello twice, excitedly" -o wave.json
+// three-ws-motion --score sit.json --no-idle -o sit.json
+// three-ws-motion --schema print the score schema for a tool call
+// three-ws-motion --actions list what the model-free lane knows
+//
+// The output is a three.js AnimationClip document. Load it with
+// AnimationClip.parse() and play it on any humanoid, or hand it to the three.ws
+// retargeter to run on a rig it was not authored for.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+import {
+ ACTION_NAMES,
+ compileScore,
+ describeScore,
+ motionFromText,
+ scoreSchema,
+} from '../src/index.js';
+
+const USAGE = `three-ws-motion: text or a Motion Score into an AnimationClip.
+
+Usage
+ three-ws-motion <prompt> [options]
+ three-ws-motion --score <file.json> [options]
+ three-ws-motion --schema | --actions
+
+Options
+ -o, --out <file> write the clip here (default: stdout)
+ --score <file> compile a Motion Score instead of a prompt
+ --name <name> clip name (default: the prompt, or the score's name)
+ --loop close the last beat back into the first
+ --effort <name> override the performance quality for every beat
+ --no-idle leave out the breathing and micro-sway layer
+ --no-root leave out the hip translation track, for a clip in place
+ --no-fingers leave out the finger bones
+ --score-out <f> also write the Motion Score that produced the clip
+ --quiet no summary on stderr
+ --schema print the Motion Score JSON Schema and exit
+ --actions list the actions the model-free lane recognizes
+ -h, --help this
+`;
+
+const argv = process.argv.slice(2);
+if (!argv.length || argv.includes('-h') || argv.includes('--help')) {
+ process.stdout.write(USAGE);
+ process.exit(argv.length ? 0 : 1);
+}
+
+if (argv.includes('--schema')) {
+ process.stdout.write(`${JSON.stringify(scoreSchema(), null, 2)}\n`);
+ process.exit(0);
+}
+
+if (argv.includes('--actions')) {
+ process.stdout.write(`${ACTION_NAMES.join('\n')}\n`);
+ process.exit(0);
+}
+
+const opts = { idle: true, rootMotion: true, fingers: true, loop: false, quiet: false };
+const words = [];
+for (let i = 0; i < argv.length; i++) {
+ const arg = argv[i];
+ switch (arg) {
+ case '-o': case '--out': opts.out = argv[++i]; break;
+ case '--score': opts.scoreFile = argv[++i]; break;
+ case '--score-out': opts.scoreOut = argv[++i]; break;
+ case '--name': opts.name = argv[++i]; break;
+ case '--effort': opts.effort = argv[++i]; break;
+ case '--loop': opts.loop = true; break;
+ case '--no-idle': opts.idle = false; break;
+ case '--no-root': opts.rootMotion = false; break;
+ case '--no-fingers': opts.fingers = false; break;
+ case '--quiet': opts.quiet = true; break;
+ default:
+ if (arg.startsWith('-')) fail(`unknown option ${arg}`);
+ words.push(arg);
+ }
+}
+
+function fail(message) {
+ process.stderr.write(`three-ws-motion: ${message}\n`);
+ process.exit(2);
+}
+
+let result;
+try {
+ if (opts.scoreFile) {
+ const raw = JSON.parse(await readFile(opts.scoreFile, 'utf8'));
+ if (opts.loop) raw.loop = true;
+ if (opts.effort) raw.effort = opts.effort;
+ result = compileScore(raw, opts);
+ } else {
+ if (!words.length) fail('give a prompt, or --score <file>');
+ result = motionFromText(words.join(' '), opts);
+ }
+} catch (err) {
+ fail(err.message);
+}
+
+const json = `${JSON.stringify(result.clip, null, opts.out ? 0 : 2)}\n`;
+if (opts.out) await writeFile(opts.out, json);
+else process.stdout.write(json);
+
+if (opts.scoreOut) await writeFile(opts.scoreOut, `${JSON.stringify(result.score, null, 2)}\n`);
+
+if (!opts.quiet) {
+ const where = opts.out ? ` -> ${opts.out}` : '';
+ process.stderr.write(`${describeScore(result.score)}, ${result.clip.tracks.length} tracks${where}\n`);
+ for (const warning of result.warnings) process.stderr.write(` warning: ${warning}\n`);
+}
diff --git a/packages/motion/src/index.d.ts b/packages/motion/src/index.d.ts
new file mode 100644
index 000000000..056e394ca
--- /dev/null
+++ b/packages/motion/src/index.d.ts
@@ -0,0 +1,215 @@
+/** Public types for @three-ws/motion. */
+
+export type Side = 'Left' | 'Right';
+export type SideKey = 'left' | 'right';
+export type Vec3 = [number, number, number];
+export type Quat = [number, number, number, number];
+
+export type EaseName = 'linear' | 'smooth' | 'in' | 'out' | 'snap' | 'overshoot' | 'settle';
+export type PlantName = 'flat' | 'toe' | 'heel' | 'lift';
+export type DirectionName = 'forward' | 'back' | 'up' | 'down' | 'in' | 'out' | 'left' | 'right';
+
+export interface Effort {
+ /** 0 light and floating, 1 heavy and committed. */
+ weight: number;
+ /** 0 sustained and unhurried, 1 sudden and urgent. */
+ time: number;
+ /** 0 bound and controlled, 1 free and released. */
+ flow: number;
+}
+
+export interface ArmSpec {
+ at?: string | Vec3;
+ out?: number;
+ up?: number;
+ forward?: number;
+ palm?: DirectionName;
+ point?: DirectionName;
+ elbow?: string;
+ hand?: string | { shape?: string; curl?: number; thumb?: number; spread?: number };
+}
+
+export interface FootSpec {
+ out?: number;
+ forward?: number;
+ lift?: number;
+ heading?: number;
+ plant?: PlantName;
+}
+
+export interface Beat {
+ label?: string;
+ at?: number;
+ in?: number;
+ hold?: number;
+ ease?: EaseName;
+ effort?: string | Partial<Effort> & { preset?: string };
+ posture?: string;
+ root?: { height?: number; forward?: number; side?: number; rise?: number; turn?: number };
+ torso?: { lean?: number; twist?: number; sideBend?: number };
+ gaze?: string | { preset?: string; yaw?: number; pitch?: number; roll?: number };
+ arms?: { left?: ArmSpec | string; right?: ArmSpec | string };
+ legs?: string | { stance?: string; left?: FootSpec; right?: FootSpec };
+ face?: string | Record<string, number>;
+}
+
+export interface MotionScore {
+ version?: number;
+ name?: string;
+ seed?: string;
+ loop?: boolean;
+ effort?: string;
+ beats: Beat[];
+}
+
+/** A normalized score: every field resolved, every beat carrying an absolute time. */
+export interface NormalizedScore extends Required<Pick<MotionScore, 'version' | 'name' | 'seed' | 'loop'>> {
+ effort: Effort;
+ beats: Array<Required<Pick<Beat, 'at' | 'in' | 'hold' | 'ease'>> & Beat & { effort: Effort }>;
+ duration: number;
+}
+
+/** A three.js AnimationClip.toJSON() document. */
+export interface ClipDocument {
+ name: string;
+ duration: number;
+ uuid: string;
+ blendMode: number;
+ tracks: Array<{ type: string; name: string; times: number[]; values: number[] }>;
+}
+
+export interface CompileOptions {
+ name?: string;
+ /** Layer breathing and micro-sway on top. Default true. */
+ idle?: boolean;
+ /** Emit the hip translation track. Default true. */
+ rootMotion?: boolean;
+ /** Emit the finger bones. Default true. */
+ fingers?: boolean;
+}
+
+export interface CompileResult {
+ clip: ClipDocument;
+ score: NormalizedScore;
+ warnings: string[];
+}
+
+export const MOTION_SCORE_VERSION: number;
+export const MOTION_BONES: readonly string[];
+export const ACTION_NAMES: readonly string[];
+export const LIMITS: Readonly<Record<string, number>>;
+
+export function compileScore(score: MotionScore, opts?: CompileOptions): CompileResult;
+export function motionFromText(
+ prompt: string,
+ opts?: CompileOptions & { loop?: boolean; effort?: string },
+): CompileResult & { matched: string };
+export function motionCapabilities(): { version: number; schema: object; limits: object; actions: string[] };
+
+export function normalizeScore(input: unknown): NormalizedScore;
+export function validateScore(input: unknown): { ok: boolean; score: NormalizedScore | null; error: { path: string; message: string } | null };
+export function scoreSchema(): object;
+export function describeScore(score: NormalizedScore): string;
+export function composeScore(
+ prompt: string,
+ opts?: { name?: string; loop?: boolean; effort?: string },
+): { score: MotionScore | null; matched: string | null; reason: string | null };
+
+export declare class Pose {
+ constructor(from?: Pose | null);
+ local: Map<string, Quat>;
+ face: Map<string, number>;
+ rootOffset: Vec3;
+ readonly isRest: boolean;
+ clone(): Pose;
+ getLocal(bone: string): Quat;
+ setLocal(bone: string, q: Quat): this;
+ rotateLocal(bone: string, axis: Vec3, deg: number): this;
+ setRootOffset(offset: Vec3): this;
+ worldQuat(bone: string): Quat;
+ worldPos(bone: string): Vec3;
+ worldDir(bone: string): Vec3;
+ setWorldQuat(bone: string, q: Quat): this;
+ aim(bone: string, dirWorld: Vec3, refWorld?: Vec3 | null, refLocal?: Vec3 | null): this;
+ setFace(weights: Record<string, number>): this;
+ getFace(shape: string): number;
+ locals(): Record<string, Quat>;
+}
+
+export function restPose(): Pose;
+export function blendPose(a: Pose, b: Pose, t: number): Pose;
+
+export function solveBeat(beat: Beat): { pose: Pose; warnings: string[] };
+export function solveScorePoses(score: NormalizedScore): {
+ keys: Array<{ time: number; pose: Pose; beat: object }>;
+ warnings: string[];
+};
+
+export function solveArm(pose: Pose, side: Side, spec: {
+ wrist: Vec3; fingers?: Vec3; palm?: Vec3; pole?: Vec3; reach?: number; clavicle?: boolean;
+}): Pose;
+export function solveLeg(pose: Pose, side: Side, spec: {
+ ankle: Vec3; heading?: number; plant?: PlantName; toe?: Vec3; sole?: Vec3; pole?: Vec3; reach?: number;
+}): Pose;
+export function solveSpine(pose: Pose, spec: { lean?: number; twist?: number; sideBend?: number }): Pose;
+export function solveGaze(pose: Pose, spec: { yaw?: number; pitch?: number; roll?: number }): Pose;
+export function solveTurn(pose: Pose, degrees: number): Pose;
+export function shapeHand(pose: Pose, side: Side, spec: {
+ curl?: number; thumb?: number; spread?: number; only?: string[];
+}): Pose;
+
+export function centreOfMass(pose: Pose): Vec3;
+export function supportCentre(pose: Pose, weights?: { Left?: number; Right?: number }): Vec3;
+export function balanceError(pose: Pose, weights?: { Left?: number; Right?: number }): number;
+export function balanceOffset(pose: Pose, weights?: { Left?: number; Right?: number }): Vec3;
+
+export function anchorPoint(pose: Pose, anchor: string | Vec3, offset?: {
+ out?: number; up?: number; forward?: number; side?: Side;
+}): Vec3;
+export function restAnchor(anchor: string | Vec3, offset?: {
+ out?: number; up?: number; forward?: number; side?: Side;
+}): Vec3;
+export function bodyDirection(pose: Pose, name: DirectionName, side?: Side): Vec3;
+
+export function buildClip(
+ keys: Array<{ time: number; pose: Pose; beat?: object }>,
+ opts: { name: string; seed?: string; loop?: boolean; idle?: boolean; rootMotion?: boolean; fingers?: boolean },
+): ClipDocument;
+export function restClip(name: string): ClipDocument;
+export function stableUuid(seed: string): string;
+export function expressionWeights(spec: Record<string, number>): Record<string, number>;
+
+export const POSTURES: Readonly<Record<string, object>>;
+export const POSTURE_NAMES: readonly string[];
+export const STANCES: Readonly<Record<string, object>>;
+export const STANCE_NAMES: readonly string[];
+export const HAND_SHAPES: Readonly<Record<string, object>>;
+export const HAND_SHAPE_NAMES: readonly string[];
+export const ELBOW_POLES: Readonly<Record<string, object>>;
+export const ELBOW_NAMES: readonly string[];
+export const GAZES: Readonly<Record<string, object>>;
+export const GAZE_NAMES: readonly string[];
+export const EXPRESSIONS: Readonly<Record<string, Record<string, number>>>;
+export const EXPRESSION_NAMES: readonly string[];
+export const EXPRESSION_SHAPES: readonly string[];
+export const EFFORTS: Readonly<Record<string, Effort>>;
+export const EFFORT_NAMES: readonly string[];
+export const EASE_NAMES: readonly string[];
+export const ANCHORS: Readonly<Record<string, unknown>>;
+export const ANCHOR_NAMES: readonly string[];
+export const DIRECTIONS: Readonly<Record<string, Vec3>>;
+export const UNITS: Readonly<Record<string, number>>;
+export const PLANT_TILT: Readonly<Record<PlantName, number>>;
+
+export const BODY_FORWARD: Readonly<Vec3>;
+export const BODY_LEFT: Readonly<Vec3>;
+export const BODY_UP: Readonly<Vec3>;
+export const CANONICAL_BONES: readonly string[];
+export const ARM_REACH: number;
+export const LEG_LENGTH: number;
+export const SHOULDER_SPAN: number;
+export const STANDING_HIP_HEIGHT: number;
+export const GROUND_Y: number;
+export function boneLength(bone: string): number;
+export function hasBone(bone: string): boolean;
+export function restPos(bone: string): Vec3;
diff --git a/packages/motion/src/rig/index.js b/packages/motion/src/rig/index.js
new file mode 100644
index 000000000..d4640cf4e
--- /dev/null
+++ b/packages/motion/src/rig/index.js
@@ -0,0 +1,9 @@
+// The kinematics layer on its own, for callers building something other than a
+// score compiler: an interactive posing tool, a constraint solver, a different
+// authoring format. Nothing here knows what a Motion Score is.
+
+export * from './math.js';
+export * from './skeleton.js';
+export * from './pose.js';
+export * from './ik.js';
+export * from './anchors.js';
diff --git a/packages/render/bin/tty.js b/packages/render/bin/tty.js
new file mode 100755
index 000000000..cf388521c
--- /dev/null
+++ b/packages/render/bin/tty.js
@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * three-ws-tty: render a 3D avatar without a GPU, from a terminal.
+ *
+ * npx @three-ws/render model.glb draw it in the terminal
+ * npx @three-ws/render model.glb --out avatar.png write a still
+ * npx @three-ws/render model.glb --clip walk --frames 24 --out walk.png
+ * npx @three-ws/render https://three.ws/avatars/default.glb --spin 360
+ *
+ * With `--out` it writes a PNG (or an animated PNG when frames > 1). Without
+ * one it draws into the terminal: a real image on Kitty, Ghostty, WezTerm and
+ * iTerm2, and truecolor half-blocks everywhere else.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { AvatarModel } from '../src/model.js';
+import { loadModel } from '../src/load.js';
+import { parseClipJson } from '../src/clips.js';
+import { renderFrame, renderFrames } from '../src/render.js';
+import { encodePng, encodeApng } from '../src/encode.js';
+import { toHalfBlocks, toKitty, toITerm, detectTerminal, CURSOR } from '../src/ansi.js';
+
+const USAGE = `three-ws-tty <model.glb | url> [options]
+
+ --out <file> write a PNG (animated PNG when --frames > 1)
+ --width <n> output width in pixels (default: fits the terminal)
+ --height <n> output height in pixels
+ --focus <mode> full | bust | head (default: full)
+ --preset <name> studio | terminal | daylight (default: terminal for tty)
+ --clip <name|idx> clip to play, from the model or --animation
+ --animation <file> GLB or clip JSON to retarget onto this rig
+ --frames <n> frame count (default: 1, or 36 with --spin)
+ --fps <n> frames per second (default: 20)
+ --spin <deg> turntable degrees across the loop
+ --yaw <deg> camera yaw (default: 26)
+ --pitch <deg> camera pitch (default: 6)
+ --bg <color> hex colour or 'transparent'
+ --loop keep animating in the terminal until interrupted
+ --blocks force half-blocks even where inline images work
+ --clips list the model's clips and exit
+ --help this text
+`;
+
+function parseArgs(argv) {
+ const args = { _: [] };
+ for (let i = 0; i < argv.length; i++) {
+ const token = argv[i];
+ if (!token.startsWith('--')) {
+ args._.push(token);
+ continue;
+ }
+ const key = token.slice(2);
+ const next = argv[i + 1];
+ if (next === undefined || next.startsWith('--')) {
+ args[key] = true;
+ } else {
+ args[key] = next;
+ i++;
+ }
+ }
+ return args;
+}
+
+const num = (value, fallback) => {
+ const n = Number.parseFloat(value);
+ return Number.isFinite(n) ? n : fallback;
+};
+
+function fail(message) {
+ process.stderr.write(`three-ws-tty: ${message}\n`);
+ process.exit(1);
+}
+
+async function loadAnimation(model, source) {
+ if (/\.json$/i.test(source)) {
+ const raw = await fs.readFile(source, 'utf8');
+ return model.addClips([parseClipJson(raw)]);
+ }
+ const extra = await loadModel(source, { textures: false });
+ return model.addClips(extra.animations);
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ if (args.help || args._.length === 0) {
+ process.stdout.write(USAGE);
+ process.exit(args.help ? 0 : 1);
+ }
+
+ const source = args._[0];
+ const term = detectTerminal();
+ const writingFile = typeof args.out === 'string';
+
+ // A terminal cell is about twice as tall as it is wide, and half-blocks give
+ // back two pixels per cell, so a square render maps to columns x columns.
+ const fitted = Math.max(24, Math.min(160, term.columns - 2));
+ const width = Math.round(num(args.width, writingFile ? 512 : fitted));
+ const height = Math.round(num(args.height, width));
+
+ let model;
+ try {
+ model = await AvatarModel.load(source);
+ } catch (err) {
+ fail(err?.message || String(err));
+ }
+
+ if (args.animation) {
+ try {
+ await loadAnimation(model, String(args.animation));
+ } catch (err) {
+ fail(`could not load --animation: ${err?.message || err}`);
+ }
+ }
+
+ if (args.clips) {
+ const names = model.clipNames;
+ process.stdout.write(names.length ? `${names.join('\n')}\n` : 'no clips in this model\n');
+ return;
+ }
+
+ const spin = num(args.spin, 0);
+ const explicitFrames = args.frames !== undefined;
+ const frames = Math.max(1, Math.round(num(args.frames, spin || args.clip || args.loop ? 36 : 1)));
+ const fps = Math.max(1, Math.round(num(args.fps, 20)));
+ const options = {
+ width,
+ height,
+ supersample: writingFile ? 2 : 1,
+ preset: args.preset || (writingFile ? 'studio' : 'terminal'),
+ focus: ['full', 'bust', 'head'].includes(args.focus) ? args.focus : 'full',
+ yaw: num(args.yaw, 26),
+ pitch: num(args.pitch, 6),
+ background: args.bg === undefined ? undefined : args.bg === 'transparent' ? 'transparent' : String(args.bg),
+ clip: args.clip === undefined ? null : Number.isFinite(Number(args.clip)) ? Number(args.clip) : String(args.clip),
+ frames,
+ fps,
+ spin,
+ };
+
+ if (args.clip !== undefined && !model.play(options.clip)) {
+ fail(`no clip matching "${args.clip}". Try --clips to list them.`);
+ }
+
+ if (writingFile) {
+ const out = path.resolve(String(args.out));
+ const rendered = frames > 1 ? await renderFrames(model, options) : [renderFrame(model, options)];
+ const bytes = rendered.length > 1 ? encodeApng(rendered, { fps }) : encodePng(rendered[0]);
+ await fs.writeFile(out, bytes);
+ process.stdout.write(`${out} (${rendered.length} frame${rendered.length === 1 ? '' : 's'}, ${bytes.length} bytes)\n`);
+ return;
+ }
+
+ const inline = !args.blocks && (term.kitty || term.iterm);
+ const draw = (frame) => {
+ if (inline) {
+ const png = encodePng(frame, { level: 1 });
+ return term.kitty ? toKitty(png, { columns: Math.round(width / 2) }) : toITerm(png, { columns: Math.round(width / 2) });
+ }
+ return toHalfBlocks(frame, { truecolor: term.truecolor });
+ };
+
+ const animated = frames > 1 || args.loop;
+ if (!animated) {
+ process.stdout.write(`${draw(renderFrame(model, options))}\n`);
+ return;
+ }
+
+ const rendered = await renderFrames(model, options);
+ const painted = rendered.map(draw);
+ const lines = inline ? Math.round(height / 2 / 2) : Math.ceil(height / 2);
+
+ let stop = false;
+ const cleanup = () => {
+ stop = true;
+ process.stdout.write(CURSOR.show);
+ };
+ process.on('SIGINT', () => {
+ cleanup();
+ process.exit(0);
+ });
+
+ process.stdout.write(CURSOR.hide);
+ try {
+ do {
+ for (const frame of painted) {
+ if (stop) break;
+ process.stdout.write(`${frame}\n`);
+ await new Promise((resolve) => setTimeout(resolve, Math.round(1000 / fps)));
+ process.stdout.write(CURSOR.up(lines + 1));
+ }
+ } while (args.loop && !stop);
+ // Land the cursor below the last frame instead of on top of it.
+ process.stdout.write(`${painted[painted.length - 1]}\n`);
+ } finally {
+ cleanup();
+ }
+ void explicitFrames;
+}
+
+main().catch((err) => fail(err?.stack || err?.message || String(err)));