[Feature] Add root motion extraction and application - #1135
Open
miogds wants to merge 1 commit into
Open
Conversation
Locomotion clips authored with a traveling root previously dragged the mesh away from the entity transform and snapped back on loop. With root motion enabled (opt-in per entity, default off), the root joint's horizontal translation and yaw deltas are extracted from the raw sampled pose each frame and applied to the entity transform in character space via translateBy/rotateTo; the pose root is grounded (horizontal zeroed, yaw removed via swing-twist decomposition). Vertical motion, pitch, and roll stay in the pose. - Loop wrap corrected with the clip's precomputed per-loop root displacement and yaw (CompiledAnimationClip root metadata) — no backward snap when the clip wraps - setRootMotionEnabled(entityId:enabled:rootJointPath:) resolves hierarchical assets like the other animation APIs; the root defaults to the skeleton's first parentless joint, overridable by joint path - Deltas anchor to the entity the public API was called on (the gameplay handle): hierarchical assets carry the AnimationComponent on a skinned child, and applying deltas there would drift the child inside the asset while the root the game steers stays put - Runs on the raw sampled pose before transition offsets, and the transition capture grounds the incoming clip's samples, so inertialized transitions blend grounded poses and never teleport the character - Defends against LocalTransformComponent's zero-quaternion default rotation, which rotates every vector to zero Docs: docs/API/UsingRootMotion.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Next link in the animation chain after inertialized transitions (#1125): root motion. A locomotion clip authored with a traveling root previously dragged the mesh away from the entity transform and snapped it back on every loop. With root motion enabled — opt-in per entity, default off, zero cost when disabled — the root joint's horizontal translation and yaw deltas are extracted from the raw sampled pose each frame and applied to the entity transform in character space (
translateBy/rotateTo), while the pose root is grounded: horizontal travel zeroed, yaw removed via swing–twist decomposition. Vertical motion, pitch, and roll stay in the pose — a crouch still lowers the character, a stagger still leans it.API
CompiledAnimationCliproot metadata, and the wrapped-time jump is corrected with them.setEntityMeshAsync) carry theAnimationComponenton a skinned child while the game steers the asset root. Deltas are applied to the entity the public API was called on, so nothing drifts inside the asset. Flat entities behave exactly as before.changeAnimationre-baselines extraction, so a clip switch contributes no spurious delta.LocalTransformComponent's zero-quaternion default rotation (which rotates every vector to zero) by treating it as identity.How-to guide:
docs/API/UsingRootMotion.md. Single commit cherry-picked onto current develop (5f61789).Testing
AnimationRootMotionTests(11 tests, all passing):Inertialization, compiled-sampler, and policy suites still pass on this base. SwiftFormat lint clean.