3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Let set-motion remove tracks by selector (#2288)
Nguyen Xuan An0e267fb6b497
diff --git a/changes/2288-remove-track.md b/changes/2288-remove-track.mdnew file mode 100644index 00000000..e99f2ade--- /dev/null+++ b/changes/2288-remove-track.md@@ -0,0 +1 @@+- `scene_apply` `set-motion` takes `removeTracks` selectors, so one camera or node track is dropped without sending the whole scene again (#2288)diff --git a/changes/2288-remove-track.size.md b/changes/2288-remove-track.size.mdnew file mode 100644index 00000000..b8d0d213--- /dev/null+++ b/changes/2288-remove-track.size.md@@ -0,0 +1,5 @@+- tool:scene_apply: one removeTracks field (238 bytes) lets an agent drop a single motion track in one apply instead of resending the whole scene with scene_create.+- tool-total: the same 238 bytes in scene_apply.+- scene:agent-scene: the track removal code loads on demand; the core only gains the branch that calls it and the report line (about 225 bytes gzip).+- scene:agent-scene+lazy: the on-demand chunk adds about 900 bytes gzip, loaded only by a batch that names removeTracks.+- goal:agent-scene: removing one track otherwise costs a full scene_create round trip, so the bytes buy a visible agent capability.diff --git a/docs/agent-motion.md b/docs/agent-motion.mdindex b1c8f331..46934004 100644--- a/docs/agent-motion.md+++ b/docs/agent-motion.md@@ -29,6 +29,8 @@ Omitting `motionTime` preserves the current preview pose.Its bounds remain in `authored-base-world` space, independent of the sampled pose.`set-motion` requires a complete motion record or explicit `null` to clear it.+To drop only some tracks, give `removeTracks` instead of `motion`: selectors such as `{ kind: 'camera' }` or `{ kind: 'node', id: 'cube', property: 'translation' }`, where a field left out matches any track.+The other tracks and fields stay. A selector that matches nothing throws an error that lists the tracks there are. Giving both `motion` and `removeTracks` is refused.The final batch must resolve every track reference, including after node or material removal.Failed edits or seeks preserve the previous recipe, rendered pose and revisions.diff --git a/docs/mcp.md b/docs/mcp.mdindex eaf7865b..6c9186b6 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -218,7 +218,7 @@ A `mesh` geometry starts from one of the others as `base` and replays an edit loGeometry fields remain flat inside each geometry record.Set operations use `set-node`, `set-material`, or `set-camera`, with fields directly on each command.-`set-motion` accepts a complete motion record or `null` to clear it.+`set-motion` accepts a complete motion record or `null` to clear it, or `removeTracks` selectors to drop some tracks {since 0.22.0}.`scene_look` can seek procedural `motionTime` without changing revisions. Omission preserves the last preview pose.An explicit `null` restores the authored base pose. Release `0.8.0` also supports imported source-node motion.Imported clip sampling remains available through `set-animation`.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 79aac447..995be9a3 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -841,7 +841,8 @@ const nodeOperations = (nodeFieldShape, nodeSchema) => [const otherOperations = [materialListed(z.strictObject({ type: z.literal('set-material'), id: identifier, ...materialFields }, { error: flatFieldsHint('set-material', 'material') }), 'Change a material.', { type: z.literal('set-material'), id: identifier }),z.strictObject({ type: z.literal('set-camera'), ...cameraFields }),- z.strictObject({ type: z.literal('set-motion'), motion: recipeMotionReference.nullable() }),+ z.strictObject({ type: z.literal('set-motion'), motion: recipeMotionReference.nullable().optional(), removeTracks: z.array(z.record(z.string(), z.string())).min(1).max(64).optional().describe('Instead of motion: selectors { kind, id, property } of tracks to drop.') })+ .refine(operationBody => (operationBody.motion !== undefined) !== (operationBody.removeTracks !== undefined), { message: 'set-motion takes one of motion or removeTracks.' }),z.strictObject({ type: z.literal('bake-motion'), nodes: z.array(identifier).min(1).max(32), start: nonnegative.optional(), end: nonnegative.optional(), step: positive.optional(), tolerance: z.record(z.string(), z.number()).optional() }),z.strictObject({type: z.literal('fracture-node'), node: identifier, cells: z.number().int().min(2).max(64), strength: positive,diff --git a/src/agent-apply-report.js b/src/agent-apply-report.jsindex da4d0c3f..4bc6dbb1 100644--- a/src/agent-apply-report.js+++ b/src/agent-apply-report.js@@ -66,7 +66,7 @@ function targetOf(operation) {}// Applies one operation to the working copy and says what it changed. Fields it cannot judge count as changed.-function describeOperation(working, operation, maxText) {+function describeOperation(working, operation, maxText, after) {const { type } = operation;const add = /^add-(node|material|geometry)$/.exec(type);if (add) {@@ -100,6 +100,14 @@ function describeOperation(working, operation, maxText) {for (const name of differing) target[name] = structuredClone(operation[name]);return { changed: shortList(differing, maxText) };}+ if (type === 'set-motion' && Object.hasOwn(operation, 'removeTracks')) {+ // The selectors are resolved by the scene when it applies the batch; the report reads the result from the recipe after it.+ const before = working.motion?.tracks?.length ?? 0;+ const remaining = after.motion;+ if (remaining) working.motion = structuredClone(remaining);+ else delete working.motion;+ return { changed: `removed ${before - (remaining?.tracks?.length ?? 0)} motion tracks` };+ }if (Object.hasOwn(OWN_SECTIONS, type)) {const name = OWN_SECTIONS[type];const next = operation[name] === null ? undefined : operation[name];@@ -153,7 +161,7 @@ export function describeApplication(before, after, operations, limits = APPLY_REconst working = structuredClone(before);for (const collection of Object.values(COLLECTIONS)) working[collection] ??= [];const entries = operations.map((operation, index) => {- const outcome = describeOperation(working, operation, limits.maxText);+ const outcome = describeOperation(working, operation, limits.maxText, after);const target = targetOf(operation);return { i: index, op: operation.type, ...(target === undefined ? {} : { target }), ...outcome };});diff --git a/src/agent-asset.js b/src/agent-asset.jsindex 07ac918e..a74112de 100644--- a/src/agent-asset.js+++ b/src/agent-asset.js@@ -985,6 +985,8 @@ export function createAgentAssetScene(asset, inputRecipe, { sources } = {}) {candidate.root[field] = operation[field];}}+ } else if (operation.type === 'set-motion' && Object.hasOwn(operation, 'removeTracks')) {+ candidate.motion = agentSceneModule('motionTrackRemoval').removeMotionTracks(operation, candidate.motion, path);} else if (operation.type === 'set-motion') {knownKeys(operation, ['type', 'motion'], path);if (!Object.hasOwn(operation, 'motion')) {diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 02bf804f..01e3ec2b 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -391,6 +391,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({}),motionModifiers: 'Track extrapolation constant|linear; modifiers [{type: cycles|stepped|noise|generator|limits|envelope, ...}], 8 at most; cycles and stepped remap time first.',motionLimits: Object.freeze({ maxTracks: 128, maxKeyframesPerTrack: 64, maxKeyframes: 2048, maxDuration: 30 }),+ motionRemoveTracks: 'scene_apply set-motion { removeTracks: [{ kind?, id?, property? }] } (64 at most, instead of motion) drops the tracks whose fields equal the selector, a field left out matching any: { kind: "camera" } drops the camera track, { kind: "node", id: "cube" } every track of that node. Other motion fields stay; a selector that matches nothing is an error listing the tracks; no motion left becomes null.',motionBake: 'scene_apply bake-motion { nodes (32 at most), start 0, end (motion or physics duration), step 1/30 (512 samples), tolerance { position m, angle deg, scale } }: samples tracks, IK, constraints, drivers and physics into LINEAR tracks and removes those sources (an IK solver or the physics world only when all its nodes are baked). tolerance drops keys within it; without it a track keeps every sample, 64 keys at most. Procedural scenes only.',springBones: 'motion.springs { chains: [{ bones: [node IDs root to tip, each the child of the one before, 16 per chain, 64 in all], stiffness 0-4 (1), dragForce 0-1 (0.4), gravityPower 0-2 (0), gravityDir [0,-1,0], hitRadius (0.02), tipLength (0.07), colliders: [ids] }] (16 at most), colliders: [{ id, bone, type sphere|capsule, offset, radius, tail }] }: VRM spring bones for hair and tails; fixed 1/60 s steps, sample times in increasing order; bake-motion bakes whole chains; needs loadAgentSceneModules.',});diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex bc7fcd70..47fc379e 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -9,6 +9,7 @@ const MODULE_LOADERS = {text: () => import('./text-geometry.js'),motion: () => import('./agent-motion.js'),motionBake: () => import('./agent-motion-bake.js'),+ motionTrackRemoval: () => import('./motion-track-removal.js'),springs: () => import('./spring-bones.js'),settle: () => import('./agent-settle.js'),drive: () => import('./agent-drive.js'),@@ -78,6 +79,7 @@ const MODULE_MARKERS = {text: ['"type":"text"'],motion: ['"motion":{', '"bake-motion"', '"add-explosion"'],motionBake: ['"bake-motion"'],+ motionTrackRemoval: ['"removeTracks"'],springs: ['"springs":{'],settle: ['"type":"settle"'],drive: ['"drive":{'],diff --git a/src/agent-scene.js b/src/agent-scene.jsindex c274d27a..5342fb6d 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -2213,6 +2213,10 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {const removals = [];for (const operation of operations) {const section = Object.hasOwn(NULLABLE_SECTION_OPERATIONS, operation.type) ? NULLABLE_SECTION_OPERATIONS[operation.type] : null;+ if (operation.type === 'set-motion' && Object.hasOwn(operation, 'removeTracks')) {+ candidate.motion = agentSceneModule('motionTrackRemoval').removeMotionTracks(operation, candidate.motion);+ continue;+ }if (section) {knownKeys(operation, ['type', section], 'operation');if (!Object.hasOwn(operation, section)) {diff --git a/src/motion-track-removal.js b/src/motion-track-removal.jsnew file mode 100644index 00000000..4202d1fa--- /dev/null+++ b/src/motion-track-removal.js@@ -0,0 +1,59 @@+// The removeTracks field of a set-motion operation: drop the motion tracks that match selectors, keep everything else.+// A leaf module, so scripts/mcp-server.mjs and the scene backends can share it without pulling in the motion compiler.+import { invalidField } from './field-error.js';++export const MAXIMUM_TRACK_SELECTORS = 64;+const SELECTOR_FIELDS = ['kind', 'id', 'property'];+const NO_MOTION_KEYS = new Set(['duration', 'loop', 'tracks']);++function describeTrack(track) {+ return [track.kind, track.id, track.property].filter(part => part !== undefined).join('.');+}++function describeSelector(selector) {+ return JSON.stringify(selector);+}++function assertSelectors(selectors, path) {+ if (!Array.isArray(selectors) || selectors.length < 1 || selectors.length > MAXIMUM_TRACK_SELECTORS) {+ throw invalidField(path, selectors, `a list of 1 to ${MAXIMUM_TRACK_SELECTORS} track selectors, such as [{ "kind": "camera" }]`, TypeError);+ }+ selectors.forEach((selector, index) => {+ const isPlain = selector !== null && typeof selector === 'object' && !Array.isArray(selector);+ const fields = isPlain ? Object.keys(selector) : [];+ const valid = isPlain+ && fields.length > 0+ && fields.every(field => SELECTOR_FIELDS.includes(field) && typeof selector[field] === 'string' && selector[field].length > 0);+ if (!valid) {+ throw invalidField(`${path}[${index}]`, selector, 'an object with some of kind, id and property as strings, such as { "kind": "node", "id": "cube", "property": "translation" }', TypeError);+ }+ });+}++function selectorMatches(selector, track) {+ return SELECTOR_FIELDS.every(field => selector[field] === undefined || selector[field] === track[field]);+}++/** The motion a set-motion operation with removeTracks leaves: the tracks its selectors match are gone; null when no motion content is left. */+export function removeMotionTracks(operation, motion, path = 'operation') {+ const keys = Object.keys(operation);+ if (keys.some(key => key !== 'type' && key !== 'removeTracks')) {+ throw invalidField(`${path}.removeTracks`, 'removeTracks next to other fields', 'one of motion (replace all motion, or null) or removeTracks (drop some tracks), not both');+ }+ assertSelectors(operation.removeTracks, `${path}.removeTracks`);+ return motionWithoutTracks(motion, operation.removeTracks, `${path}.removeTracks`);+}++/** The motion without the tracks the selectors match; null when no motion content is left. */+export function motionWithoutTracks(motion, selectors, path = 'operation.removeTracks') {+ const tracks = Array.isArray(motion?.tracks) ? motion.tracks : [];+ const listed = tracks.length > 0 ? tracks.map(describeTrack).join(', ') : 'none (the scene has no motion tracks)';+ const unmatched = selectors.filter(selector => !tracks.some(track => selectorMatches(selector, track)));+ if (unmatched.length > 0) {+ throw invalidField(path, unmatched.map(describeSelector).join(', '), `selectors that each match a track the scene has; its tracks are: ${listed}`);+ }+ const kept = tracks.filter(track => !selectors.some(selector => selectorMatches(selector, track)));+ const remaining = { ...motion, tracks: kept };+ const hasOtherMotion = Object.keys(remaining).some(key => !NO_MOTION_KEYS.has(key) && remaining[key] !== undefined);+ return kept.length === 0 && !hasOtherMotion ? null : remaining;+}diff --git a/tests/agent-asset-motion.test.js b/tests/agent-asset-motion.test.jsindex 8578360a..703838eb 100644--- a/tests/agent-asset-motion.test.js+++ b/tests/agent-asset-motion.test.js@@ -2,6 +2,7 @@ import test from 'node:test';import assert from 'node:assert/strict';import { parseGltf } from '../src/gltf.js';import { createAgentAssetScene } from '../src/agent-asset.js';+import { loadAgentSceneModules } from '../src/agent-scene-modules.js';import { skinnedStripAsset } from './fixtures/skinned-strip.js';const recipe = () => ({ format: 'crucible.asset', schemaVersion: 1, assetId: 'ac'.repeat(32) });@@ -148,3 +149,17 @@ test('independent imported and authored clocks stage once without an invalid intassert.deepEqual(pose(scene), final);} finally { asset.dispose(); }});++test('set-motion removeTracks drops one asset track and names the tracks there are when a selector misses', async () => {+ await loadAgentSceneModules([{ type: 'set-motion', removeTracks: [] }]);+ const asset = await parseGltf(skinnedStripAsset());+ try {+ const scene = createAgentAssetScene(asset, { ...recipe(), motion: motion() });+ assert.throws(+ () => scene.apply([{ type: 'set-motion', removeTracks: [{ kind: 'camera' }] }], { expectedRevision: 0 }),+ error => error.message.includes('camera') && error.message.includes('node.node-3.rotation'),+ );+ scene.apply([{ type: 'set-motion', removeTracks: [{ kind: 'node', id: 'node-3' }] }], { expectedRevision: 0 });+ assert.equal(scene.exportRecipe().motion ?? null, null);+ } finally { asset.dispose(); }+});diff --git a/tests/agent-motion-remove-tracks.test.js b/tests/agent-motion-remove-tracks.test.jsnew file mode 100644index 00000000..d9add42d--- /dev/null+++ b/tests/agent-motion-remove-tracks.test.js@@ -0,0 +1,66 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { describeApplication } from '../src/agent-apply-report.js';+import { motionWithoutTracks } from '../src/motion-track-removal.js';++const keys = (start, end) => [{ time: 0, value: start }, { time: 1, value: end }];++function applyTo(scene, operations) {+ return scene.apply(operations, { expectedRevision: scene.revision });+}++function sceneWithTwoTracks() {+ return createAgentScene({+ format: 'crucible.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box' }],+ materials: [{ id: 'paint', color: [0.5, 0.5, 0.5] }],+ nodes: [{ id: 'cube', geometry: 'box', material: 'paint' }],+ camera: { eye: [4, 3, 5], target: [0, 0, 0] },+ motion: {+ duration: 1,+ tracks: [+ { kind: 'camera', property: 'fov', keyframes: keys(40, 60) },+ { kind: 'node', id: 'cube', property: 'translation', keyframes: keys([0, 0, 0], [1, 0, 0]) },+ ],+ },+ });+}++test('removeTracks drops the matching camera track and keeps the node track', () => {+ const scene = sceneWithTwoTracks();+ const before = scene.exportRecipe();+ const operations = [{ type: 'set-motion', removeTracks: [{ kind: 'camera' }] }];+ applyTo(scene, operations);+ const tracks = scene.exportRecipe().motion.tracks;+ assert.deepEqual(tracks.map(track => `${track.kind}.${track.property}`), ['node.translation']);+ assert.match(JSON.stringify(describeApplication(before, scene.exportRecipe(), operations)), /removed 1 motion tracks/);+});++test('removing every track leaves no motion', () => {+ const scene = sceneWithTwoTracks();+ applyTo(scene, [{ type: 'set-motion', removeTracks: [{ kind: 'camera' }, { kind: 'node', id: 'cube', property: 'translation' }] }]);+ assert.equal(scene.exportRecipe().motion ?? null, null);+});++test('a selector that matches nothing names itself and lists the tracks there are', () => {+ const scene = sceneWithTwoTracks();+ assert.throws(+ () => applyTo(scene, [{ type: 'set-motion', removeTracks: [{ kind: 'node', id: 'ghost' }] }]),+ error => error.message.includes('ghost') && error.message.includes('camera.fov, node.cube.translation'),+ );+ assert.equal(scene.exportRecipe().motion.tracks.length, 2);+});++test('motion and removeTracks together are refused, and so is an empty or unknown selector', () => {+ const scene = sceneWithTwoTracks();+ assert.throws(() => applyTo(scene, [{ type: 'set-motion', motion: null, removeTracks: [{ kind: 'camera' }] }]), /not both/);+ assert.throws(() => applyTo(scene, [{ type: 'set-motion', removeTracks: [] }]), /1 to 64 track selectors/);+ assert.throws(() => applyTo(scene, [{ type: 'set-motion', removeTracks: [{ colour: 'red' }] }]), /kind, id and property/);+});++test('other motion fields survive when some tracks remain or only tracks were set', () => {+ const motion = { duration: 2, loop: true, tracks: [{ kind: 'camera', property: 'fov' }], ik: [{ id: 'leg' }] };+ assert.deepEqual(motionWithoutTracks(motion, [{ kind: 'camera' }]), { duration: 2, loop: true, tracks: [], ik: [{ id: 'leg' }] });+});diff --git a/tests/mcp-tools.test.js b/tests/mcp-tools.test.jsindex 2d755170..795b78e2 100644--- a/tests/mcp-tools.test.js+++ b/tests/mcp-tools.test.js@@ -381,9 +381,16 @@ test('real SDK round trip authors motion, seeks without revisions and rejects unassert.equal(exported.structuredContent.recipe.motion.tracks[0].property, 'translation');await rejected(client, 'scene_apply', { sessionId, expectedRevision: 0, operations: [{ type: 'set-motion',motion: { ...motion, tracks: [{ ...motion.tracks[0], javascript: 'run()' }] } }] });- const cleared = await client.callTool({ name: 'scene_apply', arguments: { sessionId, expectedRevision: 0,+ await rejected(client, 'scene_apply', { sessionId, expectedRevision: 0, operations: [{ type: 'set-motion', motion: null, removeTracks: [{ kind: 'node' }] }] });+ const trimmed = await client.callTool({ name: 'scene_apply', arguments: { sessionId, expectedRevision: 0,+ operations: [{ type: 'set-motion', removeTracks: [{ kind: 'node', id: 'mesh' }] }] } });+ assert.equal(trimmed.isError, undefined);+ assert.equal(trimmed.structuredContent.revision, 1);+ const withoutTracks = await client.callTool({ name: 'scene_export_recipe', arguments: { sessionId } });+ assert.equal(withoutTracks.structuredContent.recipe.motion ?? null, null);+ const cleared = await client.callTool({ name: 'scene_apply', arguments: { sessionId, expectedRevision: 1,operations: [{ type: 'set-motion', motion: null }] } });- assert.equal(cleared.structuredContent.revision, 1);+ assert.equal(cleared.structuredContent.revision, 2);});test('real SDK calls preserve atomic revisions, checkpoints, recipe snapshots and PNG content', async context => {