Swarm Pressure Recycler¶

Overview¶

SwarmPressureRecycler moves distant agents that have drifted behind the player back in front of them. It relocates the lowest-value candidates — those far away and off screen — into the forward arc before the player notices they were gone. Use it in endless or horde-style games where the swarm must feel infinite but your agent pool is fixed.

Recycling vs. spawning

A spawner creates agents from the pool and consumes capacity. The recycler moves agents that already exist — no allocation, no despawn cost in the default mode. Pair it with a SwarmSpawnerDirector in Maintain Population mode to keep the pool full, then let the recycler handle the spatial redistribution.

Parameter Reference¶

Setup¶

Player¶

Visible effect — All zone rings and the reinjection arc are centered on this transform. Nothing works without it.
Gameplay effect — Every recycling decision is relative to the player's position and travel direction.
Technical effect — Read every tick to compute per-agent distances, candidate scores, and the forward placement direction.

Visibility Camera¶

Visible effect — Controls which agents are considered "on screen" and therefore protected from recycling.
Gameplay effect — Agents visible to this camera are never recycled, preventing visible teleportation.
Technical effect — When left empty, the recycler falls back to the scene's MainCamera tag or the first active camera at runtime. Assign explicitly when your project has multiple cameras.

Zones¶

Three concentric rings around the player define the recycling policy for every agent. Select the component in the Scene view to preview the rings.

Combat Radius¶

Visible effect — Agents inside this ring are never touched, no matter how long they have been off screen.
Gameplay effect — Guarantees close-range enemies stay engaged. Shrink this when you want the recycler to reach in closer; expand it for a wider "hands-off" combat bubble.
Increase when — Enemies cluster tightly and you want a larger safe zone around the player.
Decrease when — The swarm feels too sparse near the player because the protected zone is too wide.
Pitfalls — Front Distance Min is clamped to at least this value. If Combat Radius is large, the reinjection arc is pushed outward automatically — reinjected agents may appear further than you expect.
Technical effect — Agents within this distance reset their offscreen timer and are excluded from the candidate list entirely.

Support Radius¶

Visible effect — Agents between Combat Radius and Support Radius are considered locally relevant and are usually left alone.
Gameplay effect — Creates a buffer zone of nearby enemies that are not yet close enough to fight but are still adding positional pressure.
Increase when — You want a wider buffer before the recycler starts pulling agents.
Decrease when — Agents are being left too far away for too long before recycling begins.
Technical effect — Agents inside this ring have their offscreen timer reset to zero and are excluded from candidates. Candidate score uses InverseLerp(supportRadius, recycleRadius, distance) as its base — agents just outside this ring score low, agents at and beyond Recycle Radius score higher.

Recycle Radius¶

Visible effect — Agents beyond this distance become strong recycle candidates, scoring above 1.0 in the priority ranking.
Gameplay effect — Sets the outer boundary of the meaningful swarm. Agents beyond this are cleanly expendable.
Increase when — The game world is large and agents naturally spread far before you want them recycled.
Decrease when — Agents are loitering at medium range and not getting recycled soon enough.
Technical effect — Agents beyond this radius receive an additional flat score bonus of 1.0 on top of their distance-based score, making them higher priority than any agent still between Support and Recycle Radius.

Candidate Rules¶

Require Offscreen¶

Visible effect — When on, agents are only recycled if they are outside the camera view. When off, any agent past the support zone can be recycled regardless of visibility.
Gameplay effect — Keeping this on prevents the player from watching enemies vanish. Turning it off is only appropriate for top-down games with tight camera crops where distant agents are always off screen anyway.
Pitfalls — Disabling this on a third-person game with a wide FOV causes visible agent pop — enemies disappear in plain sight.
Technical effect — When enabled, candidates must also pass the IsOffscreen viewport check and have accumulated at least Offscreen Grace Time seconds before they qualify.

Offscreen Grace Time¶

Visible effect — Agents that just left the screen edge are held in place for this many seconds before they become recyclable.
Gameplay effect — Prevents agents from being teleported the instant they scroll off screen, which would feel wrong if the player pans back quickly.
Increase when — Players frequently pan the camera and see enemies reappear too quickly.
Decrease when — Agents accumulate behind the player too long before being recycled.
Technical effect — Each agent accumulates offscreen time per tick. Time resets to zero if the agent re-enters screen or moves inside Support Radius. Only active when Require Offscreen is enabled.

Behind Score Bonus¶

Visible effect — Agents directly behind the player's travel direction are prioritized for recycling ahead of agents at the same distance on the sides.
Gameplay effect — The tail of the swarm clears out first, which feels natural and prevents a growing mob pile-up behind the player.
Increase when — The swarm feels like it's piling up behind the player faster than the recycler clears it.
Decrease when — You want lateral and rear agents to be treated equally.
Technical effect — Added to the candidate's distance-based score when the dot product of the player's travel direction and the agent's relative position is negative (agent is behind).

Keep Behind Quota¶

