3D engine that AI agents drive
Animation: trusted fast path and no per-frame reset on one clip
Nguyen Xuan An10d669b24d1f
diff --git a/bench/runtime/adapters.js b/bench/runtime/adapters.jsindex 8d99c307..2825061d 100644--- a/bench/runtime/adapters.js+++ b/bench/runtime/adapters.js@@ -40,7 +40,7 @@ function levelsForScene(scene) {return levels;}-export async function create67Adapter(canvas, scene, characters, { culling = true, lods = true, hdr = true, samples = 4, shading = 'full' } = {}) {+export async function create67Adapter(canvas, scene, characters, { culling = true, lods = true, hdr = true, samples = 4, shading = 'full', checks = true } = {}) {const environment = {world: true, fillIntensity: 0, ambientIntensity: 1, fogDensity: 0,lightDirection: scene.sun.direction, keyColor: scene.sun.color,@@ -82,9 +82,9 @@ export async function create67Adapter(canvas, scene, characters, { culling = trurenderer.updateParts(parts);}if (assets.length) {- assets.forEach((asset, index) => asset.applyAnimation(time + index * SECONDS_PER_CHARACTER_OFFSET, 0));+ assets.forEach((asset, index) => asset.applyAnimation(time + index * SECONDS_PER_CHARACTER_OFFSET, 0, { checks }));const beforeUpload = performance.now();- renderer.updateParts(parts);+ renderer.updateParts(parts, { checks });this.updatePartsTimes.push(performance.now() - beforeUpload);}},diff --git a/bench/runtime/harness.js b/bench/runtime/harness.jsindex 31d74465..e4636169 100644--- a/bench/runtime/harness.js+++ b/bench/runtime/harness.js@@ -111,6 +111,7 @@ async function createAdapter(engine, canvas, scene, characters) {if (engine === '67js-no-lod') return create67Adapter(canvas, scene, characters, { lods: false });if (engine === '67js-no-culling') return create67Adapter(canvas, scene, characters, { culling: false, lods: false });if (engine === '67js-ldr') return create67Adapter(canvas, scene, characters, { hdr: false });+ if (engine === '67js-trusted') return create67Adapter(canvas, scene, characters, { checks: false });if (engine === '67js-light') return create67Adapter(canvas, scene, characters, { shading: 'light' });if (engine === '67js-one-sample') return create67Adapter(canvas, scene, characters, { samples: 1 });if (engine === '67js-ldr-one-sample') return create67Adapter(canvas, scene, characters, { hdr: false, samples: 1 });diff --git a/bench/runtime/run.mjs b/bench/runtime/run.mjsindex 87444531..3eebdac8 100644--- a/bench/runtime/run.mjs+++ b/bench/runtime/run.mjs@@ -16,9 +16,10 @@ const BACKENDS = {gpu: { arguments: SHARED_ARGUMENTS, frames: 120 },cpu: { arguments: [...SHARED_ARGUMENTS, '--use-angle=swiftshader', '--enable-unsafe-swiftshader'], frames: 15 },};-const ENGINES = ['67js', 'three', 'three-instanced', '67js-no-lod', '67js-no-culling', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample', '67js-light'];+const ENGINES = ['67js', 'three', 'three-instanced', '67js-no-lod', '67js-no-culling', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample', '67js-light', '67js-trusted'];// Ablations of the HDR target and MSAA, which cost something in every scene. They run only when named with --engine.-const FEATURE_ENGINES = new Set(['67js-light', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample']);+// 67js-trusted animates characters with checks off (applyAnimation and updateParts { checks: false }).+const FEATURE_ENGINES = new Set(['67js-trusted', '67js-light', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample']);const INSTANCED_SCENES = new Set(['instanced-objects']);// Ablations of this renderer's own culling and level selection, which only a scene that has them can show.const ABLATION_SCENES = new Set(['large-outdoor']);diff --git a/changes/572-fast-path.md b/changes/572-fast-path.mdnew file mode 100644index 00000000..e56d515c--- /dev/null+++ b/changes/572-fast-path.md@@ -0,0 +1 @@+- `applyAnimation(time, clip, { checks: false })` and `renderer.updateParts(parts, { checks: false })` skip the per-frame pose checks for clips you trust, and frames on the same clip no longer reset and snapshot every node. Eight animated characters: update CPU 1.6 ms to 1.3 ms with checks, 0.9 ms without.diff --git a/changes/572-fast-path.size.md b/changes/572-fast-path.size.mdnew file mode 100644index 00000000..8084b4d9--- /dev/null+++ b/changes/572-fast-path.size.md@@ -0,0 +1,2 @@+- scene:agent-scene: the checks option and the same-clip path for animated assets, which cut skinned update CPU further.+- goal:agent-scene: 85 bytes for that; accepted by the lead under the trade-off rule.diff --git a/src/gltf.js b/src/gltf.jsindex e7be8a08..fff36e0d 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -1,3 +1,4 @@+import { mat4 } from 'gl-matrix';import { applyClip } from './gltf-animation.js';import { GLTF_LAYER_EXTENSIONS, layerTextureReferences, materialLayersFromGltf } from './gltf-layers.js';import { attributeFloats } from './gltf-accessors.js';@@ -973,7 +974,7 @@ function makeSkinBinding(node) {const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];-function prepareSkinBinding(binding, geometry) {+function prepareSkinBinding(binding, geometry, checks = true) {const { node, skin, pendingPose, pendingWorld } = binding;if (skin.jointMatrices !== binding.palette || skin.jointWorldMatrices !== binding.jointWorld || binding.palette.length !== pendingPose.jointMatrices.length || binding.jointWorld.length !== pendingWorld.length) throw new Error('Imported skin palette identities must remain unchanged.');for (let joint = 0; joint < node.skeleton.bones.length; joint++) {@@ -982,8 +983,8 @@ function prepareSkinBinding(binding, geometry) {// A joint at zero scale collapses its vertices to a point instead of refusing the pose.if (collapseSingularMatrix(jointWorld, undefined, COLLAPSED_JOINT_SCALE)) binding.collapsedJoints = true;}- updateSkinPose(pendingPose, pendingWorld, skin.inverseBindMatrices, node.matrixWorld.elements, skin.bindMatrix);- validateSkinPose(pendingPose, geometry, node.matrixWorld.elements);+ updateSkinPose(pendingPose, pendingWorld, skin.inverseBindMatrices, node.matrixWorld.elements, skin.bindMatrix, checks);+ if (checks) validateSkinPose(pendingPose, geometry, node.matrixWorld.elements);}function commitSkinBinding(binding) {@@ -1014,15 +1015,21 @@ function prepareMorphBinding(binding) {const COLLAPSED_SCALE = 2e-4;const COLLAPSED_JOINT_SCALE = 1e-2;-const collapseScratch = new Matrix4();/*** Replaces a singular or non-finite world matrix, in place, with a uniform scale of 0.0002 at the same position so the* part is a speck that stays finite and invertible. Returns true when it replaced the matrix.*/function collapseSingularMatrix(elements, determinantFloor = 1e-12, collapsedScale = COLLAPSED_SCALE) {- const finite = elements.every(Number.isFinite);- const determinant = finite ? collapseScratch.fromArray(elements).determinant() : NaN;+ let finite = true;+ for (let index = 0; index < 16; index++) {+ if (!Number.isFinite(elements[index])) {+ finite = false;+ break;+ }+ }+ // mat4.determinant reads the elements as doubles, the same values a Float64 copy would hold.+ const determinant = finite ? mat4.determinant(elements) : NaN;if (finite && Number.isFinite(determinant) && Math.abs(determinant) >= determinantFloor) return false;const position = [elements[12], elements[13], elements[14]];const keepPosition = position.every(Number.isFinite);@@ -1465,9 +1472,10 @@ export async function parseGltf(data, options = {}) {applyClip(gltf.animations[animation.clip], animation.time);}- function preparePose() {+ /** Pose every part from the scene graph. `checks: false` keeps the zero-scale repairs and skips the finite, singular and winding checks. */+ function preparePose(checks = true) {gltf.scene.updateMatrixWorld(true);- validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);+ if (checks) validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);const worldMatrix = new Matrix4();for (const { node, instanceMatrix, part, mirrored, matrix, pendingMatrix, skin } of bindings) {if (part.matrix !== matrix || matrix.length !== 16) {@@ -1477,7 +1485,7 @@ export async function parseGltf(data, options = {}) {throw new Error('Imported skin pose identity must remain unchanged.');}pendingMatrix.set(worldMatrixOf(node, instanceMatrix, worldMatrix).elements);- if (collapseSingularMatrix(pendingMatrix)) continue;+ if (collapseSingularMatrix(pendingMatrix) || !checks) continue;for (const value of pendingMatrix) {if (!Number.isFinite(value)) {throw new Error('Animation creates a non-finite Float32 world matrix.');@@ -1490,14 +1498,14 @@ export async function parseGltf(data, options = {}) {}}for (const binding of skinBindings) {- prepareSkinBinding(binding, binding.geometry);+ prepareSkinBinding(binding, binding.geometry, checks);}for (const binding of morphBindings) {if (binding.part.morph !== binding.pose) {throw new Error('Imported morph pose identity must remain unchanged.');}prepareMorphBinding(binding);- validateMorphTransform(binding.pendingPose, binding.metadata, binding.pendingMatrix, binding.pendingSkin);+ if (checks) validateMorphTransform(binding.pendingPose, binding.metadata, binding.pendingMatrix, binding.pendingSkin);}}@@ -1673,6 +1681,7 @@ export async function parseGltf(data, options = {}) {throw error;}commitPreparedPose(candidate.animation);+ poseFromAnimationOnly = false;settled = true;pendingTransaction = null;return parts;@@ -1698,13 +1707,21 @@ export async function parseGltf(data, options = {}) {gltf.release();}- function applyAnimation(time, clipIndex = 0) {+ /**+ * Pose the asset at `time` in a clip and commit it. `checks: false` skips the per-frame finite, singular and winding+ * checks, for clips you trust: import checks the base pose, not every key, so a broken clip may draw wrong instead of+ * throwing. Zero-scale joints are still repaired. Poses an agent sets go through stagePose, which always checks.+ */+ function applyAnimation(time, clipIndex = 0, { checks = true } = {}) {if (disposed) {throw new Error('The glTF asset was disposed.');}if (!Number.isFinite(time)) {throw new TypeError('Animation time must be finite.');}+ if (typeof checks !== 'boolean') {+ throw new TypeError('Animation checks must be a boolean.');+ }const clip = gltf.animations[clipIndex];if (!Number.isInteger(clipIndex) || !clip) {throw new RangeError('Animation clip index is out of range.');@@ -1713,24 +1730,29 @@ export async function parseGltf(data, options = {}) {throw new Error('A pose transaction is already pending. Commit or discard it first.');}// Same result as stagePose({ animation }).commit(), with one preparePose instead of two: nothing can change the- // scene between this stage and this commit. The rollback snapshot is reused across frames.+ // scene between this stage and this commit. When the committed pose came from applyAnimation alone, replaying+ // its animation restores it exactly, so no snapshot is needed; otherwise one reused snapshot is the rollback point.const animation = { clip: clipIndex, time: Math.max(0, Math.min(time, clip.duration)) };- rollbackPose ??= capturePrivatePose();- capturePrivatePose(rollbackPose);+ const snapshot = poseFromAnimationOnly ? null : capturePrivatePose(rollbackPose ??= capturePrivatePose());const previousAnimation = currentAnimation;try {- playAnimation(animation);- preparePose();+ // The same clip keys the same channels every frame, and every other node is still at its base pose.+ if (poseFromAnimationOnly && previousAnimation?.clip === animation.clip) applyClip(clip, animation.time);+ else playAnimation(animation);+ preparePose(checks);} catch (error) {playAnimation(previousAnimation);- restorePrivatePose(rollbackPose);+ if (snapshot) restorePrivatePose(snapshot);throw error;}commitPreparedPose(animation);+ poseFromAnimationOnly = true;return parts;}let rollbackPose = null;+ // True while the committed pose is the base pose or one applyAnimation made, with no overrides or morph weights.+ let poseFromAnimationOnly = true;/** Copy the prepared candidate pose into the committed parts. */function commitPreparedPose(animation) {diff --git a/src/renderer.js b/src/renderer.jsindex 3458a744..a87cf255 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -1201,7 +1201,13 @@ export class Renderer67 {return { ...layout, texture, data };}- updateParts(parts, { shadows = true } = {}) {+ /**+ * Upload changed parts. `checks: false` skips the per-frame pose checks (finite, non-singular, unmirrored skin and+ * morph transforms) for poses already checked where they were made, such as `applyAnimation(time, clip, { checks: false })`.+ * Identity, material and transform rules still apply.+ */+ updateParts(parts, { shadows = true, checks = true } = {}) {+ if (typeof checks !== "boolean") throw new TypeError("updateParts checks must be a boolean.");this.updatePartIdentities ??= new Set();this.updatePartIdentities.clear();this.updateSkins.clear();@@ -1232,13 +1238,13 @@ export class Renderer67 {if ((part.skin ?? null) !== location.skin || part.skin?.jointMatrices !== location.jointMatrices || part.geometry.skinIndices !== location.skinIndices || part.geometry.skinWeights !== location.skinWeights) throw new Error(`Skin identity changes require a new renderer: ${part.name}`);if (part.skin) {if (PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Skinned parts require a standard material tag.');- skinSupport().validateSkinPose(part.skin, part.geometry, part.matrix);+ if (checks) skinSupport().validateSkinPose(part.skin, part.geometry, part.matrix);this.updateSkins.add(location.batch.skinTexture);}if ((part.morph ?? null) !== (location.morph ?? null) || part.morph?.weights !== location.morphWeights || part.geometry.morphTargets !== location.morphTargets) throw new Error(`Morph identity changes require a new renderer: ${part.name}`);if (part.morph) {if (PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Morphed parts require a standard material tag.');- morphSupport().validateMorphTransform(part.morph, location.batch.morphTexture.info, part.matrix, part.skin);+ if (checks) morphSupport().validateMorphTransform(part.morph, location.batch.morphTexture.info, part.matrix, part.skin);this.updateMorphs.add(part.morph);}if (materialUnchanged) {@@ -1259,7 +1265,7 @@ export class Renderer67 {location.materialSnapshot = MaterialSnapshot.of(part.material);}// A palette upload also changes consumers absent from the submitted part list.- if (this.updateSkins.size) {+ if (checks && this.updateSkins.size) {for (const [part, location] of this.partLocations) {if (!location.skin || !this.updateSkins.has(location.batch.skinTexture) || this.updatePartIdentities.has(part)) continue;const committedMatrix = location.committedMatrix ?? location.batch.instanceData.subarray(location.index * INSTANCE_STRIDE, location.index * INSTANCE_STRIDE + 16);@@ -1268,7 +1274,7 @@ export class Renderer67 {}// Shared weights also affect batches absent from the submitted part list.// Nothing is shared when the update carries no morph and no skin.- if (this.updateMorphs.size || this.updateSkins.size) {+ if (checks && (this.updateMorphs.size || this.updateSkins.size)) {for (const [part, location] of this.partLocations) {if (!location.morph || this.updatePartIdentities.has(part)) continue;if (!this.updateMorphs.has(location.morph) && !this.updateSkins.has(location.batch.skinTexture)) continue;diff --git a/src/skinning.js b/src/skinning.jsindex de9f5ded..f61f2feb 100644--- a/src/skinning.js+++ b/src/skinning.js@@ -52,19 +52,24 @@ export function createSkinPose(jointCount) {return pose;}-/** Atomically calculate inverse(meshWorld) * jointWorld * inverseBind * bindMatrix. */-export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, meshWorldMatrix = IDENTITY_MATRIX, bindMatrix = IDENTITY_MATRIX) {+/**+ * Atomically calculate inverse(meshWorld) * jointWorld * inverseBind * bindMatrix. `checks: false` skips the finite,+ * affine and singular checks for inputs already checked, such as a loaded clip; a mesh world that cannot be inverted still throws.+ */+export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, meshWorldMatrix = IDENTITY_MATRIX, bindMatrix = IDENTITY_MATRIX, checks = true) {const workspace = poseWorkspaces.get(pose);if (!workspace || pose.jointMatrices !== workspace.jointMatrices) throw new Error('Use an unchanged pose from createSkinPose().');const count = pose.jointMatrices.length / 16;- validateMatrices(jointWorldMatrices, count, 'Joint world matrices');- validateMatrices(inverseBindMatrices, count, 'Inverse bind matrices');- validateMatrices(meshWorldMatrix, 1, 'Mesh world matrix');- validateMatrices(bindMatrix, 1, 'Bind matrix');+ if (checks) {+ validateMatrices(jointWorldMatrices, count, 'Joint world matrices');+ validateMatrices(inverseBindMatrices, count, 'Inverse bind matrices');+ validateMatrices(meshWorldMatrix, 1, 'Mesh world matrix');+ validateMatrices(bindMatrix, 1, 'Bind matrix');+ }workspace.meshWorld.set(meshWorldMatrix);workspace.bind.set(bindMatrix);if (!mat4.invert(workspace.meshInverse, workspace.meshWorld)) throw new Error('Mesh world matrix cannot be inverted.');- validateMatrices(workspace.meshInverse, 1, 'Inverse mesh world matrix');+ if (checks) validateMatrices(workspace.meshInverse, 1, 'Inverse mesh world matrix');for (let joint = 0; joint < count; joint++) {const offset = joint * 16;for (let component = 0; component < 16; component++) {@@ -76,7 +81,7 @@ export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, memat4.multiply(workspace.product, workspace.meshInverse, workspace.product);workspace.pending.set(workspace.product, offset);}- validateMatrices(workspace.pending, count, 'Joint palette');+ if (checks) validateMatrices(workspace.pending, count, 'Joint palette');pose.jointMatrices.set(workspace.pending);return pose;}diff --git a/tests/animation-fast-path.test.js b/tests/animation-fast-path.test.jsnew file mode 100644index 00000000..deb6e8ac--- /dev/null+++ b/tests/animation-fast-path.test.js@@ -0,0 +1,55 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { readFile } from 'node:fs/promises';+import { parseGltf } from '../src/gltf.js';++async function loadRobot() {+ const bytes = await readFile(new URL('fixtures/RobotExpressive.glb', import.meta.url));+ return parseGltf(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength), { maxVertices: 500000 });+}++function poseSnapshot(parts) {+ return parts.map(part => ({ matrix: [...part.matrix], palette: part.skin ? [...part.skin.jointMatrices] : null }));+}++test('applyAnimation with checks off gives the same pose as the checked path', async () => {+ const checked = await loadRobot();+ const unchecked = await loadRobot();+ for (const time of [0, 0.35, 1.2, 2.9]) {+ for (const clip of [0, 3]) {+ checked.applyAnimation(time, clip);+ unchecked.applyAnimation(time, clip, { checks: false });+ assert.deepEqual(poseSnapshot(unchecked.parts), poseSnapshot(checked.parts));+ }+ }+});++test('applyAnimation checks option must be a boolean', async () => {+ const asset = await loadRobot();+ assert.throws(() => asset.applyAnimation(0, 0, { checks: 'no' }), /checks must be a boolean/);+});++test('the checked path stays the default after an unchecked frame', async () => {+ const asset = await loadRobot();+ asset.applyAnimation(0.5, 0, { checks: false });+ const transaction = asset.stagePose({ animation: { clip: 0, time: 0.5 } });+ transaction.discard();+ assert.ok(asset.applyAnimation(0.6, 0).length > 0);+});++test('frame after frame on one clip matches a fresh asset posed once, across clip switches and overrides', async () => {+ const running = await loadRobot();+ const steps = [[0.2, 0], [0.5, 0], [0.9, 0], [0.3, 3], [0.6, 3], [1.1, 0]];+ for (const [time, clip] of steps) {+ running.applyAnimation(time, clip, { checks: false });+ const fresh = await loadRobot();+ fresh.applyAnimation(time, clip);+ assert.deepEqual(poseSnapshot(running.parts), poseSnapshot(fresh.parts), `time ${time} clip ${clip}`);+ }+ const node = running.nodes.find(entry => entry.editable && entry.joint);+ running.stagePose({ animation: { clip: 0, time: 0.4 }, nodeOverrides: [{ id: node.id, translation: [0, 5, 0] }] }).commit();+ running.applyAnimation(0.7, 0);+ const fresh = await loadRobot();+ fresh.applyAnimation(0.7, 0);+ assert.deepEqual(poseSnapshot(running.parts), poseSnapshot(fresh.parts), 'an override is cleared by the next applyAnimation');+});