Skip to content

3D engine that AI agents drive

Harden the animation mixer and graph against overflowing inputs (#2416)

Nguyen Xuan An45d7eaae5fb6
diff --git a/changes/2416.md b/changes/2416.md
new file mode 100644
index 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.md
index 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.md
index 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.js
index 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.js
index 528aab26..64dc79c2 100644
--- a/src/animation-mixer.js
+++ b/src/animation-mixer.js
@@ -3,6 +3,7 @@ import { compileAnimationSampler, retainAnimationMaterial } from './animation.js
const 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.js
index 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 sn
assert.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.js
index 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 cop
shear.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));
+});