From c34f7569b30890a5ede46e97f974eea634493cf6 Mon Sep 17 00:00:00 2001 From: Noel Stephens Date: Tue, 9 Apr 2024 10:13:22 -0500 Subject: [PATCH 1/3] update: server host shutdown and client disconnect (#1149) Co-authored-by: Vic Cooper <63712500+Vic-Cooper@users.noreply.github.com> Co-authored-by: Amy Reeve --- docs/components/networkmanager.md | 49 ++++++++++++++++++------------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/docs/components/networkmanager.md b/docs/components/networkmanager.md index 2b7a5d486..9c7f4a719 100644 --- a/docs/components/networkmanager.md +++ b/docs/components/networkmanager.md @@ -5,7 +5,7 @@ title: NetworkManager The `NetworkManager` is a required **Netcode for GameObjects (Netcode)** component that has all of your project's netcode related settings. Think of it as the "central netcode hub" for your netcode enabled project. -### `NetworkManager` Inspector Properties +### `NetworkManager` Inspector properties - **LogLevel**: Sets the network logging level - **PlayerPrefab**: When a Prefab is assigned, the Prefab will be instantiated as the player object and assigned to the newly connected and authorized client. @@ -22,7 +22,8 @@ The `NetworkManager` is a required **Netcode for GameObjects (Netcode)** compone - **Enable Scene Management**: When checked Netcode for GameObjects will handle scene management and client synchronization for you. When not checked, users will have to create their own scene management scripts and handle client synchronization. - **Load Scene Time Out**: When Enable Scene Management is checked, this specifies the period of time the `NetworkSceneManager` will wait while a scene is being loaded asynchronously before `NetworkSceneManager` considers the load/unload scene event to have failed/timed out. -### `NetworkManager` Sub-Systems +### `NetworkManager` sub-systems + `NetworkManager` is also where you can find references to other Netcode related management systems:
:::caution @@ -36,7 +37,7 @@ All `NetworkManager` sub-systems are instantiated once the `NetworkManager` is s - [NetworkManager.NetworkTickSystem](../advanced-topics/networktime-ticks#network-ticks.md): Use this to adjust the frequency of when NetworkVariables are updated. - [NetworkManager.CustomMessagingManager](../advanced-topics/message-system/custom-messages.md): Use this system to create and send custom messages. -## Starting a Server, Host, or Client +## Starting a server, host, or client In order to perform any netcode related action that involves sending messages, you must first have a server started and listening for connections with at least one client (_a server can send RPCs to itself when running as a host_) that is connected. to accomplish this, you must first start your `NetworkManager` as a server, host, or client. There are three `NetworkManager` methods you can invoke to accomplish this: @@ -92,9 +93,11 @@ If you are using Unity Relay to handle connections, however, **don't use `SetCon [More information about Netcode for GameObjects Transports](../advanced-topics/transports.md) -## Disconnecting and Shutting Down +## Disconnecting and shutting down + +### Disconnect from a network -Disconnecting is rather simple, but you can't use/access any subsystems (that is, `NetworkSceneManager`) once the `NetworkManager` is stopped because they will no longer be available. For client, host, or server modes, you only need to call the `NetworkManager.Shutdown` method as it will disconnect while shutting down. +When you disconnect from a network you can't use or access any subsystems, for example `NetworkSceneManager`, because they become unavailable when `NetworkManager` stops. For client, host, or server modes, call the `NetworkManager.Shutdown` method to disconnect and shut down at the same time. :::info When no network session is active and the `NetworkManager` has been shutdown, you will need to use `UnityEngine.SceneManagement` to load any non-network session related scene. @@ -109,7 +112,18 @@ public void Disconnect() } ``` -## Disconnecting Clients (Server Only) +### Shut down a network session + +When you invoke `NetworkManager.Shutdown` it closes any existing transport connections. The shutdown sequence for a client finishes before the next player loop update or frame. However, the shutdown sequence can take a bit longer for a server or host (server-host). + +The server-host notifies all clients when it shuts down. To do this, when you invoke `NetworkManager.Shutdown` the server-host sends out a disconnect notification to all currently connected clients and populates the `NetworkManager.Disconnect` reason with one of the two following messages, depending upon whether it's a server or host instance: + +- "Disconnected due to server shutting down." +- "Disconnected due to host shutting down." + +The server-host attempts to wait for all client connections to close before it finishes the shutdown sequence. This additional step on the server-host side helps to assure that clients receive a disconnect notification and prevents the client transport connection from timing out. If some client connections take longer than five seconds to close after `NetworkManager.Shutdown` is invoked, the server-host automatically finishes the shutdown sequence and closes any remaining connections. + +## Disconnecting clients (server only) At times you might need to disconnect a client for various reasons without shutting down the server. To do this, you can call the `NetworkManager.DisconnectClient` method while passing the identifier of the client you wish to disconnect as the only parameter. The client identifier can be found within: - The `NetworkManager.ConnectedClients` dictionary that uses the client identifier as a key and the value as the [`NetworkClient`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkClient.html). @@ -130,27 +144,22 @@ void DisconnectPlayer(NetworkObject player) } ``` -### Client Disconnection Notifications +### Client disconnection notifications -Both the client and the server can subscribe to the `NetworkManager.OnClientDisconnectCallback` event to be notified when a client is disconnected. Client disconnect notifications are "relative" to who is receiving the notification. - -**There are two general "disconnection" categories:** -- **Logical**: Custom server side code (code you might have written for your project) invokes `NetworkManager.DisconnectClient`. - - Example: A host player might eject a player or a player becomes "inactive" for too long. -- **Network Interruption**: The transport detects there is no longer a valid network connection. +Both the client and the server can subscribe to the `NetworkManager.OnClientDisconnectCallback` event to be notified when a client is disconnected. **When disconnect notifications are triggered:** - Clients are notified when they're disconnected by the server. -- The server is notified if the client side disconnects (that is, a player intentionally exits a game session) +- The server is notified when any client disconnects from the server, whether the server disconnects the client or the client disconnects itself. - Both the server and clients are notified when their network connection is unexpectedly disconnected (network interruption) -**Scenarios where the disconnect notification won't be triggered**: -- When a server "logically" disconnects a client. - - _Reason: The server already knows the client is disconnected._ -- When a client "logically" disconnects itself. - - _Reason: The client already knows that it's disconnected._ +**Client notification identifiers** +- On the server-side, the client identifier parameter is the identifier of the client that disconnects. +- On the client-side, the client identifier parameter is the identifier assigned to the client. + - _The exception to this is when a client is disconnected before its connection is approved._ + +### Connection notification manager example -### Connection Notification Manager Example Below is one example of how you can provide client connect and disconnect notifications to any type of NetworkBehaviour or MonoBehaviour derived component. :::important From 694ade43f99e01b20816072019dc3709a15e64be Mon Sep 17 00:00:00 2001 From: Amy Reeve Date: Wed, 10 Apr 2024 16:28:17 +0100 Subject: [PATCH 2/3] Multiple issue fixes (#1250) Co-authored-by: Vic Cooper <63712500+Vic-Cooper@users.noreply.github.com> --- docs/basics/networkobject.md | 2 ++ docs/components/networkmanager.md | 21 +++++++++++++-------- docs/tutorials/get-started-with-ngo.md | 3 ++- transport/workflow-client-server-udp.md | 4 +--- 4 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/basics/networkobject.md b/docs/basics/networkobject.md index 9523065e7..17c5c534f 100644 --- a/docs/basics/networkobject.md +++ b/docs/basics/networkobject.md @@ -3,6 +3,8 @@ id: networkobject title: NetworkObject --- +A NetworkObject is a [GameObject](https://docs.unity3d.com/Manual/GameObjects.html) with a NetworkObject component and at least one [NetworkBehaviour](networkbehaviour.md) component, which enables the GameObject to respond to and interact with netcode. + Netcode for GameObjects' high level components, [the RPC system](../advanced-topics/messaging-system.md), [object spawning](../object-spawning), and [NetworkVariable](networkvariable.md)s all rely on there being at least two Netcode components added to a GameObject: 1. `NetworkObject` diff --git a/docs/components/networkmanager.md b/docs/components/networkmanager.md index 9c7f4a719..fedb0427e 100644 --- a/docs/components/networkmanager.md +++ b/docs/components/networkmanager.md @@ -3,9 +3,9 @@ id: networkmanager title: NetworkManager --- -The `NetworkManager` is a required **Netcode for GameObjects (Netcode)** component that has all of your project's netcode related settings. Think of it as the "central netcode hub" for your netcode enabled project. +The `NetworkManager` is a required Netcode for GameObjects component that has all of your project's netcode-related settings. Think of it as the central netcode hub for your netcode-enabled project. -### `NetworkManager` Inspector properties +## `NetworkManager` Inspector properties - **LogLevel**: Sets the network logging level - **PlayerPrefab**: When a Prefab is assigned, the Prefab will be instantiated as the player object and assigned to the newly connected and authorized client. @@ -22,7 +22,7 @@ The `NetworkManager` is a required **Netcode for GameObjects (Netcode)** compone - **Enable Scene Management**: When checked Netcode for GameObjects will handle scene management and client synchronization for you. When not checked, users will have to create their own scene management scripts and handle client synchronization. - **Load Scene Time Out**: When Enable Scene Management is checked, this specifies the period of time the `NetworkSceneManager` will wait while a scene is being loaded asynchronously before `NetworkSceneManager` considers the load/unload scene event to have failed/timed out. -### `NetworkManager` sub-systems +## `NetworkManager` sub-systems `NetworkManager` is also where you can find references to other Netcode related management systems:
@@ -39,7 +39,7 @@ All `NetworkManager` sub-systems are instantiated once the `NetworkManager` is s ## Starting a server, host, or client -In order to perform any netcode related action that involves sending messages, you must first have a server started and listening for connections with at least one client (_a server can send RPCs to itself when running as a host_) that is connected. to accomplish this, you must first start your `NetworkManager` as a server, host, or client. There are three `NetworkManager` methods you can invoke to accomplish this: +In order to perform any netcode-related action that involves sending messages, you must first have a server started and listening for connections with at least one client (_a server can send RPCs to itself when running as a host_) that is connected. To accomplish this, you must first start your `NetworkManager` as a server, host, or client. There are three `NetworkManager` methods you can invoke to accomplish this: ```csharp NetworkManager.Singleton.StartServer(); // Starts the NetworkManager as just a server (that is, no local client). @@ -52,7 +52,8 @@ Don't start a NetworkManager within a NetworkBehaviour's Awake method as this ca ::: :::note - When starting a Server or joining an already started session as client, the `NetworkManager` can spawn a "Player Object" belonging to the client. + + When starting a server or joining an already started session as client, the `NetworkManager` can spawn a "Player Object" belonging to the client. For more information about player prefabs see: - [NetworkObject Player Prefab Documentation](../basics/networkobject.md#player-objects) @@ -61,7 +62,7 @@ Don't start a NetworkManager within a NetworkBehaviour's Awake method as this ca ## Connecting -When Starting a Client, the `NetworkManager` uses the IP and the Port provided in your `Transport` component for connecting. While you can set the IP address in the editor, many times you might want to be able to set the IP address and port during runtime. +When starting a client, the `NetworkManager` uses the IP and the Port provided in your `Transport` component for connecting. While you can set the IP address in the editor, many times you might want to be able to set the IP address and port during runtime. The below examples use [Unity Transport](../../../transport/current/about) to show a few ways you can gain access to the `UnityTransport` component via the `NetworkManager.Singleton` to configure your project's network settings programmatically: @@ -74,6 +75,7 @@ NetworkManager.Singleton.GetComponent().SetConnectionData( ``` If you are using the same code block to configure both your server and your client and you want to configure your server to listen to all IP addresses assigned to it, then you can also pass a 'listen address' of "0.0.0.0" to the `SetConnectionData` method, like so: + ```csharp NetworkManager.Singleton.GetComponent().SetConnectionData( "127.0.0.1", // The IP address is a string @@ -125,7 +127,8 @@ The server-host attempts to wait for all client connections to close before it f ## Disconnecting clients (server only) -At times you might need to disconnect a client for various reasons without shutting down the server. To do this, you can call the `NetworkManager.DisconnectClient` method while passing the identifier of the client you wish to disconnect as the only parameter. The client identifier can be found within: +At times you might need to disconnect a client for various reasons without shutting down the server. To do this, you can call the `NetworkManager.DisconnectClient` method while passing the identifier of the client you wish to disconnect as the only parameter. The client identifier can be found within: + - The `NetworkManager.ConnectedClients` dictionary that uses the client identifier as a key and the value as the [`NetworkClient`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkClient.html). - As a read only list of `NetworkClients` via the `NetworkManager.ConnectedClientsList`. - A full list of all connected client identifiers can be accessed via `NetworkManager.ConnectedClientsIds`. @@ -151,13 +154,15 @@ Both the client and the server can subscribe to the `NetworkManager.OnClientDisc **When disconnect notifications are triggered:** - Clients are notified when they're disconnected by the server. - The server is notified when any client disconnects from the server, whether the server disconnects the client or the client disconnects itself. -- Both the server and clients are notified when their network connection is unexpectedly disconnected (network interruption) +- Both the server and clients are notified when their network connection is unexpectedly disconnected (network interruption). **Client notification identifiers** - On the server-side, the client identifier parameter is the identifier of the client that disconnects. - On the client-side, the client identifier parameter is the identifier assigned to the client. - _The exception to this is when a client is disconnected before its connection is approved._ +You can also use the `NetworkManager.OnServerStopped` and `NetworkManager.OnClientStopped` callbacks to get local notifications when the server or client stops respectively. + ### Connection notification manager example Below is one example of how you can provide client connect and disconnect notifications to any type of NetworkBehaviour or MonoBehaviour derived component. diff --git a/docs/tutorials/get-started-with-ngo.md b/docs/tutorials/get-started-with-ngo.md index 13fc0c0ef..08b0d92db 100644 --- a/docs/tutorials/get-started-with-ngo.md +++ b/docs/tutorials/get-started-with-ngo.md @@ -178,7 +178,6 @@ This section guides you through testing the RPCs you added in the earlier sectio 1. Select **File** > **Build And Run**. 2. Stop the player. 3. Launch the client and server together in a terminal, as shown in [Testing the command line helper](command-line-helper.md). - * Alternatively, you can use Multiplayer Play Mode package, which lets you run multiple instances of the Unity Editor to test multiplayer functionality. Refer to [Multiplayer Play Mode](https://docs-multiplayer.unity3d.com/tools/current/mppm) to learn more. After the client and server spawn, a log displays in the **Console** of the client and server sending RPC messages to each other. @@ -220,6 +219,8 @@ The `NetworkObjectId` here is `2` because the host also has a NetworkObject with ::: +Alternatively, you can use the Multiplayer Play Mode package, which lets you run multiple instances of the Unity Editor to test multiplayer functionality. Refer to the [Multiplayer Play Mode documentation](https://docs-multiplayer.unity3d.com/mppm/current/about/) to learn more. + ## Extend functionality with scripts The section shows how to extend the functionality of the Hello World project with two scripts: [`HelloWorldPlayer.cs`](#the-helloworldplayercs-script) and [`HelloWorldManager.cs`](#the-helloworldmanagercs-script). diff --git a/transport/workflow-client-server-udp.md b/transport/workflow-client-server-udp.md index e98c07d7c..28067e9a9 100644 --- a/transport/workflow-client-server-udp.md +++ b/transport/workflow-client-server-udp.md @@ -28,9 +28,7 @@ The client-server workflow in this guide shows the subtle differences between us A server is an endpoint that listens for incoming connection requests and sends and receives messages. This section shows creating a simple server with UTP 2.0. -Start by creating a C# script in the Unity Editor. Name the script ServerBehaviour.cs. - -**Filename**: [`ServerBehaviour.cs`](samples/serverbehaviour.cs.md) +Start by creating a C# script in the Unity Editor. Name the script `ServerBehaviour.cs`. ```csharp using System.Collections; From 7ee10a42bb885dd3e3029fd1446ceebff555441f Mon Sep 17 00:00:00 2001 From: Amy Reeve Date: Wed, 10 Apr 2024 16:37:14 +0100 Subject: [PATCH 3/3] Fixing broken links on Bossroom page --- docs/learn/bossroom/getting-started-boss-room.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/learn/bossroom/getting-started-boss-room.md b/docs/learn/bossroom/getting-started-boss-room.md index 9f430f6f5..352574f43 100644 --- a/docs/learn/bossroom/getting-started-boss-room.md +++ b/docs/learn/bossroom/getting-started-boss-room.md @@ -106,7 +106,7 @@ One of the eight clients acts as the host/server. That client will use a composi * The game is server-authoritative, with latency-masking animations. * Position updates are carried out through NetworkTransform that sync position and rotation. -* Code is organized in domain-based assemblies. See our [ARCHITECTURE.md](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/v2.2.0/ARCHITECTURE.md) file for more details. +* Code is organized in domain-based assemblies. ### Testing multiplayer @@ -235,9 +235,12 @@ Boss Room includes the following tools and utilities: * ParrelSync - [Packages/manifest.json](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/v2.2.0/Packages/manifest.json) ### Troubleshooting + #### Bugs -Report bugs in Boss Room using Github [issues](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/issues) Report Netcode for GameObjects bugs using Netcode for GameObjects Github [issues](https://github.com/Unity-Technologies/com.unity.netcode.gameobjects) Report Unity bugs using the [Unity bug submission process](https://unity3d.com/unity/qa/bug-reporting). +- Report bugs in Boss Room using Github [issues](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/issues) +- Report Netcode for GameObjects bugs using Netcode for GameObjects Github [issues](https://github.com/Unity-Technologies/com.unity.netcode.gameobjects/issues) +- Report Unity bugs using the [Unity bug submission process](https://unity3d.com/unity/qa/bug-reporting). ### Licence @@ -257,7 +260,7 @@ The [Bitesize Samples](https://github.com/Unity-Technologies/com.unity.multiplay ### Contributing -Please check out [CONTRIBUTING.md](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/v2.2.0p/CONTRIBUTING.md) for full guidelines on submitting issues and PRs to Boss Room. +Please check out [CONTRIBUTING.md](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/main/CONTRIBUTING.md) for full guidelines on submitting issues and PRs to Boss Room. Our projects use the `git-flow` branching strategy: