Network Instantiation & Spawning

1. Overview

HoloMIT provides a robust system for instantiating GameObjects across the network. While typical Unity Instantiate only creates objects locally, the NetworkSpawner ensures that an object created by one user is replicated on all other connected clients with perfectly synchronized identities (NetworkId).

---

2. NetworkSpawner

The NetworkSpawner is the core component responsible for managing networked instantiation. It acts as a factory that knows how to map local prefabs to network messages.

2.1. Inspector Reference

Figure 1: The NetworkSpawner component showing a list of spawnable prefabs.

• Spawnable Prefabs (List<GameObject>): A list of all objects that this spawner is allowed to create over the network. The index of the prefab in this list is used as the identifier in network messages.

2.2. The Spawning Flow (Step-by-Step)

1. Initiation: A client calls NetworkSpawner.Spawn(index, position, rotation).
2. Local Creation: The spawner instantiates the prefab locally.
3. Identity Collection: The spawner finds all NetworkIdBehaviour components within the new object's hierarchy and collects their NetworkId GUIDs.
4. Broadcasting: A NetworkSpawnData message is sent to all clients containing:
   • The Spawner's ID.
   • The Prefab Index.
   • The list of Network IDs for the hierarchy.
   • Position and Rotation.
5. Remote Replication: Other clients receive the message, instantiate the same prefab (using the index), and manually call SetNetworkId() on each component to match the initiator's IDs.

---

3. Player Instantiation

Player spawning is a specialized case of networked instantiation, often managed by higher-level controllers (like SessionPlayerManager), but relying on the same principles.

3.1. Initialization Logic

When a player avatar is spawned:

• The Initiator (the player joining) sets their own instance to SetIsLocalPlayer(true).
• The Remote Clients receive the spawn event and keep the instance as remote.
• The PlayerId (from the Session System) is assigned to the NetworkPlayer component to link the network messages to the correct avatar.

---

4. Public API

• public GameObject Spawn(int prefabIndex, Vector3 position, Quaternion rotation): Instantiates a prefab by index and broadcasts the event. Returns the local GameObject.

---

5. Setup Guidelines

To set up a networked spawnable object:

1. Create a Prefab and ensure it has a NetworkIdBehaviour at its root.
2. If the prefab has child objects that also need individual networking (e.g., a car with 4 networked wheels), add NetworkIdBehaviour to those children as well.
3. Add the Prefab to the Spawnable Prefabs list of a NetworkSpawner in your scene.
4. IMPORTANT: The Spawnable Prefabs list MUST be identical across all clients. If Client A has "UserAvatar" at index 0 and Client B has "Car" at index 0, spawning index 0 will cause a mismatch.

---

6. Common Pitfalls

• Prefab Mismatch: If the list of prefabs in the inspector is different between clients, the wrong object will be spawned.
• Hierarchy Complexity: The system relies on GetComponentsInChildren<NetworkIdBehaviour>() returning objects in the same order on all clients. Avoid changing the hierarchy order at runtime before the spawn is fully synchronized.
• Master Client Forwarding: In the current architecture, the Master Client acts as a relay for some events. Ensure the Master is always active during critical spawning phases.