Visible effect — A fraction of the active swarm is always preserved behind the player, never recycled even if they score highly.
Gameplay effect — Prevents the recycler from completely emptying the rear. Keeps the surround feel intact so the player never has a clean escape direction.
Increase when — The swarm stops feeling like a surround because all rear agents get recycled to the front.
Decrease when — Too many agents are pinned behind the player and the front pressure is too thin.
Pitfalls — Setting this to 1.0 disables all recycling of rear agents. Setting it to 0 means the recycler will clear the tail entirely if scores are high enough.
Technical effect — Computes Ceil(activeCount * quota) as a minimum rear-agent count. Rear candidates are skipped once the rear count falls to or below this minimum.

Recycle Budget¶

Recycle Mode¶

Visible effect — No visual difference in most setups.
Gameplay effect — Determines how agent state is handled when relocating.
Increase when — N/A (enum).
Decrease when — N/A (enum).
Technical effect — Relocate In Place teleports the agent to the new position directly via manager.RelocateAgent — cheapest and simplest. Despawn And Respawn calls DespawnAgent then TrySpawnAgent with the same spawn state, going through the full pool lifecycle. Use Despawn And Respawn only if your archetype setup requires a clean respawn event (e.g. to reset per-agent state); Relocate In Place is the correct default.

Tick Interval¶

Visible effect — Controls how frequently the recycler evaluates and moves agents.
Gameplay effect — Lower values recycle more responsively; higher values reduce CPU cost.
Increase when — You have many agents and the recycler's candidate scan is measurable in a profiler capture.
Decrease when — Agents are accumulating in the rear faster than the recycler can clear them.
Technical effect — The recycler runs in Update. Candidate collection and scoring only execute when the accumulated timer exceeds this interval.

Max Recycle Per Tick¶

Visible effect — How many agents jump to the front on each evaluation tick.
Gameplay effect — A low value smooths out the relocation across many frames; a high value clears the tail faster but may produce a brief visible cluster of agents appearing at once.
Increase when — The recycler can't keep up with agents escaping beyond the recycle radius.
Decrease when — Multiple agents appearing near-simultaneously in the reinjection arc is noticeable.
Technical effect — Iteration stops once this many agents have been successfully relocated or respawned on the current tick. Candidates that fail placement (no off-screen slot found) do not count toward the budget.

Front Reinjection¶

Use Player Movement Direction¶

Visible effect — When on, the reinjection arc tracks the direction the player is actually moving. When off, it follows the player transform's forward axis.
Gameplay effect — Movement-direction tracking keeps the arc aimed where the player is going, which is almost always the right choice in top-down survivors and run-and-gun games.
Pitfalls — In games where the player character faces the cursor (decoupled movement and facing), disable this and drive the arc from player forward instead if forward-facing is more meaningful.
Technical effect — When enabled, the recycler computes the XZ delta of the player's position each frame and updates a smoothed direction only when the delta magnitude is non-negligible. The last known non-zero direction is held when the player is stationary.

Front Distance Min¶

Visible effect — The inner edge of the yellow reinjection arc in the Scene view.
Gameplay effect — Sets how close to the player reinjected agents can appear. Keep this outside the Combat Radius so recycled agents do not teleport into the middle of a fight.
Increase when — Reinjected agents are appearing too close and immediately engaging before the player has a moment to react.
Decrease when — The reinjection arc is placed so far ahead that enemies appear after the player has already passed that area.
Technical effect — Clamped to at least Combat Radius by OnValidate. Placement attempts that land closer than Combat Radius to the player are rejected and retried.

Front Distance Max¶

Visible effect — The outer edge of the yellow reinjection arc in the Scene view.
Gameplay effect — Defines how far ahead agents can be dropped. A wider min–max band produces more natural clustering variation; a narrow band places all agents at nearly the same range.
Increase when — Reinjected agents all appear at the same distance and feel artificial.
Decrease when — Agents are being placed too far ahead to serve as immediate pressure.
Technical effect — Clamped to at least Front Distance Min by OnValidate. Each placement attempt draws a random distance uniformly in [FrontDistanceMin, FrontDistanceMax].

Front Arc Angle¶

Visible effect — The angular width of the yellow sector in the Scene view. At 180° it covers the full hemisphere ahead; at 1° it is a narrow cone.
Gameplay effect — Wider arcs spread reinjected agents across the full front; narrower arcs stack pressure in a tighter column directly ahead.
Increase when — All reinjected agents appear in the same spot and the forward cluster feels unrealistic.
Decrease when — Agents are appearing to the sides and not building forward pressure.
Technical effect — Each placement attempt draws a random angle uniformly within ±(FrontArcAngle / 2) from the reinjection forward direction, then rotates the placement vector by that angle.

Offscreen Viewport Padding¶

