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): 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.js
index 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.js
index 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.SI
export 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.js
new file mode 100644
index 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.js
index 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',