fix: half float delta position dither (#4128)

* fix: half float position encoding manufactures motion on resting objects

NetworkDeltaPosition carries the half float rounding loss of each update
into the next one, which keeps the average transmitted position accurate
while a value is moving. The loss alone is enough to change the encoded
delta, so once the value stops moving that mechanism keeps changing what is
sent even though the position has not moved. The encoded value alternates
between neighbouring representable values and a stationary object is
transmitted as one that oscillates. The rounding loss is now only carried
forward while the value moves by at least one representable step.

MaxDeltaBeforeAdjustment also determined the transmitted resolution, since
a half float's step size grows with its magnitude. At 64 the coarsest step
was 31.25mm, so objects away from their base position were reproduced in
~3cm increments. At 2 it is 0.977mm. Folding the delta into the base more
often costs no bandwidth with reliable deltas because both sides apply the
same rule to the same value, and the reconstructed position is unchanged by
the fold. UseUnreliableDeltas forces a full precision base synchronization
per fold, so those projects will send those more often.

Measured on 10 settling physics objects with half float enabled: 28-42mm of
oscillation before, none after, matching the same scene with half float
disabled. Objects in motion improve as well, peak error dropping from
12.5mm to 0.587mm.

Sender and receiver must agree on MaxDeltaBeforeAdjustment, so this is not
compatible across builds. NetworkConstants.PROTOCOL_VERSION already
participates in the connection config hash, so mismatched versions cannot
connect.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test: integration coverage for half float position encoding

Two NetcodeIntegrationTest cases, one for an object moving in steps too
small for the encoding to represent and one for an object at rest. Both
move the authority forwards only and require non-authority instances to
follow without ever moving backwards. Interpolation cannot overshoot, so
movement opposite to the authority's has to have come from the encoding.
That also avoids a tolerance that would need revisiting whenever the
resolution changes.

Two setup details are needed for these to detect anything. The object has to
travel away from the base position established when it spawned, since
resolution is fine near the base. It then has to step by an amount the
encoding cannot represent before coming to rest, because a position a half
float represents exactly leaves no rounding loss and so cannot exhibit the
problem: resting on 30.0 produces no backwards movement at all while resting
on 30.0007 produces 15.6mm.

Verified in both directions. Without the fix all four cases fail on the
intended assertion, reporting 7.9mm to 10.1mm of backwards movement. With
the fix all four pass.

These do not use the time travel harness because the behavior only appears
over multiple real state update and interpolation cycles.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Update CHANGELOG for NetworkTransform precision changes

Updated changelog entries for NetworkTransform.UseHalfFloatPrecision to reflect changes in issue tracking numbers.

* test - update

Adding better coverage and adjusting some of the test to better leverage from NetcodeIntegrationTest helper methods.

* test - update

Moving the NetworkDeltaPositionTests into its own file.

* update

Bumping the protocol version to assure legacy clients cannot connect to a session with the fixes. While the fixes aren't technically a "breaking change", any projects using the legacy lerp will end up with an offset from the expected final position.  Since motion continually feeds the full position (half float or full precision) as deltas this would prevent from "long term drift".
Either case, updating the protocol version only assures that clients of a previous version cannot connect to a session with the newer version.

* test: Refer to the single non-authority instance directly

There is one connected client, so the per instance dictionaries and the
loops over m_NetworkManagers only ever held one entry. Resolve the
non-authority instance once through GetNonAuthorityNetworkManager and
name the two sampling frame counts that were inline literals.

* update

Removed note about why we don't use time travel (too verbose).

Enabling this on the CMB service pass to validate this works as expected against a live session.

* test: Drop two NetworkDeltaPosition tests that cover an already covered path

ADeltaUnderTheThresholdIsLeftAsADelta asserted nothing the other tests do
not: MovingFoldsThePreviousRoundingLossBackIn already requires the delta
to stay under the threshold, and UnsynchronizedAxesAreLeftUntouched
already requires the synchronized axis to hold the movement.

QuantumDropsTheSignBecauseTheLatticeIsSymmetric ran its own value list to
assert one thing, so it moves into the loop in
QuantumIsTheSmallestChangeTheEncodingCanSee, which already walks the same
kind of values. 300f joins that list so no input is lost.

The masking it covers is a common path executed by every call, so the
coverage score is unchanged either way.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: NoelStephensUnity

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -13,6 +13,8 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Changed
 
+- Changed `NetworkTransform.UseHalfFloatPrecision` to synchronize position with a resolution of approximately 1mm regardless of how far an object has travelled. Previously the resolution could degrade to approximately 3cm. This does not increase bandwidth, but projects using `NetworkTransform.UseUnreliableDeltas` will send full precision position updates more often. (#4128)
+
 
 ### Deprecated
 
@@ -27,6 +29,7 @@ Additional documentation and release notes are available at [Multiplayer Documen
 - Issue where `NetworkTransform.GetTickLatencyInSeconds` returned an absolute network timestamp that grew for as long as the session ran, rather than the tick latency as a duration in seconds that it is documented to return. (#4133)
 - Issue where lerp smoothing was applied per frame instead of over time, which caused the `Lerp` and `SmoothDampening` interpolation types to smooth by different amounts at different frame rates. Results at 60fps are unchanged. (#4130)
 - Issue where setting a maximum interpolation time of 1.0 would stop a `NetworkTransform` from interpolating at all when using the `Lerp` or `SmoothDampening` interpolation types. (#4130)
+- Issue where objects using `NetworkTransform.UseHalfFloatPrecision` appeared to jitter on non-authority instances while they were stationary or coming to rest, even though the authority was not moving them. (#4128)
 
 ### Security
 

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

@@ -11,7 +11,14 @@ namespace Unity.Netcode.Components
     [Serializable]
     public struct NetworkDeltaPosition : INetworkSerializable
     {
-        internal const float MaxDeltaBeforeAdjustment = 64f;
+        /// <summary>
+        /// How far the delta may grow before it is folded into the base position.
+        /// </summary>
+        /// <remarks>
+        /// This determines the transmitted position resolution, since a half float's step size grows with its
+        /// magnitude. Keeping the delta small keeps that step small: at 2 the coarsest step is roughly 1mm.
+        /// </remarks>
+        internal const float MaxDeltaBeforeAdjustment = 2f;
 
         /// <summary>
         /// The HalfVector3 used to synchronize the delta in position
@@ -138,14 +145,29 @@ public void UpdateFrom(ref Vector3 vector3, int networkTick)
         {
             CollapsedDeltaIntoBase = false;
             NetworkTick = networkTick;
-            DeltaPosition = (vector3 + PrecisionLossDelta) - CurrentBasePosition;
             for (int i = 0; i < HalfVector3.Length; i++)
             {
                 if (HalfVector3.AxisToSynchronize[i])
                 {
+                    var rawDelta = vector3[i] - CurrentBasePosition[i];
+
+                    // Adding the previous rounding loss back in keeps the average position accurate while the
+                    // value is moving, but it also changes the value being sent. Once the value stops moving
+                    // that is all it does, which makes a stationary object appear to oscillate.
+                    var movedSinceLastSend = Mathf.Abs(vector3[i] - PreviousPosition[i]);
+                    var applyPrecisionLoss = movedSinceLastSend >= HalfPrecisionQuantum(rawDelta);
+
+                    DeltaPosition[i] = applyPrecisionLoss ? rawDelta + PrecisionLossDelta[i] : rawDelta;
+
                     HalfVector3.Axis[i] = math.half(DeltaPosition[i]);
                     HalfDeltaConvertedBack[i] = Mathf.HalfToFloat(HalfVector3.Axis[i].value);
-                    PrecisionLossDelta[i] = DeltaPosition[i] - HalfDeltaConvertedBack[i];
+
+                    // Left unchanged when skipped so it is still applied once movement resumes.
+                    if (applyPrecisionLoss)
+                    {
+                        PrecisionLossDelta[i] = DeltaPosition[i] - HalfDeltaConvertedBack[i];
+                    }
+
                     if (Mathf.Abs(HalfDeltaConvertedBack[i]) >= MaxDeltaBeforeAdjustment)
                     {
                         CurrentBasePosition[i] += HalfDeltaConvertedBack[i];
@@ -165,6 +187,26 @@ public void UpdateFrom(ref Vector3 vector3, int networkTick)
             }
         }
 
+        /// <summary>
+        /// The smallest change a half float can represent at the magnitude of the value passed in.
+        /// </summary>
+        /// <param name="value">The value to get the step size for.</param>
+        /// <returns>The distance to the next representable half float value.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static float HalfPrecisionQuantum(float value)
+        {
+            // The step size is symmetric about zero, so the sign is dropped.
+            var magnitude = (ushort)(math.half(value).value & 0x7FFF);
+
+            // Guard only: stepping past the largest finite half float would give infinity.
+            if (magnitude >= 0x7BFF)
+            {
+                return MaxDeltaBeforeAdjustment;
+            }
+
+            return Mathf.HalfToFloat((ushort)(magnitude + 1)) - Mathf.HalfToFloat(magnitude);
+        }
+
         /// <summary>
         /// Constructor
         /// </summary>

com.unity.netcode.gameobjects/Runtime/Configuration/NetworkConstants.cs

@@ -5,6 +5,6 @@ namespace Unity.Netcode
     /// </summary>
     internal static class NetworkConstants
     {
-        internal const string PROTOCOL_VERSION = "15.0.0";
+        internal const string PROTOCOL_VERSION = "15.1.0";
     }
 }