Skip to content

3D engine that AI agents drive

Keep weights animations on their own node and refuse masks that exclude every joint (#2526, #2527)

Nguyen Xuan Ana54e400e7eb8
diff --git a/changes/2526.md b/changes/2526.md
new file mode 100644
index 00000000..f6989313
--- /dev/null
+++ b/changes/2526.md
@@ -0,0 +1 @@
+- A glTF weights animation moves only its own node, no longer the morph weights of its child nodes (#2526)
diff --git a/changes/2526.size.md b/changes/2526.size.md
new file mode 100644
index 00000000..eaf6aea9
--- /dev/null
+++ b/changes/2526.size.md
@@ -0,0 +1 @@
+- goal:gltf-box: 9 bytes gzip so a weights animation stops moving the morph weights of child nodes, a wrong pose in any file where a morph mesh has a morph child
diff --git a/changes/2527.md b/changes/2527.md
new file mode 100644
index 00000000..f9e70c3d
--- /dev/null
+++ b/changes/2527.md
@@ -0,0 +1 @@
+- A motion layer mask whose `exclude` covers all its `joints` is refused instead of loading a layer that moves nothing (#2527)
diff --git a/docs/agent-motion.md b/docs/agent-motion.md
index ee80c0dd..07480c3c 100644
--- a/docs/agent-motion.md
+++ b/docs/agent-motion.md
@@ -152,7 +152,7 @@ each blending over the pose so far, before tracks and IK:
| Field | Meaning |
| --- | --- |
| `clip` | The `id` of an entry in `scene_inspect` `animations` |
-| `mask` | `{ joints, descendants = true, exclude }`, up to 32 node IDs or names each. The layer moves only these joints and what hangs below them; mesh parts follow their bone, and morph weights follow the bone that owns the mesh |
+| `mask` | `{ joints, descendants = true, exclude }`, up to 32 node IDs or names each; `exclude` may not cover every joint. The layer moves only these joints and what hangs below them; mesh parts follow their bone, and morph weights follow the bone that owns the mesh |
| `weight` | 0 to 1, default 1 |
| `speed`, `offset` | Layer time is `time * speed + offset`. `speed` 0.05 to 8, `offset` within 30 seconds |
| `loop` | Default `true`: the clip repeats. `false` holds its last key |
diff --git a/src/agent-clip-layers.js b/src/agent-clip-layers.js
index 4f52bef2..e12aeee9 100644
--- a/src/agent-clip-layers.js
+++ b/src/agent-clip-layers.js
@@ -70,6 +70,9 @@ function normalizedMask(input, resolveNode, position) {
if (input.exclude !== undefined) {
denseArray(input.exclude, MAX_MASK_JOINTS, `${label} exclude`);
mask.exclude = input.exclude.map(joint => resolveNode(joint, `${path}.exclude`));
+ if (mask.joints.every(joint => mask.exclude.includes(joint))) {
+ throw invalidField(`${path}.exclude`, input.exclude, 'a list that leaves at least one of the mask joints in; drop exclude or name other nodes');
+ }
}
return mask;
}
diff --git a/src/gltf-animation.js b/src/gltf-animation.js
index ae28587d..467cd18d 100644
--- a/src/gltf-animation.js
+++ b/src/gltf-animation.js
@@ -172,7 +172,9 @@ function tracksForChannel(channel, sampler, node, readAccessor) {
targetByTrack.set(track, node);
return [track];
}
- const meshes = [node, ...node.children].filter(candidate => candidate.morphTargetInfluences);
+ // Only the node's own primitives move. A child that carries a glTF node index is another node with its own weights.
+ const ownPrimitives = node.children.filter(child => child.association?.nodes === undefined);
+ const meshes = [node, ...ownPrimitives].filter(candidate => candidate.morphTargetInfluences);
return meshes.map(mesh => {
const track = createTrack(`${nodeTrackName(mesh)}.${property}`, times, values, interpolation);
targetByTrack.set(track, mesh);
diff --git a/tests/agent-clip-layers-mask.test.js b/tests/agent-clip-layers-mask.test.js
new file mode 100644
index 00000000..71a8dcd8
--- /dev/null
+++ b/tests/agent-clip-layers-mask.test.js
@@ -0,0 +1,27 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeClipLayers } from '../src/agent-clip-layers.js';
+
+const context = {
+ clips: [{ duration: 2, targets: new Set(['Hips']) }],
+ nodes: [{ id: 'node-0', name: 'Hips' }, { id: 'node-1', name: 'Spine' }],
+ hierarchy: [],
+ external: new Map(),
+};
+
+test('a mask that excludes every one of its joints is refused, since the layer would move nothing', () => {
+ assert.throws(
+ () => normalizeClipLayers([{ clip: 0, mask: { joints: ['Hips'], exclude: ['node-0'] } }], context),
+ /motion\.layers\[0\]\.mask\.exclude.*leaves at least one of the mask joints in/,
+ );
+ assert.throws(
+ () => normalizeClipLayers([{ clip: 0, mask: { joints: ['Hips', 'Spine'], exclude: ['Spine', 'Hips'], descendants: false } }], context),
+ /mask\.exclude/,
+ );
+});
+
+test('a mask that excludes only some joints, or other nodes, still loads', () => {
+ const layers = normalizeClipLayers([{ clip: 0, mask: { joints: ['Hips', 'Spine'], exclude: ['Spine'] } }], context);
+ assert.deepEqual(layers[0].mask, { joints: ['Hips', 'Spine'], exclude: ['Spine'] });
+ assert.doesNotThrow(() => normalizeClipLayers([{ clip: 0, mask: { joints: ['Hips'], exclude: ['Spine'] } }], context));
+});
diff --git a/tests/gltf-morph.test.js b/tests/gltf-morph.test.js
index 843fb630..e047e022 100644
--- a/tests/gltf-morph.test.js
+++ b/tests/gltf-morph.test.js
@@ -318,3 +318,18 @@ test('malformed deltas, defaults, accessor shapes and all animation channels rej
];
for (const edit of cases) await assert.rejects(parseGltf(morphAsset(edit)));
});
+
+test('a weights animation moves only its own node, not a child node that has its own morph mesh', async () => {
+ const asset = await parseGltf(morphAsset((document, append) => {
+ addWeightsClip(document, append);
+ document.nodes[0].children = [2];
+ document.nodes.push({ name: 'Child', mesh: 0, translation: [0, 5, 0] });
+ document.nodes[2].weights = [0.25, 0.5];
+ }));
+ const child = asset.parts.find(part => part.matrix[13] === 5);
+ const parent = asset.parts.find(part => part.matrix[12] === 0 && part.matrix[13] === 0);
+ asset.applyAnimation(1);
+ assert.deepEqual(Array.from(parent.morph.weights), [0.5, -0.5]);
+ assert.deepEqual(Array.from(child.morph.weights), [0.25, 0.5]);
+ asset.dispose();
+});