Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.mjs
index d7afd4d6,ca9b345e..7eb3f03d
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@@ -426,8 -431,12 +431,12 @@@ const recipeMeshEdits = z.array(z.recor
const 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.md
index 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 val
1. Name the parts and their rough sizes first. One part is one `mesh` geometry: a `base` primitive, an `edits` log and
an 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 offsets
stay 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.js
index 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 = Obje
smooth_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_CAPABILITIES
meshStack: 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.js
index 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);
}
}