Runtime Spawner

The Runtime Spawner component is the master ‘brain’ of the package. It handles the logic for the spawning and controls any number of Local Area Spawners that you would like to add into a scene.

Adding a Runtime Spawner

To add a Runtime Spawner into your scene, right click in the Scene hierarchy and choose ‘Runtime Spawner -> Runtime Spawner (Full Stack)’.

This will add a new GameObject into the scene configured with a Spawn Director and Special Encounter Manager.

Configuring the Runtime Spawner

The Runtime Spawner inspector only shows what features you are using at any given point in time. The default settings are shown below.

By default, the Runtime Spawner does nothing. You need to choose how you want to configure the spawning in your game.

The ‘Samples’ that ship with the Runtime Spawner provide a few example configurations of how you might use the Runtime Spawner in your own game.

These will be described in more detail in the ‘Installing Samples’ section below.

There are 8 sample scenes that showcase different configurations and use cases for how you can use the Runtime Spawner in your game. Check the Samples section for more details.

Basic Global Spawner
Local Area Spawner (Biome)
Wave Spawner
Combined Example
API Example
Directed Ambient Spawner
Special Encounters
Spawn Hints

Properties

There are a wide range of options available in the Runtime Spawner to configure the spawning in your game. Some are only shown if a parent selection is enabled. For example the ‘Global Spawners’ property is only visible if you enable the ‘Use Global Spawners?’ option. This allows us to keep the inspector clean and tidy.

Auto Launch on Start

Should object spawning start immediately when the game starts? In most cases you will want to check this box, however there is also a fully documented API that you can use to manually control the Runtime Spawner from script, should you choose to.

Note if Auto Launch on Start is false, you will need to call StartSpawners() yourself to start the spawning!

For example:

var spawner = FindObjectOfType<RuntimeSpawner>(); spawner.StartSpawners();

Note that you will need to reference the namespace for the Runtime Spawner to use the above code, like so:

using PixelWizards.Spawner;

Look at the RuntimeSpawnerControl script that is included in the Samples for an example of using this approach or check out the full Runtime Spawner API documentation for more information on the rest of the API included with the package!

The Player Object

This holds a reference to the Player game object in the scene. Simply drag your player into the field.

All spawning happens in a bubble around the player during gameplay. If left empty, the spawner will use the camera (as defined by the MainCamera tag) as the reference point. It is recommended to use the player instead however.

Note: If you spawn your player dynamically (or otherwise), you can also configure the Player Object at runtime using the SetPlayer() method.

For example:

var spawner = FindObjectOfType<RuntimeSpawner>(); spawner.SetPlayer(myGameObject); spawner.StartSpawners();

Note that you will need to reference the namespace for the Runtime Spawner to use the above code, like so:

using PixelWizards.Spawner;

Check out the full Runtime Spawner API documentation for more information on the rest of the API included with the package!

Player Tag

The Player Tag maps to one of the Tags that you have configured in your project.

Tags is optional, and can be used to tell your AI objects where the players are in the scene.

The default is ‘Player’

World Extents

This property defines the size of the spawn area in your world. It should ideally encompass the entire playable area of the world that you have built. You can visualize the extents by clicking the ‘Show’ button.

A Runtime Spawner with the ‘Show World Extents’ button enabled.

Minimum Spawn Range

Defines the minimum distance to the player that the Runtime Spawner should spawn AI objects. Objects will spawn at a distance between this range and the ‘Culling Range’ (if you are using Internal Culling), and as such, the Minimum Spawn Range should be a lower value than the Culling Range. Ideally your minimum spawn range will be far enough away from the Player so that they do not see the objects ‘Pop’ into view, but instead appear (and disappear) seamlessly as they players move through the level.

Note that if you are using the Wave Spawner and have Wave SpawnPoints that are outside of this range, they may inadvertently get culled if you are using the internal culling system provided by the Runtime Spawner.

