Skip to content

3D engine that AI agents drive

Accept every mesh edit op in mesh_edit and drop two refused types from the operations topic (#2126)

Nguyen Xuan An0aa37d5cd829
diff --git a/changes/2126.md b/changes/2126.md
new file mode 100644
index 00000000..fec46049
--- /dev/null
+++ b/changes/2126.md
@@ -0,0 +1 @@
+- `mesh_edit` takes `split_edges`, `flatten`, `circularize`, `delete_loose` and `unsubdivide` like a recipe geometry edit does, its op list is checked against the engine list at load, and `scene_capabilities operations` no longer lists `edit-mesh` and `set-mesh-stack`, which `scene_apply` refuses (they are the `mesh_edit` and `mesh_stack` tools) (#2126)
diff --git a/changes/2126.size.md b/changes/2126.size.md
new file mode 100644
index 00000000..b5524ccd
--- /dev/null
+++ b/changes/2126.size.md
@@ -0,0 +1 @@
+- tool:mesh_edit: the five missing op names (split_edges, delete_loose, flatten, unsubdivide, circularize) are 67 bytes in the op enum; the engine and docs already list them and agents got an enum error without them.
diff --git a/docs/mesh.md b/docs/mesh.md
index d13609f8..134a3e89 100644
--- a/docs/mesh.md
+++ b/docs/mesh.md
@@ -567,6 +567,7 @@ A recipe geometry of type `mesh` starts from a primitive or profile and replays
Edges bending more than `smoothAngle` degrees (default 30, or 180 for a mesh with an `ocean` edit or stack node, so a choppy sea keeps its smooth normals) render hard. `mesh_edit` appends edits to such a
geometry (or replaces its log with `replace: true`) as one atomic revision, so checkpoints and `expectedRevision`
work as for `scene_apply`. It returns the render status and the mesh report below, including one result per edit.
+`mesh_edit` takes every op in the edit table; its op list comes from the same list as `scene_capabilities meshEdits`. `scene_apply` has no `edit-mesh` or `set-mesh-stack` type in MCP: those are the `mesh_edit` and `mesh_stack` tools.
`mesh_inspect` runs the same conversion and lint on the geometries of a procedural recipe scene and returns one
compact record per geometry:
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index c92fb7d4..1a1f0230 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -13,7 +13,7 @@ import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import packageMetadata from '../package.json' with { type: 'json' };
-import { MODIFIER_OPERATIONS } from '../src/mesh-operations.js';
+import { MESH_EDIT_OPERATIONS, MODIFIER_OPERATIONS } from '../src/mesh-operations.js';
import { VIEW_TRANSFORM_NAMES, LOOK_NAMES } from '../src/view-transform-names.js';
import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, CATALOG_FILE_ID } from '../src/look-catalog.js';
import { MATERIAL_PATTERN_TYPES, MATERIAL_MAPPINGS, LIGHTING_SETUP_NAMES, RENDER_PASS_NAMES, RENDER_OUTPUT_FORMATS, MAXIMUM_JOB_FPS, VIDEO_ENCODERS, MAXIMUM_JOB_SIDE, maximumMemoryMiB, memoryRangeError, MAXIMUM_STILLS_FRAMES } from '../src/agent-scene-capabilities.js';
@@ -385,6 +385,7 @@ const editName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/).optional(
const edgeRule = z.record(z.string(), z.unknown()).describe('Edge rule: {"all":true}, {"angle":30}, {"along":[x,y,z]}, {"between":[faceRule,faceRule]}, {"boundaryOf":faceRule} or {"open":true} for boundary edges (also {"open":{"inside":{"min":[x,y,z],"max":[x,y,z]}}}).');
const shortSelect = z.record(z.string(), z.unknown()).describe('Face rule, as in set_position.');
const shortField = z.union([finite, z.record(z.string(), z.unknown())]);
+const vertexRule = z.record(z.string(), z.unknown()).describe('Vertex rule: {"all":true}, {"vertices":[indices]}, {"valence":2} or {"inside":{"min":[x,y,z],"max":[x,y,z]}}.');
const meshEdit = z.discriminatedUnion('op', [
z.strictObject({ op: z.literal('extrude_face_region'), select: selectRule.optional(), name: editName, offset: finite.describe('Distance along each connected region\'s average normal (negative pushes in).'), direction: vector3.optional().describe('Move along this direction instead of the normal.'), alongNormals: z.boolean().optional().describe('Move each vertex along its own normal instead, keeping the region joined: use for rings and curved bands.') }),
z.strictObject({ op: z.literal('extrude_individual'), select: selectRule.optional(), name: editName, offset: finite.describe('Distance along each face\'s own normal.'), direction: vector3.optional() }),
@@ -428,6 +429,11 @@ const meshEdit = z.discriminatedUnion('op', [
z.strictObject({ op: z.literal('symmetrize'), name: editName, axis: z.enum(['x', 'y', 'z']).optional(), keep: z.enum(['positive', 'negative']).optional().describe('Side of the plane kept and mirrored. Defaults to positive.'), distance: bounded(0, 1).optional().describe('Vertices this close to the plane count as on it. Defaults to 0.0001.') }).describe('Cut at the plane through the origin, drop the other half and mirror the kept half. Mirrored faces get <name>.mirrored.'),
z.strictObject({ op: z.literal('scale_elements'), select: selectRule.optional(), scale: finite.describe('Factor above 0 about each connected group of selected faces.') }).describe('Scale connected groups of selected faces about their own centres.'),
z.strictObject({ op: z.literal('extrude_edges'), name: editName, edges: edgeRule.describe('Edges to extrude, usually {"open":true} for a boundary.'), offset: vector3.describe('Where the copied vertices move.') }).describe('Extrude edges into quads, tagged <name>.side.'),
+ z.strictObject({ op: z.literal('split_edges'), name: editName, edges: edgeRule.describe('Edges to open.') }).describe('Open the surface along these edges.'),
+ z.strictObject({ op: z.literal('delete_loose') }).describe('Remove vertices no face uses.'),
+ z.strictObject({ op: z.literal('flatten'), verts: vertexRule, normal: vector3.optional().describe('Plane normal.'), factor: unit.optional().describe('0 to 1, default 1.') }).describe('Move vertices onto a plane.'),
+ z.strictObject({ op: z.literal('unsubdivide') }).describe('Reverse one Catmull-Clark level.'),
+ z.strictObject({ op: z.literal('circularize'), verts: vertexRule, factor: unit.optional().describe('0 to 1, default 1.'), regular: z.boolean().optional().describe('Default true.') }).describe('Put each closed loop of vertices on a circle.'),
z.strictObject({ op: z.literal('tag'), select: selectRule, name: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/).describe('Tag to add to the selected faces.') }),
z.strictObject({
op: z.literal('boolean'), name: editName,
@@ -505,6 +511,14 @@ const stackNodeUnion = z.union([z.discriminatedUnion('op', stackNodes), modifier
const meshEditUnion = z.union([z.discriminatedUnion('op', [...meshEdit.options, ...stackNodes]), modifierRecord]);
const stackOperationNames = [...stackNodes.map(node => node.shape.op.value), ...Object.keys(MODIFIER_OPERATIONS)];
const editOperationNames = [...meshEdit.options.map(option => option.shape.op.value), ...stackOperationNames];
+// The tool's op list must be the engine's list (MESH_EDIT_OPERATIONS, also what scene_capabilities meshEdits reports): an op the engine
+// takes but this schema lacks, or the reverse, is refused here at load instead of by an agent mid-edit.
+const engineOperationNames = Object.keys(MESH_EDIT_OPERATIONS);
+const missingFromSchema = engineOperationNames.filter(name => !editOperationNames.includes(name));
+const missingFromEngine = editOperationNames.filter(name => !engineOperationNames.includes(name));
+if (missingFromSchema.length > 0 || missingFromEngine.length > 0) {
+ throw new Error(`mesh_edit schema and MESH_EDIT_OPERATIONS differ: schema lacks [${missingFromSchema.join(', ')}], engine lacks [${missingFromEngine.join(', ')}]. Add the op to both.`);
+}
const meshStack = z.array(listed('meshStack', stackNodeUnion, 'Stack node { op, ...fields }; fields per op: scene_capabilities meshStack.', { op: z.enum(stackOperationNames) })).max(16);
const meshEdits = z.array(listed('meshEdit', meshEditUnion, 'Edit { op, ...fields }, applied in order; fields per op: scene_capabilities meshEdit, or meshEdit.<op> for one op.', { op: z.enum(editOperationNames) })).max(64);
// The full edit and stack schemas live in mesh_edit and mesh_stack. Repeating them in every recipe cost about 45 KB
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index 4c9e755d..1a1146b1 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -261,7 +261,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
operations: Object.freeze([
'set-node', 'set-material', 'set-camera', 'add-node', 'remove-node',
'add-geometry', 'remove-geometry', 'add-material', 'remove-material',
- 'set-environment', 'set-effects', 'set-shadow', 'set-motion', 'set-armatures', 'set-physics', 'set-cloth', 'set-timeline', 'set-particles', 'set-bake', 'set-post-passes', 'set-game', 'edit-mesh', 'set-mesh-stack', 'bake-motion', 'fracture-node', 'add-explosion', 'settle',
+ 'set-environment', 'set-effects', 'set-shadow', 'set-motion', 'set-armatures', 'set-physics', 'set-cloth', 'set-timeline', 'set-particles', 'set-bake', 'set-post-passes', 'set-game', 'bake-motion', 'fracture-node', 'add-explosion', 'settle',
]),
materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']),
// A flat water sheet; the largest sets the level. A bed d metres down keeps exp(-absorption * d) per channel (RGB per metre).
diff --git a/tests/mcp-mesh-edit-ops.test.js b/tests/mcp-mesh-edit-ops.test.js
new file mode 100644
index 00000000..b6d9bf41
--- /dev/null
+++ b/tests/mcp-mesh-edit-ops.test.js
@@ -0,0 +1,113 @@
+import './support/load-agent-scene-modules.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Client } from '@modelcontextprotocol/client';
+import { InMemoryTransport } from '@modelcontextprotocol/server';
+import { createAgentMcpServer } from '../scripts/mcp-server.mjs';
+import { createAgentScene, AGENT_SCENE_CAPABILITIES } from '../src/agent-scene.js';
+import { MESH_EDIT_OPERATIONS } from '../src/mesh-operations.js';
+
+// The mesh_edit tool takes the ops the recipe path takes (#2126): both lists come from MESH_EDIT_OPERATIONS, scene_capabilities
+// meshEdits reports it, and the `operations` topic lists only types scene_apply accepts.
+
+const SESSION_ID = '3f1c2a64-9d7e-4b1a-8c55-2a6f0e9d1b77';
+
+function meshRecipe(edits) {
+ return {
+ format: 'crucible.scene', schemaVersion: 1,
+ geometries: [{ id: 'm', type: 'mesh', base: { type: 'box', bevel: 0 }, edits }],
+ materials: [{ id: 'blue', color: [0.1, 0.3, 0.8] }],
+ nodes: [{ id: 'n', geometry: 'm', material: 'blue' }],
+ };
+}
+
+async function connect(context) {
+ let scene;
+ const runtime = {
+ async capabilities() { return { scene: AGENT_SCENE_CAPABILITIES, phase: 'idle', availableIn: 'test' }; },
+ async create({ recipe }) {
+ scene = createAgentScene(recipe);
+ return { sessionId: SESSION_ID, revision: scene.revision, render: { backend: 'fake' } };
+ },
+ async editMesh({ expectedRevision, geometry, edits, replace }) {
+ scene.apply([{ type: 'edit-mesh', geometry, edits, ...(replace === undefined ? {} : { replace }) }], { expectedRevision });
+ return { sessionId: SESSION_ID, revision: scene.revision, mesh: scene.inspectMeshes({ geometries: [geometry] }).meshes[0] };
+ },
+ async apply({ expectedRevision, operations }) {
+ scene.apply(operations, { expectedRevision });
+ return { sessionId: SESSION_ID, revision: scene.revision, render: { backend: 'fake' } };
+ },
+ async close() {},
+ activeSessionId() { return scene ? SESSION_ID : null; },
+ };
+ const server = createAgentMcpServer(runtime);
+ const client = new Client({ name: 'mesh-edit-ops-test', version: '1' });
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ context.after(async () => {
+ await client.close();
+ await server.close();
+ });
+ return client;
+}
+
+// Each case is a mesh before the op (prelude edits in the recipe) and the op itself. delete_loose has no recipe prelude that leaves a loose
+// vertex, so it must reach the engine and fail there with the engine's own error, the same as in a recipe.
+const OP_CASES = {
+ split_edges: { prelude: [], edit: { op: 'split_edges', edges: { all: true } } },
+ flatten: { prelude: [{ op: 'translate', select: { tag: 'top' }, offset: [0, 0.3, 0.1] }], edit: { op: 'flatten', verts: { all: true }, normal: [0, 1, 0] } },
+ circularize: { prelude: [{ op: 'loop_cut', name: 'ring', edges: { along: [0, 1, 0] } }], edit: { op: 'circularize', verts: { inside: { min: [-1, -0.01, -1], max: [1, 0.01, 1] } } } },
+ unsubdivide: { prelude: [{ op: 'subdivide', levels: 1 }], edit: { op: 'unsubdivide' } },
+ delete_loose: { prelude: [], edit: { op: 'delete_loose' }, engineError: /no loose vertex/ },
+};
+
+function recipeMeshReport(edits) {
+ return createAgentScene(meshRecipe(edits)).inspectMeshes({ geometries: ['m'] }).meshes[0];
+}
+
+for (const [name, { prelude, edit, engineError }] of Object.entries(OP_CASES)) {
+ test(`mesh_edit runs ${name} like a recipe geometry edit`, async context => {
+ const client = await connect(context);
+ await client.callTool({ name: 'scene_create', arguments: { recipe: meshRecipe(prelude) } });
+ const result = await client.callTool({ name: 'mesh_edit', arguments: { sessionId: SESSION_ID, expectedRevision: 0, geometry: 'm', edits: [edit] } });
+ if (engineError) {
+ assert.equal(result.isError, true);
+ assert.match(result.content[0].text, engineError);
+ assert.throws(() => recipeMeshReport([...prelude, edit]), engineError);
+ return;
+ }
+ assert.equal(result.isError, undefined, result.content?.[0]?.text);
+ const fromRecipe = recipeMeshReport([...prelude, edit]);
+ const reported = result.structuredContent.mesh;
+ assert.equal(reported.edits.length, prelude.length + 1, 'the new edit ran after the prelude');
+ assert.deepEqual(reported.edits.at(-1), fromRecipe.edits.at(-1));
+ assert.deepEqual(reported.counts, fromRecipe.counts);
+ assert.deepEqual(reported.bounds, fromRecipe.bounds);
+ assert.ok(Object.keys(reported.edits.at(-1)).length > 0, `${name} reports what it did`);
+ });
+}
+
+test('the mesh_edit op list is MESH_EDIT_OPERATIONS, the list scene_capabilities meshEdits reports', async context => {
+ const client = await connect(context);
+ const tool = (await client.listTools()).tools.find(candidate => candidate.name === 'mesh_edit');
+ const toolOperations = tool.inputSchema.properties.edits.items.properties.op.enum;
+ assert.deepEqual([...toolOperations].sort(), Object.keys(MESH_EDIT_OPERATIONS).sort());
+ assert.deepEqual([...AGENT_SCENE_CAPABILITIES.meshEdits.operations].sort(), [...toolOperations].sort());
+});
+
+test('every type the operations topic lists is accepted by scene_apply', async context => {
+ const client = await connect(context);
+ await client.callTool({ name: 'scene_create', arguments: { recipe: meshRecipe([]) } });
+ for (const type of AGENT_SCENE_CAPABILITIES.operations) {
+ let message = '';
+ try {
+ const result = await client.callTool({ name: 'scene_apply', arguments: { sessionId: SESSION_ID, expectedRevision: 0, operations: [{ type }] } });
+ message = result.isError ? result.content[0].text : '';
+ } catch (error) {
+ message = error.message;
+ }
+ assert.doesNotMatch(message, /Invalid discriminator|invalid_union/i, `scene_apply refuses the listed type ${type}`);
+ }
+ for (const type of ['edit-mesh', 'set-mesh-stack']) assert.ok(!AGENT_SCENE_CAPABILITIES.operations.includes(type), `${type} is the mesh_edit or mesh_stack tool, not a scene_apply type`);
+});