NetworkObject
A NetworkObject is a GameObject with a NetworkObject component and at least one NetworkBehaviour component, which enables the GameObject to respond to and interact with netcode. NetworkObjects are session-mode agnostic and used in both client-server and distributed authority contexts.
Netcode for GameObjects' high level components, the RPC system, object spawning, and NetworkVariables all rely on there being at least two Netcode components added to a GameObject:
NetworkObjectNetworkBehaviour
NetworkObjects require the use of specialized NetworkObjectReference structures before you can serialize and use them with RPCs and NetworkVariables.
Using NetworkObjects
To replicate any Netcode-aware properties or send/receive RPCs, a GameObject must have a NetworkObject component and at least one NetworkBehaviour component. Any Netcode-related component, such as a NetworkTransform or a NetworkBehaviour with one or more NetworkVariables or RPCs, requires a NetworkObject component on the same relative GameObject (or on a parent of the GameObject in question).
When spawning a NetworkObject, the NetworkObject.GlobalObjectIdHash value initially identifies the associated network prefab asset that clients instantiate to create a client-local clone. After instantiated locally, each NetworkObject is assigned a NetworkObjectId that's used to associate NetworkObjects across the network. For example, one peer can say "Send this RPC to the object with the NetworkObjectId 103," and everyone knows what object it's referring to. A NetworkObject is spawned on a client when it's instantiated and assigned a unique NetworkObjectId.
You can use NetworkBehaviours to add your own custom Netcode logic to the associated NetworkObject.
The order of networked objects matters. Make sure to load any NetworkBehaviour components before the Network Object component on the GameObject.
Ownership
Either the server (default) or any connected and approved client owns each NetworkObject. By default, Netcode for GameObjects is server-authoritative, which means only the server can spawn and despawn NetworkObjects, but you can also build distributed authority games where clients have the authority to spawn and despawn NetworkObjects as well.
The default NetworkObject.Spawn method assumes server-side ownership:
GetComponent<NetworkObject>().Spawn();
To spawn NetworkObjects with ownership use the following:
GetComponent<NetworkObject>().SpawnWithOwnership(clientId);
To change ownership, use the ChangeOwnership method:
GetComponent<NetworkObject>().ChangeOwnership(clientId);
To give ownership back to the server use the RemoveOwnership method:
GetComponent<NetworkObject>().RemoveOwnership();
To see if the local client is the owner of a NetworkObject, you can check the NetworkBehaviour.IsOwner property.
To see if the server owns the NetworkObject, you can check the NetworkBehaviour.IsOwnedByServer property.
When you want to despawn and destroy the owner but you don't want to destroy a specific NetworkObject along with the owner, you can set the NetworkObject.DontDestroyWithOwner property to true which ensures that the owned NetworkObject isn't destroyed with the owner.
Player NetworkObjects
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 always only have at most one player object.
If you want a client to control more than one NetworkObject, use the ownership methods described above under the ownership section.
If you want to be able to assign a unique player prefab on a per-client connection basis, use client connection approval.
Creating a PlayerObject
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.
To manually spawn an object as PlayerObject, use the following method:
GetComponent<NetworkObject>().SpawnAsPlayerObject(clientId);
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.
Finding PlayerObjects
To find a PlayerObject for a specific client ID, you can use the following methods:
Within a NetworkBehaviour, you can check the local NetworkManager.LocalClient to get the local PlayerObjects:
NetworkManager.LocalClient.PlayerObject
Conversely, on the server-side, if you need to get the PlayerObject instance for a specific client, you can use the following:
NetworkManager.Singleton.ConnectedClients[clientId].PlayerObject;
To find your own player object just pass NetworkManager.Singleton.LocalClientId as the clientId in the sample above.
Network prefabs
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.
However, when you want to limit which prefabs are available (for example, to reduce memory usage), you can disable this behavior in Project Settings > Netcode For GameObjects > Project Settings. You can also manually create a NetworkPrefabsList by right-clicking in the assets view and selecting Create > Netcode > Network Prefabs List and adding your prefabs to it. That prefab list can then be assigned to a NetworkManager to allow that NetworkManager to create those prefabs.
You can only have one NetworkObject at the root of a prefab. Don't create prefabs with nested NetworkObjects.
Spawning with (or without) observers
The NetworkObject.SpawnWithObservers property (default is true) enables you to spawn a NetworkObject with no initial observers. This is the recommended alternative to using NetworkObject.CheckObjectVisibility when you just want it to be applied globally to all clients (only when spawning an instance of the NetworkObject in question). If you want more precise per-client control then NetworkObject.CheckObjectVisibility is recommended. NetworkObject.SpawnWithObservers is only applied upon the initial server-side spawning and once spawned it has no impact on object visibility.
Transform synchronization
There are times when you want to use a NetworkObject for something that doesn't require the synchronization of its transform. You might have an in-scene placed NetworkObject that's only used to manage game state and it doesn't make sense to incur the initial client synchronization cost of synchronizing its transform. To prevent a NetworkObject from initially synchronizing its transform when spawned, deselect the Synchronize Transform property. This property is enabled by default.
If you're planning to use a NetworkTransform, then you always want to make sure the Synchronize Transform property is enabled.
Active scene synchronization
When a GameObject is instantiated, it gets instantiated in the current active scene. However, sometimes you might find that you want to change the currently active scene and would like specific NetworkObject instances to automatically migrate to the newly assigned active scene. While you could keep a list or table of the NetworkObject instances and write the code/logic to migrate them into a newly assigned active scene, this can be time consuming and become complicated depending on project size and complexity. The alternate and recommended way to handle this is by enabling the Active Scene Synchronization property of each NetworkObject you want to automatically migrate into any newly assigned scene. This property defaults to disabled.
Refer to the NetworkSceneManager active scene synchronization page for more details.
Scene migration synchronization
Similar to NetworkObject.ActiveSceneSynchronization, this property automatically synchronizes client-side NetworkObject instances that are migrated to a scene via SceneManager.MoveGameObjectToScene on the host or server side. This can be useful if you have a specific scene you wish to migrate NetworkObject instances to that is not the currently active scene.
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.