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.mdnew file mode 100644index 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.mdindex 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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.jsnew file mode 100644index 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 }))]));+}