fix: buffered linear interpolator jitter and exposing more properties #3355

NoelStephensUnity · 2025-03-21T02:35:20Z

After doing some testing I noticed a few anomalies with the updated BufferedLinearInterpolator<T>. As it turns out, there are more than one approaches a user might need depending upon what they are trying to accomplish and each option really performs best when tweaking some properties within the BufferedLinearInterpolator<T> that were not completely exposed.

Various options:

You might want to enable, disable, or adjust the maximum interpolation time of the last smooth lerp phase for each interpolator type.
You might want to manually adjust the tick latency offset (NetworkTransform.InterpolationBufferTickOffset) used depending upon context.
- When using a client-server topology, you might want this to be set to something like 0 or 1 (depending upon interpolator).
  - You might want this value to be higher (like say +2-3 depending on latency and interpolation type) on non-authority instances where the authority is some other client and not the host/server.

This PR renames `Lerp` to `LegacyLerp` and adds a 3rd new `Lerp` interpolator type:

Lerp (new)

Uses a 1 to 2 phase approach that lerps towards the target, lerps towards the next target (if one exists) ahead by 1 frame delta, blends the two results, and (optionally) smooth the final value.

The first phase lerps towards the current tick state update being processed.
The second phase (optional) performs a lerp smoothing where the current respective transform value is lerped towards the result of the first phase at a rate of 1.0f minus the max interpolation time.

Changelog

Added: Lerp interpolation type that still uses a lerp approach but uses the new buffer consumption logic.
Added: Property to enable or disable lerp smoothing for position, rotation, and scale interpolators.
Added: NetworkTransform.InterpolationBufferTickOffset static property to provide users with a way to increase or decrease the time marker where interpolators will pull state update from the queue.
Fixed: Issue where the time delta that interpolators used would not be properly updated during multiple fixed update invocations within the same player loop frame.
Changed: The original Lerp to be renamed to LegacyLerp.

Testing and Documentation

Includes integration test updates.
Includes documentation for public API entry points.
Includes updates to public documentation for NetworkTransform. (Will be adding to PR-1443)

Getting closer to what I am hoping to achieve.

Adding more properties for users to adjust as well as an additional interpolation type as there are various use cases where one model doesn't fit all genres.

Just wrapping some code that I will be removing anyway before marking this PR ready for review. Adding some line breaks in new XML API documentation.

Updating PositionMaxInterpolationTime, RotationMaxInterpolationTime, and ScaleMaxInterpolationTime to be set when `NetworkTransform.SetMaxInterpolationBound` is invoked.

updating the xml api

