[email protected]

## [2.0.1] - 2023-04-17 ### Changes * Updated Collections dependency to 2.1.1. ## [2.0.0] - 2023-04-14 ### Changes * `NetworkEndpoint.ToString` and its fixed string variant now return "invalid" for invalid endpoints instead of an empty string. * Updated Burst dependency to 1.8.4. * Updated Collections dependency to 2.1.0. ### Fixes * Fixed an issue where the TLS handshake of a new secure WebSocket connection could possibly fail if there were already other active connections on the same server.
needle-mirror · Apr 17, 2023 · 483a47e · 483a47e
1 parent 5950d52
commit 483a47e
Show file tree

Hide file tree

Showing 18 changed files with 221 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,20 @@
 # Change log
 
+## [2.0.1] - 2023-04-17
+
+### Changes
+* Updated Collections dependency to 2.1.1.
+
+## [2.0.0] - 2023-04-14
+
+### Changes
+* `NetworkEndpoint.ToString` and its fixed string variant now return "invalid" for invalid endpoints instead of an empty string.
+* Updated Burst dependency to 1.8.4.
+* Updated Collections dependency to 2.1.0.
+
+### Fixes
+* Fixed an issue where the TLS handshake of a new secure WebSocket connection could possibly fail if there were already other active connections on the same server.
+
 ## [2.0.0-pre.8] - 2023-03-30
 
 ### New features

diff --git a/Documentation~/index.md b/Documentation~/index.md
@@ -19,8 +19,26 @@ Cherry on top, *pipelines* offer additional optional functionalities like reliab
 
 ## Requirements
 
