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
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.jsnew file mode 100755index 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.tsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100755index 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)));