Skip to content

Commit 18db768

Browse files
Update networkbehaviour pre, post, and synchronize methods
Adding documentation for PR-2906: Unity-Technologies/com.unity.netcode.gameobjects#2906
1 parent 4090aa0 commit 18db768

File tree

1 file changed

+24
-0
lines changed

1 file changed

+24
-0
lines changed

docs/basics/networkbehaviour.md

+24
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,30 @@ Start | OnNetworkSpawn
3737

3838
For more information about `NetworkBehaviour` methods and when they are invoked, see the [Pre-Spawn and MonoBehaviour Methods](networkbehaviour.md#pre-spawn-and-monobehaviour-methods) section.
3939

40+
### PreSpawn, Spawn, Post Spawn and Synchronization
41+
The `NetworkObject` spawn process can become complicated when there are multiple `NetworkBehaviour` components attached to the same `GameObject`. Additionally, there can be times where you want to be able to handle pre and post spawn oriented tasks.
42+
- Pre-Spawn example: Instantiating a `NetworkVariable` with owner write permissions and assigning a value to that `NetworkVariable` on the server or host side.
43+
- Spawn example: Applying a local value or setting that may be used during post spawn by another local `NetworkBehaviour` component.
44+
- Post-Spawn example: Accessing a `NetworkVariable` or other property that is set during the spawn process.
45+
46+
Below we can see the three virtual methods you can override within a `NetworkBehaviour` derrived class:
47+
48+
Method | Scope | Use Case | Context
49+
---------------------------- | ------------------------ | ------------------------------------------------------ | -------------
50+
OnNetworkPreSpawn | NetworkObject | Pre-Spawn initialization | client & server
51+
OnNetworkSpawn | NetworkObject | During spawn initialization | client & server
52+
OnNetworkPostSpawn | NetworkObject | Post spawn actions | client & server
53+
OnNetworkSessionSynchronized | All NetworkObjects | New client finished synchronizing | client-side only **
54+
OnInSceneObjectsSpawned | In-Scene NetworkObjects | New client finished synchronizing or a scene is loaded | client & server
55+
56+
Looking at the above list, there are two additional special case "convenience" methods:
57+
- OnNetworkSessionSynchronized: When scene management is enabled and a new client joins a session the client will start synchronizing with the network session. During this period of time the client might need to load additional scenes as well as instantiate and spawn `NetworkObjects`. When a client has finished loading all scenes and all `NetworkObject`s are spawned, this method gets invoked on all `NetworkBehaviours` associated with any spawned `NetworkObject`s. This can be useful if you want to write script that might require access to other spawned `NetworkObject`s and/or their `NetworkBehaviour` components. When this method is invoked, you are assured everything is spawned and ready to be accessed and/or to have messages sent from them. Of course, take in mind this is on invoked on clients and will not be invoked on a server or host.
58+
- OnInSceneObjectsSpawned: Sometimes you might want to have the same kind of assurance that any in-scene placed `NetworkObject`s have been spawned prior to a specific set of script being invoked. This method is invoked on in-scene placed `NetworkObject`s when:
59+
- A server or host first starts up after all in-scene placed NetworkObjects in the currently loaded scene(s) have been spawned.
60+
- A client finishes synchronizing.
61+
- On the server and client side after a scene has been loaded and all newly instantiated in-scene placed NetworkObjects have been spawned.
62+
63+
4064
#### Dynamically Spawned NetworkObjects
4165

4266
For dynamically spawned `NetworkObjects` (instantiating a network Prefab during runtime) the `OnNetworkSpawn` method is invoked **before** the `Start` method is invoked. So, it's important to be aware of this because finding and assigning components to a local property within the `Start` method exclusively will result in that property not being set in a `NetworkBehaviour` component's `OnNetworkSpawn` method when the `NetworkObject` is dynamically spawned. To circumvent this issue, you can have a common method that initializes the components and is invoked both during the `Start` method and the `OnNetworkSpawned` method like the code example below:

0 commit comments

Comments
 (0)