Skip to content

Targets

Add the SwarmTarget component to any GameObject you want the swarm to chase. It registers with SwarmManager automatically on OnEnable and unregisters on OnDisable.

Quick create

To drop a ready-made target into the scene, use GameObject → Massive Swarm System → Swarm Target (or right-click in the Hierarchy). This instantiates the Default Swarm Target Prefab set in Project Settings and guarantees a SwarmTarget component on it. For an existing player GameObject, add the component directly instead.

The bundled default target also includes a simple movement controller. In Play Mode, move it with WASD or the left stick on a connected gamepad. It works with Legacy Input, the Unity Input System, or both, so you can test a swarm before replacing it with your own player controller.

Body Radius

SwarmTarget owns the per-target body radius used by Approach & Press (inner ring), Target Crowd Blocking, Target Body Blocking, and attack reach checks.

  • Body Radius Source — Auto Detect (default) or Manual. Auto Detect measures every non-trigger collider on the GameObject, plus a CharacterController if one is on the same GameObject, and uses the largest planar radius among them. Supported types: SphereCollider (radius × planar scale), CapsuleCollider (radius × planar scale), BoxCollider (inscribed — the smaller of the X and Z half-extents), MeshCollider (the smaller of the X and Z world-space bounds extents), and CharacterController (radius × planar scale, read from this GameObject only). When Include Child Colliders is on (default), child colliders are also measured — the CharacterController is never read from children. Skinned mesh renderers do not contribute — add a Capsule or Box collider sized to the body.
  • Manual Body Radius — explicit value in world units used when source is Manual.
  • Detected Radius — read-only readout of the resolved value. A warning appears when Auto Detect found no collider source.

The body-radius gizmo (cyan wire sphere) draws on the selected target so you can see what the swarm will use.

Priority and Selection Radius

Two optional knobs bias which target the swarm goes for, instead of leaving it down to distance alone.

  • Priority — how strongly the swarm prefers this target. 1 is normal. Higher values pull more agents: at 2 the target ranks as if it sat at half its real distance, so the horde favors it over closer targets still on 1. Small values (1.2–2) give a nudge; larger ones (5+) give a hard pull, the kind you want on a boss or a level objective. Priority feeds both the active-set ranking and each agent's own choice. You can change it from script at runtime, so a lure flare can ramp its Priority up to drag the swarm off the player, then drop it back to release them.
  • Selection Radius — how close an agent must be, in world units, before it will pick this target. 0 (the default) means unlimited reach: any agent in the active set can choose it. Above 0, only agents inside the radius peel off toward it while the rest keep going for whatever they preferred. Use it for an exposed unit that should draw the agents right next to it without yanking the whole horde over. An agent already chasing the target lets go once it drifts back outside the radius.

The two combine the way the names suggest. An objective on Priority 4 holds the bulk of the swarm, while a crew member on Priority 1 with Selection Radius 4 still grabs the few agents who wander within 4 units of it. Leaving both at their defaults (Priority 1, Selection Radius 0) keeps selection exactly as distance-only, so adding the component changes nothing until you reach for these.

Setting them from code

Registering a target through script instead of the component? SwarmManager.RegisterTarget(transform, priority, selectionRadius) takes the same two hints. When a SwarmTarget component is present it stays authoritative, so its inspector values win over the arguments.

Behavior

  • Any number of SwarmTarget objects can be registered at once. Agents only react to the closest Max Active Target Count of them at any moment — extras stay registered as fallbacks and become active automatically when they move closer to the swarm than a current active target. See Max Active Target Count on SwarmManager.
  • Agents use hysteresis when deciding to switch targets, so crossing movements between close targets do not cause thrashing.
  • Remove or disable a SwarmTarget component and agents reassign to remaining active targets automatically.
  • Velocity prediction for moving targets lives in the Predictive Catch-Up behavior, set per behavior profile (see Predictive Catch-Up). The manager records each active target's velocity; the behavior controls how far ahead agents lead it.

Adding the movement controller to your own target

The bundled default target prefab includes a DefaultTargetMoveController component for testing. If you want to add it to your own target GameObject:

  1. Select your target GameObject in the Hierarchy.
  2. In the Inspector, click Add Component.
  3. Navigate to Massive Swarm System → Input → Default Target Move Controller, or search for "Default Target Move Controller".

This is a getting-started helper. Replace it with your own player controller once the swarm is working. Real input controllers should implement IMoveInputSource rather than copying the DefaultTargetMoveController pattern.

Common patterns

Pattern How
Single player target One SwarmTarget on the player GameObject. Default behavior.
Multiple players (co-op) One SwarmTarget per player. Agents pick the closest by hysteresis.
Decoy / distraction Spawn a temporary GameObject with SwarmTarget, give it a high Priority to pull the swarm in, then disable it to release agents back to the player.
Boss + minions as targets One SwarmTarget per object the swarm should consider. Raise Priority on the boss so the swarm favors it over the minions.
Protect an exposed unit Give the unit a small Selection Radius so only nearby agents break off toward it, while the rest hold on the main objective.