The relationship between the Minimum Spawn Range and Culling Range are shown in the incredible artist rendering below. As such, the Minimum Spawn Range MUST be lower than the Culling Range.

Use Internal Culling

The Runtime Spawner will optionally cull any AI Objects that have been spawned when they get too far away from the Player.

Culling Range

Culling Check Frequency

Spawner Tag

Optional property - if you want to add a specific ‘Tag’ to your spawned AI objects, enter it here.

Max Global Population

This field controls the master population of this Runtime Spawner. It will override any specific population controls specified by any of the sub spawn systems (global, local or wave).

Use Global Spawners?

Check to enable Global Spawners. Global Spawners will spawn anywhere on the navmesh within the World Extents of this spawner. Enabling this will activate the Global Spawner section of the Runtime Spawner UI.

Create

When Use Global Spawners is enabled, you can ‘Create’ a new Spawn Entry scriptable object directly from the inspector.

Global Spawners

This defines the list of Spawn Entry AI Agents for this spawner. You can create a new Spawn Entry scriptable Object by clicking on the ‘+’ button, which will prompt you to save

Restrict to Navmesh Areas

Restricts the Global Spawner AI Agents to only spawn on specific Navmesh Areas within the map. Check the Unity Navmesh Area documentation for more information about Navmesh Areas and how to use them

Layer Mask

Only spawn AI Agents on a specific Layer within the scene.

For example, you may set up ‘Ground’ and ‘Building’ layers and only have the AI Agents spawn on the Ground layer.

Min Global Object Count

Max Global Object Count

These two properties define the number of AI Agents that you wish to spawn in the global context for this spawner. The Runtime Spawner will spawn a random number of agents between these two numbers.

Note: may be overridden by the ‘Max Global Population’ setting (see above).

Use Region Spawners (Biomes)?

Check to enable Region Spawners. Region Spawners will spawn anywhere on the navmesh within the World Extents of this spawner. Enabling this will activate the Region Spawner section of the Runtime Spawner UI.

Init

When Use Region Spawners is enabled, an ‘Init’ button will appear. Clicking this will search the Runtime Spawner child hierarchy for any Local Area Spawners that may be present and automatically add them to the Spawn Regions list. Note: only child objects of the parent Runtime Spawner will be searched.

Spawn Regions

This list defines the spawn regions that will be used by this spawner. You can click the ‘+’ button to add a new Spawn Region to the scene. The size of the trigger (the Box Collider) defines the spawn area.

See the Local Area Spawner section below for details on the parameters for Spawn Regions.

Show / Hide Spawn Region Volumes

This button will show / hide the Spawn Region gizmos in the scene view

Use Wave Spawners?

Check to enable Wave Spawners. Wave Spawners will spawn AI Agents as defined by the Wave Spawner configuration. Enabling this will activate the Wave Spawner section of the Runtime Spawner UI. Waves are spawned as defined by a ‘Wave Trigger’ component. You can add a new Wave Trigger by clicking the ‘+’ button on the Wave Triggers UI.

Wave Triggers

Waves are spawned as defined by a ‘Wave Trigger’ component. You can add a new Wave Trigger by clicking the ‘+’ button on the Wave Triggers UI, which will add a child Game Object with a Wave Trigger component attached.

Check the Wave Triggers section of the documentation for more information on the Wave Triggers and its properties.

Show / Hide Wave Triggers

This button will show / hide the Wave Trigger gizmos in the scene view

Log Entries to the Console

Enabling this will log information from the Runtime Spawner into the Unity Console.

Fundamentals

RuntimeSpawner is the main entry point for driving all spawn flows at runtime:

Global spawning (ambient population within world extents)
Region spawning (player-proximity regions via LocalAreaSpawner)
Wave spawning (encounter tables via WaveTrigger)

It also owns the object pool integration, culling loop, and global population caps.

Responsibilities

Maintain a global list of spawned objects (SpawnedObjects)
Enforce population caps across global, region, wave (and special) spawns
Drive background spawn loops and culling
Coordinate wave triggers and region activation
Provide a simple static Despawn(GameObject) API

