feat: quaternion synchronization, delta position, and NetworkTransform bandwidth optimizations

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -7,15 +7,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 Additional documentation and release notes are available at [Multiplayer Documentation](https://docs-multiplayer.unity3d.com).
 
 ## [Unreleased]
-
 ### Added
 
+- Added `NetworkTransform.UseHalfFloatPrecision` property that, when enabled, will use half float values for position, rotation, and scale. This yields a 50% bandwidth savings a the cost of precision. (#2388)
+- Added `NetworkTransform.UseQuaternionSynchronization` property that, when enabled, will synchronize the entire quaternion. (#2388)
+- Added `NetworkTransform.UseQuaternionCompression` property that, when enabled, will use a smallest three implementation reducing a full quaternion synchronization update to the size of an unsigned integer. (#2388)
+- Added `NetworkTransform.SlerpPosition` property that, when enabled along with interpolation being enabled, will interpolate using `Vector3.Slerp`. (#2388)
+- Added `BufferedLinearInterpolatorVector3` that replaces the float version, is now used by `NetworkTransform`, and provides the ability to enable or disable `Slerp`. (#2388)
+- Added `HalfVector3` used for scale when half float precision is enabled. (#2388)
+- Added `HalfVector4` used for rotation when half float precision and quaternion synchronization is enabled. (#2388)
+- Added `HalfVector3DeltaPosition` used for position when half float precision is enabled. This handles loss in position precision by updating only the delta position as opposed to the full position. (#2388)
+- Added `NetworkTransform.GetSpaceRelativePosition` and `NetworkTransform.GetSpaceRelativeRotation` helper methods to return the proper values depending upon whether local or world space. (#2388)
+- Added `NetworkTransform.OnAuthorityPushTransformState` virtual method that is invoked just prior to sending the `NetworkTransformState` to non-authoritative instances. This provides users with the ability to obtain more precise delta values for prediction related calculations. (#2388)
+- Added `NetworkTransform.OnNetworkTransformStateUpdated` virtual method that is invoked just after the authoritative `NetworkTransformState` is applied. This provides users with the ability to obtain more precise delta values for prediction related calculations. (#2388)
+- Added `NetworkTransform.OnInitialize`virtual method that is invoked after the `NetworkTransform` has been initialized or re-initialized when ownership changes. This provides for a way to make adjustments when `NetworkTransform` is initialized (i.e. resetting client prediction etc) (#2388)
+- Added `NetworkObject.SynchronizeTransform` property (default is true) that provides users with another way to help with bandwidth optimizations where, when set to false, the `NetworkObject`'s associated transform will not be included when spawning and/or synchronizing late joining players. (#2388)
 - Added `NetworkSceneManager.ActiveSceneSynchronizationEnabled` property, disabled by default, that enables client synchronization of server-side active scene changes. (#2383)
 - Added `NetworkObject.ActiveSceneSynchronization`, disabled by default, that will automatically migrate a `NetworkObject` to a newly assigned active scene. (#2383)
 - Added `NetworkObject.SceneMigrationSynchronization`, enabled by default, that will synchronize client(s) when a `NetworkObject` is migrated into a new scene on the server side via `SceneManager.MoveGameObjectToScene`. (#2383)
 
 ### Changed
 
+- Changed `NetworkTransform` authority handles delta checks on each new network tick and no longer consumes processing cycles checking for deltas for all frames in-between ticks. (#2388)
+- Changed the `NetworkTransformState` structure is now public and now has public methods that provide access to key properties of the `NetworkTransformState` structure. (#2388)
+- Changed `NetworkTransform` interpolation adjusts its interpolation "ticks ago" to be 2 ticks latent if it is owner authoritative and the instance is not the server or 1 tick latent if the instance is the server and/or is server authoritative. (#2388)
 - Updated `NetworkSceneManager` to migrate dynamically spawned `NetworkObject`s with `DestroyWithScene` set to false into the active scene if their current scene is unloaded. (#2383)
 - Updated the server to synchronize its local `NetworkSceneManager.ClientSynchronizationMode` during the initial client synchronization. (#2383)
 
@@ -25,6 +40,8 @@ Additional documentation and release notes are available at [Multiplayer Documen
 - Fixed registry of public `NetworkVariable`s in derived `NetworkBehaviour`s (#2423)
 - Fixed issue where runtime association of `Animator` properties to `AnimationCurve`s would cause `NetworkAnimator` to attempt to update those changes. (#2416)
 - Fixed issue where `NetworkAnimator` would not check if its associated `Animator` was valid during serialization and would spam exceptions in the editor console. (#2416)
+- Fixed issue with a child's rotation rolling over when interpolation is enabled on a `NetworkTransform`. Now using half precision or full quaternion synchronization will always update all axis. (#2388)
+- Fixed issue where `NetworkTransform` was not setting the teleport flag when the `NetworkTransform.InLocalSpace` value changed. This issue only impacted `NetworkTransform` when interpolation was enabled. (#2388)
 - Fixed issue when the `NetworkSceneManager.ClientSynchronizationMode` is `LoadSceneMode.Additive` and the server changes the currently active scene prior to a client connecting then upon a client connecting and being synchronized the NetworkSceneManager would clear its internal ScenePlacedObjects list that could already be populated. (#2383)
 - Fixed issue where a client would load duplicate scenes of already preloaded scenes during the initial client synchronization and `NetworkSceneManager.ClientSynchronizationMode` was set to `LoadSceneMode.Additive`. (#2383)
 - Fixed float NetworkVariables not being rendered properly in the inspector of NetworkObjects. (#2441)

com.unity.netcode.gameobjects/Components/HalfVector3.cs

@@ -0,0 +1,131 @@
+using System.Runtime.CompilerServices;
+using UnityEngine;
+
+namespace Unity.Netcode.Components
+{
+    /// <summary>
+    /// Half float precision <see cref="Vector3"/>.
+    /// </summary>
+    /// <remarks>
+    /// The Vector3T<ushort> values are half float values returned by <see cref="Mathf.FloatToHalf(float)"/> for each
+    /// individual axis and the 16 bits of the half float are stored as <see cref="ushort"/> values since C# does not have
+    /// a half float type.
+    /// </remarks>
+    public struct HalfVector3 : INetworkSerializable
+    {
+        /// <summary>
+        /// The half float precision value of the x-axis as a <see cref="ushort"/>.
+        /// </summary>
+        public ushort X => Axis.X;
+        /// <summary>
+        /// The half float precision value of the y-axis as a <see cref="ushort"/>.
+        /// </summary>
+        public ushort Y => Axis.Y;
+        /// <summary>
+        /// The half float precision value of the z-axis as a <see cref="ushort"/>.
+        /// </summary>
+        public ushort Z => Axis.Z;
+
+        /// <summary>
+        /// Used to store the half float precision value as a <see cref="ushort"/>.
+        /// </summary>
+        public Vector3T<ushort> Axis;
+
+        internal Vector3AxisToSynchronize AxisToSynchronize;
+
+        /// <summary>
+        /// The serialization implementation of <see cref="INetworkSerializable"/>.
+        /// </summary>
+        public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
+        {
+            for (int i = 0; i < Axis.Length; i++)
+            {
+                if (AxisToSynchronize.SyncAxis[i])
+                {
+                    var axisValue = Axis[i];
+                    serializer.SerializeValue(ref axisValue);
+                    if (serializer.IsReader)
+                    {
+                        Axis[i] = axisValue;
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Gets the full precision value as a <see cref="Vector3"/>.
+        /// </summary>
+        /// <returns>a <see cref="Vector3"/> as the full precision value.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public Vector3 ToVector3()
+        {
+            Vector3 fullPrecision = Vector3.zero;
+            for (int i = 0; i < Axis.Length; i++)
+            {
+                if (AxisToSynchronize.SyncAxis[i])
+                {
+                    fullPrecision[i] = Mathf.HalfToFloat(Axis[i]);
+                }
+            }
+            return fullPrecision;
+        }
+
+        /// <summary>
+        /// Converts a full precision <see cref="Vector3"/> to half precision and updates the current instance.
+        /// </summary>
+        /// <param name="vector3">The <see cref="Vector3"/> to convert.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void UpdateFrom(ref Vector3 vector3)
+        {
+            for (int i = 0; i < Axis.Length; i++)
+            {
+                if (AxisToSynchronize.SyncAxis[i])
+                {
+                    Axis[i] = Mathf.FloatToHalf(vector3[i]);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Constructor
+        /// </summary>
+        /// <param name="vector3">The initial axial values (converted to half floats) when instantiated.</param>
+        /// <param name="vector3AxisToSynchronize">The axis to synchronize.</param>
+        public HalfVector3(Vector3 vector3, Vector3AxisToSynchronize vector3AxisToSynchronize)
+        {
+            Axis = default;
+            AxisToSynchronize = vector3AxisToSynchronize;
+            UpdateFrom(ref vector3);
+        }
+
+        /// <summary>
+        /// Constructor that defaults to all axis being synchronized.
+        /// </summary>
+        /// <param name="vector3">The initial axial values (converted to half floats) when instantiated.</param>
+        public HalfVector3(Vector3 vector3) : this(vector3, Vector3AxisToSynchronize.AllAxis)
+        {
+
+        }
+
+        /// <summary>
+        /// Constructor
+        /// </summary>
+        /// <param name="x">The initial x axis (converted to half float) value when instantiated.</param>
+        /// <param name="y">The initial y axis (converted to half float) value when instantiated.</param>
+        /// <param name="z">The initial z axis (converted to half float) value when instantiated.</param>
+        /// <param name="vector3AxisToSynchronize">The axis to synchronize.</param>
+        public HalfVector3(float x, float y, float z, Vector3AxisToSynchronize vector3AxisToSynchronize) : this(new Vector3(x, y, z), vector3AxisToSynchronize)
+        {
+        }
+
+        /// <summary>
+        /// Constructor that defaults to all axis being synchronized.
+        /// </summary>
+        /// <param name="x">The initial x axis (converted to half float) value when instantiated.</param>
+        /// <param name="y">The initial y axis (converted to half float) value when instantiated.</param>
+        /// <param name="z">The initial z axis (converted to half float) value when instantiated.</param>
+        public HalfVector3(float x, float y, float z) : this(new Vector3(x, y, z), Vector3AxisToSynchronize.AllAxis)
+        {
+        }
+    }
+}