Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Animation graph: fix pose weight chain for blends and prove planted feet hold still (#774)

Nguyen Xuan An76269eba1f51
diff --git a/changes/774-foot-slide.md b/changes/774-foot-slide.md
new file mode 100644
index 00000000..c6285d21
--- /dev/null
+++ b/changes/774-foot-slide.md
@@ -0,0 +1 @@
+- Animation graph: blended clips now end with their own shares in `poseLayers()` (the chain of lerp factors ran in the wrong order, so a walk to run blend played as full run); planted feet no longer slide in a blend space (#774)
diff --git a/docs/animation-graph.md b/docs/animation-graph.md
index e94dd2b4..38d5e263 100644
--- a/docs/animation-graph.md
+++ b/docs/animation-graph.md
@@ -136,6 +136,10 @@ const parameterSystem = {
The controller turns the travel by its yaw. It faces -Z at yaw 0 while a glTF model faces +Z, so start it at `yaw: Math.PI` or turn the model's node. In the air the controller falls back to its own velocity, and vertical motion always stays with the controller.
+### Foot slide
+
+`tests/animation-foot-slide.test.js` measures it. A biped with idle, walk (1.4 m/s) and run (3.6 m/s) clips in a blend space plays through root motion, and each foot is followed in the world. The drift of a contact is how far the planted foot strays from where it landed. At constant speeds, in the walk, the run and both blends, the worst drift is under 1e-6 m. While the speed ramps from 0 to 3.6 m/s it stays under 0.03 m, because the blend weights change in the middle of a stance. This holds when the clips are authored so a planted foot moves back at the speed the root travels and the cycles share their foot-down phase; a clip with a foot that slides in its own authoring slides in the graph too.
+
## IK hooks
`createFootPlacement` and `createLookAt` build entries for the `ik` list of `createSkeletonPose` and `createAssetPose`. They read the game through a function, ease toward it with the pose time, and are deterministic.
diff --git a/src/animation-graph.js b/src/animation-graph.js
index 86fba2e0..0cc40c84 100644
--- a/src/animation-graph.js
+++ b/src/animation-graph.js
@@ -473,18 +473,20 @@ function createLayerRuntime(layer, parameters) {
writePoseWeights();
}
- // createSkeletonPose layers blend one over another, so a normalized set of weights becomes a chain of lerp factors.
+ // createSkeletonPose layers blend one over another, so each later clip lerps over the ones before it. For every clip to
+ // end with its own share, a clip's factor is its share divided by what the clips after it leave free.
function writePoseWeights() {
- let accumulated = 0;
- for (const slot of layer.slots) {
+ let laterShares = 0;
+ for (let index = layer.slots.length - 1; index >= 0; index--) {
+ const slot = layer.slots[index];
const share = runtime.weight * slot.weight;
if (layer.additive) {
slot.poseWeight = share;
continue;
}
- const remaining = 1 - accumulated;
- slot.poseWeight = remaining > 0 ? Math.min(1, Math.max(0, share / remaining)) : 0;
- accumulated += share;
+ const free = 1 - laterShares;
+ slot.poseWeight = free > 0 ? Math.min(1, Math.max(0, share / free)) : 0;
+ laterShares += share;
}
}
diff --git a/tests/animation-foot-slide.test.js b/tests/animation-foot-slide.test.js
new file mode 100644
index 00000000..e786603d
--- /dev/null
+++ b/tests/animation-foot-slide.test.js
@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { locomotionGraph, measureFootSlide } from './fixtures/foot-slide.js';
+
+// A character walks and runs through a blend space with root motion. A planted foot must hold still in the world, so the
+// drift of each contact (how far the foot strays from where it landed) is measured and held under a bound.
+
+const CONSTANT_SPEED_BOUND = 1e-6;
+const CHANGING_SPEED_BOUND = 0.03;
+const MINIMUM_CONTACTS = 6;
+
+function worstDrift(contactsByFoot) {
+ return Math.max(...Object.values(contactsByFoot).flatMap(contacts => contacts.map(contact => contact.drift)));
+}
+
+function contactCount(contactsByFoot) {
+ return Math.min(...Object.values(contactsByFoot).map(contacts => contacts.length));
+}
+
+for (const [label, speed] of [['walk', 1.4], ['run', 3.6], ['a walk to run blend', 2.5], ['an idle to walk blend', 0.7]]) {
+ test(`a planted foot does not slide while ${label} holds a constant speed`, () => {
+ const contacts = measureFootSlide({ seconds: 8, speedAt: () => speed });
+ assert.ok(contactCount(contacts) >= MINIMUM_CONTACTS, `each foot lands at least ${MINIMUM_CONTACTS} times`);
+ assert.ok(worstDrift(contacts) < CONSTANT_SPEED_BOUND, `worst drift ${worstDrift(contacts)} m`);
+ });
+}
+
+test('a planted foot stays under the drift bound while the speed ramps from idle to run', () => {
+ const contacts = measureFootSlide({ seconds: 12, speedAt: time => Math.min(3.6, time * 0.4) });
+ assert.ok(contactCount(contacts) >= MINIMUM_CONTACTS);
+ assert.ok(worstDrift(contacts) < CHANGING_SPEED_BOUND, `worst drift ${worstDrift(contacts)} m`);
+});
+
+test('the same speed sequence gives the same contacts and drift', () => {
+ const speedAt = time => 1.8 + 1.2 * Math.sin(time * 0.5);
+ const first = measureFootSlide({ seconds: 6, speedAt });
+ const second = measureFootSlide({ seconds: 6, speedAt });
+ assert.deepEqual(first, second);
+ assert.ok(worstDrift(first) < CHANGING_SPEED_BOUND, `worst drift ${worstDrift(first)} m`);
+});
+
+test('a walk to run blend halfway chains its pose weights to half walk and half run', () => {
+ const graph = locomotionGraph();
+ graph.set('speed', 2.5).advance(1 / 60);
+ const weights = graph.poseLayers().map(layer => layer.weight());
+ // Idle 0, walk about 0.5 of the pose so far, run 0.5: the later clips share what the earlier ones leave free.
+ assert.equal(weights[0], 0);
+ assert.ok(Math.abs(weights[1] - 1) < 1e-9);
+ assert.ok(weights[2] > 0.45 && weights[2] < 0.55);
+});
diff --git a/tests/animation-graph.test.js b/tests/animation-graph.test.js
index 4fc73f5e..612d78b8 100644
--- a/tests/animation-graph.test.js
+++ b/tests/animation-graph.test.js
@@ -247,7 +247,8 @@ test('pose weights chain so blended clips match a direct weighted mix', () => {
}] }));
graph.set('speed', 3).advance(0.01);
const weights = graph.poseLayers().map(layer => Number(layer.weight().toFixed(6)));
- assert.deepEqual(weights, [0, 0.5, 1]);
+ // Run lerps over walk by 0.5, and walk is the whole pose before it: walk and run end with half each.
+ assert.deepEqual(weights, [0, 1, 0.5]);
});
test('the same parameter sequence gives identical weights and times', () => {
diff --git a/tests/fixtures/foot-slide.js b/tests/fixtures/foot-slide.js
new file mode 100644
index 00000000..83d65bf9
--- /dev/null
+++ b/tests/fixtures/foot-slide.js
@@ -0,0 +1,101 @@
+import { createAnimationClip } from '../../src/animation.js';
+import { createAnimationGraph } from '../../src/animation-graph.js';
+import { createSkeletonPose } from '../../src/skeleton-pose.js';
+
+// A biped gait for measuring foot slide. The rig faces +z like a glTF model. Each foot is driven directly in the space of
+// the in-place root, so a foot in contact moves back at exactly the speed the root travels and stays still in the world.
+
+export const FOOT_SLIDE_STEP = 1 / 60;
+const LIFT_HEIGHT = 0.12;
+const CONTACT_HEIGHT = 1e-6;
+const SWING_KEYS = 8;
+const SIDES = Object.freeze([{ foot: 'FootL', x: 0.1, phase: 0 }, { foot: 'FootR', x: -0.1, phase: 0.5 }]);
+
+function wrap(fraction) {
+ return ((fraction % 1) + 1) % 1;
+}
+
+function footKeyframes({ x, phase }, { cycle, stride, stanceFraction }) {
+ // Phase 0 is the instant the foot lands. Over the stance it moves back by `stride`, then swings forward and up.
+ const position = (cycleFraction) => {
+ const fraction = wrap(cycleFraction + phase);
+ if (fraction < stanceFraction) return [x, 0, stride / 2 - stride * (fraction / stanceFraction)];
+ const swing = (fraction - stanceFraction) / (1 - stanceFraction);
+ return [x, Math.sin(swing * Math.PI) * LIFT_HEIGHT, -stride / 2 + stride * swing];
+ };
+ const fractions = new Set([0, 1, wrap(-phase), wrap(stanceFraction - phase)]);
+ for (let index = 1; index < SWING_KEYS; index++) fractions.add(wrap(stanceFraction + (1 - stanceFraction) * index / SWING_KEYS - phase));
+ return [...fractions].sort((a, b) => a - b).map(fraction => ({ time: fraction * cycle, value: position(fraction) }));
+}
+
+/** A looping gait whose root travels `speed` m/s along +z and whose planted feet move back at the same rate. */
+export function gaitClip({ speed, cycle, stanceFraction = 0.6 }) {
+ const stride = speed * cycle * stanceFraction;
+ const tracks = [{
+ target: 'Root',
+ property: 'translation',
+ keyframes: [{ time: 0, value: [0, 0, 0] }, { time: cycle, value: [0, 0, speed * cycle] }],
+ }];
+ for (const side of SIDES) tracks.push({ target: side.foot, property: 'translation', keyframes: footKeyframes(side, { cycle, stride, stanceFraction }) });
+ return createAnimationClip({ duration: cycle, loop: true, tracks });
+}
+
+export function standClip() {
+ const tracks = SIDES.map(side => ({ target: side.foot, property: 'translation', keyframes: [{ time: 0, value: [side.x, 0, 0] }, { time: 1, value: [side.x, 0, 0] }] }));
+ return createAnimationClip({ duration: 1, loop: true, tracks });
+}
+
+export function bipedRig() {
+ const joints = [{ name: 'Root', parent: -1, translation: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] }];
+ for (const side of SIDES) joints.push({ name: side.foot, parent: 0, translation: [side.x, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] });
+ return { joints };
+}
+
+export function locomotionGraph({ walkSpeed = 1.4, runSpeed = 3.6 } = {}) {
+ return createAnimationGraph({
+ rootMotion: { bone: 'Root' },
+ clips: {
+ idle: standClip(),
+ walk: gaitClip({ speed: walkSpeed, cycle: 1.0 }),
+ run: gaitClip({ speed: runSpeed, cycle: 0.6 }),
+ },
+ parameters: { speed: { type: 'number' } },
+ layers: [{
+ name: 'base',
+ states: [{ name: 'move', blend: { parameter: 'speed', motions: [{ clip: 'idle', threshold: 0 }, { clip: 'walk', threshold: walkSpeed }, { clip: 'run', threshold: runSpeed }] } }],
+ }],
+ });
+}
+
+/**
+ * Play the graph while `speedAt(time)` sets its speed parameter and follow each foot in the world. A contact is a run of
+ * frames with the foot on the ground; its drift is how far the foot strays from where it landed. Returns per-foot contacts.
+ */
+export function measureFootSlide({ graph = locomotionGraph(), seconds = 12, speedAt }) {
+ const pose = createSkeletonPose({ rig: bipedRig(), layers: graph.poseLayers() });
+ const position = [0, 0];
+ const feet = new Map(SIDES.map(side => [side.foot, { contacts: [], current: null }]));
+ for (let step = 0; step < Math.round(seconds / FOOT_SLIDE_STEP); step++) {
+ graph.set('speed', speedAt(graph.time));
+ graph.advance(FOOT_SLIDE_STEP);
+ position[0] += graph.rootMotion.delta[0];
+ position[1] += graph.rootMotion.delta[1];
+ pose.apply(graph.time);
+ for (const [name, record] of feet) {
+ const local = pose.jointWorld(name).position;
+ // The model faces +z while the player convention faces -z, so the model is turned half a turn about y.
+ const world = [position[0] - local[0], position[1] - local[2]];
+ if (local[1] > CONTACT_HEIGHT) {
+ record.current = null;
+ continue;
+ }
+ if (!record.current) {
+ record.current = { start: graph.time, anchor: world, drift: 0, frames: 0 };
+ record.contacts.push(record.current);
+ }
+ record.current.drift = Math.max(record.current.drift, Math.hypot(world[0] - record.current.anchor[0], world[1] - record.current.anchor[1]));
+ record.current.frames++;
+ }
+ }
+ return Object.fromEntries([...feet].map(([name, record]) => [name, record.contacts.map(({ start, drift, frames }) => ({ start, drift, frames }))]));
+}