3D engine that AI agents drive
Mesh: shape keys on recipe meshes as morph targets (issue #610)
Nguyen Xuan An4fdf97f00c08
diff --git a/changes/610.md b/changes/610.mdnew file mode 100644index 00000000..baab1fec--- /dev/null+++ b/changes/610.md@@ -0,0 +1 @@+- A recipe mesh takes `shapeKeys` (named offsets or move-only edits), animated by the existing morph tracks and written as morph targets in a GLB (#610)diff --git a/changes/610.size.md b/changes/610.size.mdnew file mode 100644index 00000000..ae08c23c--- /dev/null+++ b/changes/610.size.md@@ -0,0 +1,7 @@+- scene:agent-scene: the shape key part handling (morph pose per part, weight publish, validation call), 481 bytes gzip (#610)+- scene:agent-scene+lazy: shape key normalizing and offset targets in the mesh engine, 1204 bytes gzip+- goal:agent-scene: shape keys let agents animate faces, blinks and squash on built models; the engine code loads only with meshes+- tool-total: one shapeKeys field on the mesh geometry in two tools, 500 bytes; the field details sit in scene_capabilities meshShapeKeys+- tool:scene_create: the shapeKeys field, 250 bytes+- tool:scene_apply: the same recipe schema, 250 bytes+- result:scene_capabilities: meshShapeKeys explains keys, offsets, edits, value and the morph track in under 1 KB so the tool schemas stay smalldiff --git a/docs/mesh.md b/docs/mesh.mdindex 26d2cab5..34b4c22a 100644--- a/docs/mesh.md+++ b/docs/mesh.md@@ -204,6 +204,18 @@ and misses. `evaluateMeshStack(mesh, stack, { cache, cacheKey })` runs a stack oThe `mesh_stack` tool sets the whole stack in one revision. `apply: n` moves the first `n` nodes into the edit log,as Blender's Apply modifier, which leaves the result unchanged.+### Shape keys++A recipe `mesh` geometry may carry `shapeKeys` (up to 16), named offsets from the finished mesh that become glTF morph targets.+A key is `{ "name": "blink", "offsets": [{ "select": { "tag": "lid" }, "offset": [0, -0.1, 0] }] }`, a list of moves like the+`translate` edit, or `{ "name": "squash", "edits": [...] }`, mesh edits that only move vertices (`set_position`, `displace`,+`sculpt`, `simple_deform`, `lattice`, `hook`, `wave`) run on the mesh after the stack. A key that adds or removes vertices is+refused with the vertex counts. `value` (0 to 1) is the weight without motion.++Animate a key with the existing morph track: `{ "kind": "morph", "id": "blink", "property": "weight", "keyframes": [...] }`. Weights+from 0 to 1 add up, so two keys blend. A GLB export writes the targets, their names as `mesh.extras.targetNames` and the weights.+Normals stay those of the base mesh. Test: `tests/mesh-shape-keys.test.js`.+### Whole-mesh modifiers`weld`, `triangulate`, `edge_split`, `smooth`, `simple_deform`, `cast`, `screw`, `wireframe`, `skin`, `lattice`, `curve`, `hook`, `wave`, `weighted_normal` and `smooth_by_angle` take no selection and no name, and work as edits or stack nodes. Their fields and defaults are plain data in `MESH_MODIFIER_NOTES` (`src/agent-scene-capabilities.js`), which `scene_capabilities` returns as `meshModifiers`; the code is in `src/mesh-modifiers.js` and `src/mesh-restructure.js`.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex aaea8696..d7afd4d6 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -427,7 +427,7 @@ 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.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 --git a/skills/build-67js-scene/references/mesh-modeling.md b/skills/build-67js-scene/references/mesh-modeling.mdindex 2bca742b..e216b57b 100644--- a/skills/build-67js-scene/references/mesh-modeling.md+++ b/skills/build-67js-scene/references/mesh-modeling.md@@ -19,6 +19,8 @@ requires a clean lint, so keep them valid when the API changes.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 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.+ 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 --git a/src/agent-mesh-engine.js b/src/agent-mesh-engine.jsindex b3f4fae8..91ee8216 100644--- a/src/agent-mesh-engine.js+++ b/src/agent-mesh-engine.js@@ -1,6 +1,7 @@// Everything the agent scene needs for mesh geometry, behind one on-demand import (see agent-scene-modules.js).export { meshReport, generateMeshGeometry, taggedFacePositions } from './agent-mesh.js';export { normalizeMeshEdits, normalizeMeshStack } from './mesh-recipe.js';+export { normalizeShapeKeys } from './mesh-shape-keys.js';export { generateMeshLods, generateGeometryLods, generateAssetLods } from './mesh-lod.js';export { expandInstancedNodes } from './mesh-instances.js';export { loadMeshBooleans, meshBooleansLoaded, setManifoldModuleLoader } from './mesh-boolean.js';diff --git a/src/agent-mesh.js b/src/agent-mesh.jsindex 58533a46..274d51bd 100644--- a/src/agent-mesh.js+++ b/src/agent-mesh.js@@ -3,6 +3,7 @@ import { facesWithTag } from './mesh-data.js';import { lintMesh } from './mesh-lint.js';import { applyMeshEdits, evaluateMeshStack } from './mesh-recipe.js';import { extractRender } from './mesh-render.js';+import { normalizeShapeKeys, shapeKeyTargets } from './mesh-shape-keys.js';import { MESH_SMOOTH_ANGLE_DEFAULT } from './agent-scene-capabilities.js';export { MESH_SMOOTH_ANGLE_DEFAULT };@@ -83,7 +84,7 @@ export function meshCacheStats() {* does. `cacheKey` identifies the base; the edit result and every stack prefix are cached under it.*/export function generateMeshGeometry(baseGeometry, edits, {- maxVertices, smoothAngle = MESH_SMOOTH_ANGLE_DEFAULT, resolveCutter, stack = [], cacheKey,+ maxVertices, smoothAngle = MESH_SMOOTH_ANGLE_DEFAULT, resolveCutter, stack = [], cacheKey, shapeKeys = [],}) {const editsKey = cacheKey === undefined ? undefined : `${cacheKey}|edits|${JSON.stringify(edits)}`;let edited = editsKey === undefined ? undefined : evaluationCache.get(editsKey);@@ -97,10 +98,16 @@ export function generateMeshGeometry(baseGeometry, edits, {if (editsKey !== undefined) evaluationCache.set(editsKey, edited);}const evaluated = evaluateMeshStack(edited.mesh, stack, { maxVertices, maxFaces: maxVertices, cache: evaluationCache, cacheKey: editsKey });- const { geometry } = extractRender(evaluated.mesh, { sharpAngle: smoothAngle * Math.PI / 180 });+ const { geometry, renderVertexSource } = extractRender(evaluated.mesh, { sharpAngle: smoothAngle * Math.PI / 180 });if (geometry.positions.length / 3 > maxVertices) {throw new RangeError(`The edited mesh needs ${geometry.positions.length / 3} render vertices, over maxVertices ${maxVertices}.`);}+ const keys = normalizeShapeKeys(shapeKeys);+ if (keys.length) {+ geometry.morphTargets = shapeKeyTargets(evaluated.mesh, renderVertexSource, keys, { maxVertices, maxFaces: maxVertices, resolveCutter: resolveCutter && (cutter => meshFromGeometry(resolveCutter(cutter))) });+ geometry.morphTargetNames = keys.map(key => key.name);+ geometry.morphTargetValues = Float32Array.from(keys, key => key.value);+ }polygonMeshes.set(geometry, { mesh: evaluated.mesh, results: edited.result, stack: evaluated.results });return geometry;}diff --git a/src/agent-motion.js b/src/agent-motion.jsindex b80da211..8db7294f 100644--- a/src/agent-motion.js+++ b/src/agent-motion.js@@ -368,7 +368,8 @@ export function normalizeAgentMotion(input, recipe) {}const nodes = new Set((recipe.nodes ?? []).map(node => node.id));const materials = new Set((recipe.materials ?? []).map(material => material.id));- const morphTargets = new Set(recipe.morphTargets ?? []);+ // An imported asset lists its morph targets; a recipe mesh offers the names of its shape keys.+ const morphTargets = new Set(recipe.morphTargets ?? (recipe.geometries ?? []).flatMap(geometry => (geometry.shapeKeys ?? []).map(key => key.name)));const identities = new Set();let keyframeCount = 0;const tracks = inputTracks.map((track, index) => {diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex efc33124..a99d4f42 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -154,6 +154,11 @@ export const MESH_MODIFIER_NOTES = Object.freeze({smooth_by_angle: 'edges bending over angle 30 (0-180) become sharp, others smooth, over smoothAngle; ignoreSharp true also clears hand-made sharp edges.',});+// 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.',@@ -171,6 +176,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({meshStack: Object.freeze({ operations: STACK_OPERATIONS, maxNodes: MAX_STACK_NODES }),meshModifiers: MESH_MODIFIER_NOTES,meshSculpt: MESH_SCULPT_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 --git a/src/agent-scene.js b/src/agent-scene.jsindex 703c4931..b3a6d588 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -427,7 +427,7 @@ const GEOMETRY_FIELDS = {tube: ['path', 'radius', 'segments', 'radialSegments', 'closed'],curve: ['points', 'closed', 'radius', 'taper', 'profile', 'resolution', 'radialSegments'],text: ['text', 'size', 'depth', 'font', 'align', 'curveSegments'],- mesh: ['base', 'edits', 'stack', 'smoothAngle'],+ mesh: ['base', 'edits', 'stack', 'smoothAngle', 'shapeKeys'],terrain: ['size', 'resolution', 'seed', 'amplitude', 'holes'],};@@ -449,7 +449,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', 'points', 'taper', 'text', 'font', 'align'].includes(field)) {+ if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align'].includes(field)) {finite(value[field], field);}}@@ -513,6 +513,7 @@ function geometryEstimate(value) {}// Stack nodes multiply the mesh: arrays by their count, mirror and solidify at most by two.for (const node of agentSceneModule('mesh').normalizeMeshStack(value.stack ?? [])) estimate *= node.op === 'array' ? node.count : 2;+ if (value.shapeKeys !== undefined) agentSceneModule('mesh').normalizeShapeKeys(value.shapeKeys);if (value.smoothAngle !== undefined && (value.smoothAngle < 0 || value.smoothAngle > 180)) {throw new RangeError('smoothAngle is degrees from 0 to 180.');}@@ -566,7 +567,7 @@ function generateGeometry(value, maxVertices) {case 'mesh':return agentSceneModule('mesh').generateMeshGeometry(() => generateGeometry(value.base, maxVertices), value.edits ?? [], {maxVertices, smoothAngle: value.smoothAngle ?? MESH_SMOOTH_ANGLE_DEFAULT,- stack: value.stack ?? [], cacheKey: JSON.stringify(value.base),+ stack: value.stack ?? [], cacheKey: JSON.stringify(value.base), shapeKeys: value.shapeKeys ?? [],resolveCutter: cutter => {cutterEstimate(cutter);return generateGeometry(cutter, maxVertices);@@ -940,7 +941,7 @@ function stagePose(stagedState, time) {// Staged last: a pose pending on a decoded asset must be committed or discarded, so nothing above may throw after it.const assetClips = stagedState.assetRuntime.animators.length ? agentSceneModule('assets').stageAssetClips(stagedState.assetRuntime, graph, time) : null;const movedLook = stagedState.motionSampler && agentSceneModule('motion').motionMovesLook(sampled) ? sampled : null;- return { graph, materialUpdates, camera, time, clothGeometries, assetClips, hiddenNodes, movedLook };+ return { graph, materialUpdates, camera, time, clothGeometries, assetClips, hiddenNodes, movedLook, morphs: sampled?.morphs ?? null };}// Cloth and particles replace the geometry of their own nodes at a sampled time; no node belongs to both.@@ -1000,11 +1001,21 @@ function partsWithCloth(restParts, clothGeometries, previousParts) {return next.every((part, index) => part === previousParts[index]) ? previousParts : Object.freeze(next);}+// A shape key weighs what its morph track samples at this time, or its starting value when no track names it.+function publishShapeKeyWeights(part, sampledMorphs) {+ const { morphTargetNames, morphTargetValues } = part.geometry;+ if (!morphTargetNames || !part.morph) return;+ morphTargetNames.forEach((name, index) => {+ part.morph.weights[index] = sampledMorphs?.get(name)?.weight ?? morphTargetValues[index];+ });+}+/** Returns true when the parts handed to a renderer changed, which the caller counts as a topology change. */function publishPose(stagedState, pose) {for (const part of stagedState.restParts) {if (part.visibility) part.visibility.visible = !pose.hiddenNodes.has(part.name);Float32Array.prototype.set.call(part.matrix, pose.graph.getNode(part.name).worldMatrix);+ publishShapeKeyWeights(part, pose.morphs);}for (const update of pose.materialUpdates) {update.holder.snapshot = update.snapshot;@@ -1220,9 +1231,11 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {const geometry = binding?.geometry ?? geometries.get(node.geometry);const material = materialHandles.get(node.material).output;const assetExtras = assetRuntime.partExtras.get(node.id);+ // Shape keys of a recipe mesh are morph targets with their own weights per part; an imported asset brings its own pose.+ const shapeKeyMorph = geometry.morphTargetValues && !assetExtras?.morph ? { weights: Float32Array.from(geometry.morphTargetValues) } : undefined;const activePart = removedNodes.has(node.id) ? null : activeParts.get(node.id);const existing = [activePart, preferredParts.get(node.id)]- .find(part => part?.geometry === geometry && part.material === material && part.skin === (assetExtras?.skin ?? binding?.skin) && part.morph === assetExtras?.morph && depthLayerOf(part) === depthLayerOf(node) && sameRenderFlags(part, node, usesVisibility, assetExtras));+ .find(part => part?.geometry === geometry && part.material === material && part.skin === (assetExtras?.skin ?? binding?.skin) && (assetExtras?.morph ? part.morph === assetExtras.morph : Boolean(part.morph) === Boolean(shapeKeyMorph)) && depthLayerOf(part) === depthLayerOf(node) && sameRenderFlags(part, node, usesVisibility, assetExtras));return existing ?? Object.freeze({name: node.id, geometry, material,...(depthLayerOf(node) ? { depthLayer: depthLayerOf(node) } : {}),@@ -1231,6 +1244,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {...(usesVisibility ? { visibility: { visible: true } } : {}),matrix: new Float32Array(graph.getNode(node.id).worldMatrix),...(binding ? { skin: binding.skin } : {}),+ ...(shapeKeyMorph ? { morph: shapeKeyMorph } : {}),...assetExtras,});});diff --git a/src/export.js b/src/export.jsindex 5417e4da..8e6772fb 100644--- a/src/export.js+++ b/src/export.js@@ -304,7 +304,9 @@ export function exportGlb(parts, options = {}) {const meshKey = `${geometry.indices}:${material}`;if (!meshes.has(meshKey)) {meshes.set(meshKey, document.meshes.length);- document.meshes.push({ primitives: [{ ...geometry, material }] });+ // glTF has no field for morph target names; the common convention is mesh.extras.targetNames.+ const targetNames = part.geometry.morphTargetNames;+ document.meshes.push({ primitives: [{ ...geometry, material }], ...(targetNames ? { extras: { targetNames } } : {}) });}const host = part.skin ? null : hostOfPart(partIndex, hierarchy, worldCache);// The mesh node of an imported asset is one of its nodes: keep the mesh on it instead of nesting a same-named node.diff --git a/src/mesh-shape-keys.js b/src/mesh-shape-keys.jsnew file mode 100644index 00000000..11add362--- /dev/null+++ b/src/mesh-shape-keys.js@@ -0,0 +1,74 @@+import { applyMeshEdits, normalizeMeshEdits } from './mesh-recipe.js';++// Shape keys of a recipe mesh: named vertex offsets from the evaluated mesh, written as glTF morph targets so the+// existing morph tracks (motion kind "morph", id = key name) animate their weights and a GLB export carries them.+//+// "shapeKeys": [+// { "name": "blink", "offsets": [{ "select": { "tag": "lid" }, "offset": [0, -0.1, 0] }] },+// { "name": "squash", "edits": [{ "op": "simple_deform", "mode": "taper", "axis": "y", "factor": -0.4 }], "value": 0 }+// ]++export const MAX_SHAPE_KEYS = 16;+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/;+const KEY_FIELDS = ['name', 'edits', 'offsets', 'value'];+const OFFSET_FIELDS = ['select', 'offset', 'falloff'];++function keyError(index, message) {+ return new TypeError(`Shape key ${index} (${message})`);+}++function offsetEdit(entry, keyIndex) {+ if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw keyError(keyIndex, 'each offsets entry must be { select, offset, falloff }');+ for (const field of Object.keys(entry)) {+ if (!OFFSET_FIELDS.includes(field)) throw keyError(keyIndex, `offsets entries do not take ${field}; fields: ${OFFSET_FIELDS.join(', ')}`);+ }+ return { op: 'translate', ...entry };+}++/**+ * Validate shape keys and return them with offsets turned into translate edits: [{ name, value, edits }].+ * A key is built from `edits` (mesh edits that only move vertices) or `offsets` ({ select, offset, falloff } moves).+ */+export function normalizeShapeKeys(shapeKeys) {+ if (!Array.isArray(shapeKeys) || shapeKeys.length > MAX_SHAPE_KEYS) {+ throw new RangeError(`shapeKeys must be an array of at most ${MAX_SHAPE_KEYS} keys.`);+ }+ const names = new Set();+ return shapeKeys.map((key, index) => {+ if (!key || typeof key !== 'object' || Array.isArray(key)) throw keyError(index, 'each key must be an object');+ for (const field of Object.keys(key)) {+ if (!KEY_FIELDS.includes(field)) throw keyError(index, `does not take ${field}; fields: ${KEY_FIELDS.join(', ')}`);+ }+ if (typeof key.name !== 'string' || !NAME_PATTERN.test(key.name)) throw keyError(index, 'name must be 1 to 48 letters, digits, dots, dashes or underscores');+ if (names.has(key.name)) throw keyError(index, `name ${key.name} is used twice`);+ names.add(key.name);+ if ((key.edits === undefined) === (key.offsets === undefined)) throw keyError(index, 'give exactly one of edits or offsets');+ const value = key.value ?? 0;+ if (typeof value !== 'number' || !(value >= 0 && value <= 1)) throw keyError(index, 'value is the starting weight, from 0 to 1');+ const edits = key.edits ?? (Array.isArray(key.offsets) ? key.offsets.map(entry => offsetEdit(entry, index)) : null);+ if (!edits) throw keyError(index, 'offsets must be an array');+ normalizeMeshEdits(edits);+ return { name: key.name, value, edits };+ });+}++/**+ * The morph targets of the keys: each key's edits run on the evaluated mesh and the per-vertex difference is gathered into+ * render vertices. A key that adds, removes or reorders vertices is an error, because a morph target is one offset per vertex.+ */+export function shapeKeyTargets(mesh, renderVertexSource, keys, editOptions) {+ return keys.map(key => {+ const shaped = applyMeshEdits(mesh, key.edits, editOptions).mesh;+ if (shaped.vertexCount !== mesh.vertexCount || shaped.faceCount !== mesh.faceCount) {+ throw new RangeError(`Shape key ${key.name} changed the mesh from ${mesh.vertexCount} to ${shaped.vertexCount} vertices. Use edits that only move vertices (translate, set_position, displace, sculpt, shrinkwrap, smooth, simple_deform, lattice, hook, wave) or offsets.`);+ }+ const positions = new Float32Array(renderVertexSource.length * 3);+ for (let renderVertex = 0; renderVertex < renderVertexSource.length; renderVertex++) {+ const vertex = renderVertexSource[renderVertex];+ for (let axis = 0; axis < 3; axis++) {+ positions[renderVertex * 3 + axis] = shaped.positions[vertex * 3 + axis] - mesh.positions[vertex * 3 + axis];+ }+ }+ return { positions };+ });+}diff --git a/tests/mesh-shape-keys.test.js b/tests/mesh-shape-keys.test.jsnew file mode 100644index 00000000..2b193f18--- /dev/null+++ b/tests/mesh-shape-keys.test.js@@ -0,0 +1,115 @@+import './support/load-agent-scene-modules.mjs';+import assert from 'node:assert/strict';+import test from 'node:test';+import { createAgentScene } from '../src/agent-scene.js';+import { exportGlb } from '../src/export.js';++function faceRecipe(extra = {}) {+ return {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{+ id: 'face', type: 'mesh', base: { type: 'box', bevel: 0, subdivisions: 2 },+ shapeKeys: [+ { name: 'lift', offsets: [{ select: { tag: 'top' }, offset: [0, 0.5, 0] }] },+ { name: 'widen', edits: [{ op: 'set_position', offset: { vec: [{ mul: [{ attr: 'position', component: 'x' }, 0.5] }, 0, 0] } }] },+ ],+ }],+ materials: [{ id: 'skin' }],+ nodes: [{ id: 'head', geometry: 'face', material: 'skin' }],+ motion: {+ duration: 2,+ tracks: [+ { kind: 'morph', id: 'lift', property: 'weight', keyframes: [{ time: 0, value: 0 }, { time: 1, value: 1 }] },+ { kind: 'morph', id: 'widen', property: 'weight', keyframes: [{ time: 0, value: 0 }, { time: 1, value: 0.5 }] },+ ],+ },+ ...extra,+ };+}++// The renderer adds weight times offset to every vertex; this does the same on the CPU.+function blendedPositions(part) {+ const { positions, morphTargets } = part.geometry;+ const blended = Float32Array.from(positions);+ morphTargets.forEach((target, index) => {+ for (let component = 0; component < blended.length; component++) blended[component] += part.morph.weights[index] * target.positions[component];+ });+ return blended;+}++function highestY(positions) {+ let highest = -Infinity;+ for (let index = 1; index < positions.length; index += 3) highest = Math.max(highest, positions[index]);+ return highest;+}++function widestX(positions) {+ let widest = -Infinity;+ for (let index = 0; index < positions.length; index += 3) widest = Math.max(widest, positions[index]);+ return widest;+}++test('a recipe mesh carries named shape keys as morph targets with offsets only where the key moves vertices', () => {+ const scene = createAgentScene(faceRecipe());+ const [part] = scene.parts;+ assert.deepEqual(part.geometry.morphTargetNames, ['lift', 'widen']);+ assert.equal(part.geometry.morphTargets.length, 2);+ assert.deepEqual(Array.from(part.morph.weights), [0, 0]);+ const lift = part.geometry.morphTargets[0].positions;+ const base = part.geometry.positions;+ for (let vertex = 0; vertex < base.length / 3; vertex++) {+ const onTop = Math.abs(base[vertex * 3 + 1] - 0.5) < 1e-6;+ assert.ok(Math.abs(lift[vertex * 3 + 1] - (onTop ? 0.5 : 0)) < 1e-6, `vertex ${vertex}`);+ }+});++test('morph tracks blend two shape keys of a recipe mesh', () => {+ const scene = createAgentScene(faceRecipe());+ const [part] = scene.parts;+ const rest = Float32Array.from(part.geometry.positions);+ scene.sampleMotion(0);+ assert.deepEqual(Array.from(part.morph.weights), [0, 0]);+ scene.sampleMotion(0.5);+ assert.deepEqual(Array.from(part.morph.weights), [0.5, 0.25]);+ const half = blendedPositions(part);+ assert.ok(Math.abs(highestY(half) - (highestY(rest) + 0.25)) < 1e-6, 'lift at half weight raises the top by 0.25');+ assert.ok(Math.abs(widestX(half) - widestX(rest) * (1 + 0.5 * 0.25)) < 1e-6, 'widen at quarter weight stretches x by 12.5 percent');+ scene.sampleMotion(1);+ assert.deepEqual(Array.from(part.morph.weights), [1, 0.5]);+ const full = blendedPositions(part);+ assert.ok(Math.abs(highestY(full) - (highestY(rest) + 0.5)) < 1e-6);+ assert.ok(Math.abs(widestX(full) - widestX(rest) * 1.25) < 1e-6);+});++test('shape keys that change the vertex count, repeat a name or sit on a missing track are refused', () => {+ const mesh = faceRecipe();+ const extruding = structuredClone(mesh);+ delete extruding.motion;+ extruding.geometries[0].shapeKeys = [{ name: 'grow', edits: [{ op: 'extrude_face_region', select: { tag: 'top' }, offset: 0.2 }] }];+ assert.throws(() => createAgentScene(extruding), /changed the mesh/);+ const repeated = structuredClone(mesh);+ repeated.geometries[0].shapeKeys[1].name = 'lift';+ assert.throws(() => createAgentScene(repeated), /used twice/);+ const both = structuredClone(mesh);+ both.geometries[0].shapeKeys[0].edits = [];+ assert.throws(() => createAgentScene(both), /exactly one of edits or offsets/);+ const unknownTrack = structuredClone(mesh);+ unknownTrack.motion.tracks[0].id = 'smile';+ assert.throws(() => createAgentScene(unknownTrack), /Motion target was not found: smile/);+});++test('the starting value of a key is the weight without motion, and a GLB export writes the morph targets', () => {+ const recipe = faceRecipe();+ delete recipe.motion;+ recipe.geometries[0].shapeKeys[0].value = 0.75;+ const scene = createAgentScene(recipe);+ const [part] = scene.parts;+ assert.deepEqual(Array.from(part.morph.weights), [0.75, 0]);+ const bytes = new Uint8Array(exportGlb(scene.parts));+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ const document = JSON.parse(new TextDecoder().decode(bytes.subarray(20, 20 + view.getUint32(12, true))));+ assert.equal(document.meshes[0].primitives[0].targets.length, 2);+ assert.ok(document.meshes[0].primitives[0].targets.every(target => target.POSITION !== undefined));+ assert.deepEqual(document.meshes[0].extras.targetNames, ['lift', 'widen']);+ assert.deepEqual(document.nodes.find(node => node.mesh === 0).weights, [0.75, 0]);+});