-* Unity Editor 2022.2 and later.
-* For runtime builds, this package supports all platforms supported by the Unity Engine (with WebGL only supporting WebSocket connections in client mode).
+Unity Transport supports all platforms supported by the Unity Engine. For WebGL, only WebSocket connections in client mode are supported (it is however still possible to host games if using [Unity Relay](https://unity.com/products/relay)).
+
+### Editor compatibility matrix
+
+The page you are reading is the documentation for Unity Transport 2.X, which is only compatible with Unity Editor 2022.2 and later. Older editor versions are supported by Transport 1.X. Here is the compatibility matrix:
+
+| Editor Version | 2020 LTS | 2021 LTS | 2022.2 and LTS | 2023.1 and later |
+|:--------------:|:--------:|:--------:|:--------------:|:----------------:|
+| Transport 1.X  | **Yes**  | **Yes**  | **Yes**        | No               |
+| Transport 2.X  | No       | No       | **Yes**        | **Yes**          |
+
+### Which version should I use?
+
+If you are using Unity Transport on its own, we recommend using version 2.X if your editor version supports it. If you are using Unity Transport as part of one of Unity's Netcode solutions, refer to the table below for the _minimum_ supported version for each solution:
+
+| Editor Version                    | 2020 LTS      | 2021 LTS      | 2022.2 and LTS | 2023.1 and later |
+|:---------------------------------:|:-------------:|:-------------:|:--------------:|:----------------:|
+| Netcode for GameObjects (1.2.0+)  | Transport 1.X | Transport 1.X | Transport 1.X  | Transport 2.X    |
+| Netcode for Entities (1.0.0+)     | N/A           | N/A           | Transport 2.X  | Transport 2.X    |
+| Recommended for custom solutions  | Transport 1.X | Transport 1.X | Transport 2.X  | Transport 2.X    |
 
 ## Note
 This package should not be confused with the `NetworkTransport` abstraction in Netcode for GameObjects. Please see the [transports section of its documentation](https://docs-multiplayer.unity3d.com/netcode/current/advanced-topics/transports) for more information.
diff --git a/Documentation~/migration.md b/Documentation~/migration.md
@@ -4,6 +4,18 @@ This section describes the breaking changes introduced in version 2.0 of the Uni
 
 **Note**: In most use cases, there’s no need to perform any additional steps to migrate from 1.X to 2.0. The core APIs like `NetworkDriver` remain the same, and the most significant changes are limited to specialized scenarios, such as custom network interfaces.
 
+## Collections-related errors following upgrade
+
+Under certain circumstances, it is possible that upgrading a project from version 1.X to 2.0 will result in errors like the following appearing in the console:
+
+```
+Unity.Collections/NativeParallelHashSetExtensions.gen.cs(17,51): error CS0246: The type or namespace name 'NativeHashSet<>' could not be found (are you missing a using directive or an assembly reference?)
+
+Unity.Collections/UnsafeParallelHashSetExtensions.gen.cs(1084,78): error CS0246: The type or namespace name 'UnsafeHashSet<>' could not be found (are you missing a using directive or an assembly reference?)
+```
+
+There errors can occur when upgrading the Collections package from version 1.2 to 2.X. Closing and restarting the editor is usually enough to get rid of the errors.
+
 ## Editor version support
 
 UTP 1.X supports Unity Editor 2020.3 and up, but 2.0 only supports 2022.2 and up to keep the Collections package dependency up to date. Unity Editor 2022.2 brings many changes to the core engine runtime, allowing more code to be Burst-compiled. UTP benefits from this through increased performance.

diff --git a/LICENSE.md b/LICENSE.md
@@ -1,4 +1,4 @@
-Unity Transport Package © 2018-2022 Unity Technologies
+Unity Transport copyright © 2023 Unity Technologies
 
 Licensed under the Unity Companion License for Unity-dependent projects (see https://unity3d.com/legal/licenses/unity_companion_license).
 

diff --git a/Runtime/BaselibNetworkArray.cs b/Runtime/BaselibNetworkArray.cs
@@ -100,6 +100,8 @@ public void Dispose()
                 Binding.Baselib_Memory_ReleasePages(pageAllocation, &error);
                 UnsafeUtility.Free(buffer, Allocator.Persistent);
             }
+
+            m_BufferPool.Dispose();
         }
 
         /// <summary>

diff --git a/Runtime/INetworkInterface.cs b/Runtime/INetworkInterface.cs
@@ -54,13 +54,13 @@ internal struct NetworkInterfaceSendHandle
     /// Network interfaces are the lowest level of the Unity Transport library. They are responsible
     /// for sending and receiving packets directly to/from the network. Conceptually, they act like
     /// sockets. Users can provide their own network interfaces by implementing this interface and
-    /// passing a new instance of it to <see cref="NetworkDriver.Create"/>.
+    /// passing a new instance of it to <see cref="NetworkDriver.Create{N}(N)"/>.
     /// </para>
     /// <para>
     /// Note that network interfaces are expected to be unmanaged types compatible with Burst.
     /// However, it is possible to write them using managed types and code. Simply wrap them with
     /// <see cref="ManagedNetworkInterfaceExtensions.WrapToUnmanaged"/> before passing them to
-    /// <see cref="NetworkDriver.Create"/>. This comes at a small performance cost, but allows
+    /// <see cref="NetworkDriver.Create{N}(N)"/>. This comes at a small performance cost, but allows
     /// writing network interfaces that interact with managed C# libraries.
     /// </para>
     /// </summary>
@@ -79,7 +79,7 @@ public interface INetworkInterface : IDisposable
         /// <param name="settings">Configuration settings provided to the driver.</param>
         /// <param name="packetPadding">
         /// Return value parameter for how much padding the interface adds to packets. Note that
-        /// this parameter is only concerned that padding that would be added directly in the
+        /// this parameter is only concerned about padding that would be added directly in the
         /// packets stored in the send and receive queues, not to padding that would be added by
         /// lower levels of the network stack (e.g. IP headers).
         /// </param>

diff --git a/Runtime/IPCNetworkInterface.cs b/Runtime/IPCNetworkInterface.cs
@@ -20,7 +20,7 @@ namespace Unity.Networking.Transport
     /// <para>
     /// Note that the interface expects loopback addresses when binding/connecting. It is
     /// recommended to only use <see cref="NetworkEndpoint.LoopbackIpv4"/> when dealing with the IPC
-    /// network interface, and to use different port for different drivers (see example).
+    /// network interface, and to use different ports for different drivers (see example).
     /// </para>
     /// </summary>
     /// <example>

diff --git a/Runtime/Layers/DTLSLayer.cs b/Runtime/Layers/DTLSLayer.cs
@@ -309,6 +309,7 @@ private void HandleConnectionState(ConnectionId connection)
 
                         // No matter if the connection is newly-connected or not, try to make
                         // progress on the handshake (e.g. with Client Hello resends).
+                        UnityTLSCallbackContext->ReceivedPacket = default;
                         UnityTLSCallbackContext->NewPacketsEndpoint = connectionEndpoint;
                         AdvanceHandshake(ConnectionsData[connection].UnityTLSClientPtr);
 

diff --git a/Runtime/Layers/TLSLayer.cs b/Runtime/Layers/TLSLayer.cs
@@ -370,6 +370,7 @@ private void HandleConnectingState(ConnectionId connection)
                     var clientState = Binding.unitytls_client_get_state(clientPtr);
                     if (clientState == Binding.UnityTLSClientState_Init || clientState == Binding.UnityTLSClientState_Handshake)
                     {
+                        UnityTLSCallbackContext->ReceivedPacket = default;
                         UnityTLSCallbackContext->NewPacketsEndpoint = endpoint;
                         UnityTLSCallbackContext->NewPacketsConnection = underlyingId;
                         AdvanceHandshake(clientPtr);

diff --git a/Runtime/NetworkEndpoint.cs b/Runtime/NetworkEndpoint.cs
@@ -393,7 +393,7 @@ internal static FixedString128Bytes AddressToString(ref Binding.Baselib_NetworkA
                     str.Append((ushort)(rawNetworkAddress.port1 | (rawNetworkAddress.port0 << 8)));
                     break;
                 default:
-                    break;
+                    return "invalid";
             }
             return str;
         }

diff --git a/Runtime/NetworkEventQueue.cs b/Runtime/NetworkEventQueue.cs
@@ -10,13 +10,35 @@ namespace Unity.Networking.Transport
     public struct NetworkEvent
     {
         /// <summary>
-        /// NetworkEvent.Type enumerates available network events for this driver.
+        /// Types of network events that can be returned by <see cref="NetworkDriver.PopEvent"/>.
         /// </summary>
         public enum Type : short
         {
+            /// <summary>No event. Returned when there are no more events to pop.</summary>
             Empty = 0,
+
+            /// <summary>
+            /// A message was received on the connection. The contents of the message can be read
+            /// from the <see cref="DataStreamReader"/> that was returned along with the event.
+            /// Furthermore, the pipeline on which the message was received will also be returned
+            /// (for the variants of <c>PopEvent</c> that return it).
+            /// </summary>
             Data,
+
+            /// <summary>
+            /// Connection has been successfully established. From this point on it's okay to send
+            /// data on the connection. Returned after calling <see cref="NetworkDriver.Connect"/>
+            /// when the connection was successful. Note that servers do not get this event (new
+            /// connections are notified through the <see cref="NetworkDriver.Accept"/> call).
+            /// </summary>
             Connect,
+
+            /// <summary>
+            /// Connection has been closed, or has failed to be established. The reason for the
+            /// disconnection can be read as a single byte off the <see cref="DataStreamReader"/>
+            /// obtained along with the event. That single byte will represent a value from the
+            /// <see cref="Error.DisconnectReason"/> enum.
+            /// </summary>
             Disconnect
         }
 

diff --git a/Runtime/NetworkParams.cs b/Runtime/NetworkParams.cs
@@ -227,15 +227,58 @@ public static class CommonNetworkParametersExtensions
         /// Sets the <see cref="NetworkConfigParameter"/> in the settings.
         /// </summary>
         /// <param name="settings">Settings to modify.</param>
-        /// <param name="connectTimeoutMS"><inheritdoc cref="NetworkConfigParameter.connectTimeoutMS" path="/summary"/></param>
-        /// <param name="maxConnectAttempts"><inheritdoc cref="NetworkConfigParameter.maxConnectAttempts" path="/summary"/></param>
-        /// <param name="disconnectTimeoutMS"><inheritdoc cref="NetworkConfigParameter.disconnectTimeoutMS" path="/summary"/></param>
-        /// <param name="heartbeatTimeoutMS"><inheritdoc cref="NetworkConfigParameter.heartbeatTimeoutMS" path="/summary"/></param>
-        /// <param name="reconnectionTimeoutMS"><inheritdoc cref="NetworkConfigParameter.reconnectionTimeoutMS" path="/summary"/></param>
-        /// <param name="maxFrameTimeMS"><inheritdoc cref="NetworkConfigParameter.maxFrameTimeMS" path="/summary"/></param>
-        /// <param name="fixedFrameTimeMS"><inheritdoc cref="NetworkConfigParameter.fixedFrameTimeMS" path="/summary"/></param>
-        /// <param name="receiveQueueCapacity"><inheritdoc cref="NetworkConfigParameter.receiveQueueCapacity" path="/summary"/></param>
-        /// <param name="sendQueueCapacity"><inheritdoc cref="NetworkConfigParameter.sendQueueCapacity" path="/summary"/></param>
+        /// <param name="connectTimeoutMS">Time between connection attempts.</param>
+        /// <param name="maxConnectAttempts">
+        /// Maximum number of connection attempts to try. If no answer is received from the server
+        /// after this number of attempts, a <see cref="NetworkEvent.Type.Disconnect"/> event is
+        /// generated for the connection.
+        /// </param>
+        /// <param name="disconnectTimeoutMS">
+        /// Inactivity timeout for a connection. If nothing is received on a connection for this
+        /// amount of time, it is disconnected (a <see cref="NetworkEvent.Type.Disconnect"/> event
+        /// will be generated). To prevent this from happenning when the game session is simply
+        /// quiet, set <c>heartbeatTimeoutMS</c> to a positive non-zero value.
+        /// </param>
+        /// <param name="heartbeatTimeoutMS">
+        /// Time after which if nothing from a peer is received, a heartbeat message will be sent
+        /// to keep the connection alive. Prevents the <c>disconnectTimeoutMS</c> mechanism from
+        /// kicking when nothing happens on a connection. A value of 0 will disable heartbeats.
+        /// </param>
+        /// <param name="reconnectionTimeoutMS">
+        /// Time after which to attempt to re-establish a connection if nothing is received from the
+        /// peer. This is used to re-establish connections for example when a peer's IP address
+        /// changes (e.g. mobile roaming scenarios). To be effective, should be less than
+        /// <c>disconnectTimeoutMS</c> but greater than <c>heartbeatTimeoutMS</c>. A value of 0 will
+        /// disable this functionality.
+        /// </param>
+        /// <param name="maxFrameTimeMS">
+        /// Maximum amount of time a single frame can advance timeout values. In this scenario, a
+        /// frame is defined as the time between two <see cref="NetworkDriver.ScheduleUpdate"/>
+        /// calls. Useful when debugging to avoid connection timeouts.
+        /// </param>
+        /// <param name="fixedFrameTimeMS">
+        /// Fixes a fixed amount of time to be used each frame for the purpose of timeout
+        /// calculations. For example, setting this value to 1000 will have the driver consider
+        /// that 1 second passed between each call to <see cref="NetworkDriver.ScheduleUpdate"/>,
+        /// even if that's not actually the case. Only useful for testing scenarios, where
+        /// deterministic behavior is more important than correctness.
+        /// </param>
+        /// <param name="receiveQueueCapacity">
+        /// Capacity of the receive queue. This should be the maximum number of packets expected to
+        /// be received in a single update (each frame). The best value for this will depend heavily
+        /// on the game type, but generally should be a multiple of the maximum number of players.
+        /// The only impact of increasing this value is increased memory usage, with an expected
+        /// ~1400 bytes of memory being used per unit of capacity. The queue is shared across all
+        /// connections, so servers should set this higher than clients.
+        /// </param>
+        /// <param name="sendQueueCapacity">
+        /// Capacity of the send queue. This should be the maximum number of packets expected to be
+        /// send in a single update (each frame). The best value will depend heavily on the game
+        /// type, but generally should be a multiple of the maximum number of players. The only
+        /// impact of increasing this value is increased memory usage, with an expected ~1400 bytes
+        /// of memory being used per unity of capacity. The queue is shared across all connections,
+        /// so servers should set this higher than clients.
+        /// </param>
         /// <returns>Settings structure with modified values.</returns>
         public static ref NetworkSettings WithNetworkConfigParameters(
             ref this NetworkSettings settings,

diff --git a/Runtime/Pipelines/FragmentationUtility.cs b/Runtime/Pipelines/FragmentationUtility.cs
@@ -10,7 +10,12 @@ public static class FragmentationStageParameterExtensions
         /// Sets the <see cref="FragmentationUtility.Parameters"/> in the settings.
         /// </summary>
         /// <param name="settings">Settings to modify.</param>
-        /// <param name="payloadCapacity"><inheritdoc cref="FragmentationUtility.Parameters.PayloadCapacity" path="/summary"/></param>
+        /// <param name="payloadCapacity">
+        /// Maximum size that can be fragmented by the <see cref="FragmentationPipelineStage"/>.
+        /// Attempting to send a message larger than that will result in the send operation
+        /// returning <see cref="Error.StatusCode.NetworkPacketOverflow"/>. Maximum value is
+        /// ~20MB for unreliable packets, and ~88KB for reliable ones.
+        /// </param>
         /// <returns>Settings structure with modified values.</returns>
         public static ref NetworkSettings WithFragmentationStageParameters(
             ref this NetworkSettings settings,

diff --git a/Runtime/Pipelines/ReliableUtility.cs b/Runtime/Pipelines/ReliableUtility.cs
@@ -16,9 +16,20 @@ public static class ReliableStageParameterExtensions
         /// Sets the <see cref="ReliableUtility.Parameters"/> in the settings.
         /// </summary>
         /// <param name="settings">Settings to modify.</param>
-        /// <param name="windowSize"><inheritdoc cref="ReliableUtility.Parameters.WindowSize"/></param>
-        /// <param name="minimumResendTime"><inheritdoc cref="ReliableUtility.Parameters.MinimumResendTime"/></param>
-        /// <param name="maximumResendTime"><inheritdoc cref="ReliableUtility.Parameters.MaximumResendTime"/></param>
+        /// <param name="windowSize">
+        /// Maximum number in-flight packets per pipeline/connection combination. Default value
+        /// is 32 but can be increased to 64 at the cost of slightly larger packet headers.
+        /// </param>
+        /// <param name="minimumResendTime">
+        /// Minimum amount of time to wait before a reliable packet is resent if it's not been
+        /// acknowledged. Default value is 64ms, which should be set lower if all connections
+        /// are expected to be very good (RTT of 25ms or less).
+        /// </param>
+        /// <param name="maximumResendTime">
+        /// Maximum amount of time to wait before a reliable packet is resent if it's not been
+        /// acknowledged. Default value is 200ms, which should be set higher if all connections
+        /// are expected to have a higher latency than that.
+        /// </param>
         /// <returns>Settings structure with modified values.</returns>
         public static ref NetworkSettings WithReliableStageParameters(
             ref this NetworkSettings settings,