diff --git a/docs/advanced-topics/transports.md b/docs/advanced-topics/transports.md index cc9dbe8dc..55521e10c 100644 --- a/docs/advanced-topics/transports.md +++ b/docs/advanced-topics/transports.md @@ -22,6 +22,97 @@ A transport layer can provide: Netcode's default transport Unity Transport is an entire transport layer that you can use to add multiplayer and network features to your project with or without Netcode. Refer to the [Transport documentation](https://docs-multiplayer.unity3d.com/transport/current/about/) for more information and how to [install the Transport package](https://docs-multiplayer.unity3d.com/transport/current/install/). +## `SinglePlayerTransport` + +Netcode for GameObjects provides a `SinglePlayerTransport` that you can use to create a local single player network session. This simplifies switching between multiplayer and single player sessions within the same project, while still being able to use existing netcode scripts. The `SinglePlayerTransport` is a effectively a mock transport that ensures full `NetworkTransport` functionality without any transport dependencies. + +### Set up a single player session + +In addition to your default network transport, you need to add the `SinglePlayerTransport` to the `NetworkManager` `GameObject` (or child of). + +![image](/img/transport/SinglePlayerTransport_AddComponent.png) + +To start a single player session, assign the `SinglePlayerTransport` to the `NetworkManager.NetworkConfig.NetworkTransport` configuration property using a script. + +For example: + +```csharp +using Unity.Netcode; +using Unity.Netcode.Transports.UTP; +using Unity.Netcode.Transports.SinglePlayer; +using UnityEngine; + +public class ExtendedNetworkManager : NetworkManager +{ + private UnityTransport m_UnityTransport; + private SinglePlayerTransport m_SinglePlayerTransport; + + private void Awake() + { + m_UnityTransport = GetComponent(); + m_SinglePlayerTransport = GetComponent(); + } + + public void StartSinglePlayer() + { + // Use the single player transport when starting a single player session. + NetworkConfig.NetworkTransport = m_SinglePlayerTransport; + if (!StartHost()) + { + NetworkLog.LogError("Failed to start single player session!"); + } + } + + public void StartHostedSession() + { + // Use the network transport when starting a multiplayer session. + NetworkConfig.NetworkTransport = m_UnityTransport; + if (!StartHost()) + { + NetworkLog.LogError("Failed to start hosted session!"); + } + } +} +``` + +As shown in the script above, when starting a single player session the `SinglePlayerTransport` is assigned to the `NetworkConfig.NetworkTransport`, and when starting a hosted multiplayer session the `UnityTransport` is assigned. + +### Single player limitations + +When running a single player session, you should take any netcode script into consideration that requires an actual multiplayer session to exist. + +#### RPC considerations +You can invoke any RPC that includes: + +- The host's client. +- The host's server. +- `SendTo` targets that will be invoked locally: + - `SendTo.Me` + - `SendTo.Server` + - `SendTo.Everyone` + - `SendTo.Authority` + - `SendTo.Owner` + - `ClientsAndHost` + - `SpecifiedInParams`: As long as it is targeting the `NetworkManager.LocalClientId`. +- `SendTo` targets that will **not be** invoked locally: + - `SendTo.NotOwner` + - `SendTo.NotServer` + - `SendTo.NotMe` + - `SendTo.NotAuthority` + - `SpecifiedInParams`: Anything not targeting the `NetworkManager.LocalClientId` will not be invoked locally. + +#### NetworkVariable considerations + +NetworkVariables should work as expected because the host will always be both the server and the owner of anything spawned. This means that write permissions, whether server or owner, should not be an issue. + +#### Distributed authority considerations + +To start a single player session using the distributed authority network topology you should: +- Keep your network topology setting set to distributed authority. +- Set the `NetworkConfig.NetworkTransport` to the `SinglePlayerTransport` component. +- Start as a host. + + ## Unity's UNet transport layer API UNet is a deprecated solution that is no longer supported after Unity 2022.2. Unity Transport Package is the default transport for Netcode for GameObjects. We recommend transitioning to Unity Transport as soon as possible. diff --git a/static/img/transport/SinglePlayerTransport_AddComponent.png b/static/img/transport/SinglePlayerTransport_AddComponent.png new file mode 100644 index 000000000..39a06fce3 Binary files /dev/null and b/static/img/transport/SinglePlayerTransport_AddComponent.png differ