3D engine that AI agents drive
Merge remote-tracking branch 'origin/main' into feat/610-shape-keys
Nguyen Xuan An512b49040a69
diff --cc scripts/mcp-server.mjsindex d7afd4d6,ca9b345e..7eb3f03d--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@@ -426,8 -431,12 +431,12 @@@ const recipeMeshEdits = z.array(z.recorconst recipeMeshStack = z.array(z.record(z.string(), z.unknown())).max(16);const geometry = z.discriminatedUnion('type', [...primitiveGeometries(true),- z.strictObject({ id: identifier, type: z.literal('grid'), segments: detail(1, 64) }),+ z.strictObject({ id: identifier, type: z.enum(['grid', 'plane']), segments: detail(1, 64) }).describe('Unit sheet in XY facing +Z; plane = grid.'),+ z.strictObject({ id: identifier, type: z.literal('cone'), radiusTop: finite.optional(), radiusBottom: finite.optional(), segments }).describe('Along Y, height 1; radiusTop 0 is a point, radiusBottom 1.'),+ z.strictObject({ id: identifier, type: z.literal('icoSphere'), subdivisions: detail(0, 7) }),+ z.strictObject({ id: identifier, type: z.literal('circle'), segments, innerRadius: finite.optional() }).describe('Unit disc facing +Z; innerRadius makes a ring.'),+ z.strictObject({ id: identifier, type: z.literal('line'), from: vector3, to: vector3, radius: finite.optional(), radialSegments: detail(3, 128) }),- z.strictObject({ id: identifier, type: z.literal('mesh'), base: z.discriminatedUnion('type', primitiveGeometries(false)).describe('Starting shape, converted to welded quads with axis face tags.'), edits: recipeMeshEdits.optional().describe('Replayable edit log, applied in order. Each item has the shape of one mesh_edit edit; read that tool for every op and field.'), stack: recipeMeshStack.optional().describe('Non-destructive modifier stack evaluated after the edits. Each item has the shape of one mesh_stack node; read that tool for the ops.'), smoothAngle: bounded(0, 180).optional().describe('Edges bending more than this many degrees render hard. Defaults to 30.') }),+ z.strictObject({ id: identifier, type: z.literal('mesh'), base: z.discriminatedUnion('type', primitiveGeometries(false)).describe('Starting shape, converted to welded quads with axis face tags.'), edits: recipeMeshEdits.optional().describe('Replayable edit log, applied in order. Each item has the shape of one mesh_edit edit; read that tool for every op and field.'), stack: recipeMeshStack.optional().describe('Non-destructive modifier stack evaluated after the edits. Each item has the shape of one mesh_stack node; read that tool for the ops.'), smoothAngle: bounded(0, 180).optional().describe('Edges bending more than this many degrees render hard. Defaults to 30.'), shapeKeys: recipeMeshEdits.optional().describe('Named morph targets, at most 16: { name, offsets | edits, value }. See scene_capabilities meshShapeKeys.') }),]);// No description: this field repeats in every motion track schema. A wrong name fails with every valid form, and docs/agent-motion.md lists them.const easingField = z.string().max(80).optional();diff --cc skills/build-67js-scene/references/mesh-modeling.mdindex e216b57b,e50a60e1..378b28e7--- a/skills/build-67js-scene/references/mesh-modeling.md+++ b/skills/build-67js-scene/references/mesh-modeling.md@@@ -16,11 -16,17 +16,19 @@@ requires a clean lint, so keep them val1. Name the parts and their rough sizes first. One part is one `mesh` geometry: a `base` primitive, an `edits` log andan optional `stack`. Separate parts (a lid, a handle) are separate geometries placed by nodes.2. Start from the closest base. `box` is a unit cube from -0.5 to 0.5 (`bevel: 0` for crisp edits); `cylinder` has- radius 1 and height 1 centred on the origin (`bevel: 0`); `sphere` has radius 1; `lathe` turns a profile;- `extrude` makes outlines with holes. Set proportions first by translating tagged faces, so later widths and offsets+ radius 1 and height 1 centred on the origin (`bevel: 0`); `sphere` has radius 1; `lathe` turns a+ profile; `extrude` makes outlines with holes. These shapes are plain geometry records only (not mesh bases):+ `cone` (`{ "id": "spike", "type": "cone", "radiusBottom": 1, "segments": 32 }`, point on top, height 1; a `radiusTop` makes a+ frustum), `icoSphere` (`{ "id": "ball", "type": "icoSphere", "subdivisions": 2 }`, even triangles, no poles), `circle`+ (`{ "id": "ring", "type": "circle", "innerRadius": 0.6 }`, a unit disc facing +Z, a ring when `innerRadius` is above 0),+ `line` (`{ "id": "rod", "type": "line", "from": [0, 0, 0], "to": [0, 2, 0], "radius": 0.03 }`) and `grid` (`plane` is the same+ shape). To edit one, build the mesh from a cylinder or sphere base instead. Set proportions first by translating tagged faces, so later widths and offsetsstay in real units: a 0.5 x 0.6 x 1.0 box is `right` by -0.25, `left` by 0.25, `top` by -0.4.+ Paint and weight after the shape edits: `vertex_color` (`color`, `field` or a two-color `gradient`) colors the selected faces and+ exports as `COLOR_0`; `vertex_group` (`name` plus `weight`, `field` or `gradient`) makes weights that `displace` reads with `group`+ and a cloth sheet reads with `pinGroup`. Example: `{ "op": "vertex_group", "name": "hem", "gradient": { "axis": "y", "range": [-0.5, 0.5], "weights": [1, 0] } }`.+ Faces, blinks and squash are shape keys on the same mesh geometry: `"shapeKeys": [{ "name": "blink", "offsets": [{ "select": { "tag": "lid" }, "offset": [0, -0.1, 0] }] }]`+ (offsets or move-only `edits`, at most 16, no new vertices), animated by a motion track `{ "kind": "morph", "id": "blink", "property": "weight", "keyframes": [...] }`.3. Add edits in small batches with `mesh_edit` (or in the recipe). Name every edit (`name: "lid"` gives `lid.cap`,`lid.side`); an unnamed one gets `<op>-<index>`, which is hard to predict. Select faces by tags, never by index.4. After each batch read the `mesh_edit` result: `edits[i].selected`, `tags` and `edges` say what each edit touched;diff --cc src/agent-scene-capabilities.jsindex a99d4f42,745e57d2..4154c4c8--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@@ -154,11 -154,12 +154,17 @@@ export const MESH_MODIFIER_NOTES = Objesmooth_by_angle: 'edges bending over angle 30 (0-180) become sharp, others smooth, over smoothAngle; ignoreSharp true also clears hand-made sharp edges.',});+ // Vertex colors and groups. Details stay here so the tool schemas stay small.+ export const MESH_ATTRIBUTE_NOTES = Object.freeze({+ vertex_group: 'name (required) sets the weights 0-1 of the vertices of the selected faces; the rest keep theirs (0 in a new group). One of weight (1), field (number expression) or gradient { axis x|y|z, range [low, high], weights [atLow, atHigh] }. At most 32 groups. displace takes group: name and scales each move by the weight; cloth sheets take pinGroup: name and hold vertices of weight 0.5 or more. Put it after the shape edits: a stack node that rebuilds the mesh (mirror, array and so on) drops groups.',+ vertex_color: 'sets the corner colors (0-1, linear, white until set) of the selected faces. One of color [r, g, b], field (vector expression of the vertex) or gradient { axis, range [low, high], colors [[r,g,b] atLow, [r,g,b] atHigh] }. Shown by the renderer and written as COLOR_0 in a GLB; it multiplies the material color.',+ });++// Shape keys on a recipe mesh. Details stay here so the tool schemas stay small.+export const MESH_SHAPE_KEY_NOTES = Object.freeze({+ shapeKeys: 'On a mesh geometry, at most 16: { name, offsets, value } or { name, edits, value }. offsets is a list of { select, offset: [x,y,z], falloff } moves like the translate edit; edits are mesh edits that only move vertices (set_position, displace, sculpt, simple_deform, lattice, hook and so on) run on the finished mesh, after the stack. A key that adds or removes vertices is refused. value (0, from 0 to 1) is the weight without motion. Each key becomes a glTF morph target of the mesh. Animate it with a motion track { kind: "morph", id: <key name>, property: "weight", keyframes } (weight 0 to 1; keys add up); a GLB export writes the targets, their names (mesh.extras.targetNames) and the weights. Normals stay those of the base mesh.',+});+// Organic shaping edits. Details stay here so the tool schemas stay small.export const MESH_SCULPT_NOTES = Object.freeze({sculpt: 'strokes run in order on the vertices of the selected faces; other vertices stay, so a tag confines them. A stroke has type inflate (along the vertex normal), displace (along direction, needed) or smooth (strength 0 to 1), center and radius, strength in mesh units (negative pushes in). Falloff is smooth to zero at the radius. For bulges, dents and softened forms.',@@@ -176,7 -177,7 +182,8 @@@ export const AGENT_SCENE_CAPABILITIESmeshStack: Object.freeze({ operations: STACK_OPERATIONS, maxNodes: MAX_STACK_NODES }),meshModifiers: MESH_MODIFIER_NOTES,meshSculpt: MESH_SCULPT_NOTES,+ meshAttributes: MESH_ATTRIBUTE_NOTES,+ meshShapeKeys: MESH_SHAPE_KEY_NOTES,fieldExpressions: Object.freeze({operators: FIELD_OPERATOR_NAMES, attributes: FIELD_ATTRIBUTES,maxNodes: MAX_FIELD_NODES, maxDepth: MAX_FIELD_DEPTH, maxElements: MAX_FIELD_ELEMENTS,diff --cc src/agent-scene.jsindex b3a6d588,d5445d5b..9126fc90--- a/src/agent-scene.js+++ b/src/agent-scene.js@@@ -449,7 -461,7 +461,7 @@@ function geometryEstimate(value)return input.length;}for (const field of GEOMETRY_FIELDS[value.type]) {- if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align'].includes(field)) {- if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'points', 'taper', 'text', 'font', 'align', 'from', 'to'].includes(field)) {++ if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align', 'from', 'to'].includes(field)) {finite(value[field], field);}}