Key Properties

These are the main properties that may be read or adjust at runtime:

General

static RuntimeSpawner Instance Singleton-style access to the active spawner in the scene.
bool IsInitialized True once Init() has successfully run.
List<GameObject> SpawnedObjects Live list of all active spawned instances.
Transform PlayerTransform The transform used for range checks and spawn context.

Feature toggles

bool UseGlobalSpawners
bool UseRegionSpawners
bool UseWaveSpawners
bool UseInternalCulling

Enable/disable each spawn flow or the internal culling loop.

Population & world

int MinGlobalObjectCount / int MaxGlobalObjectCount Global population window for the ambient/global spawn loop.
int MaxObjectCount Hard cap on total alive spawned objects (all flows combined).
float CullDistance Distance from player beyond which internal culling can despawn instances.
Vector2 WorldSizeVector2 / Vector3 WorldSizeVector3 World bounds used by global spawning and gizmos.

Misc

string PlayerTag Tag used for fallback player discovery if playerObject is not assigned.
bool UseSpawnHints / SpawnHintSettings HintSettings Enable and configure hint-driven spawn placement if you’re using the spawn hint system.

Lifecycle & Control Methods

These are the core methods your own systems can call to drive the spawner.

Initialization & startup

void Init()

Discovers regions and wave triggers.
Wires up services (pool, locator, executor, loops).
Resets all population counters.
Safe to call multiple times; re-scans regions and clears caches.

void StartSpawners()

Ensures Init() has run.
Creates object pools for all configured entries.
Starts enabled spawn loops:
- Global spawn loop (if UseGlobalSpawners == true)
- Region spawn loop (if UseRegionSpawners == true)
- Wave execution (on demand via triggers)
Starts deferred placement and culling helpers.
Starts optional collaborators (SpawnDirector, SpecialEncounterManager).

Use this when your gameplay session actually begins (e.g., after lobby load).

void StopSpawners(bool despawnAll = false, bool stopWaves = true)

Stops all spawn loops and background helpers.
Optionally:
- despawnAll: immediately despawns all spawned instances.
- stopWaves: cancels active wave sequences and disables triggers.
Does not destroy pools or reset initialization; you can StartSpawners() again to resume.

void PauseSpawners()
void ResumeSpawners()

PauseSpawners stops coroutines but keeps current population and internal state.
ResumeSpawners restarts the loops with the existing configuration.
Useful for pause menus, cutscenes, or loading transitions where you don’t want to clear the world.

Player & startup configuration

void SetPlayer(GameObject player)

Assign a specific player object for range checks and spawn context.

void SetStartAutomatically(bool value)

Controls whether Init() and StartSpawners() are automatically called from Start().

void SetGlobalSeed(int seed)
int GetGlobalSeed()
bool UseDeterminism

Sets/reads the global deterministic seed used by spawn flows.
Calling SetGlobalSeed automatically enables deterministic mode and raises onSeedChanged.

Runtime Tuning API

These methods allow you to adjust difficulty / pacing at runtime (e.g., via a director or game mode config). These are also used by the SpawnDirector and Region Population System.

void SetConcurrentAliveCap(int cap)

Sets MaxObjectCount – the hard cap on total alive spawned objects (all flows combined).

void SetGlobalSpawnWindow(int min, int max)

Adjusts the target window for global spawns. The global loop tries to maintain population between these bounds.

void SetSpawnRateMultiplier(float mult)

Scales the global spawn tick rate ( <1 = slower, >1 = faster).

void SetWaveRateMultiplier(float mult)

Scales timing between wave entries ( <1 = shorter intervals, >1 = longer).

These are intended to be driven by systems like SpawnDirector or your own difficulty manager.

Region & Wave Management

These are usually called by helper components (LocalAreaSpawner, WaveTrigger), but you can drive them manually if needed.

Local regions

