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)
 

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

@@ -0,0 +1,114 @@
+using System.Runtime.CompilerServices;
+using UnityEngine;
+
+namespace Unity.Netcode.Components
+{
+    /// <summary>
+    /// Half float precision <see cref="Vector3"/>
+    /// </summary>
+    public struct HalfVector3 : INetworkSerializable
+    {
+        /// <summary>
+        /// The half float precision value of the x-axis as a <see cref="ushort"/>
+        /// </summary>
+        public ushort X => Axis[0];
+        /// <summary>
+        /// The half float precision value of the y-axis as a <see cref="ushort"/>
+        /// </summary>
+        public ushort Y => Axis[1];
+        /// <summary>
+        /// The half float precision value of the z-axis as a <see cref="ushort"/>
+        /// </summary>
+        public ushort Z => Axis[2];
+
+        public ushort[] Axis;
+
+        private HalfVector3AxisToSynchronize m_HalfVector3AxisToSynchronize;
+
+        /// <summary>
+        /// The serialization implementation of <see cref="INetworkSerializable"/>
+        /// </summary>
+        /// <typeparam name="T"></typeparam>
+        /// <param name="serializer"></param>
+        public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
+        {
+            for (int i = 0; i < 3; i++)
+            {
+                if (m_HalfVector3AxisToSynchronize.SyncAxis[i])
+                {
+                    var axisValue = Axis[i];
+                    serializer.SerializeValue(ref axisValue);
+                    if (serializer.IsReader)
+                    {
+                        Axis[i] = axisValue;
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Converts the <see cref="HalfVector3"/> to a full precision <see cref="Vector3"/>
+        /// </summary>
+        /// <param name="vector3">the <see cref="Vector3"/> to store the full precision values in</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void ToVector3(ref Vector3 vector3)
+        {
+            for (int i = 0; i < 3; i++)
+            {
+                if (m_HalfVector3AxisToSynchronize.SyncAxis[i])
+                {
+                    vector3[i] = Mathf.HalfToFloat(Axis[i]);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Converts a <see cref="Vector3"/> full precision to a <see cref="HalfVector3"/>
+        /// </summary>
+        /// <param name="vector3">the <see cref="Vector3"/> to convert to a half precision <see cref="Vector3"/></param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void FromVector3(ref Vector3 vector3)
+        {
+            for (int i = 0; i < 3; i++)
+            {
+                if (m_HalfVector3AxisToSynchronize.SyncAxis[i])
+                {
+                    Axis[i] = Mathf.FloatToHalf(vector3[i]);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Constructor that initializes the HalfVector3 along with its precision adjustment
+        /// </summary>
+        /// <remarks>
+        /// Note about decimal precision:
+        /// If you know that all components (x, y, and z) of a Vector3 will not exceed a specific threshold, then you
+        /// can increase the decimal precision of a Vector3 by increasing the decimalPrecision value. The decimal precision
+        /// valid values range from 0 to 4 decimal places to adjust up and back down (1000 to 1 : 1 to 0.001).
+        /// </remarks>
+        /// <param name="vector3">the vector3 to initialize the HalfVector3 with</param>
+        public HalfVector3(Vector3 vector3, HalfVector3AxisToSynchronize halfVector3AxisToSynchronize)
+        {
+            Axis = new ushort[3];
+            m_HalfVector3AxisToSynchronize = halfVector3AxisToSynchronize;
+            FromVector3(ref vector3);
+        }
+
+        /// <summary>
+        /// Constructor that initializes the HalfVector3 along with its precision adjustment
+        /// </summary>
+        /// <remarks>
+        /// Note about decimal precision:
+        /// If you know that all components (x, y, and z) of a Vector3 will not exceed a specific threshold, then you
+        /// can increase the decimal precision of a Vector3 by increasing the decimalPrecision value. The decimal precision
+        /// valid values range from 0 to 4 decimal places to adjust up and back down (1000 to 1 : 1 to 0.001).
+        /// </remarks>
+        /// <param name="x">x component to initialize the HalfVector3 with</param>
+        /// <param name="y">y component of initialize the HalfVector3 with</param>
+        /// <param name="z">z component of initialize the HalfVector3 with</param>
+        public HalfVector3(float x, float y, float z, HalfVector3AxisToSynchronize halfVector3AxisToSynchronize) : this(new Vector3(x, y, z), halfVector3AxisToSynchronize)
+        {
+        }
+    }
+}

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

@@ -0,0 +1,41 @@
+
+namespace Unity.Netcode.Components
+{
+    /// <summary>
+    /// Structure that defines which axis of a <see cref="HalfVector3"/>
+    /// and <see cref="HalfVector3DeltaPosition"/> will be serialized.
+    /// </summary>
+    public struct HalfVector3AxisToSynchronize
+    {
+        /// <summary>
+        /// When enabled, serialize the X axis
+        /// </summary>
+        public bool X => SyncAxis[0];
+
+        /// <summary>
+        /// When enabled, serialize the Y axis
+        /// </summary>
+        public bool Y => SyncAxis[1];
+
+        /// <summary>
+        /// When enabled, serialize the Z axis
+        /// </summary>
+        public bool Z => SyncAxis[2];
+
+        public bool[] SyncAxis;
+
+        /// <summary>
+        /// Constructor to preinitialize the x, y, and z values
+        /// </summary>
+        /// <param name="x">when <see cref="true"/> the x-axis will be serialized</param>
+        /// <param name="y">when <see cref="true"/> the y-axis will be serialized</param>
+        /// <param name="z">when <see cref="true"/> the z-axis will be serialized</param>
+        public HalfVector3AxisToSynchronize(bool x = true, bool y = true, bool z = true)
+        {
+            SyncAxis = new bool[3];
+            SyncAxis[0] = x;
+            SyncAxis[1] = y;
+            SyncAxis[2] = z;
+        }
+    }
+}