Skip to content
This repository was archived by the owner on Jul 23, 2025. It is now read-only.

Commit 129d8a1

Browse files
jabbacakesjabbacakes
authored
Publishing NGO 2.0.0 docs (#1348)
2 parents d563c54 + 2d36e45 commit 129d8a1

File tree

8 files changed

+140
-78
lines changed

8 files changed

+140
-78
lines changed

‎docs/basics/networkbehaviour.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,18 @@ title: NetworkBehaviour spawning and despawning
55

66
[`NetworkBehaviour`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.html) is an abstract class that derives from [`MonoBehaviour`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.html) and is primarily used to create unique netcode or game logic. To replicate any netcode-aware properties or send and receive RPCs, a [GameObject](https://docs.unity3d.com/Manual/GameObjects.html) must have a [NetworkObject](networkobject.md) component and at least one `NetworkBehaviour` component.
77

8-
A `NetworkBehaviour` requires a NetworkObject component on the same relative GameObject or on a parent of the GameObject with the `NetworkBehaviour` component assigned to it. If you add a `NetworkBehaviour` to a GameObject that doesn't have a NetworkObject (or any parent), then Netcode for GameObjects automatically adds a NetworkObject component to the `GameObject` in which the `NetworkBehaviour` was added.
9-
10-
`NetworkBehaviour`s can use `NetworkVariable`s and RPCs to synchronize states and send messages over the network. When you call an RPC function, the function isn't called locally. Instead, a message is sent containing your parameters, the `networkId` of the NetworkObject associated with the same GameObject (or child) that the `NetworkBehaviour` is assigned to, and the index of the NetworkObject-relative `NetworkBehaviour` (NetworkObjects can have several `NetworkBehaviours`, the index communicates which one).
8+
`NetworkBehaviour`s can use `NetworkVariable`s and RPCs to synchronize states and send messages over the network. When you call an RPC function in a `NetworkBehaviour`, the function isn't called locally. Instead, a message is sent containing your parameters, the `networkId` of the NetworkObject associated with the same GameObject (or child) that the `NetworkBehaviour` is assigned to, and the index of the NetworkObject-relative `NetworkBehaviour` (NetworkObjects can have several `NetworkBehaviours`, the index communicates which one).
119

1210
For more information about serializing and synchronizing `NetworkBehaviour`s, refer to the [NetworkBehaviour synchronization page](networkbehaviour-synchronize.md).
1311

14-
:::note
12+
## `NetworkBehaviour` requirements
13+
14+
A `NetworkBehaviour` requires a NetworkObject component on the same relative GameObject or on a parent of the GameObject with the `NetworkBehaviour` component assigned to it. If you add a `NetworkBehaviour` to a GameObject that doesn't have a NetworkObject (or any parent), then Netcode for GameObjects automatically adds a NetworkObject component to the `GameObject` in which the `NetworkBehaviour` was added.
15+
1516
It's important that the `NetworkBehaviour`s on each NetworkObject remain the same for the server and any client connected. When using multiple projects, this becomes especially important so the server doesn't try to call a client RPC on a `NetworkBehaviour` that might not exist on a specific client type (or set a `NetworkVariable` that doesn't exist, and so on).
17+
18+
:::warning Disabling automatic NetworkObject addition
19+
You can optionally disable the automatic addition of NetworkObjects to GameObjects in the Editor using the **Multiplayer** > **Netcode for GameObjects** project settings. However, this is only recommended for advanced users who understand the implications and have alternative strategies in place to ensure that GameObjects with `NetworkBehaviour`s always have an associated NetworkObject.
1620
:::
1721

1822
## Spawning

‎docs/basics/networkobject.md

Lines changed: 11 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@ Netcode for GameObjects' high level components, [the RPC system](../advanced-top
1010
1. NetworkObject
1111
2. [`NetworkBehaviour`](networkbehaviour.md)
1212

13-
NetworkObjects require the use of specialized [`NetworkObjectReference`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkObjectReference.html) structures before you can serialize and use them with RPCs and `NetworkVariable`s.
13+
NetworkObjects require the use of specialized [`NetworkObjectReference`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkObjectReference.html) structures before you can serialize and use them with RPCs and `NetworkVariable`s
14+
15+
Netcode for GameObjects also has [PlayerObjects](playerobjects.md), an optional feature that you can use to assign a NetworkObject to a specific client.
1416

1517
## Using NetworkObjects
1618

@@ -34,6 +36,8 @@ You can avoid execution order issues in any NetworkBehaviour component scripts t
3436

3537
Either the server (default) or any connected and approved client owns each NetworkObject. By default, Netcode for GameObjects is [server-authoritative](../terms-concepts/client-server.md), which means only the server can spawn and despawn NetworkObjects, but you can also build [distributed authority](../terms-concepts/distributed-authority.md) games where clients have the authority to spawn and despawn NetworkObjects as well.
3638

39+
If you're creating a client-server game and you want a client to control more than one NetworkObject, use the following ownership methods.
40+
3741
The default `NetworkObject.Spawn` method assumes server-side ownership:
3842

3943
```csharp
@@ -68,71 +72,6 @@ When you want to despawn and destroy the owner but you don't want to destroy a s
6872

6973
:::
7074

71-
## Player NetworkObjects
72-
73-
Player objects are an optional feature in Netcode for GameObjects that you can use to assign a networked object to a specific client. A client can only have at most one player object.
74-
75-
If you want a client to control more than one NetworkObject, use the ownership methods described above under the ownership section.
76-
77-
If you want to be able to assign a unique player prefab on a per-client connection basis, use client [connection approval](connection-approval.md).
78-
79-
### Creating a PlayerObject
80-
81-
Netcode for GameObjects can spawn a default PlayerObject for you. If you enable **Create Player Prefab** (true) in the NetworkManager and assign a valid prefab, then Netcode for GameObjects spawns a unique instance of the designated player prefab for each connected and approved client.
82-
83-
To manually spawn an object as PlayerObject, use the following method:
84-
85-
```csharp
86-
GetComponent<NetworkObject>().SpawnAsPlayerObject(clientId);
87-
```
88-
89-
If the player already had a prefab instance assigned, then the client owns the NetworkObject of that prefab instance unless there's additional server-side specific user code that removes or changes the ownership.
90-
91-
### Defining defaults for PlayerObjects
92-
93-
If you're using `UnityEngine.InputSystem.PlayerInput` or `UnityEngine.PhysicsModule.CharacterController` components on your player prefab(s), you should disable them by default and only enable them for the local client's PlayerObject. Otherwise, you may get events from the most recently instantiated player prefab instance, even if it isn't the local client instance.
94-
95-
You can disable these components in the **Inspector** view on the prefab itself, or disable them during `Awake` in one of your `NetworkBehaviour` components. Then you can enable the components only on the owner's instance using code like the example below:
96-
97-
```
98-
PlayerInput m_PlayerInput;
99-
private void Awake()
100-
{
101-
m_PlayerInput = GetComponent<PlayerInput>();
102-
m_PlayerInput.enabled = false;
103-
}
104-
105-
public override void OnNetworkSpawn()
106-
{
107-
m_PlayerInput.enabled = IsOwner;
108-
base.OnNetworkSpawn();
109-
}
110-
111-
public override void OnNetworkDespawn()
112-
{
113-
m_PlayerInput.enabled = false;
114-
base.OnNetworkDespawn();
115-
}
116-
```
117-
118-
### Finding PlayerObjects
119-
120-
To find a PlayerObject for a specific client ID, you can use the following methods:
121-
122-
Within a NetworkBehaviour, you can check the local `NetworkManager.LocalClient` to get the local PlayerObjects:
123-
124-
```csharp
125-
NetworkManager.LocalClient.PlayerObject
126-
```
127-
128-
Conversely, on the server-side, if you need to get the PlayerObject instance for a specific client, you can use the following:
129-
130-
```csharp
131-
NetworkManager.Singleton.ConnectedClients[clientId].PlayerObject;
132-
```
133-
134-
To find your own player object just pass `NetworkManager.Singleton.LocalClientId` as the `clientId` in the sample above.
135-
13675
## Network prefabs
13776

13877
Network prefabs are registered to a `NetworkPrefabsList` object (a type of `ScriptableObject`). By default, a default prefabs list containing every network prefab in your project.
@@ -178,3 +117,9 @@ Similar to `NetworkObject.ActiveSceneSynchronization`, this property automatical
178117
:::info
179118
`NetworkObject.ActiveSceneSynchronization` can be used with `NetworkObject.SceneMigrationSynchronization` as long as you take into consideration that if you migrate a NetworkObject into a non-active scene via `SceneManager.MoveGameObjectToScene` and then later change the active scene, then the NetworkObject instance will be automatically migrated to the newly set active scene.
180119
:::
120+
121+
## Additional resources
122+
123+
- [PlayerObjects and player prefabs](playerobjects.md)
124+
- [NetworkBehaviour](networkbehaviour.md)
125+
- [NetworkVariable](networkvariable.md)

‎docs/basics/playerobjects.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
id: playerobjects
3+
title: PlayerObjects and player prefabs
4+
---
5+
6+
PlayerObjects are an optional feature in Netcode for GameObjects that you can use to assign a [NetworkObject](networkobject.md) to a specific client. A client can only have one PlayerObject.
7+
8+
PlayerObjects are instantiated by reference to a player prefab, which defines the characteristics of the PlayerObject.
9+
10+
## Defining defaults for player prefabs
11+
12+
If you're using `UnityEngine.InputSystem.PlayerInput` or `UnityEngine.PhysicsModule.CharacterController` components on your player prefab(s), you should disable them by default and only enable them for the local client's PlayerObject. Otherwise, you may get events from the most recently instantiated player prefab instance, even if it isn't the local client instance.
13+
14+
You can disable these components in the **Inspector** view on the prefab itself, or disable them during `Awake` in one of your `NetworkBehaviour` components. Then you can enable the components only on the owner's instance using code like the example below:
15+
16+
```
17+
PlayerInput m_PlayerInput;
18+
private void Awake()
19+
{
20+
m_PlayerInput = GetComponent<PlayerInput>();
21+
m_PlayerInput.enabled = false;
22+
}
23+
24+
public override void OnNetworkSpawn()
25+
{
26+
m_PlayerInput.enabled = IsOwner;
27+
base.OnNetworkSpawn();
28+
}
29+
30+
public override void OnNetworkDespawn()
31+
{
32+
m_PlayerInput.enabled = false;
33+
base.OnNetworkDespawn();
34+
}
35+
```
36+
37+
## Spawning PlayerObjects
38+
39+
## Session-mode agnostic methods
40+
41+
Netcode for GameObjects can spawn a default PlayerObject for you. If you enable **Create Player Prefab** in the [NetworkManager](../components/networkmanager.md) and assign a valid prefab, then Netcode for GameObjects spawns a unique instance of the designated player prefab for each connected and approved client, referred to as the PlayerObject.
42+
43+
To manually spawn an object as PlayerObject, use the following method:
44+
45+
```csharp
46+
GetComponent<NetworkObject>().SpawnAsPlayerObject(clientId);
47+
```
48+
49+
If the player already had a prefab instance assigned, then the client owns the NetworkObject of that prefab instance unless there's additional server-side specific user code that removes or changes the ownership.
50+
51+
Alternatively, you can choose not to spawn anything immediately after a client connects and instead use a [NetworkBehaviour component](networkbehaviour.md) to handle avatar/initial player prefab selection. This NetworkBehaviour component could be configured by the server or initiating session owner, or be associated with an [in-scene](scenemanagement/inscene-placed-networkobjects.md) or [dynamically spawned](object-spawning.md#dynamically-spawned-network-prefabs) NetworkObject, as suits the needs of your project.
52+
53+
### Client-server contexts only
54+
55+
In addition to the [session-mode agnostic spawning methods](#session-mode-agnostic-methods) above, you can assign a unique player prefab on a per-client connection basis using a client [connection approval process](connection-approval.md) when in [client-server contexts](../terms-concepts/client-server.md).
56+
57+
### Distributed authority contexts only
58+
59+
In addition to the [session-mode agnostic spawning methods](#session-mode-agnostic-methods) above, you can use the [`OnFetchLocalPlayerPrefabToSpawn`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkManager.html#Unity_Netcode_NetworkManager_OnFetchLocalPlayerPrefabToSpawn) method to assign a unique player prefab on a per-client basis when in [distributed authority contexts](../terms-concepts/distributed-authority.md).
60+
61+
To use `OnFetchLocalPlayerPrefabToSpawn` in your project, assign a callback handler to `OnFetchLocalPlayerPrefabToSpawn` and whatever the client script returns is what will be spawned for that client. Ensure that the prefab being spawned is in a NetworkPrefabList [registered with the NetworkManager](object-spawning.md#registering-a-network-prefab).
62+
63+
If you don't assign a callback handler to `OnFetchLocalPlayerPrefabToSpawn`, then the default behaviour is to return the `NetworkConfig.PlayerPrefab` (or null if neither are set).
64+
65+
:::note `AutoSpawnPlayerPrefabClientSide` required
66+
For `OnFetchLocalPlayerPrefabToSpawn` to work, [`AutoSpawnPlayerPrefabClientSide`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkManager.html#Unity_Netcode_NetworkManager_AutoSpawnPlayerPrefabClientSide) must be enabled.
67+
:::
68+
69+
## PlayerObject spawning timeline
70+
71+
When using automatic methods of PlayerObject spawning (such as enabling **Create Player Prefab** in the [NetworkManager](../components/networkmanager.md)), PlayerObjects are spawned at different times depending on whether you have [scene management](scenemanagement/scene-management-overview.md) enabled.
72+
73+
- When scene management is disabled, PlayerObjects are spawned when a joining client's connection is approved.
74+
- When scene management is enabled, PlayerObjects are spawned when a joining client finishes initial synchronization.
75+
76+
If you choose not to automatically spawn a PlayerObject when a client joins, then the timing of when a PlayerObject is spawned is up to you based on your own implemented code.
77+
78+
## Finding PlayerObjects
79+
80+
To find a PlayerObject for a specific client ID, you can use the following methods:
81+
82+
Within a NetworkBehaviour, you can check the local `NetworkManager.LocalClient` to get the local PlayerObjects:
83+
84+
```csharp
85+
NetworkManager.LocalClient.PlayerObject
86+
```
87+
88+
Conversely, on the server-side, if you need to get the PlayerObject instance for a specific client, you can use the following:
89+
90+
```csharp
91+
NetworkManager.Singleton.ConnectedClients[clientId].PlayerObject;
92+
```
93+
94+
To find your own player object just pass `NetworkManager.Singleton.LocalClientId` as the `clientId` in the sample above.
95+
96+
## Additional resources
97+
98+
- [NetworkObject](networkobject.md)
99+
- [NetworkManager](../components/networkmanager.md)
100+
- [Distributed authority topologies](../terms-concepts/distributed-authority.md)
101+
- [Client-server topologies](../terms-concepts/client-server.md)
102+
- [Object spawning](objectspawning.md)

‎docs/components/networkmanager.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The `NetworkManager` is a required Netcode for GameObjects component that has al
88
### `NetworkManager` Inspector properties
99

1010
- **LogLevel**: Sets the network logging level
11-
- **PlayerPrefab**: When a prefab is assigned, the prefab will be instantiated as the player object and assigned to the newly connected and authorized client. For more information about player prefabs, refer to [Player NetworkObjects](../basics/networkobject.md#player-networkobjects).
11+
- **PlayerPrefab**: When a prefab is assigned, the prefab will be instantiated as the PlayerObject and assigned to the newly connected and authorized client. For more information about player prefabs, refer to [PlayerObjects and player prefabs](../basics/playerobjects.md).
1212
- **NetworkPrefabs**: Where you register your network prefabs. You can also create a single network prefab override per registered network prefab here.
1313
- **Protocol Version**: Set this value to help distinguish between builds when the most current build has new assets that can cause issues with older builds connecting.
1414
- **Network Transport**: Where your network specific settings and transport type is set. This field accepts any INetworkTransport implementation. However, unless you have unique transport specific needs UnityTransport is the recommended transport to use with Netcode for GameObjects.

‎docs/terms-concepts/distributed-authority.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Distributed authority provides additional permissions to manage object distribut
2020
Using a distributed authority topology is typically not suitable for high-performance competitive games that require an accurate predictive motion model. The distributed authority model successfully addresses a lot of visual and input-related issues, but does have some limitations:
2121

2222
* Since authority and ownership of objects is distributed across clients, there's typically no single physics simulation governing the interaction of all objects. This can require approaching physics-related gameplay differently compared to a traditional client-server context.
23-
* Depending on the platform and overall design of your product, client-side cheating and hacking can become less complicated for bad actors since there's no single authority.
23+
* Depending on the platform and overall design of your product, it can be easier for bad actors to cheat. The authority model gives more trust to individual clients. Evaluate your cheating tolerance when developing with distributed authority.
2424

2525
For game designs that don't require a precise physics simulation or client prediction model (with potentially some form of rollback), a distributed authority approach can be a good option. It's less resource intensive than having a dedicated game server, and can make it simpler to implement many common netcode features when compared with equivalent implementations in a client-server topology.
2626

‎docusaurus.config.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,7 @@ module.exports = {
237237
lastVersion: "current",
238238
versions: {
239239
current: {
240-
label: "2.0.0-pre",
240+
label: "2.0.0",
241241
path: "current",
242242
},
243243
"1.11.0": {

‎sidebars.js

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,10 @@ module.exports = {
132132
"type": "doc",
133133
"id": "basics/networkobject"
134134
},
135+
{
136+
"type": "doc",
137+
"id": "basics/playerobjects"
138+
},
135139
{
136140
"type": "doc",
137141
"id": "advanced-topics/networkobject-parenting"
@@ -551,10 +555,6 @@ module.exports = {
551555
"type": "doc",
552556
"id": "learn/bitesize/bitesize-introduction"
553557
},
554-
{
555-
"type": "doc",
556-
"id": "learn/bitesize/bitesize-invaders"
557-
},
558558
{
559559
"type": "doc",
560560
"id": "learn/bitesize/bitesize-spaceshooter"
@@ -569,6 +569,17 @@ module.exports = {
569569
},
570570
]
571571
},
572+
{
573+
"collapsed": true,
574+
"type": "category",
575+
"label": "Deprecated samples",
576+
"items": [
577+
{
578+
"type": "doc",
579+
"id": "learn/bitesize/bitesize-invaders"
580+
},
581+
]
582+
},
572583
],
573584
},
574585
{

0 commit comments

Comments
 (0)