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): reject frozen, torn and skating clips before they reach the library
nirholas37288a1b2939
diff --git a/api/_lib/motion-quality.js b/api/_lib/motion-quality.jsindex 15e19db33..8d31c6d41 100644--- a/api/_lib/motion-quality.js+++ b/api/_lib/motion-quality.js@@ -35,8 +35,9 @@ import {CANONICAL_REST_POSITION,CANONICAL_REST_WORLD,} from '../../src/animation-canonical-rest.js';+import { worldMotionMetrics, footContactMetrics } from './motion-seed.js';-export const MOTION_GATE_VERSION = 1;+export const MOTION_GATE_VERSION = 2;/*** Every bound the gate enforces, in one frozen object so a caller (or a report)@@ -61,17 +62,28 @@ export const MOTION_BOUNDS = Object.freeze({// Averaged angular speed across every rotation track. A clip below this is// standing in bind pose: technically valid, worthless in a library.minMeanAngularSpeedDeg: 5,- // A single inter-frame step this large is a tear, not motion. 45 degrees at- // 30 fps is 1350 deg/s on one joint, well past anything a body does.- maxFrameAngularStepDeg: 45,+ // Largest single-frame WORLD step of a witness joint, over that joint's own+ // p95 step. Measured on local rotations instead, this test cannot work: the+ // sampler emits a 180 degree twist about a bone's own axis that the child+ // bone cancels, which is invisible on the mesh but maxes out any local+ // angular bound, and the authored library itself reaches 121 degrees in a+ // single frame. A local threshold therefore rejects real motion and genuine+ // tears alike (measured: 100% of generated clips and 66% of the authored+ // library). Judging joint POSITIONS separates them. Authored clips score a+ // median of 1.69 and a worst case of 5.79, so 6.5 leaves headroom.+ // See docs/animation-seeding.md.+ maxWorldStepRatio: 6.5,// Loop clips only: the pose distance between the first and last frame. A// seam wider than this visibly pops every cycle.maxLoopSeamDeg: 30,// Space.- // Planted-foot horizontal drift over one contact span, as a fraction of the- // rig's hip height. Above this the character skates.- maxFootSlideRatio: 0.45,+ // Planted-foot drift as a multiple of the stride the clip actually covers,+ // counting only frames where a foot is on this clip's own floor AND the hips+ // are upright over it. Without the upright test, floor work (a fall, a crawl,+ // a breakdance flair) reads as skating because the "lower" foot is merely the+ // one that happens to be less high.+ maxSlidePerStride: 0.85,// A foot below the ground plane by more than this (metres) is clipping// through the floor.maxGroundPenetration: 0.15,@@ -506,9 +518,9 @@ export function decideMotionVerdict(m, opts = {}) {if (m.worstQuatNormError > b.quatNormTolerance) reasons.push('quaternions_not_normalized');if (m.missingBones.length) reasons.push('missing_required_bones');if (m.meanAngularSpeedDeg < b.minMeanAngularSpeedDeg) reasons.push('motion_too_still');- if (m.maxFrameStepDeg > b.maxFrameAngularStepDeg) reasons.push('frame_discontinuity');+ if (m.worldStepRatio > b.maxWorldStepRatio) reasons.push('frame_discontinuity');if (m.maxRootSpeedMetresPerSecond > b.maxRootSpeedMetresPerSecond) reasons.push('root_velocity_implausible');- if (m.footSlideRatio > b.maxFootSlideRatio) reasons.push('foot_slide');+ if (m.slidePerStride > b.maxSlidePerStride) reasons.push('foot_slide');if (m.groundPenetrationMetres > b.maxGroundPenetration) reasons.push('ground_penetration');if (opts.loop && m.loopSeamDeg > b.maxLoopSeamDeg) reasons.push('loop_seam_open');@@ -543,6 +555,17 @@ export function gateMotionClip(raw, opts = {}) {};}const metrics = measureClip(clip);+ // World-space smoothness, liveliness and foot contact, measured on the raw+ // clip by the shared forward-kinematics implementation in motion-seed.js.+ // These are what a viewer actually sees, so they carry the two rules that a+ // local-rotation measure gets wrong.+ const world = worldMotionMetrics(raw);+ const foot = footContactMetrics(raw);+ metrics.worldStepRatio = world.continuity;+ metrics.worldTravelMetres = world.travel;+ metrics.worstWitnessJoint = world.continuityJoint;+ metrics.slidePerStride = foot.slidePerStride;+ metrics.plantedFrames = foot.plantedFrames;const { pass, reasons } = decideMotionVerdict(metrics, opts);return { pass, reasons, detail: '', metrics, gateVersion: MOTION_GATE_VERSION };}diff --git a/api/_lib/motion-seed.js b/api/_lib/motion-seed.jsindex 79158b740..f59ada178 100644--- a/api/_lib/motion-seed.js+++ b/api/_lib/motion-seed.js@@ -677,3 +677,40 @@ export function freeClipNames(names, { now = Date.now(), size = FREE_ROTATION.SIexport function isFreeThisEpoch(name, allNames, opts = {}) {return freeClipNames(allNames, opts).includes(name);}++// ── Lane assertion ──────────────────────────────────────────────────────────+//+// The GCP provider packs its job id as base64url JSON naming the worker it+// dispatched to (packJobId in api/_providers/gcp.js). Reading that back out is+// how a bulk run proves it is spending credits on our own fleet rather than+// quietly billing a paid third party for a few hundred clips. Being unable to+// tell which lane billed a job is itself a reason to stop, so an unreadable+// envelope throws rather than passing.++export function decodeJobEnvelope(jobId) {+ try {+ const parsed = JSON.parse(Buffer.from(String(jobId), 'base64url').toString('utf8'));+ return parsed && typeof parsed === 'object' ? parsed : null;+ } catch {+ return null;+ }+}++export function assertSelfHostedLane(jobId) {+ const envelope = decodeJobEnvelope(jobId);+ if (!envelope) throw new Error('lane assertion failed: job id is not a provider envelope');+ if (envelope.mode !== 'text2motion') throw new Error(`lane assertion failed: mode ${envelope.mode}`);+ let host;+ try {+ host = new URL(envelope.baseUrl).host;+ } catch {+ throw new Error(`lane assertion failed: unusable baseUrl ${envelope.baseUrl}`);+ }+ if (!/\.run\.app$/.test(host)) {+ throw new Error(`lane assertion failed: ${host} is not a self-hosted Cloud Run lane`);+ }+ if (!/^model-text2motion/.test(host)) {+ throw new Error(`lane assertion failed: unexpected worker ${host}`);+ }+ return { host, taskId: envelope.taskId };+}diff --git a/tests/motion-quality.test.js b/tests/motion-quality.test.jsnew file mode 100644index 000000000..6ae1a7283--- /dev/null+++ b/tests/motion-quality.test.js@@ -0,0 +1,193 @@+// The generated-motion gate (api/_lib/motion-quality.js) is the only thing+// standing between a diffusion sampler and the public animation library, so+// every rule it enforces is pinned here. Clips are built programmatically+// rather than committed as fixtures: a rule is only meaningful if the test can+// state exactly which property of the motion trips it.++import { describe, it, expect } from 'vitest';+import {+ MOTION_BOUNDS,+ MOTION_GATE_RULES,+ REQUIRED_BONES,+ explainMotionGate,+ gateMotionClip,+ measureClip,+ readClip,+} from '../api/_lib/motion-quality.js';++const FPS = 30;++/** Rotation about X by `deg`, as a unit [x,y,z,w] quaternion. */+function quatX(deg) {+ const h = ((deg * Math.PI) / 180) / 2;+ return [Math.sin(h), 0, 0, Math.cos(h)];+}++/**+ * Build a well-formed clip whose driven bones sweep smoothly through `sweepDeg`+ * over `seconds`. The default is a clip the gate accepts, so each test below+ * changes exactly one thing.+ */+function makeClip({+ seconds = 4,+ sweepDeg = 24,+ bones = REQUIRED_BONES,+ rootPath = null,+ loopClosed = true,+ name = 'gen-test',+} = {}) {+ const frames = Math.round(seconds * FPS) + 1;+ const times = Array.from({ length: frames }, (_, i) => i / FPS);+ const tracks = [];+ for (const bone of bones) {+ const values = [];+ for (let i = 0; i < frames; i++) {+ // A full sine cycle returns to the start, so the loop seam closes; a+ // half cycle leaves it open.+ const phase = (i / (frames - 1)) * (loopClosed ? 2 : 1) * Math.PI;+ values.push(...quatX(Math.sin(phase) * sweepDeg));+ }+ tracks.push({ name: `${bone}.quaternion`, type: 'quaternion', times, values });+ }+ if (rootPath) {+ const values = [];+ for (let i = 0; i < frames; i++) values.push(...rootPath(i / (frames - 1), i));+ tracks.push({ name: 'Hips.position', type: 'vector', times, values });+ }+ return { name, duration: (frames - 1) / FPS, tracks, uuid: 'test', blendMode: 2500 };+}++describe('a well-formed generated clip', () => {+ it('passes every rule', () => {+ const verdict = gateMotionClip(makeClip(), { loop: true, requestedDuration: 4 });+ expect(verdict.reasons).toEqual([]);+ expect(verdict.pass).toBe(true);+ expect(verdict.gateVersion).toBeGreaterThan(0);+ });++ it('reports the measurements the decision was made on', () => {+ const m = measureClip(readClip(makeClip()));+ expect(m.frames).toBe(121);+ expect(m.fps).toBeCloseTo(30, 5);+ expect(m.rotationTracks).toBe(REQUIRED_BONES.length);+ expect(m.missingBones).toEqual([]);+ expect(m.nonFinite).toBe(0);+ });+});++describe('structural rejects', () => {+ it('refuses a response that is not a clip at all', () => {+ const verdict = gateMotionClip({ hello: 'world' });+ expect(verdict.pass).toBe(false);+ expect(verdict.reasons).toEqual(['unreadable_clip']);+ expect(verdict.detail).toMatch(/no tracks/);+ });++ it('refuses a track whose values do not match its key count', () => {+ const clip = makeClip();+ clip.tracks[0].values = clip.tracks[0].values.slice(0, 7);+ const verdict = gateMotionClip(clip);+ expect(verdict.reasons).toEqual(['unreadable_clip']);+ expect(verdict.detail).toMatch(/values for/);+ });++ it('rejects NaN keyframes rather than shipping a pose that cannot be evaluated', () => {+ const clip = makeClip();+ clip.tracks[2].values[12] = Number.NaN;+ expect(gateMotionClip(clip).reasons).toContain('non_finite_keyframes');+ });++ it('rejects keyframe times that do not advance', () => {+ const clip = makeClip();+ for (const t of clip.tracks) t.times[5] = t.times[4];+ expect(gateMotionClip(clip).reasons).toContain('times_not_increasing');+ });++ it('rejects rotation keys that are not unit quaternions', () => {+ const clip = makeClip();+ for (let i = 0; i < 4; i++) clip.tracks[0].values[i] *= 1.4;+ expect(gateMotionClip(clip).reasons).toContain('quaternions_not_normalized');+ });++ it('rejects a clip that leaves a required humanoid bone undriven', () => {+ const clip = makeClip({ bones: REQUIRED_BONES.filter((b) => b !== 'LeftFoot') });+ expect(gateMotionClip(clip).reasons).toContain('missing_required_bones');+ });++ it('rejects clips shorter or longer than the library takes', () => {+ expect(gateMotionClip(makeClip({ seconds: 0.4 })).reasons).toContain('duration_too_short');+ expect(gateMotionClip(makeClip({ seconds: 20 })).reasons).toContain('duration_too_long');+ });++ it('rejects a clip whose length does not match what was asked for', () => {+ const verdict = gateMotionClip(makeClip({ seconds: 9 }), { requestedDuration: 4 });+ expect(verdict.reasons).toContain('duration_off_request');+ });+});++describe('motion content rejects', () => {+ it('rejects a clip that is effectively a frozen bind pose', () => {+ const verdict = gateMotionClip(makeClip({ sweepDeg: 0.05 }));+ expect(verdict.reasons).toContain('motion_too_still');+ });++ it('rejects a single-frame pose discontinuity, the tear the sampler actually produces', () => {+ // This is the real failure mode observed on the live lane: one frame where+ // the pose flips by 180 degrees while its neighbours are smooth.+ const clip = makeClip();+ const track = clip.tracks[4];+ const flipped = quatX(180);+ for (let i = 0; i < 4; i++) track.values[20 * 4 + i] = flipped[i];+ const verdict = gateMotionClip(clip);+ expect(verdict.reasons).toContain('frame_discontinuity');+ expect(verdict.metrics.maxFrameStepDeg).toBeGreaterThan(MOTION_BOUNDS.maxFrameAngularStepDeg);+ });++ it('rejects an open loop seam only when the clip is meant to loop', () => {+ const open = makeClip({ loopClosed: false, sweepDeg: 40 });+ expect(gateMotionClip(open, { loop: true }).reasons).toContain('loop_seam_open');+ expect(gateMotionClip(open, { loop: false }).reasons).not.toContain('loop_seam_open');+ });++ it('rejects a root that travels faster than a body can move', () => {+ const clip = makeClip({ rootPath: (_t, i) => [i * 0.5, 0.98, 0] });+ expect(gateMotionClip(clip).reasons).toContain('root_velocity_implausible');+ });+});++describe('foot slide, measured by forward kinematics', () => {+ it('accepts a clip that stands still', () => {+ const verdict = gateMotionClip(makeClip({ sweepDeg: 12 }), {});+ expect(verdict.reasons).not.toContain('foot_slide');+ expect(verdict.metrics.footSlideRatio).toBeLessThan(MOTION_BOUNDS.maxFootSlideRatio);+ });++ it('rejects a character whose planted feet are dragged across the floor', () => {+ // The legs barely move while the root translates a full body length: the+ // definition of skating. The feet follow the hips because forward+ // kinematics puts them there, which is the whole point of measuring+ // rather than trusting the prompt.+ const clip = makeClip({+ sweepDeg: 10,+ rootPath: (t) => [t * 1.2, 0.98, 0],+ });+ const verdict = gateMotionClip(clip);+ expect(verdict.reasons).toContain('foot_slide');+ expect(verdict.metrics.footSlideMetres).toBeGreaterThan(0.4);+ });++ it('rejects a character sunk through the ground plane', () => {+ const clip = makeClip({ sweepDeg: 12, rootPath: () => [0, 0.3, 0] });+ expect(gateMotionClip(clip).reasons).toContain('ground_penetration');+ });+});++describe('explanations', () => {+ it('names every reason the gate can produce', () => {+ const clip = makeClip({ seconds: 0.4, sweepDeg: 0.01 });+ const { reasons } = gateMotionClip(clip);+ expect(reasons.length).toBeGreaterThan(0);+ for (const reason of reasons) expect(MOTION_GATE_RULES[reason]).toBeTruthy();+ expect(explainMotionGate(reasons).every((s) => typeof s === 'string' && s.length > 10)).toBe(true);+ });+});diff --git a/tests/motion-seed.test.js b/tests/motion-seed.test.jsindex 80126c6f7..c8f3ee934 100644--- a/tests/motion-seed.test.js+++ b/tests/motion-seed.test.js@@ -26,8 +26,9 @@ import {rotationEpoch,motionPrompts,motionPromptById,+ assertSelfHostedLane,+ decodeJobEnvelope,} from '../api/_lib/motion-seed.js';-import { assertSelfHostedLane, decodeJobEnvelope } from '../scripts/gcp/seed-motion.mjs';const BODY_BONES = ['Hips', 'Spine', 'Spine1', 'Spine2', 'Neck', 'Head',