# Photon Fusion Integration Guide

<details>

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

The Runtime Spawner Fusion integration allows you to use **Runtime Spawner’s encounter, wave, and region systems inside a Photon Fusion session**, while respecting Fusion’s authoritative networking model.

In a Fusion-powered game:

* **One authoritative peer** (Host / Server / StateAuthority) decides *what spawns and when*
* **All other peers** automatically observe the results through Fusion’s replication

Runtime Spawner fits into this model by:

* Running all spawn logic on the authoritative peer
* Spawning networked prefabs via Fusion
* Allowing clients to remain passive observers of spawned content

This makes Runtime Spawner suitable for:

* Cooperative PvE games
* Horde / wave-based encounters
* Open-world population systems
* Networked AI, NPCs, and ambient actors

</details>

<details>

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

Runtime Spawner is designed **offline-first**.

Core components such as:

* `WaveTrigger`
* `LocalAreaSpawner`

are authored as **pure gameplay components** that work in single-player without networking.

When running inside Fusion:

* These components switch to **External activation mode**
* Dedicated **Fusion driver components** take responsibility for:
  * detecting trigger events on the correct peer
  * replicating state changes
  * calling the spawner’s public APIs in a network-safe way

This keeps your gameplay logic:

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

</details>

<details>

<summary>What Runtime Spawner does not replace</summary>

Runtime Spawner does **not** replace Fusion’s networking systems.

Fusion still owns:

* object replication
* authority rules
* network transforms
* snapshot synchronization
* interest management

Runtime Spawner simply decides:

* *when* something should spawn
* *what* should spawn
* *where* it should spawn

Fusion decides:

* *how* that object is synchronized across the network

</details>

<details>

<summary>Authority model</summary>

In Fusion terms:

* **Only the authoritative peer runs spawn logic**
  * Host / Server
  * or StateAuthority owner (Shared mode)
* Clients:
  * do not run spawn loops
  * do not activate wave logic
  * do not decide region state
  * only observe results

Runtime Spawner enforces this through:

* explicit authority checks
* driver-level execution targets
* replication-only RPC flows

This avoids:

* duplicate spawns
* race conditions
* desync between peers

</details>

<details>

<summary>Pooling integration (optional, recommended)</summary>

Runtime Spawner can run with **any existing Fusion object provider**.

If your project already uses:

* Fusion’s default provider
* a custom `INetworkObjectProvider`

you can keep it.

However, Runtime Spawner also provides **optional Fusion pool providers** that tightly integrate spawning, despawning, and prewarming with the spawner’s internal pool system.

You can choose between:

* a **core provider** passed into `StartGameArgs.ObjectProvider`
* a **behaviour-based provider** attached to the `NetworkRunner`

Using these providers is:

* **optional**
* **recommended** for consistent lifecycle behavior across spawner-spawned objects

The integration pages explain when and how to use them.

</details>

<details>

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

Runtime Spawner supports networked trigger-driven gameplay via **driver components**:

* **Wave triggers**
  * scripted encounters
  * horde events
  * defense arenas
* **Local area spawners**
  * biome-based population
  * density-based spawning
  * region-aware systems

In Fusion:

* trigger detection runs only on the allowed authority
* inside / activate / reset state is replicated
* public APIs are called on the authoritative instance only

Each trigger type has its own Fusion driver with:

* inspector-driven configuration
* execution target controls
* detailed runtime debug snapshots

These drivers are documented on the corresponding component pages.

</details>

<details>

<summary>Typical project flow</summary>

At a high level, a Fusion + Runtime Spawner project looks like this:

1. Fusion session starts (`NetworkRunner`)
2. Players connect and spawn
3. Authoritative peer initializes Runtime Spawner
4. Runtime Spawner begins:
   * wave systems
   * region population
   * encounter logic
5. Spawned networked objects replicate automatically to all peers

Clients never need to “know” about the spawner — they simply receive synchronized results.

</details>

### Documentation structure

From here, the Fusion documentation is split into focused pages:

* **Setup & Configuration**
  * project wiring
  * asmdefs and CodeGen
  * bootstrap patterns
  * optional pooling providers
* **Scene Setup & Usage**
  * where to place spawners and triggers
  * how to start spawner logic safely
  * common runtime patterns
* **Troubleshooting & Errors**
  * common Fusion integration issues
  * authority mistakes
  * CodeGen problems
  * trigger misconfiguration

Detailed driver behavior lives with the components they control:

* [WaveTrigger ](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference)→ [FusionWaveTriggerDriver](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)→ [FusionLocalAreaSpawnerDriver](https://megacrush.gitbook.io/megacrush-unity-assets/runtime-spawner/runtime-spawner-user-manual/networking-integrations/broken-reference)

***

### When to use this integration

Use Runtime Spawner with Fusion when you want:

* authoritative, deterministic spawning
* scalable PvE content
* reusable single-player + multiplayer gameplay logic
* minimal custom networking code around encounters

If you’re already comfortable with Fusion’s networking model, Runtime Spawner plugs into it cleanly without forcing a specific architecture.