Skip to content

Swarm Spawner Director

Attach a SwarmSpawnerDirector to any GameObject (typically the Swarm Manager or a dedicated "Encounter" object) and assign one or more shape spawners.

Modes

Mode picks the encounter pattern:

  • One Shot — spawn the Initial Batch once and stop. Re-trigger from script if you want another wave.
  • Continuous — keep spawning at Spawn Rate. Optionally cap concurrent agents with Max Alive.
  • Maintain Population — top up to Max Alive at startup, then replenish whenever an owned agent despawns (gameplay damage or manual DespawnAgent). A recycler in DespawnAndRespawn mode also triggers replenishment; the default RelocateInPlace mode does not — it reuses the agent in place, which is itself the replenishment.
  • Finite Encounter — spawn at Spawn Rate until Total Spawned reaches the limit, then stop.

Auto Start is a top-level toggle. When off, no mode runs until a script calls SwarmSpawnerDirector.Trigger() (or you use the context menu Trigger action).

Key fields

Field What it does
Spawners Shape spawners this director will drive.
Mode Encounter pattern. See above.
Auto Start Begin spawning automatically on Start. Off = manual Trigger().
Composition Weighted archetype list. Empty falls back to each spawner's own Spawn Profile.
Initial Batch Spawn count fired immediately on Start (when Auto Start is on) or on Trigger().
Spawn Rate Base over-time rate, in agents per second. Used by Continuous, Maintain Population, and Finite Encounter.
Max Spawn Per Frame Hard cap on whole spawns emitted in a single frame. If a frame hitch causes the accumulator to build up more than this, the excess is dropped, not queued — there is no catch-up burst on the next frame.
Use Max Alive / Max Alive Concurrent agent cap owned by this director. Maintain Population requires this. When the difficulty ramp is on, Max Alive acts as the hard ceiling the ramp grows toward.
Use Total Spawned Limit / Total Spawned Limit Lifetime spawn budget owned by this director. Finite Encounter requires this.
Increase Difficulty Over Time Optional ramp that increases spawn pressure over time. Exposes three additional fields: see Difficulty Ramp below. Off by default.

Weighted composition

Each composition entry has Enabled / Archetype / Weight. The director picks an archetype for each spawn using cumulative weight: an entry with weight 2 is picked twice as often as one with weight 1. Disabled entries, entries with no archetype, or entries with weight ≤ 0 are skipped. The inspector shows the resulting percentage next to each entry.

Difficulty Ramp

Enable Increase Difficulty Over Time to have the director automatically intensify pressure as the encounter runs. Four fields work together:

Field What it does
Increase Difficulty Over Time Master toggle. Off = static Spawn Rate and Max Alive for the whole encounter.
Initial Max Alive The concurrent cap the encounter starts with. Must be less than or equal to Max Alive.
Max Alive Increase Per Second How many concurrent slots to add each second. The value grows continuously — fractional slots accumulate correctly.
Spawn Rate Increase Per Second How many agents per second to add to the base Spawn Rate each second. Stacks on top of Spawn Rate, it does not replace it.

How the formulas work:

At any moment during the encounter, the effective values are:

  • Effective Max Alive = Initial Max Alive + (elapsed seconds × Max Alive Increase Per Second), floored and clamped to Max Alive.
  • Effective Spawn Rate = Spawn Rate + (elapsed seconds × Spawn Rate Increase Per Second).

Max Alive is the hard ceiling. Once the ramp reaches it, the cap stops climbing even if the encounter continues.

Worked example — survivors-style horde over two minutes:

A calm opening that builds to peak pressure around the two-minute mark:

  • Spawn Rate: 4 agents/sec (opening trickle)
  • Max Alive: 200 (peak capacity you want at full pressure)
  • Increase Difficulty Over Time: on
  • Initial Max Alive: 30 (small crowd at the start)
  • Max Alive Increase Per Second: 0.9 (reaches 200 after ~189 seconds ≈ 3 min, so pressure keeps climbing through the two-minute window)
  • Spawn Rate Increase Per Second: 0.05 (adds 1 agent/sec every 20 seconds — at 2 min the rate is ~10/sec)

After 60 seconds: ~84 concurrent cap, ~7 agents/sec. After 120 seconds: ~138 concurrent cap, ~10 agents/sec — no scripted wave triggers required.

Ramp tuning order

  1. Set Max Alive to the ceiling you want at peak pressure.
  2. Set Initial Max Alive to roughly 15–25% of Max Alive for a noticeable opening calm.
  3. Decide how many seconds until full pressure, then set Max Alive Increase Per Second to (Max Alive − Initial Max Alive) ÷ target seconds.
  4. Adjust Spawn Rate Increase Per Second last — small values (0.02–0.1) go a long way over a long encounter.

Three common recipes

One Shot crowd — drop a fixed encounter and stop.

  • Mode: One Shot
  • Initial Batch: e.g. 40
  • Auto Start: on (or call Trigger() from your gameplay script)
  • Composition: pick the mix you want, or leave empty to use the spawner's Spawn Profile.

Maintain Population pressure — keep a steady crowd around the player.

  • Mode: Maintain Population
  • Initial Batch: a small kickstart, e.g. 20
  • Spawn Rate: e.g. 8 agents/sec
  • Max Alive: target population, e.g. 160
  • Composition: weighted mix for variety.

Finite Encounter budget — a wave with a fixed total spend.

  • Mode: Finite Encounter
  • Initial Batch: opening burst, e.g. 24
  • Spawn Rate: e.g. 6 agents/sec
  • Total Spawned Limit: full wave size, e.g. 200
  • Optional: turn on Use Max Alive to spread the budget over time instead of dumping it.

Escalating horde — pressure that builds automatically without scripted wave triggers.

  • Mode: Continuous (or Maintain Population for a self-replenishing horde)
  • Spawn Rate: e.g. 4 agents/sec (opening trickle)
  • Max Alive: e.g. 200 (peak cap)
  • Increase Difficulty Over Time: on
  • Initial Max Alive: e.g. 30
  • Max Alive Increase Per Second + Spawn Rate Increase Per Second: tune using the guidance in Difficulty Ramp.

The Runtime Status section of the inspector reports source-owned alive count, total spawned, current rate, and the latest blocker once you enter Play mode.