[Feature] Motion matching

[miogds]

Summary

M3 of the animation roadmap (docs/Architecture/animationPoseLayer.md): characters animate with no animation state machine. Gameplay states a goal — desired velocity and facing, typically straight from SteeringSystem — and every search interval (default 0.1 s) the controller finds the database frame best matching the current pose and the predicted future trajectory, then jumps there through the existing inertialized-transition machinery. Root motion moves the entity: clips are the vocabulary, the search is the state machine.

setRootMotionEnabled(entityId: zombie, enabled: true)
setMotionMatching(entityId: zombie, descriptor: MotionMatchingDescriptor(
    leftFootPath: "root/hips/.../foot_l", rightFootPath: "root/hips/.../foot_r"))
setMotionMatchingEnabled(entityId: zombie, enabled: true)
// per frame, from AI:
setMotionMatchingGoal(entityId: zombie, desiredVelocity: steeringOutput)

Design points

• MotionDatabase — clips resampled at 30 Hz into 27-dim character-space feature vectors: foot positions/velocities, hip velocity, and future root trajectory positions + facings at 0.33/0.66/1.0 s, loop-wrapped with the clip's per-loop root displacement so trajectories never snap at clip ends. Per-dimension std-dev normalization, per-group weights (MotionMatchingWeights). Built lazily at runtime from the entity's loaded clips — no new file format or exporter changes; a persisted database is deferred until Learned Motion Matching needs one.
• Search — brute force with per-dimension early-out (a few thousand frames ≈ hundreds of microseconds), seeded with the currently playing frame's cost discounted 10% as hysteresis: only meaningfully better frames cause a jump, and winners near the natural playback position are skipped. This kills the pointless phase-jump churn a naive argmin produces.
• Frame-of-reference subtlety (bug found during development): the database measures foot velocities in character space including root travel; the query must therefore use world-space finite differences rotated into the character frame. Measuring character-relative deltas instead zeroes out travel and biases every query toward idle — test-covered.
• Trajectory prediction — first-order lag of a simulated velocity toward the goal (predictionHalflife), integrated in closed form; facing eases toward the desired facing (or the velocity direction).
• beginAnimationTransition generalized to arbitrary target times, so jumps land mid-clip through the standard transition path with root motion re-baselined.

Stacked on #10 (feature/animation_foot_ik) — merge #10 into develop first via its own PR page, then this retargets/merges cleanly.

Testing

AnimationMotionMatchingTests (10 tests, all passing):

• Database: frame count/layout exact; walk frames encode hip velocity 1 m/s and trajectory 0.33/0.66/1.0 m ahead; idle frames encode stillness; trajectory wraps across the clip loop without snapping
• Search: querying a stored frame's own features returns it (or an identical twin); walk-like vs idle-like queries land in the right clips
• End to end: a forward goal selects the walk clip and root motion moves the entity toward the goal; zeroing the goal settles on idle and stops the entity; playback stays monotonic under a constant matched goal (hysteresis); disabled by default

All six animation suites (sampler, policy, inertialization, root motion, foot IK, motion matching) pass together.