bool RegisterRegion(LocalAreaSpawner region)
bool UnregisterRegion(LocalAreaSpawner region)

Register/unregister region spawners with the central RuntimeSpawner.
Regions send “player entered/left” notifications, which drive the region spawn loop.

Wave triggers

bool RegisterWaveTrigger(WaveTrigger trigger)
bool UnregisterWaveTrigger(WaveTrigger trigger)

Control which WaveTrigger components this spawner manages.

void ActivateWaveTrigger(WaveTrigger trigger)
void DeactivateWaveTrigger(WaveTrigger trigger)

Programmatically start or stop a wave sequence on a trigger, using the same flow as volume-based activation.

void NotifyWaveTriggerActivated(WaveTrigger trigger)

Instance-side helper that forwards a trigger activation to listeners without touching static events. Useful if you want a custom trigger component that still plugs into the standard wave events.

Despawning & Culling

void DespawnAllSpawned()

Returns all tracked spawned objects to the pool and updates population.

static void Despawn(GameObject go)

Convenience API: despawns a spawned object when you don’t know which RuntimeSpawner owns it.

Resolves the owning spawner via internal registry.
Prefers network-aware handles (Fusion, PUN, etc.) when available.
Falls back to pool/destruction for offline usage.

Internal culling uses the same path:

DoCulling() periodically checks distance to PlayerTransform.
Objects beyond CullDistance are despawned via OnObjectCulled → DespawnInternal.

Events

These static events expose useful hooks for UI, analytics, and game logic.

static event Action<int> onSeedChanged;

Raised whenever the global seed changes.

static event Action<GameObject> onObjectSpawned;
static event Action<GameObject> onObjectCulled;
static event Action<int> onUpdateCurrentPopulation;

onObjectSpawned: fired whenever any loop successfully spawns an instance.
onObjectCulled: fired whenever an object is culled or despawned.
onUpdateCurrentPopulation: fired whenever overall spawn population changes.

static event Action<float> onSpawnerInit;

Raised after Init(), providing the configured CullDistance.

static event Action<WaveEntry>   onNewWaveTriggered;
static event Action<WaveTrigger> onWaveTriggerActivated;
static event Action<WaveTrigger> onWaveSpawnerComplete;

onNewWaveTriggered: a wave entry is about to begin.
onWaveTriggerActivated: a wave trigger volume has been activated.
onWaveSpawnerComplete: a wave sequence finishes for that trigger.

static event Action<LocalAreaSpawner> onRegionRegistered;
static event Action<LocalAreaSpawner> onRegionUnregistered;

Region lifecycle notifications.

Typical Usage Patterns

Starting/stopping with a game session

public class GameSessionController : MonoBehaviour
{
    [SerializeField] private RuntimeSpawner spawner;

    void Start()
    {
        spawner.Init();
        spawner.SetGlobalSeed(Random.Range(int.MinValue, int.MaxValue));
        spawner.StartSpawners();
    }

    public void OnGameOver()
    {
        // Stop spawning and clear the world
        spawner.StopSpawners(despawnAll: true);
    }
}

Listening for spawned objects

public class SpawnCounterUI : MonoBehaviour
{
    void OnEnable()
    {
        RuntimeSpawner.onUpdateCurrentPopulation += HandlePopulationChanged;
    }

    void OnDisable()
    {
        RuntimeSpawner.onUpdateCurrentPopulation -= HandlePopulationChanged;
    }

    private void HandlePopulationChanged(int count)
    {
        // Update a UI label, difficulty, etc.
        // Example: populationText.text = $"Active: {count}";
    }
}

Triggering a wave from code

public class WaveButton : MonoBehaviour
{
    [SerializeField] private RuntimeSpawner spawner;
    [SerializeField] private WaveTrigger trigger;

    public void TriggerWave()
    {
        spawner.ActivateWaveTrigger(trigger);
    }
}

PreviousComponents NextLocal Area Spawner

Last updated 22 days ago