NetworkPrefabHandler

Abstract base class that implements Unity Netcode's INetworkPrefabInstanceHandler to route network prefab instantiation and destruction through the Paragon factory system. Handles Netcode prefab handler registration, prefab instantiation with GlobalObjectIdHash override, and cleanup on destroy.

Definition

Namespace: Paragon.Core.Network Assembly: Paragon.dll

internal abstract class NetworkPrefabHandler : INetworkPrefabInstanceHandler

Implements: INetworkPrefabInstanceHandler (Unity.Netcode)

Remarks

NetworkPrefabHandler is the bridge between Unity Netcode's prefab spawning system and Paragon's factory pooling. When Netcode needs to instantiate or destroy a NetworkObject, it delegates to this handler instead of using Object.Instantiate / Object.Destroy.

Key Mechanics

1. Registration — The constructor calls NetworkManager.RegisterPrefabHandler() with the factory's GlobalObjectIdHash, telling Netcode to use this handler for all spawn/destroy operations for that prefab.

2. Hash Override — InstantiateNetworkPrefab() instantiates the prefab via Object.Instantiate() and then overrides the instance's GlobalObjectIdHash via reflection. This is necessary because pooled instances may have been created from a different prefab source, and Netcode requires the hash to match the expected prefab.

3. Cleanup — Destroy() calls NetworkManager.RemovePrefabHandler() to deregister the handler when the factory shuts down.

Reflection Usage

The GlobalObjectIdHash field on NetworkObject is private. This class accesses it via a static FieldInfo resolved once in the static constructor using BindingFlags.NonPublic | BindingFlags.Instance. This is necessary because Netcode does not expose a public API for overriding the hash on instantiated objects.

Quick Lookup

Goal	How
Instantiate prefab with correct hash	InstantiateNetworkPrefab() (protected)
Unregister from Netcode	Destroy()
Get the source prefab	Prefab property
Handle Netcode instantiation	Override OnInstantiateNetworkObject()
Handle Netcode destruction	Override OnDestroyNetworkObject()

Properties

Prefab

The source prefab GameObject from the NetworkPrefab configuration.

public GameObject Prefab { get; }

Constructor

NetworkPrefabHandler(INetworkScriptableFactory, NetworkPrefab)

Creates the handler and registers it with Netcode's prefab handler system.

protected NetworkPrefabHandler(INetworkScriptableFactory factory, NetworkPrefab networkPrefab)

Parameter	Type	Description
factory	INetworkScriptableFactory	The factory that owns this handler (provides GlobalObjectIdHash)
networkPrefab	NetworkPrefab	Netcode prefab configuration containing the source prefab reference

Side Effect: Calls NetworkManager.RegisterPrefabHandler(factory.GlobalObjectIdHash, this).

Methods

InstantiateNetworkPrefab (protected)

Instantiates the prefab and overrides the GlobalObjectIdHash on the resulting NetworkObject to match the factory's hash.

protected GameObject InstantiateNetworkPrefab()

Returns: A new GameObject instance with corrected GlobalObjectIdHash.

This method only performs Object.Instantiate() and hash override. It does not call NetworkObject.Spawn() — that is the responsibility of the caller or Netcode.

Destroy

Unregisters this handler from Netcode's prefab handler system.

public void Destroy()

Side Effect: Calls NetworkManager.RemovePrefabHandler(factory.GlobalObjectIdHash).

Extension Points

Required Overrides

Method	Return Type	Purpose
OnInstantiateNetworkObject(ulong, Vector3, Quaternion)	NetworkObject	Called by Netcode when a NetworkObject needs to be instantiated on a remote client. Must return a configured NetworkObject.
OnDestroyNetworkObject(NetworkObject)	void	Called by Netcode when a NetworkObject is being destroyed/despawned. Must handle returning the object to the pool.

Explicit Interface Implementation

The INetworkPrefabInstanceHandler.Instantiate() and INetworkPrefabInstanceHandler.Destroy() methods are implemented explicitly and delegate directly to the abstract methods above.

Common Pitfalls

GlobalObjectIdHash override via reflection The hash override uses reflection to write to a private field on NetworkObject. If Unity changes the field name or visibility in a future Netcode version, this will break silently. The ! null-forgiving operator on GetField() will produce a NullReferenceException at startup if the field is not found.

Registration happens in the constructor NetworkManager.RegisterPrefabHandler() is called during construction. If the NetworkManager is not ready at this point, registration will fail. Ensure the handler is created after NetworkManager initialization.

Destroy must be called for cleanup If Destroy() is not called before the factory shuts down, the Netcode prefab handler registration will remain, potentially causing errors on subsequent spawns. The factory implementation is responsible for calling Destroy() during its OnQuit() lifecycle.

See Also

• NetworkPrefabHandler<TObject> — generic handler with spawn queues

• NetworkPrefabHandler<TObject, TData> — variant-aware sealed handler

• INetworkScriptableFactory — factory interface providing GlobalObjectIdHash

• PrefabHandler Overview — subsystem overview