# Photon PUN 2+ Integration Guide

The **Runtime Spawner** package includes optional support for **Photon PUN 2+**, enabling fully networked spawning, pooling, and synchronization in cooperative or multiplayer games.

This guide explains how to connect the Runtime Spawner to Photon PUN 2+, using the included sample scene and bootstrap scripts.

***

### Requirements

| Requirement                   | Minimum Version / Note                       |
| ----------------------------- | -------------------------------------------- |
| **Unity**                     | 2022.3 or newer                              |
| **Photon PUN 2 or PUN 2+**    | Imported from the Asset Store                |
| **Megacrush Runtime Spawner** | v 1.5.0 or newer                             |
| **Megacrush Object Pool**     | Installed automatically with Runtime Spawner |

***

### 1. Import Samples

Runtime Spawner provides several sample scenes.\
To get started with PUN integration:

1. In **Package Manager → Runtime Spawner → Samples**, import:
   * **Runtime Spawner Sample**
   * **Runtime Spawner PUN Sample**
2. The PUN sample includes an example **PunBootstrap** script showing how to:
   * Connect to Photon
   * Register prefabs in the pool
   * Start the Runtime Spawner on the **Master Client**

Use this as a reference for your own network bootstrap logic.

***

### 2. Scene Setup

1. Create a new scene or open the **PUN Sample Scene**.
2. Add an **Empty GameObject** named `PunBootstrap`.
3. Attach **`PunBootstrap.cs`**\
   (`Assets/Samples/Runtime Spawner/1.5.0/Runtime Spawner PUN Sample/Code/Runtime/Bootstrap/PunBootstrap.cs`).

#### Inspector Fields

| Field                       | Description                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------- |
| **Spawner**                 | Optional reference to your `RuntimeSpawner` in-scene. Runs *only* on the Master Client. |
| **Player Prefab**           | Prefab with a `PhotonView` and optional controller script.                              |
| **PUN Prefabs to Register** | List of other prefabs used by the spawner (enemies, pickups, etc.).                     |
| **Prewarm Each**            | Number of pooled instances per prefab to create at startup.                             |
| **Player Spawn Point**      | Optional Transform for initial player placement.                                        |
| **VCam**                    | Optional Cinemachine Virtual Camera to follow the local player.                         |
| **UI Fields**               | TMP Input, Buttons, and Status Text for the sample UI.                                  |

***

### 3. Player Prefab Setup

Each networked prefab must have a **PhotonView**.

1. Add a `PhotonView` component.
2. *(Optional)* Add a `PUNPrefabKey` component and assign a unique ID string.
   * If no ID is set, the prefab name is used as its key.
3. Place the prefab anywhere under `Assets/Prefabs/` or another included folder - no need for `Resources`.

The Runtime Spawner’s PUN provider handles lookup and registration automatically.

***

### 4. Prefab Registration with the Provider

`PunBootstrap` registers all relevant prefabs at runtime:

* Registers the **Player Prefab** and all **Prefabs to Register**.
* Auto-registers prefabs referenced by `RuntimeSpawner`, `LocalAreaSpawner`, `WaveSpawner`, and `SpecialEncounterManager` via

  ```csharp
  PUNPrefabRegistrar.RegisterFromScene(_provider);
  ```

If you add new prefabs at runtime or after a scene change, refresh manually:

```csharp
_provider.Clear();
PUNPrefabRegistrar.RegisterFromScene(_provider, prewarmEach);
```

***

### 5. Running the Sample

1. Enter Play mode.
2. In the UI:
   * Type a Room Name (or use the default).
   * Click **Connect / Start**.

The bootstrap will:

1. Connect to Photon Cloud.
2. Join or create the room.
3. Register all prefabs in the pool.
4. Spawn the local player.
5. Start the Runtime Spawner on the Master Client.

You’ll see logs like:

```
[PunBootstrap] Joined room as Master
[PunBootstrap] Spawner started (Master Client)
```

***

### 6. Multiplayer Testing

To verify networked spawning:

1. Run one instance (Host) from the Editor.
2. Build and launch a second (Client) instance.
3. Both join the same room.
   * The first client is the **Master Client** and runs the Runtime Spawner.
   * Additional clients spawn their player objects via Photon instantiation.
4. When the Master Client leaves, Photon elects a new master;\
   the new master automatically restarts the spawner.

***

### 7. Common Pitfalls and Fixes

| Issue                           | Likely Cause                              | Fix                                                                                           |
| ------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Prefab not found**            | Not registered with provider              | Add prefab to *PUN Prefabs to Register* or reference it in scene spawner                      |
| **“Has no PhotonView” warning** | Prefab missing PhotonView                 | Add a PhotonView component; verify it gets a View ID at runtime                               |
| **Double spawners running**     | Bootstrap not restricted to Master Client | Keep `PunBootstrap.masterOnly = true`                                                         |
| **Missing pools**               | Object Pool package not imported          | Import **Megacrush Object Pool** from Package Manager                                         |
| **No spawn activity in room**   | Spawner never started on master           | Ensure `PunBootstrap` calls `spawner.Init()` and `spawner.StartSpawners()` after joining room |

***

### 8. Extending the Integration

For custom projects, you can:

* Replace `PunBootstrap` with your own connection manager.
* Use `PUNPoolPrefabProvider` directly and register prefabs manually.
* Integrate the registration and spawner start/stop calls into your existing Photon game flow.

Example snippet:

```csharp
if (PhotonNetwork.IsMasterClient)
{
    spawner.Init();
    spawner.StartSpawners();
}
```

***

### 9. Quick Checklist

* ✅ Player Prefab has a PhotonView (and optional `PUNPrefabKey`)
* ✅ All networked prefabs are registered in `PUNPoolPrefabProvider`
* ✅ `PunBootstrap` in scene with UI + Spawner wired up
* ✅ Megacrush Object Pool imported
* ✅ Press Play → Connect → Spawn → Master Client runs spawner

***

### 10. Integration Notes

* **Only the Master Client** runs the Runtime Spawner; other clients observe replicated objects.
* **Pooling** is handled via `PUNPoolPrefabProvider`, bridging Photon instantiation and the Runtime Spawner’s object pool.
* **Lifecycle control** (`Pause`, `Resume`, `End`) is automatically supported through the Spawner API, allowing safe room transitions or disconnects.
* Works alongside the **Fusion Integration** – choose either based on your network stack.

***

### ✅ You’re Ready to Go

Once your prefabs are registered and the `PunBootstrap` is configured,\
the Runtime Spawner handles all networked spawn and despawn activity through Photon PUN 2+, automatically synchronizing players, AI, and encounter systems across all clients.

> Use the included **PUN Sample Scene** as a template for your own multiplayer project.
