3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Refuse malformed GLB animation keys and node parent loops (#2365)
Nguyen Xuan An47769c0fa735
diff --git a/changes/2365.md b/changes/2365.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsindex 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.jsnew file mode 100644index 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);+});