Skip to content

3D engine that AI agents drive

Refuse malformed GLB animation keys and node parent loops (#2365)

Nguyen Xuan An47769c0fa735
diff --git a/changes/2365.md b/changes/2365.md
new file mode 100644
index 00000000..0ee097d9
--- /dev/null
+++ b/changes/2365.md
@@ -0,0 +1 @@
+- GLB export refuses animation keyframes of the wrong width and cubic keys without tangents, and a node list whose parents form a loop, each with an error that names the track or node instead of a misaligned accessor, an unnamed TypeError or a stack overflow (#2365, #2366, #2367)
diff --git a/changes/2365.size.md b/changes/2365.size.md
new file mode 100644
index 00000000..ea17b1cd
--- /dev/null
+++ b/changes/2365.size.md
@@ -0,0 +1,2 @@
+- entry:core: three guards (keyframe width and tangents, node parent loop) turn files with misaligned animation accessors and a stack overflow into one-line errors that name the track or node, for about 145 bytes gzip.
+- entry:core+lazy: the same guards.
diff --git a/src/export-skeleton.js b/src/export-skeleton.js
index 3c89ea8e..98eb3075 100644
--- a/src/export-skeleton.js
+++ b/src/export-skeleton.js
@@ -58,12 +58,22 @@ function worldMatrixOf(index, nodes, cache) {
/** Hierarchy records from `options.nodes` (the `nodes` of a parsed asset, or the same fields): name, id, parent id. */
function nodesFromRecords(records) {
const indexById = new Map(records.map((record, index) => [record.id ?? record.name, index]));
- return records.map(record => {
+ const nodes = records.map(record => {
if (typeof record.name !== 'string' || !record.name) throw new TypeError('GLB nodes need a name.');
const parent = record.parent === null || record.parent === undefined ? -1 : indexById.get(record.parent);
if (parent === undefined) throw new RangeError(`GLB node ${record.name} names a parent that is not in the node list.`);
return { name: record.name, parent, translation: record.translation, rotation: record.rotation, scale: record.scale, meshIds: record.meshIds ?? [] };
});
+ requireNoParentLoop(nodes);
+ return nodes;
+}
+
+function requireNoParentLoop(nodes) {
+ for (const node of nodes) {
+ let ancestor = node.parent;
+ for (let step = 0; ancestor >= 0 && step < nodes.length; step++) ancestor = nodes[ancestor].parent;
+ if (ancestor >= 0) throw new RangeError(`GLB node ${node.name} has a parent loop.`);
+ }
}
function jointWorld(skin, joint) {
@@ -194,6 +204,13 @@ function validateKeyframes(track) {
const timesValid = keyframes?.length > 0 && keyframes.every(({ time }) => time > previousTime && Number.isFinite(previousTime = time));
const valuesValid = keyframes?.every(({ value }) => Array.from(value).every(Number.isFinite));
if (!timesValid || !valuesValid) throw new RangeError(`GLB ${track.property} track on ${track.target} needs keyframes with finite values and strictly increasing finite times.`);
+ const fixedWidth = COMPONENTS_BY_PATH[track.property];
+ const width = fixedWidth ?? keyframes[0].value.length;
+ const sized = (list, size) => list?.length === size && Array.from(list).every(Number.isFinite);
+ const cubic = track.interpolation === 'CUBICSPLINE';
+ if (!keyframes.every(({ value, inTangent, outTangent }) => (!fixedWidth || value.length === width) && (!cubic || (sized(inTangent, width) && sized(outTangent, width))))) {
+ throw new RangeError(`GLB ${track.property} track on ${track.target} needs ${width} values${cubic ? ' and tangents' : ''} in every keyframe.`);
+ }
}
function writeTrack(writer, animation, sourceTrack, nodeIndex) {
diff --git a/tests/export-skeleton-guards.test.js b/tests/export-skeleton-guards.test.js
new file mode 100644
index 00000000..c0d75a78
--- /dev/null
+++ b/tests/export-skeleton-guards.test.js
@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mat4 } from 'gl-matrix';
+import { exportGlb } from '../src/export.js';
+import { box } from '../src/geometry.js';
+
+const plainMaterial = { color: [1, 1, 1], metallic: 0, roughness: 1 };
+
+function readDocument(binary) {
+ const view = new DataView(binary);
+ const jsonLength = view.getUint32(12, true);
+ return JSON.parse(new TextDecoder().decode(new Uint8Array(binary, 20, jsonLength)));
+}
+
+function clipOf(property, keyframes, interpolation) {
+ return { name: 'clip', tracks: [{ target: 'Rod', property, interpolation, keyframes }] };
+}
+
+const rodPart = () => ({ name: 'Rod', geometry: box(), matrix: mat4.create(), material: plainMaterial });
+
+test('a translation keyframe with the wrong number of components is refused, not written as a misaligned accessor', () => {
+ const clip = clipOf('translation', [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [1, 2] }]);
+ assert.throws(() => exportGlb([rodPart()], { clips: [clip] }), /translation track on Rod.*3 values/i);
+});
+
+test('a rotation keyframe needs four components', () => {
+ const clip = clipOf('rotation', [{ time: 0, value: [0, 0, 0, 1] }, { time: 1, value: [0, 0, 1] }]);
+ assert.throws(() => exportGlb([rodPart()], { clips: [clip] }), /rotation track on Rod.*4 values/i);
+});
+
+test('a cubic keyframe without tangents names the track instead of failing inside Array.from', () => {
+ const clip = clipOf('translation', [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [1, 0, 0] }], 'CUBICSPLINE');
+ assert.throws(() => exportGlb([rodPart()], { clips: [clip] }), /translation track on Rod.*tangent/i);
+});
+
+test('well formed cubic keyframes still export with three values per tangent', () => {
+ const tangent = [0, 0, 0];
+ const keyframes = [0, 1].map(time => ({ time, value: [time, 0, 0], inTangent: tangent, outTangent: tangent }));
+ const binary = exportGlb([rodPart()], { clips: [clipOf('translation', keyframes, 'CUBICSPLINE')] });
+ const document = readDocument(binary);
+ assert.equal(document.accessors[document.animations[0].samplers[0].output].count, 6);
+});
+
+test('a node list whose parents form a loop is refused with the loop named', () => {
+ const nodes = [
+ { name: 'Rod', id: 'a', parent: 'b', meshIds: ['mesh-0'] },
+ { name: 'Handle', id: 'b', parent: 'a', meshIds: [] },
+ ];
+ assert.throws(() => exportGlb([rodPart()], { nodes }), /GLB node (Rod|Handle).*parent.*loop/i);
+});