feat: Make INetworkStreamDriverConstructor useful (#3501)

This PR addresses MTTB-1331 by making it simpler to use a custom driver
constructor without breaking things.

`INetworkStreamDriverConstructor` is a mechanism that was added a long
time ago that allows users to override the creation of the
`NetworkDriver` that `UnityTransport` is using. As the name might hint
at, it was pulled directly out of N4E and was never properly integrated
into `UnityTransport`.

For example, before this PR, a user implementing a custom driver
constructor would need to recreate the settings and pipelines manually
if they wanted to mimic the default behavior of `UnityTransport`, which
required reading the code to figure out how we are settings things up.
In the case of pipelines, it's not even possible to do that in all cases
because one of the pipelines used when the multiplayer tools package is
installed is internal.

This PR addresses this by making both the default settings and default
pipeline configurations available through the new
`GetDefaultNetworkSettings` and `GetDefaultPipelineConfigurations`
methods. A user can use these methods to reuse or extend the
configuration `UnityTransport` uses by default. The (new and improved)
documentation of the driver constructor interface provides an example of
how to do so.

As a bonus, this centralizes all the `NetworkSettings` in one place
which makes the code a tiny bit more organized.

## Changelog

- Added: Added methods `GetDefaultNetworkSettings` and
`GetDefaultPipelineConfigurations` to `UnityTransport`. These can be
used to retrieve the default settings and pipeline stages that are used
by `UnityTransport`. This is useful when providing a custom driver
constructor through `UnityTransport.s_DriverConstructor`, since it
allows reusing or tuning the existing configuration instead of trying to
recreate it. This means a transport with a custom driver can now easily
benefit from most of the features of `UnityTransport`, like integration
with the Network Simulator and Network Profiler from the multiplayer
tools package.

## Testing and Documentation

- No tests have been added.
- Includes edits to existing public API documentation.

## Backport

I don't plan on backporting this, unless the team feels strongly
otherwise.

---------

Co-authored-by: Noel Stephens <[email protected]>

Author: simon-lemay-unity

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -10,6 +10,7 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Added
 
+- Added methods `GetDefaultNetworkSettings` and `GetDefaultPipelineConfigurations` to `UnityTransport`. These can be used to retrieve the default settings and pipeline stages that are used by `UnityTransport`. This is useful when providing a custom driver constructor through `UnityTransport.s_DriverConstructor`, since it allows reusing or tuning the existing configuration instead of trying to recreate it. This means a transport with a custom driver can now easily benefit from most of the features of `UnityTransport`, like integration with the Network Simulator and Network Profiler from the multiplayer tools package. (#3501)
 - Added mappings between `ClientId` and `TransportId`. (#3516)
 - Added `NetworkPrefabInstanceHandlerWithData<T>`, a variant of `INetworkPrefabInstanceHandler` that provides access to custom instantiation data directly within the `Instantiate()` method. (#3430)
 

com.unity.netcode.gameobjects/Runtime/Transports/UTP/INetworkStreamDriverConstructor.cs

@@ -0,0 +1,79 @@
+using Unity.Networking.Transport;
+
+namespace Unity.Netcode.Transports.UTP
+{
+    /// <summary>
+    /// <para>
+    /// This interface allows one to override the creation of the <see cref="NetworkDriver"/> object
+    /// that will be used under the hood by <see cref="UnityTransport"/>. This can be useful when
+    /// implementing a custom <see cref="INetworkInterface"/> or to add custom pipeline stages to
+    /// the default pipelines.
+    /// </para>
+    /// <para>
+    /// To use a custom driver constructor, set <see cref="UnityTransport.s_DriverConstructor"/> to
+    /// an instance of an implementation of this interface. This must be done before calling
+    /// <see cref="UnityTransport.StartClient"/> or <see cref="UnityTransport.StartServer"/>.
+    /// </para>
+    /// </summary>
+    /// <example>
+    /// <para>
+    /// This example implements a custom driver constructor that uses the IPC network interface from
+    /// the Unity Transport package. This network interface is used for intra-process communications
+    /// which can be useful for implementing a single-player version of a game. Since the example is
+    /// also preserving all the default settings and pipelines, you'd also benefit from all the
+    /// existing features of the transport, like integration with the Network Profiler.
+    /// </para>
+    /// <code>
+    ///     public class IPCDriverConstructor : INetworkStreamDriverConstructor
+    ///     {
+    ///         public void CreateDriver(
+    ///             UnityTransport transport,
+    ///             out NetworkDriver driver,
+    ///             out NetworkPipeline unreliableFragmentedPipeline,
+    ///             out NetworkPipeline unreliableSequencedFragmentedPipeline,
+    ///             out NetworkPipeline reliableSequencedPipeline)
+    ///         {
+    ///             var settings = transport.GetDefaultNetworkSettings();
+    ///             driver = NetworkDriver.Create(new IPCNetworkInterface(), settings);
+    ///
+    ///             transport.GetDefaultPipelineConfigurations(
+    ///                 out var unreliableFragmentedPipelineStages,
+    ///                 out var unreliableSequencedFragmentedPipelineStages,
+    ///                 out var reliableSequencedPipelineStages);
+    ///
+    ///             unreliableFragmentedPipeline = driver.CreatePipeline(unreliableFragmentedPipelineStages);
+    ///             unreliableSequencedFragmentedPipeline = driver.CreatePipeline(unreliableSequencedFragmentedPipelineStages);
+    ///             reliableSequencedPipeline = driver.CreatePipeline(reliableSequencedPipelineStages);
+    ///         }
+    ///     }
+    /// </code>
+    /// </example>
+    public interface INetworkStreamDriverConstructor
+    {
+        /// <summary>
+        /// Creates the <see cref="NetworkDriver"/> instance to be used by the transport.
+        /// </summary>
+        /// <param name="transport">The transport for which the driver is created.</param>
+        /// <param name="driver">The newly-created <see cref="NetworkDriver"/>.</param>
+        /// <param name="unreliableFragmentedPipeline">
+        /// The driver's pipeline on which to send unreliable traffic. This pipeline must also
+        /// support fragmentation (payloads larger than the MTU).
+        /// </param>
+        /// <param name="unreliableSequencedFragmentedPipeline">
+        /// The driver's pipeline on which to send unreliable but sequenced traffic. Traffic sent
+        /// on this pipeline must be delivered in the right order, although packet loss is okay.
+        /// This pipeline must also support fragmentation (payloads larger than the MTU).
+        /// </param>
+        /// <param name="reliableSequencedPipeline">
+        /// The driver's pipeline on which to send reliable traffic. This pipeline must ensure that
+        /// all of its traffic is delivered, and in the correct order too. There is no need for that
+        /// pipeline to support fragmentation (<see cref="UnityTransport"/> will handle that).
+        /// </param>
+        void CreateDriver(
+            UnityTransport transport,
+            out NetworkDriver driver,
+            out NetworkPipeline unreliableFragmentedPipeline,
+            out NetworkPipeline unreliableSequencedFragmentedPipeline,
+            out NetworkPipeline reliableSequencedPipeline);
+    }
+}