3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Harden the animation mixer and graph against overflowing inputs (#2416)
Nguyen Xuan An45d7eaae5fb6
diff --git a/changes/2416.md b/changes/2416.mdnew file mode 100644index 00000000..3ddd5f8c--- /dev/null+++ b/changes/2416.md@@ -0,0 +1 @@+- Refuse a mixer `play()` timeScale beyond 1e6, hold the graph speedParameter multiplier to 0 to 100 and keep 2D blend weights summing to 1 when positions overflow (#2416, #2417, #2418).diff --git a/docs/animation-graph.md b/docs/animation-graph.mdindex 38754f26..9d4738c0 100644--- a/docs/animation-graph.md+++ b/docs/animation-graph.md@@ -79,7 +79,7 @@ An agent builds the same graph without code: a scene recipe carries it in `game.## States and blend spaces-A state is `{ name, clip }` or `{ name, blend }`, plus optional `speed` (play rate, default 1), `speedParameter` (a number parameter that multiplies it, for example to match walking pace to ground speed) and `loop` (default: the clip's `loop`, true for a blend space). A clip that does not loop holds its last frame.+A state is `{ name, clip }` or `{ name, blend }`, plus optional `speed` (play rate, default 1), `speedParameter` (a number parameter that multiplies it, for example to match walking pace to ground speed; the multiplier is held between 0 and 100) and `loop` (default: the clip's `loop`, true for a blend space). A clip that does not loop holds its last frame.- 1D: `blend: { parameter, motions: [{ clip, threshold }] }`. Weights interpolate linearly between the two nearest thresholds and clamp outside them.- 2D: `blend: { parameters: [x, y], motions: [{ clip, position: [x, y] }] }`. Weights use gradient band interpolation: each motion is 1 at its own position, falls to 0 at every other motion, and stays local. Positions must differ.diff --git a/docs/animation-mixer.md b/docs/animation-mixer.mdindex 1b8c19aa..8cc3860a 100644--- a/docs/animation-mixer.md+++ b/docs/animation-mixer.md@@ -20,7 +20,7 @@ mixer.apply(1);| Method | Behavior || --- | --- |-| `play({ at, offset = 0, timeScale = 1, weight = 1 })` | Starts or restarts playback at `at`, with the given local offset and speed. |+| `play({ at, offset = 0, timeScale = 1, weight = 1 })` | Starts or restarts playback at `at`, with the given local offset and speed. `timeScale` stays within 1e6 either way. || `stop(at)` | Stops contributing from `at` onward. Earlier times retain their recorded playback. || `fadeTo(weight, { at, duration })` | Interpolates from the effective weight at `at` to the target weight. || `getState(time)` | Returns `phase`, `playing`, `weight` and the unwrapped `localTime`. |diff --git a/src/animation-graph.js b/src/animation-graph.jsindex a0eec3b4..253aa8ee 100644--- a/src/animation-graph.js+++ b/src/animation-graph.js@@ -19,6 +19,7 @@ export const ANIMATION_GRAPH_LIMITS = Object.freeze({maximumMotions: 16,maximumFadeSeconds: 10,maximumDeltaSeconds: 10,+ maximumSpeedMultiplier: 100,});const PARAMETER_TYPES = ['number', 'boolean', 'trigger'];@@ -351,7 +352,8 @@ function writeBlend2DWeights(state, x, y, weights) {weights[index] = weight;total += weight;}- if (total === 0) {+ if (!(total > 0)) {+ weights.fill(0);weights[0] = 1;return;}@@ -365,7 +367,7 @@ function createStateRuntime(state) {function stateSpeed(runtime, parameters) {const { state } = runtime;const multiplier = state.speedParameter ? parameters.get(state.speedParameter).value : 1;- return state.speed * Math.max(0, multiplier);+ return state.speed * Math.min(ANIMATION_GRAPH_LIMITS.maximumSpeedMultiplier, Math.max(0, multiplier));}function advanceStateRuntime(runtime, parameters, deltaSeconds) {diff --git a/src/animation-mixer.js b/src/animation-mixer.jsindex 528aab26..64dc79c2 100644--- a/src/animation-mixer.js+++ b/src/animation-mixer.js@@ -3,6 +3,7 @@ import { compileAnimationSampler, retainAnimationMaterial } from './animation.jsconst MATERIAL_PROPERTIES = new Set(['emission', 'metallic', 'roughness']);const MINIMUM_POSITIVE_VALUE = 1e-8;+const MAXIMUM_TIME_SCALE = 1e6;function finiteTime(time) {if (!Number.isFinite(time)) throw new TypeError('Mixer times must be finite.');@@ -98,6 +99,7 @@ function playState(action, { at = 0, offset = 0, timeScale = 1, weight = 1 } = {controlState(action, at);finiteTime(offset);if (!Number.isFinite(timeScale)) throw new TypeError('Action timeScale must be finite.');+ if (Math.abs(timeScale) > MAXIMUM_TIME_SCALE) throw new RangeError(`Action timeScale must be within ${MAXIMUM_TIME_SCALE}, got ${timeScale}.`);validWeight(weight);return { at, playing: true, origin: at, offset, timeScale, fromWeight: weight, toWeight: weight, fadeEnd: at };}diff --git a/tests/animation-graph.test.js b/tests/animation-graph.test.jsindex 97e4459f..0a6a8c58 100644--- a/tests/animation-graph.test.js+++ b/tests/animation-graph.test.js@@ -335,3 +335,29 @@ test('a non-looping state over a looping clip holds the last frame instead of snassert.ok(Math.abs(Math.abs(held[2]) - Math.sin(Math.PI / 4)) < 1e-6, `after ${seconds}s the arm must stay at 90 degrees, got ${held}`);}});++test('a huge speedParameter value keeps phase and clip times finite', () => {+ const graph = createAnimationGraph({+ clips: CLIPS,+ parameters: { pace: { type: 'number', initial: 1 } },+ layers: [{ name: 'base', states: [{ name: 'walk', clip: 'walk', speed: 100, speedParameter: 'pace' }] }],+ });+ graph.set('pace', 1e308).advance(1).advance(1);+ const state = graph.layerState('base');+ assert.ok(Number.isFinite(state.phase));+ assert.ok(state.clips.every(entry => Number.isFinite(entry.time)));+});++test('a 2D blend space keeps weights summing to 1 when positions overflow the gradient maths', () => {+ const graph = createAnimationGraph({+ clips: CLIPS,+ parameters: { strafe: { type: 'number' }, forward: { type: 'number' } },+ layers: [{ name: 'base', states: [{ name: 'move', blend: { parameters: ['strafe', 'forward'], motions: [+ { clip: 'walk', position: [1e200, 0] },+ { clip: 'run', position: [-1e200, 0] },+ ] } }] }],+ });+ graph.advance(0.1);+ const total = graph.layerState('base').clips.reduce((sum, entry) => sum + entry.weight, 0);+ assert.ok(Math.abs(total - 1) < 1e-9, `weights sum to ${total}`);+});diff --git a/tests/animation-mixer.test.js b/tests/animation-mixer.test.jsindex 8dd9bac7..651bfebd 100644--- a/tests/animation-mixer.test.js+++ b/tests/animation-mixer.test.js@@ -346,3 +346,12 @@ test('invalid bindings fail without publishing partially registered material copshear.matrix[4] = 0.5;assert.throws(() => createAnimationMixer([shear]), /shear/);});++test('play refuses a timeScale that would overflow later applies', () => {+ const mixer = createAnimationMixer([part('part')]);+ const action = mixer.clipAction(constantClip('part', 'emission', 2));+ assert.throws(() => action.play({ timeScale: 1e308 }), /timeScale must be within/);+ assert.throws(() => action.play({ timeScale: -1e308 }), RangeError);+ action.play({ timeScale: 1e6 });+ assert.doesNotThrow(() => mixer.apply(10));+});