# Photon PUN 2+ Integration Guide

<details>

<summary>What this integration is for</summary>

The Runtime Spawner package includes **optional support for Photon PUN 2+**, allowing Runtime Spawner–driven encounters, regions, and population systems to operate correctly inside a PUN multiplayer session.

In a PUN-based game:

* **One peer (the Master Client)** is responsible for authoritative decisions
* **All other peers** receive replicated results via Photon instantiation and events

Runtime Spawner integrates into this model by:

* Running all spawn logic **only on the Master Client**
* Using Photon instantiation for networked objects
* Synchronizing trigger and region state across all peers

This makes Runtime Spawner suitable for:

* Cooperative PvE games
* Horde and wave-based encounters
* Networked AI population systems
* Host-authoritative gameplay without a dedicated server

</details>

<details>

<summary>Offline-first, network-aware design</summary>

Runtime Spawner’s core components (such as `WaveTrigger` and `LocalAreaSpawner`) are authored to work **without networking**.

When used with Photon PUN:

* These components are placed into **External / Driven mode**
* Dedicated **PUN driver components** handle:
  * trigger detection
  * master-client authority
  * event replication
  * late-join synchronization

This keeps gameplay logic:

* clean
* testable offline
* reusable across single-player and multiplayer projects

</details>

<details>

<summary>Authority model (PUN)</summary>

In PUN terms:

* **Only the Master Client runs the Runtime Spawner**
* Clients:
  * never run spawn loops
  * never activate waves
  * never control region state
  * only observe replicated results

Runtime Spawner enforces this by:

* routing all trigger logic through the Master Client
* using Photon events / RPCs for replication
* optionally caching state for late joiners

If the Master Client disconnects:

* Photon automatically elects a new Master
* The new Master can safely restart the spawner

</details>

<details>

<summary>Pooling integration</summary>

Runtime Spawner includes a **PUN pooling bridge** that connects:

* Photon instantiation
* Runtime Spawner’s object pool
* prefab registration and lookup

This allows:

* network-safe reuse of pooled objects
* deterministic despawn behavior
* clean lifecycle handling across clients

Pooling is handled via:

* `PUNPoolPrefabProvider`
* optional `PUNPrefabKey` components for stable prefab IDs

You do **not** need to place prefabs in `Resources/`.

</details>

<details>

<summary>Trigger-driven gameplay in PUN</summary>

Runtime Spawner supports networked triggers via **PUN driver components**:

* **WaveTrigger**
  * scripted encounters
  * horde events
  * repeatable arenas
* **LocalAreaSpawner**
  * region-based population
  * biome-aware density
  * late-join safe region state

In PUN:

* trigger detection runs only on the Master Client
* inside / activate / reset state is broadcast to all peers
* spawning only ever happens on the Master Client

Each trigger type has its own PUN driver with:

* inspector-driven configuration
* optional late-join caching
* runtime debug snapshots

Detailed behavior is documented on the component-specific pages.

</details>

<details>

<summary>Typical project flow</summary>

A Runtime Spawner + PUN project usually follows this flow:

1. Photon connects to the cloud
2. A room is joined or created
3. A Master Client is elected
4. Player prefabs are spawned
5. The Master Client initializes Runtime Spawner
6. Runtime Spawner begins:
   * wave encounters
   * region population
   * AI spawning
7. Clients observe replicated results

Clients never interact directly with the spawner.

</details>

### Documentation structure

This Photon PUN Runtime Spawner documentation is split into focused pages:

* [**Setup & Configuration**](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/photon-pun-2+-integration-guide/photon-pun-2+-setup-and-configuration)
  * importing samples
  * prefab registration
  * bootstrap patterns
  * pooling provider setup
* [**Scene Setup & Usage**](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/photon-pun-2+-integration-guide/photon-pun-2+-scene-setup-and-usage)
  * where to place spawners and triggers
  * how to structure scenes
  * master-client startup patterns
* [**Troubleshooting & Common Errors**](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/photon-pun-2+-integration-guide/photon-pun-2+-troubleshooting-and-common-errors)
  * missing prefab registration
  * master-client authority mistakes
  * late-join desync issues
  * common Photon pitfalls

Trigger-specific behavior lives with the components themselves:

* [WaveTrigger](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference) -> [Wave Trigger PUN Driver](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference)
* [LocalAreaSpawner](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference) -> [Local Area Spawner PUN Driver](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference)

***

### When to use PUN vs Fusion

Use the PUN integration when:

* your project already uses Photon PUN
* you want host-authoritative gameplay without Fusion
* you’re comfortable with Master Client semantics
* you don’t need deterministic rollback or tick-based simulation

***

### Next steps

From here, continue with:

* [**PUN Setup & Configuration**](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/photon-pun-2+-integration-guide/photon-pun-2+-setup-and-configuration)
* [**PUN Scene Setup & Usage**](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/photon-pun-2+-integration-guide/photon-pun-2+-scene-setup-and-usage)
* [**PUN Troubleshooting**](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/photon-pun-2+-integration-guide/photon-pun-2+-troubleshooting-and-common-errors)

Or jump directly to:

* [WaveTrigger](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference) -> [Wave Trigger PUN Driver](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference)
* [LocalAreaSpawner](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference) -> [Local Area Spawner PUN Driver](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference)