Photon PUN 2+ - Troubleshooting & Common Errors

This page covers the most common issues teams hit when integrating Runtime Spawner with Photon PUN 2+, along with how to diagnose and fix them.

If something “kind of works but feels wrong,” it’s almost always an authority, registration, or lifecycle issue.

---

Mental Model (Read First)

When debugging, always ask:

1. Who is the Master Client?

2. Is the RuntimeSpawner only running on the Master?

3. Are triggers detected locally but executed authoritatively?

4. Are prefabs registered before spawning?

Most bugs violate one of these rules.

---

1. “Nothing Spawns”

Symptoms

• Player spawns, but no AI appear

• WaveTriggers never start

• LocalAreaSpawner volumes do nothing

Likely Causes

A. RuntimeSpawner never started

spawner.Init();
spawner.StartSpawners();

Must be called only on the Master Client.

Check:

PhotonNetwork.IsMasterClient == true

---

B. Running spawner logic on clients If clients also call StartSpawners(), spawning logic can short-circuit or conflict.

Fix:

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

---

C. Prefabs not registered If a prefab was not registered with the PUN provider:

• Photon will fail silently or log warnings

• Runtime Spawner will skip the spawn

Fix:

• Ensure the prefab:

  • has a PhotonView

  • is registered via PUNPrefabRegistrar.RegisterFromScene(...)

  • or explicitly registered in your bootstrap

---

2. “Enemies Spawn Twice” / “Way Too Many Enemies”

Symptoms

• Duplicate AI

• Population explodes

• Waves appear to start twice

Likely Causes

A. Triggers executing on both client and master Triggers must:

• detect locally

• execute only on Master Client

Fix:

• Ensure PUNWaveTriggerDriver / PUNLocalAreaSpawnerDriver is present

• Do not call trigger methods directly from gameplay scripts

---

B. Multiple RuntimeSpawners active This can happen with:

• additive scenes

• duplicated prefabs

• bootstrap scene + gameplay scene both containing spawners

Fix:

• Ensure exactly one active RuntimeSpawner controls population

• Disable or remove extras

---

3. “WaveTrigger Fires Twice”

Symptoms

• Two waves start at once

• onWaveTriggerActivated fires multiple times

Likely Causes

A. Multiple activation paths For example:

• Auto-start enabled

• Manual activation also triggered

• Script calling ActivateWaveTrigger() redundantly

Fix:

• Use one activation path

• Check target.IsActivated before activating

---

B. Trigger reset timing If reactivateTrigger is enabled:

• Reset may occur sooner than expected

• Re-entry can cause reactivation

Fix:

• Increase reactivateTime

• Or disable reactivation for one-shot encounters

---

4. “Late Joiners Don’t Match the World State”

Symptoms

• New clients see:

  • enemies missing

  • regions inactive

  • triggers in wrong state

Likely Causes

A. LocalAreaSpawner state not cached By default, region inside/outside is transient.

Fix:

• Enable Cache State for Late Joiners on PUNLocalAreaSpawnerDriver

---

B. Wave already completed WaveTriggers do not rewind history.

Expected behavior:

• Late joiners see the current world

• Completed waves remain completed

If you need:

• replayable encounters

• stateful progression

→ manage this via your own game state layer.

---

5. “Triggers Work Offline but Not in Multiplayer”

Symptoms

• Everything works without PUN

• Breaks when connected to Photon

Likely Causes

A. Using Unity trigger logic directly Example (❌):

waveTrigger.IsActivated = true;

Fix:

• Always go through:

  • PUNWaveTriggerDriver

  • RuntimeSpawner.ActivateWaveTrigger(trigger)

---

B. Missing driver components Offline mode uses:

• Unity physics directly

Networked mode requires:

• PUN drivers to mediate authority

Fix:

• Ensure the correct driver is attached for PUN builds

---

6. “Master Client Leaves and Everything Breaks”

Symptoms

• No new enemies spawn

• Regions stop updating

• Game feels frozen after host leaves

Explanation

Photon elects a new Master Client, but:

• your bootstrap must handle this

• RuntimeSpawner must be restarted

Fix

Listen for:

public override void OnMasterClientSwitched(Player newMaster)

Then:

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

RuntimeSpawner is designed to be safely restarted.

---

7. Debugging Tools You Should Use

Inspector Runtime Snapshots

Both PUN drivers expose:

• IsMasterClient

• Inside state

• Target references

• Trigger IDs

Use these while the game is running.

---

Logging (Highly Recommended)

Enable logging temporarily:

• Enable Logging

• Set verbosity to Verbose

This will show:

• authority decisions

• rejected activators

• RPC flow

• state changes

Turn it off for production.

---

8. Quick Diagnostic Checklist

When something feels wrong, check:

• Is only one RuntimeSpawner active?

• Is the Master Client the only one starting it?

• Are triggers using PUN drivers?

• Are prefabs registered before spawning?

• Is the player collider correctly tagged & layered?

• Did the Master Client change mid-session?