3D engine that AI agents drive
Carry the seven new constraint types' fields in args to keep tool schemas small (#595)
Nguyen Xuan An4cb866054810
diff --git a/changes/595-more-constraints.size.md b/changes/595-more-constraints.size.mdindex 8756a8df..d0cc3c3b 100644--- a/changes/595-more-constraints.size.md+++ b/changes/595-more-constraints.size.md@@ -1,2 +1,3 @@-- scene:agent-scene+lazy: seven constraint operators and their validation load only with motion, each a few hundred bytes of the 1.6 KB (#595)-- tool:scene_motion: one constraint entry names the seven new types and their optional fields, so strict-mode clients see them (#595)+- scene:agent-scene+lazy: seven constraint operators and their validation load only with motion (#595)+- tool:scene_create: the seven new type names join the floor entry's type enum and one args record carries their fields, validated in node-constraints with errors that list the allowed fields (#595)+- tool-total: the same enum and args record, counted once (#595)diff --git a/docs/agent-motion.md b/docs/agent-motion.mdindex 9f5136fe..0bb6d093 100644--- a/docs/agent-motion.md+++ b/docs/agent-motion.md@@ -285,6 +285,10 @@ own transform under its parent.| `transformation` | `target`, `source`, `destination` (`translation`, `rotation` or `scale`), `map` (the source axis for each destination x, y, z), `fromMin`, `fromMax` (per source axis), `toMin`, `toMax` (per destination axis), `space` | The target's channel, clamped to its range, sets the node's channel over its range. Rotation is Euler degrees || `action` | `target`, `source`, `axis`, `min`, `max`, `destination`, `keys` (2 to 16 of `{ at, value }`, `at` 0 to 1 rising), `space` | Read the curve where the target's channel sits between `min` and `max`; its value sets the node's channel |+Over MCP, the seven newest types (`copy_transforms` to `action`) take `node`, `type` and `args`, an object holding every other+field above (`target`, `influence` and the type's own); the validator names the allowed fields when one is wrong. Direct fields+also work from code, but not both for the same key.+Not covered yet: `use_*` switches on `child_of`, `damped_track`, bone sub-targets and `head_tail`.## Driversdiff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex a4017429..df804a95 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -477,8 +477,6 @@ const axisName = z.enum(['x', 'y', 'z']);const axisNames = z.array(axisName).min(1).max(3);const signedAxis = z.enum(['+x', '-x', '+y', '-y', '+z', '-z']);const constraintSpace = z.enum(['world', 'local']).optional();-const constraintChannel = z.enum(['translation', 'rotation', 'scale']).optional();-const number1e6 = z.number().min(-1e6).max(1e6);const limitRange = z.tuple([z.number().min(-1e6).max(1e6), z.number().min(-1e6).max(1e6)]).optional();// A bounded expression: data only, never code. See docs/agent-motion.md for the operators.const expression = z.lazy(() => z.union([@@ -496,17 +494,7 @@ const constraint = z.discriminatedUnion('type', [z.strictObject({ type: z.literal('limit_rotation'), node: identifier, x: degreeRange.optional(), y: degreeRange.optional(), z: degreeRange.optional(), space: constraintSpace, influence }),z.strictObject({ type: z.literal('track_to'), node: identifier, target: identifier, trackAxis: signedAxis.optional(), upAxis: axisName.optional(), worldUp: vector3.optional(), influence }),z.strictObject({ type: z.literal('child_of'), node: identifier, target: identifier, inverse: z.enum(['rest', 'none']).optional(), influence }),- z.strictObject({ type: z.literal('floor'), node: identifier, target: identifier, axis: signedAxis.optional(), offset: z.number().min(-1e6).max(1e6).optional(), influence }),- // One entry for the seven newer types; the motion validator checks which fields each one needs.- z.strictObject({- type: z.enum(['copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action']), node: identifier, target: identifier.optional(), influence,- distance: number1e6.optional(), mode: z.enum(['inside', 'outside', 'surface']).optional(), x: limitRange, y: limitRange, z: limitRange, space: constraintSpace,- restLength: number1e6.optional(), volume: z.enum(['xz', 'x', 'z', 'none']).optional(), bulge: z.number().min(0).max(4).optional(), worldUp: vector3.optional(),- trackAxis: signedAxis.optional(), lockAxis: axisName.optional(), axis: axisName.optional(),- source: constraintChannel, destination: constraintChannel, map: z.array(axisName).length(3).optional(),- fromMin: vector3.optional(), fromMax: vector3.optional(), toMin: vector3.optional(), toMax: vector3.optional(),- min: number1e6.optional(), max: number1e6.optional(), keys: z.array(z.strictObject({ at: unit, value: vector3 })).min(2).max(16).optional(),- }),+ z.strictObject({ type: z.enum(['floor', 'copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action']), node: identifier, target: identifier.optional(), axis: signedAxis.optional(), offset: z.number().min(-1e6).max(1e6).optional(), influence, args: z.record(z.string(), z.unknown()).optional() }),]);const driver = z.strictObject({target: z.union([@@ -540,7 +528,7 @@ const ikSolver = z.discriminatedUnion('type', [const motion = z.strictObject({duration: z.number().min(0.1).max(30),ik: z.array(ikSolver).max(16).optional().describe('Inverse kinematics run after the tracks and any selected clip, in order, on recipes and imported assets. IDs are recipe node IDs or an asset\'s node-N IDs; find them with scene_inspect kind hierarchy. scene_inspect reports motionIk: whether each solver reaches its target across the clip.'),- constraints: z.array(constraint).max(32).optional().describe('Blender-style node constraints, run in order after the tracks, drivers and IK, each on the pose the one before left: copy_location, copy_rotation, copy_scale, limit_location, limit_rotation, track_to, child_of, floor, and more (scene_capabilities). Euler angles are XYZ in degrees; space defaults to world. Same result at any time, so seeking equals playing.'),+ constraints: z.array(constraint).max(32).optional().describe('Blender-style node constraints, run in order after the tracks, drivers and IK, each on the pose the one before left: copy_location, copy_rotation, copy_scale, limit_location, limit_rotation, track_to, child_of, floor. Euler angles are XYZ in degrees; space defaults to world. Same result at any time, so seeking equals playing.'),drivers: z.array(driver).max(32).optional().describe('Drive one node component or material property from a bounded expression over time and other nodes\' values. A driven property cannot also have a track.'),loop: z.boolean().optional(),tracks: z.array(z.union([diff --git a/src/node-constraints.js b/src/node-constraints.jsindex a8cb701a..a718e4b9 100644--- a/src/node-constraints.js+++ b/src/node-constraints.js@@ -83,8 +83,21 @@ function influenceFrom(value, nodeIds, label) {return structuredClone(value);}-function normalizeConstraint(input, position, movableIds, visibleIds) {+const ARGUMENT_TYPES = ['copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action'];++// The newer types may carry their own fields in `args`, so the MCP schema stays small; they merge into the flat shape.+function withArguments(input, label) {+ if (!input || input.args === undefined || !ARGUMENT_TYPES.includes(input.type)) return input;+ knownKeys(input.args, ['influence', ...CONSTRAINT_FIELDS[input.type]], `${label} args`);+ const { args, ...rest } = input;+ const clash = Object.keys(args).find(key => Object.hasOwn(rest, key));+ if (clash) throw new RangeError(`${label} gives ${clash} both directly and in args.`);+ return { ...rest, ...args };+}++function normalizeConstraint(rawInput, position, movableIds, visibleIds) {const label = `Motion constraint ${position}`;+ const input = withArguments(rawInput, label);if (!input || !Object.hasOwn(CONSTRAINT_FIELDS, input.type)) {throw new RangeError(`${label} type must be one of ${CONSTRAINT_TYPES.join(', ')}.`);}diff --git a/tests/agent-motion-constraints-more.test.js b/tests/agent-motion-constraints-more.test.jsindex fb60aff6..aa9b56d2 100644--- a/tests/agent-motion-constraints-more.test.js+++ b/tests/agent-motion-constraints-more.test.js@@ -114,6 +114,14 @@ test('the new constraints refuse bad fields', () => {refuses({ type: 'copy_transforms' }, /target/);});+test('the newer types accept their fields in args, the shape the MCP schema uses', () => {+ const nested = sampled([{ ...owner, translation: [6, 8, 0] }, targetAt([0, 0, 0])], { type: 'limit_distance', args: { target: 'target', distance: 5, influence: 1 } });+ assertClose(translationOf(nested), [3, 4, 0], 'args');+ const pair = [owner, targetAt([1, 0, 0])];+ assert.throws(() => sampled(pair, { type: 'limit_distance', args: { target: 'target', distance: 5, speed: 1 } }), /Allowed fields/);+ assert.throws(() => sampled(pair, { type: 'limit_distance', target: 'target', args: { target: 'target', distance: 5 } }), /both directly and in args/);+});+test('scene_capabilities lists every constraint type', () => {assert.deepEqual([...AGENT_SCENE_CAPABILITIES.motionConstraints].sort(), [...CONSTRAINT_TYPES].sort());});