Skip to content

3D engine that AI agents drive

Make motion.tracks optional in the MCP schema (#1995)

Nguyen Xuan Ana7052de78275
diff --git a/changes/1995.md b/changes/1995.md
index 2f0455ee..00ab533a 100644
--- a/changes/1995.md
+++ b/changes/1995.md
@@ -1 +1,2 @@
- `scene_create` accepts camera, light and morph driver targets in `motion.drivers`, the ones `docs/agent-motion.md` documents, instead of failing with `recipe.motion.drivers.0.target: Invalid input` (#1995)
+- `motion.tracks` is optional in the MCP schema, so a motion made only of drivers no longer needs `tracks: []`; a motion with neither tracks nor drivers still fails and says to pass one (#1995)
diff --git a/docs/agent-motion.md b/docs/agent-motion.md
index 68701877..2269fcc9 100644
--- a/docs/agent-motion.md
+++ b/docs/agent-motion.md
@@ -460,7 +460,7 @@ A body node takes its pose from the recording. A node cannot have a body and a m
## Bounds and checks
The controller accepts durations between 0.1 and 30 seconds.
-A motion requires at least one track.
+A motion requires at least one track or driver (or an IK solver, constraint, layer, spring or drive); `tracks` can be left out of a motion made of drivers alone.
It can contain at most 128 tracks, 64 keys per track, and 2048 keys in total.
Values and tangents must remain finite at Float32 precision.
The scene integration must also enforce its total recipe byte budget.
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 077f1dc7..753e222a 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -663,7 +663,7 @@ const motion = z.strictObject({
motionTrack('camera', 'roll', finite, finite),
motionTrack('geometry', 'oceanTime', finite.min(-1e6).max(1e6), finite),
lookTrack,
- ], { error: motionTrackUnionMessage })).max(128),
+ ], { error: motionTrackUnionMessage })).max(128).optional().describe('Keyframe tracks; leave out for a motion made only of drivers, ik or constraints.'),
}).describe('One absolute-time procedural clip. Local node transforms propagate through parents. Cubic tangents are derivatives per second. Backend checks references, duplicate tracks, 2048 total keys and every sampled pose.');
const physicsBody = z.strictObject({
node: identifier.describe('Root node with a geometry; the collider is fitted to it and the body drives its pose.'),
diff --git a/src/agent-motion.js b/src/agent-motion.js
index 87545aab..c3988406 100644
--- a/src/agent-motion.js
+++ b/src/agent-motion.js
@@ -518,7 +518,7 @@ export function normalizeAgentMotion(input, recipe) {
const inputTracks = input.tracks ?? [];
denseArray(inputTracks, 128, 'Motion tracks');
if (!inputTracks.length && !input.layers?.length && !input.ik?.length && !input.springs && !input.constraints?.length && !input.drivers?.length && !drive) {
- throw invalidField('motion', input, 'at least one track, IK solver, constraint or driver, such as { "duration": 1, "tracks": [...] }; use null to clear it');
+ throw invalidField('motion', input, 'at least one track or driver (or an IK solver, constraint, layer, spring or drive), such as { "duration": 1, "tracks": [...] } or { "duration": 1, "drivers": [...] }; use null to clear it');
}
const nodes = new Set((recipe.nodes ?? []).map(node => node.id));
// A material track may also name the id of an asset.materials override, which gives a placed asset's material a handle.
diff --git a/tests/agent-motion-ik.test.js b/tests/agent-motion-ik.test.js
index c83cc72d..59712a14 100644
--- a/tests/agent-motion-ik.test.js
+++ b/tests/agent-motion-ik.test.js
@@ -159,7 +159,7 @@ test('recipes export and reload with their ik', () => {
test('mistakes say what to pass', () => {
const create = (ik, overrides) => createAgentScene(armRecipe({ duration: 1, tracks: [], ik }, overrides));
- assert.throws(() => createAgentScene(armRecipe({ duration: 1, tracks: [] })), /at least one track, IK solver, constraint or driver/);
+ assert.throws(() => createAgentScene(armRecipe({ duration: 1, tracks: [] })), /at least one track or driver/);
assert.throws(() => create([{ type: 'fabrik', target: [0, 0, 0] }]), /motion\.ik\[0\]\.type: got "fabrik"; expected one of two-bone, aim, chain or spline/);
assert.throws(() => create([armIk([0, 0, 0], { root: 'nope' })]), /motion\.ik\[0\]\.root: got "nope"; expected a node ID in this recipe/);
assert.throws(() => create([armIk({ node: 'nope' })]), /motion\.ik\[0\]\.target\.node: got "nope"; expected a node ID/);
diff --git a/tests/mcp-camera-drivers.test.js b/tests/mcp-camera-drivers.test.js
index 3bc4c6d4..39b691b4 100644
--- a/tests/mcp-camera-drivers.test.js
+++ b/tests/mcp-camera-drivers.test.js
@@ -24,7 +24,7 @@ function boxRecipe(drivers) {
materials: [{ id: 'white', color: [1, 1, 1], emission: 1, emissiveColor: [1, 1, 1] }],
nodes: [{ id: 'box', geometry: 'cube', material: 'white' }],
camera: { eye: [0, 0, 8], target: [0, 0, 0], fov: 40 },
- motion: { duration: 2, tracks: [], drivers },
+ motion: { duration: 2, drivers },
};
}
@@ -103,3 +103,13 @@ test('scene_create takes a light driver target and names what a camera eye drive
assert.equal(refused.isError, true);
assert.match(refused.content.find(item => item.type === 'text').text, /camera eye needs a component/);
});
+
+test('scene_create takes a driver-only motion without tracks and refuses a motion with neither tracks nor drivers', async () => {
+ const client = await sharedServer();
+ const driverOnly = boxRecipe([fovDriver]);
+ assert.equal(Object.hasOwn(driverOnly.motion, 'tracks'), false);
+ await call(client, 'scene_create', { recipe: driverOnly });
+ const refused = await client.callTool({ name: 'scene_create', arguments: { recipe: { ...boxRecipe([]), motion: { duration: 2 } } } });
+ assert.equal(refused.isError, true);
+ assert.match(refused.content.find(item => item.type === 'text').text, /at least one track or driver/);
+});