[Bugfix] Stop root motion from wrapping at a one-shot clip's duration

applyRootMotion computed its own channelTime via fmod(currentTime,
clipDuration), unconditionally, regardless of whether the clip's
channels repeat. Once currentTime passed a non-repeating clip's
duration, this wrapped back near zero, which wrappedChannelTime then
misread as a fresh loop and injected a full loop's root displacement
at that instant -- a visible snap right as a one-shot animation (e.g.
a kick) finished, even though ClipSampler already holds the displayed
pose correctly past that point.

Match ClipSampler: clamp to [0, duration] when no animated channel
repeats, only wrap when at least one does.

Author: untoldengine

Sources/UntoldEngine/Animation/RootMotion.swift

@@ -204,7 +204,12 @@ func applyRootMotion(
     // wrap, to detect when the clip looped between frames. Non-repeating
     // channels clamp at their last key (like the sampler), so a one-shot
     // clip never fakes a wrap and never injects a per-loop correction.
-    let channelTime = fmod(animationComponent.currentTime, clipDuration) * clipSpeed
+    // Match ClipSampler: a one-shot's clock must not wrap at completion,
+    // otherwise wrap detection injects an extra loop's root displacement.
+    let repeats = compiledClip.channels.contains { $0.animated && $0.repeats }
+    let sampleTime = repeats ? fmod(animationComponent.currentTime, clipDuration)
+        : min(max(animationComponent.currentTime, 0), clipDuration)
+    let channelTime = sampleTime * clipSpeed
     let translationTime = wrappedChannelTime(channelTime, lastKeyTime: channel.translationTimes.last, repeats: channel.repeats)
     let rotationTime = wrappedChannelTime(channelTime, lastKeyTime: channel.rotationTimes.last, repeats: channel.repeats)
 

Tests/UntoldEngineTests/AnimationRootMotionTests.swift

@@ -265,6 +265,38 @@ final class AnimationRootMotionTests: XCTestCase {
         )
     }
 
+    func testNonRepeatingClipHoldsPositionPastClipDurationWithoutLoopJump() {
+        animationComponent.animationClips["lunge"] = makeOneShotClip()
+
+        setRootMotionEnabled(entityId: entityId, enabled: true)
+        changeAnimation(entityId: entityId, name: "lunge", transitionHalflife: 0)
+
+        // 3 s: past the clip's own 2 s duration, not just the root channel's 1 s
+        // last key. Before the fix, applyRootMotion's own
+        // fmod(animationComponent.currentTime, clipDuration) wrapped unconditionally
+        // at the 2 s mark regardless of repeatAnimation, handing wrappedChannelTime
+        // a small post-wrap time it misread as a fresh loop and injecting a full
+        // loop's root displacement right at that instant — distinct from
+        // testNonRepeatingChannelDoesNotInjectLoopJump above, which only runs up to
+        // 1.89 s and so never reaches the clip's own duration.
+        var previousZ = getLocalPosition(entityId: entityId).z
+        var maxStep: Float = 0
+        run(frames: 270) { _ in
+            let z = getLocalPosition(entityId: self.entityId).z
+            maxStep = max(maxStep, abs(z - previousZ))
+            previousZ = z
+        }
+
+        XCTAssertEqual(
+            getLocalPosition(entityId: entityId).z, 1.0 - deltaTime, accuracy: 1e-3,
+            "Entity holds the authored 1 m travel; the clip's own duration elapsing must not add displacement"
+        )
+        XCTAssertLessThan(
+            maxStep, deltaTime * 1.5,
+            "currentTime crossing the clip's own duration must not be misread as a loop wrap"
+        )
+    }
+
     // MARK: - Pitch and roll preservation
 
     /// The swing–twist split must remove only yaw. A body-frame lean —