Defaulting the lerp smoothing to true (like it was originally when you couldn't enable/disable it). Removing debug script from NetworkManager.

Forgot to remove the components namespace when removing the debug script.

Only apply the InterpolationBufferTickOffset once.

Bumping the default tick latency down to 1.

Fixing some additional issues and trying to find a reasonable balance.

Updating NetworkTransformGeneral to test all interpolator types and adding a means to getting verbose debug logs,

Fixing a mistake on SD final lerp pass.

making the added verbose log history internal to avoid PVP issue.

making sure the first entry is set to having reached its final point.

Adding debug information to better understand the failure.

Sigh...

Removing the teleport I put in last week.

Dumb floating point precision.

Minor adjustment UpdateInterpolation

Removing commented out code. NetworkTransform using the realtime provider time system to be more compatible with the integration test time travel system.

providing a bit more time and reducing the target position to provide enough time to for interpolation.

Removing some of the debug information. Fixing whitespace issue. Adding a smooth lerp and non-smooth lerp pass.

Adding additional LerpExtrapolateBlend passes

Minor adjustments after a long debug session...

- Removed the lerp smoothing parameter and made it an internal bool (don't need to add to API and it should be set through the NetworkTransform anyway). - Added additional BufferedLinearInterpolator debug code. - Added additional PreUpdate pass for NetworkTransforms using Rigidbody motion in order to reset a fixed time delta. - Added incemental fixed time delta when the FixedUpdate is invoked multiple times within a single frame. - Added internal time sync counter. - Added a "1/3rd" rule to smooth dampening and LerpExtrapolateBlend when smooth lerp is enabled in order to still be able to balance between smoothing the final lerped value and reaching the target (or getting much closer).

removing the lerpSmoothing parameter from xml API documentation.

One more removal of the same lerpSmoothing parameter in comments.

arrg... lists! PVP!

2 more...evidently you can't use <list> within a <param>

Quaternion approximation calculation was wrong.

Adding [MethodImpl(MethodImplOptions.AggressiveInlining)] to float, Vector3, and Quaternion LinearBufferInterpolator methods.

Updating the approximation approach to yield a more precise end result.

Don't try to convert InterpolateState.Target if not assigned yet.

Making smooth lerp a slightly faster for LEB and SD interpolation types.

EmandM

Not sure I understand all of it, but here is an initial pass review :)

com.unity.netcode.gameobjects/Runtime/Timing/NetworkTimeSystem.cs

com.unity.netcode.gameobjects/Runtime/Components/Interpolator/BufferedLinearInterpolator.cs

com.unity.netcode.gameobjects/Runtime/Components/NetworkTransform.cs

com.unity.netcode.gameobjects/Runtime/Components/Interpolator/BufferedLinearInterpolator.cs

Exposing internal access to position and rotation interpolators for future tests and tools. Noticed the slerp for full precision rotation was only being applied when using Lerp, now it is for all interpolation types. Making the time to approximately reach adjustment be the default when there is no pending item to be consumed and slightly sooner when there is. Removing the adjustment to the slerp smoothing as this should be a consistantly applied value for all interpolation types.

Renaming NetworkTransformMultipleChangesOverTime to just MultipleChangesOverTime (no need for the NetworkTransform part as it is already part of the NetworkTransformTests). Turning off Lerp smoothing for MultipleChangesOverTime and added lengthy comment as to why. Fixed the initial check for the first state update in MultipleChangesOverTime due to a change in the Interpolation value. It was not properly checking both pushed and updated values and should only be checked when interpolation is turned off as the default is enabled and when running MultipleChangesOverTime for 3 axis it remains enabled (i.e. there will be no state update for that as nothing changed).

removing unused property.

Some clean up, renaming, and removing the change in the original BufferedLinearInterpolator<T>.ResetTo method.

EmandM

Ok! I get it! There's one Update() for Lerp, and a separate one for Smooth Dampening and LerpExtrapolateBlend! Ok, this looks good!

Renamed LerpExtrapolateBlend to LerpAhead. Found some issues with the original lerp's buffer consumption where it was always calculating 2x the time to target. Assuring that the original lerp logic isn't executed upon arriving to the final destination. Increasing the k_AproximatePrecision...preceision value to be one one hundred thousandth. Removed some debug code from NetworkTransformBase.

Adjusting changelog entry to replace LerpExtrapolateBlend with LerpAhead. Removing additional remarks tag.

…b.com/Unity-Technologies/com.unity.netcode.gameobjects into fix/bufferedlinearinterpolator-jitter

Updating the test project test for change in LerpAhead.

Reverting the change to fix that makes the original lerp properly calculate the time to target as opposed to always calculating 2x the time to target because all of the unit interpolator tests are specifically written for this specific flaw.

Whitespace fixes.

michalChrobot · 2025-04-02T08:44:04Z

Is it something that should be also ported to 1.X or not really @NoelStephensUnity?

Still had one more line of code needed to go back to original lerp buffer consumption where the time to target is always 2x the actual time to target (it ends up consuming 2 state updates for each non-authority update). Making sure some of the debugging BLI accessor methods in NetworkTransform are still accessible for internal testing purposes.

After testing for quite some time I came to the conclusion that we needed a "new" lerp and should mark the original lerp as the "legacy" lerp while keeping the added option to have the smooth dampening. Removed the additional phases from the "new" lerp and smooth dampening while also providing users with a more direct and constant maximum interpolation setting that is not directly tied to the frame time delta. This yields a wider range of fine tuning and will be easier to handle adjusting during runtime. The LinearBufferInterpolator RNSM component hooks are in place so we can provide users with a tool to be able to determine what is happening with the LinearBufferInterpolator... it will be released in the examples section once ready to be released. Adjusted API XML documentation and all places that referenced the other enum names changed.

updating changelog entry.

NoelStephensUnity added 30 commits March 19, 2025 12:19

wip

bc2e9f2

Getting closer to what I am hoping to achieve.

update

fe93343

Adding more properties for users to adjust as well as an additional interpolation type as there are various use cases where one model doesn't fit all genres.

fix

65dac85

Just wrapping some code that I will be removing anyway before marking this PR ready for review. Adding some line breaks in new XML API documentation.

update

f0fb0fd

Updating PositionMaxInterpolationTime, RotationMaxInterpolationTime, and ScaleMaxInterpolationTime to be set when `NetworkTransform.SetMaxInterpolationBound` is invoked.

style

81e551c

updating the xml api

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

9fbc654

update

565b469

Defaulting the lerp smoothing to true (like it was originally when you couldn't enable/disable it). Removing debug script from NetworkManager.

style

92d4ea9

Forgot to remove the components namespace when removing the debug script.

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

3f97156

fix

2bfcf52

Only apply the InterpolationBufferTickOffset once.

update

0d1f8ee

Bumping the default tick latency down to 1.

fix

2d53a3a

Fixing some additional issues and trying to find a reasonable balance.

test

55a0e87

Updating NetworkTransformGeneral to test all interpolator types and adding a means to getting verbose debug logs,

fix

29f5e46

Fixing a mistake on SD final lerp pass.

test

cfcd70b

making the added verbose log history internal to avoid PVP issue.

fix

d87bd75

making sure the first entry is set to having reached its final point.

test

4170dfe

Adding debug information to better understand the failure.

update

d2b552e

Sigh...

Update

1efdc3b

Removing the teleport I put in last week.

test

bdbb218

Dumb floating point precision.

update

b398f93

Minor adjustment UpdateInterpolation

update

ed45dc9

Removing commented out code. NetworkTransform using the realtime provider time system to be more compatible with the integration test time travel system.

test

4c36581

providing a bit more time and reducing the target position to provide enough time to for interpolation.

test

233188c

Removing some of the debug information. Fixing whitespace issue. Adding a smooth lerp and non-smooth lerp pass.

text

e7eaecd

Adding additional LerpExtrapolateBlend passes

update

4e705fe

Minor adjustments after a long debug session...

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

8005e8c

style

2e5e62f

removing the lerpSmoothing parameter from xml API documentation.

style

1175088

One more removal of the same lerpSmoothing parameter in comments.

NoelStephensUnity added 7 commits March 27, 2025 19:56

style

0959618

arrg... lists! PVP!

style

bcadba7

2 more...evidently you can't use <list> within a <param>

fix

f6ad63f

Quaternion approximation calculation was wrong.

update

9e9172f

Adding [MethodImpl(MethodImplOptions.AggressiveInlining)] to float, Vector3, and Quaternion LinearBufferInterpolator methods.

fix

283e2e8

Updating the approximation approach to yield a more precise end result.

fix

82306c0

Don't try to convert InterpolateState.Target if not assigned yet.

update

643329a

Making smooth lerp a slightly faster for LEB and SD interpolation types.

EmandM reviewed Mar 28, 2025

View reviewed changes

NoelStephensUnity added 6 commits March 28, 2025 18:41

style

bb7bfa0

removing unused property.

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

3b2bb8b

update

f327a1e

Some clean up, renaming, and removing the change in the original BufferedLinearInterpolator<T>.ResetTo method.

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

2e9b7c1

EmandM approved these changes Mar 31, 2025

View reviewed changes

EmandM and others added 8 commits March 31, 2025 14:40

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

9b8bde1

Merge branch 'develop-2.0.0' into fix/bufferedlinearinterpolator-jitter

7dcc5e8

style

89739c7

Adjusting changelog entry to replace LerpExtrapolateBlend with LerpAhead. Removing additional remarks tag.

Merge branch 'fix/bufferedlinearinterpolator-jitter' of https://githu…

2444548

…b.com/Unity-Technologies/com.unity.netcode.gameobjects into fix/bufferedlinearinterpolator-jitter

test

1202fe7

Updating the test project test for change in LerpAhead.

update

5b0f392

Reverting the change to fix that makes the original lerp properly calculate the time to target as opposed to always calculating 2x the time to target because all of the unit interpolator tests are specifically written for this specific flaw.

style

ac55f48

Whitespace fixes.

NoelStephensUnity added 3 commits April 2, 2025 13:18

update

8b67753

updating changelog entry.

NoelStephensUnity enabled auto-merge (squash) April 3, 2025 06:01

NoelStephensUnity merged commit cad4b4c into develop-2.0.0 Apr 3, 2025
27 checks passed

NoelStephensUnity deleted the fix/bufferedlinearinterpolator-jitter branch April 3, 2025 07:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: buffered linear interpolator jitter and exposing more properties #3355

fix: buffered linear interpolator jitter and exposing more properties #3355

NoelStephensUnity commented Mar 21, 2025 •

edited

Loading

EmandM left a comment

EmandM left a comment

michalChrobot commented Apr 2, 2025

fix: buffered linear interpolator jitter and exposing more properties #3355

fix: buffered linear interpolator jitter and exposing more properties #3355

Conversation

NoelStephensUnity commented Mar 21, 2025 • edited Loading

Various options:

This PR renames Lerp to LegacyLerp and adds a 3rd new Lerp interpolator type:

Lerp (new)

Changelog

Testing and Documentation

EmandM left a comment

Choose a reason for hiding this comment

EmandM left a comment

Choose a reason for hiding this comment

michalChrobot commented Apr 2, 2025

NoelStephensUnity commented Mar 21, 2025 •

edited

Loading

This PR renames `Lerp` to `LegacyLerp` and adds a 3rd new `Lerp` interpolator type: