3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 replaysEdges 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 ageometry (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 onecompact record per geometry:diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 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), modifierconst 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 KBdiff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 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.jsnew file mode 100644index 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`);+});