3D engine that AI agents drive
Trim the scene_walkmap schema to cut the tool cost (part of #553)
Nguyen Xuan An1d920206a8df
diff --git a/changes/553.size.md b/changes/553.size.mdindex 8395bd87..9b885bbd 100644--- a/changes/553.size.md+++ b/changes/553.size.md@@ -1 +1,2 @@- scene:agent-scene+lazy: +87 B gzip for caching the last validated matrix per mesh-query index, the top cost in the walk-map profile; scene-wide raycasts over large glTF worlds stay in seconds. Only the lazy chunk grows; the goal scenes do not.+- tool-total: +947 B for `scene_walkmap`, cut from 2455 B to the schema with session, region, cell size, clearance and includeCells; rare options (start height, ground range, lower pass) stay in the addon and docs. Agents get a walk map from imported scenes with MCP tools only, which the issue asks for.diff --git a/docs/mcp.md b/docs/mcp.mdindex a0d537ac..08d0a924 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -127,7 +127,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe| `scene_create_asset` | `recipe` using `67js.asset` | Imported scene ID, revision, inspection and render status || `scene_inspect` | `sessionId`, optional `ids`, `limit`, `includeBounds` | Compact node records and revision || `scene_apply` | `sessionId`, `expectedRevision`, `operations` | Updated revision, inspection, and render status |-| `scene_walkmap` | `sessionId`, `min`, `max`, optional `cellSize`, `clearance`, `groundRange`, `lowerPass`, `includeCells` | Grid rows of `.` walkable, `x` blocked and `#` no surface, with counts; ground height and headroom per cell with `includeCells`. See [scene-query.md](scene-query.md) |+| `scene_walkmap` | `sessionId`, `min`, `max`, optional `cellSize`, `clearance`, `includeCells` | Grid rows of `.` walkable, `x` blocked and `#` no surface, with counts; ground height and headroom per cell with `includeCells`. See [scene-query.md](scene-query.md) || `mesh_inspect` | `sessionId`, optional `geometries` (up to 16 IDs) | Per geometry: polygon counts, face sizes, parts, face tags, bounds and lint problems with fixes || `mesh_edit` | `sessionId`, `expectedRevision`, `geometry`, `edits`, optional `replace` | Updated revision, render status and the mesh report with per-edit results || `mesh_stack` | `sessionId`, `expectedRevision`, `geometry`, optional `stack`, `apply` | Updated revision, render status and the mesh report with per-node results |diff --git a/docs/scene-query.md b/docs/scene-query.mdindex 94dc52a4..64899146 100644--- a/docs/scene-query.md+++ b/docs/scene-query.md@@ -58,8 +58,7 @@ Measured on a machine under load: about 8 s for the first 12,630 cells includingRows follow z, columns follow x.```json-{ "min": [-62, -88], "max": [111, 97], "cellSize": 1, "topY": 60, "clearance": 2.4,- "groundRange": [-1, 1], "lowerPass": { "fromY": 2.4, "groundBelow": 1 } }+{ "min": [-62, -88], "max": [111, 97], "cellSize": 1, "clearance": 2.4 }``````@@ -67,8 +66,12 @@ Rows follow z, columns follow x."grid": ["######...", "##....xx.", "..."] }```-`.` is walkable (headroom of at least `clearance`, ground inside `groundRange`), `x` is ground that is blocked, `#` has no surface.+`.` is walkable (headroom of at least `clearance`), `x` is ground that is blocked, `#` has no surface.Pass `includeCells: true` for `[x, z, groundY, headroom]` per cell, up to 4,096 cells.Plan a camera path over the `.` cells, set each eye at `groundY` plus the eye height, and check it with `scene_look`.The server holds one query per session and rebuilds it when the revision or a pose changes.The MCP asset catalog is limited to 1,000,000 vertices (see [gltf.md](gltf.md)); a larger scene such as Bistro loads through `loadGltf` and `createSceneQuery` in code.++Fields: `min` and `max` are `[x, z]` corners, x runs across the rows and z down them. `cellSize` defaults to 1 and `clearance` (headroom a walkable cell needs) to 2.+The down rays start at y = 100, and the region may hold up to 65,536 cells.+The tool does not take `topY`, `groundRange` or `lowerPass`: for a scene taller than 100, ground ranges or arches, call `walkMap` from code.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 034a1f31..ac38f81f 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -755,7 +755,7 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versioregister('scene_asset_catalog', 'List content-bound GLB and PNG, JPEG or WebP image IDs from the configured local asset directory. No arbitrary paths or downloads.', z.strictObject({}), readOnly, async () => jsonResult(await runtime.assetCatalog()));register('scene_create_asset', 'Create the active scene from a catalog GLB and editable asset recipe. Preserves supported maps, skins, morphs and clips. Dispose the existing scene first.', z.strictObject({ recipe: assetRecipe }), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.createAsset(argumentsValue)));register('scene_inspect', 'Read revision, counts and selected nodes. For a recipe with physics, the result lists body final positions, resting times, contacts and sensor enter/leave events. Bounds describe authored geometry rather than shader displacement.', z.strictObject({ ...sessionFields, ids: z.array(identifier).max(4096).optional().describe('Selected node IDs. Omit to inspect scene order.'), kind: z.enum(['meshes', 'hierarchy']).optional().describe('Imported assets only: hierarchy exposes stable source-node IDs and joints.'), offset: z.number().int().min(0).max(4096).optional().describe('Imported assets only: pagination offset.'), limit: z.number().int().min(1).max(4096).optional().describe('Maximum returned node records. Defaults to 64.'), includeBounds: z.boolean().optional().describe('Include world geometry bounds. Defaults to false.'), path: z.record(z.string(), z.unknown()).optional().describe('Walking route over a ground node, around holes: fields in scene_capabilities navigation.') }), readOnly, async argumentsValue => jsonResult(await runtime.inspect(argumentsValue)));- register('scene_walkmap', 'Sample ground height and headroom on a grid over a region of the active imported asset scene with raycasts against every mesh, and return a walkable map: grid rows of "." (walkable), "x" (ground but too little headroom or outside groundRange) and "#" (no surface), x across and z down. Use it to plan a street-level camera path. Reads the current pose; the scene does not change.', z.strictObject({ ...sessionFields, min: z.tuple([z.number(), z.number()]).describe('Region corner [x, z] with the smaller values, in world units (y is up).'), max: z.tuple([z.number(), z.number()]).describe('Region corner [x, z] with the larger values.'), cellSize: z.number().min(0.05).max(100).default(1).describe('Grid step. The region may hold up to 65,536 cells.'), topY: z.number().optional().describe('Height the down rays start from, above the tallest surface. Defaults to 100.'), clearance: z.number().min(0).max(100).default(2).describe('Headroom a cell needs to count as walkable, in the same units.'), groundRange: z.tuple([z.number(), z.number()]).optional().describe('[lowest, highest] ground height that counts as walkable, to ignore roofs and upper floors.'), lowerPass: z.strictObject({ fromY: z.number(), groundBelow: z.number(), maxDistance: z.number().min(0).max(1000).optional(), minHeadroom: z.number().min(0).max(100).optional() }).optional().describe('For cells whose top surface is above groundBelow (a roof, an arch): a second down ray from fromY looks for ground underneath.'), includeCells: z.boolean().default(false).describe('Also return [x, z, groundY, headroom] for each cell with a surface (at most 4096 cells).') }), readOnly, async argumentsValue => jsonResult(await runtime.walkMap(argumentsValue)));+ register('scene_walkmap', 'Walkable map of an imported asset scene on a grid: rows of . walkable, x blocked, # no surface.', z.strictObject({ ...sessionFields, min: z.tuple([z.number(), z.number()]), max: z.tuple([z.number(), z.number()]), cellSize: z.number().min(0.05).default(1), clearance: z.number().min(0).default(2), includeCells: z.boolean().optional() }), readOnly, async argumentsValue => jsonResult(await runtime.walkMap(argumentsValue)));register('mesh_inspect', 'Check recipe geometries as polygon meshes: vertex, edge and face counts, triangles/quads/n-gons, connected and closed parts, face tags (top, bottom, side, left, right, front, back), bounds, and lint problems (non-manifold, inconsistent winding, inverted, degenerate, open, loose) with a suggested fix each. Also imported asset parts (mesh-0). Read-only and cached per geometry.', z.strictObject({ ...sessionFields, geometry: identifier.optional().describe('One geometry ID to check, as in mesh_edit.'), geometries: z.array(identifier).min(1).max(16).optional().describe('Geometry IDs to check. Omit both to check the first 16 geometries.') }), readOnly, async ({ geometry: geometryId, geometries, ...rest }) => jsonResult(await runtime.inspectMeshes({ ...rest, ...(geometries || geometryId ? { geometries: [...(geometries ?? []), ...(geometryId ? [geometryId] : [])] } : {}) })));register('mesh_edit', 'Append edits to a recipe mesh geometry or an imported asset part such as mesh-0 (or replace its edit log), atomically like scene_apply: extrude, inset, delete, flip, translate with falloff, tag, loop cut, bevel, mirror, array, solidify, UV unwrap, set_position and displace with field expressions (math, noise, attributes), booleans with a primitive cutter, sculpt brush strokes and shrinkwrap onto a primitive. Edits that select no faces or break limits fail without changing the scene. Returns the new revision, render status and the mesh report with per-edit results.', z.strictObject({ ...sessionFields, expectedRevision, geometry: identifier.describe('ID of a geometry with type mesh, or an imported part such as mesh-0.'), edits: meshEdits.min(1), replace: z.boolean().optional().describe('Replace the whole edit log instead of appending.') }), edit, async argumentsValue => jsonResult(await runtime.editMesh(argumentsValue)));register('mesh_stack', 'Set the non-destructive modifier stack of a recipe mesh geometry (ops and fields: scene_capabilities meshModifiers), evaluated after its edits, each prefix cached. apply: n moves the first n nodes into the edit log, as Blender\'s Apply modifier. Atomic like scene_apply. Returns the revision, render status and mesh report.', z.strictObject({ ...sessionFields, expectedRevision, geometry: identifier.describe('ID of a geometry with type mesh.'), stack: meshStack.optional().describe('The whole new stack. Omit to keep the current stack (for example with apply).'), apply: z.number().int().min(0).max(16).optional() }), edit, async argumentsValue => jsonResult(await runtime.setMeshStack(argumentsValue)));