Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
index 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.md
index 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`.
## Drivers
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 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.js
index 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.js
index 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());
});