Visible effect — Extends the "visible" region outward before the off-screen check triggers. A value of 0.08 means a placement up to 8% of the viewport width outside the screen edge still counts as "on screen" and is rejected.
Gameplay effect — Prevents reinjected agents from appearing just off screen and immediately walking into view. Increase this if agents seem to pop in at the very edge of the frame.
Pitfalls — Very high values push the reinjection zone so far off screen that placement can fail repeatedly, consuming all Max Placement Attempts per tick.
Technical effect — Expands the viewport test range to [-padding, 1+padding] in both X and Y. Only active when Require Offscreen is enabled.

Max Placement Attempts¶

Visible effect — No visible effect on success; on failure the recycler skips that candidate for this tick.
Gameplay effect — A higher value makes placement more persistent when off-screen constraints are tight (small Offscreen Viewport Padding, narrow arc). Too low and the recycler frequently gives up and under-performs.
Increase when — The recycler is consistently failing to place its full Max Recycle Per Tick budget, especially in scenes with a wide camera FOV.
Decrease when — Profiling shows the placement loop is a meaningful cost (unlikely at default values).
Technical effect — For each candidate, up to this many random arc positions are tested. If none pass the off-screen and combat-radius checks, that candidate is skipped for this tick.

Scene Gizmos¶

Select the SwarmPressureRecycler component in the Scene view to see the following overlays drawn around the Player transform:

Color	Shape	Meaning
Green	Wire disc	Combat zone — agents inside are never recycled
Blue	Wire disc	Support zone — agents inside have their timers reset and are excluded from candidates
Orange	Wire disc	Recycle zone — agents beyond this ring score highest and are recycled first
Yellow (filled sector)	Solid arc	Reinjection area — the arc-shaped region where recycled agents are placed
Yellow (wire arcs + lines)	Wire arc	Inner and outer distance bounds of the reinjection arc
Cyan	Arrow line + cone	Reinjection forward direction — in edit mode this is the Player's transform forward; at runtime it tracks actual movement direction when Use Player Movement Direction is on

The gizmos preview at design time using the Player's transform forward. The label on the cyan arrow reads "Preview Forward (movement at runtime)" when Use Player Movement Direction is on, and "Preview Forward" when it is off.

Practical Usage Guidance¶

When to use it. The recycler is built for games where the swarm must feel limitless but a fixed agent budget applies: endless wave games, bullet-heaven survivors, zombie hordes. Pair it with a SwarmSpawnerDirector in Maintain Population mode — the director tops up the pool when agents die, and the recycler keeps the spatial distribution front-loaded.

When not to use it. Skip the recycler for finite encounters where the enemy count is narrative (a boss room with 12 specific enemies) or games with a small agent count where every unit is meaningful. The recycler is a density tool, not a narrative one.

Typical setup.

Add SwarmPressureRecycler to the same GameObject as SwarmManager (or any active GameObject).
Assign the Player transform.
Leave Visibility Camera empty — it auto-resolves MainCamera.
Leave Recycle Mode at Relocate In Place unless you need a respawn event.
Tune the three zone radii to match your game's engagement distances.
Adjust Front Distance Min/Max so reinjection lands just outside the player's combat bubble.

Combining with the Spawner Director. The recycler works naturally with Maintain Population mode. When the director uses Use Max Alive, it counts agents regardless of position; the recycler handles spatial distribution. When agents die, the director replenishes them.

Adjusting surround feel. If all enemies appear in front and the surround feel is lost, raise Keep Behind Quota toward 0.3–0.4. If rear pile-up is a problem, lower it toward 0 and increase Behind Score Bonus so rear agents drain faster while a minimum number stay.

Disable Require Offscreen only in top-down or tight-camera games

With Require Offscreen off, agents can teleport while visible. This is undetectable when the camera crop is tight enough that distant agents are never in frame. In third-person or wide-FOV games, always leave Require Offscreen on.

Gameplay Interpretation¶

Tuning direction	Player-visible result
Wider Combat Radius	Larger "safe bubble" — enemies never vanish close to the player
Wider reinjection arc (Front Arc Angle)	Fresh enemies arrive spread across the front, feeling like a new wave
Narrower reinjection arc	Forward pressure feels more focused, like enemies are homing in
Higher Keep Behind Quota	The player always has enemies in every direction; no clean escape
Lower Keep Behind Quota	Clearing the screen feels possible; forward enemies dominate
Higher Max Recycle Per Tick + lower Tick Interval	Fast-responding swarm that snaps to new player positions quickly
Lower Max Recycle Per Tick + higher Tick Interval	Smoother, more gradual redistribution with less CPU cost

Quickstart — tune in this order

Set Combat Radius, Support Radius, and Recycle Radius to match your game's engagement distances. Use the Scene gizmos to check the rings look right relative to your arena.
Set Front Distance Min and Front Distance Max so the reinjection arc sits just outside the combat bubble.
Adjust Front Arc Angle — wider for a broad wave feel, narrower for focused pressure.
Set Keep Behind Quota to preserve enough rear pressure (start around 0.2).
If agents pop in at the screen edge, raise Offscreen Viewport Padding slightly.
Profile at your target agent count and raise Tick Interval if the recycler is measurable.