Getting Started

Your first working swarm chasing the player, in under 5 minutes.

Prerequisites

• A scene open in Unity with a player or target GameObject.
• Massive Swarm System imported into your project.

Scene View Overlay

When you open any scene after importing Massive Swarm System, a "Massive Swarm System" overlay appears in the Scene View. It is shown by default — you can hide or show it at any time via the Scene View overlays menu (the stacked-squares button in the top-right of the Scene View). See Create Overlay for the full reference.

The overlay groups every create action into three labeled cards:

• Core — Swarm Manager, Swarm Target
• Spawners — Rect Spawner, Ring Spawner
• Advanced — Spawner Director

These are the same actions as GameObject → Massive Swarm System and the Hierarchy right-click menu. Both surfaces call the same factory code, so the result is identical either way. The overlay is the only surface with branded icons — native Unity menus expose no icon API.

When an object is missing from the scene, a gold dot and highlight appear on the relevant button or group to prompt you. The Swarm Manager button highlights when no SwarmManager exists in the scene; the Swarm Target button highlights when no SwarmTarget exists; the Spawners group highlights when no spawner exists. These are guidance cues, not errors — the gold color is intentional.

The overlay groups every create action into three cards. Gold highlights appear on objects you still need to add.

Step 1 — Create the Swarm Manager

In the Hierarchy, right-click empty space → Massive Swarm System → Swarm Manager, or click Swarm Manager in the overlay's Core card.

This single click creates:

• A Swarm Manager GameObject with SwarmManager and SwarmVisualManager components.
• A sibling Swarm Agents GameObject (the parent for pooled agent visuals at runtime).
• Auto-assigns a default SwarmSettings asset to the manager.

Tip

Want level-specific tuning? Duplicate the default settings asset, drop it into the manager's Settings slot, and tweak per-scene. The same behavior and movement profiles can be shared across scenes.

Step 2 — Add a Target

The swarm chases anything with a SwarmTarget component. Pick whichever fits your scene:

• Use your existing player — select the player GameObject → in the Inspector, Add Component → SwarmTarget.
• Drop in a ready-made target — right-click in the Hierarchy → Massive Swarm System → Swarm Target, or click Swarm Target in the overlay's Core card. This creates a visible target with SwarmTarget already attached — the fastest way to see the swarm working before you have a player.

SwarmTarget registers with the SwarmManager automatically on enable. You can add as many targets as you like — the manager chases the closest few at once (its Max Active Target Count, 10 by default).

Step 3 — Add a Spawner

Right-click in Hierarchy → Massive Swarm System → Spawners → Rect Spawner (or Ring Spawner), or use the Spawners card in the overlay.

• Rect Spawner — spawns a rectangle of agents. Good for waves entering from a side.
• Ring Spawner — spawns a ring around a point. Good for ambushes or encirclement.

Position it where enemies should appear. The Scene view gizmo shows the spawn area.

In the spawner's Inspector:

• Spawn Profile → Agent Archetype — assign a SwarmAgentArchetype asset. The archetype defines the prefab, agent radius, and which behavior and movement profiles to use.
• Auto Spawn — turn this on, then set Auto Spawn Count (how many agents to spawn) and Auto Spawn Trigger (default On Start).

Don't have an archetype yet? Use the Archetype Wizard — it creates the archetype and all required profiles in one step from a built-in preset. Open it from Tools → Massive Swarm System → New Archetype…. See Swarm Agent Archetype for the full walkthrough.

A configured Rect Spawner: an archetype in the Spawn Profile and Auto Spawn on with a count set.

Step 4 — Press Play

The swarm spawns and approaches the player.

The default profile — Approach And Surround + Personal Space — produces a pursuing crowd that spreads around the target rather than collapsing to a point.

What each asset does

Four ScriptableObjects do all the configuration:

Asset	Role
SwarmSettings	Global sim params: capacity, grounding, LOD, body blocking. One per scene.
SwarmAgentArchetype	Visual prefab + agent radius + which behavior and movement profiles to use.
SwarmBehaviorProfile	Which steering behaviors are active (Approach, Surround, Personal Space…) and their weights.
SwarmMovementProfile	Max speed, acceleration, turn rate.

The included sample profile uses Approach And Surround + Personal Space as a starting point. You can swap behavior profiles per archetype without touching the manager.

Common first-run issues

Symptom	Fix
Agents fall through the ground	In the SwarmSettings asset, set Ground Layer Mask to include your floor's collider layer.
Agents clip into walls	In the SwarmSettings asset, set Obstacle Layer Mask to the layer your wall colliders are on.
No agents appear	Confirm the spawner has a Spawn Profile (archetype) assigned and Auto Spawn Count > 0. Confirm the archetype has a prefab assigned, or that the manager's SwarmVisualManager has a Fallback Agent Prefab.
Agents face the wrong direction	The prefab's visual mesh must face local +Z. Open the prefab and rotate the mesh to fix it.

See the Troubleshooting page for the full list.

See it running — MSS Pyramid Level

The fastest way to see what the system can do is to open the MSS Pyramid Level scene at Assets/MassiveSwarmSystem/Samples/FullDemo/Scenes/MSS Pyramid Level.unity and press Play.

It has multi-level Egyptian terrain, a player-controlled SwarmTarget, up to 1000 agents maintained continuously by a SwarmSpawnerDirector, and a baked Surface Flow Field handling stairs, obelisks, and ruins routing. Copy from it when starting a horde-survivor project.

See Sample Scenes for the full list of shipped scenes and what each demonstrates.

Next steps

• Read Concepts to understand how the manager, data, and visual layers divide responsibility before customizing.
• Browse Behaviors to pick the steering set that matches your game (survivor, melee pack, harasser, flanker).
• Visit Core Setup for the full reference on every component and ScriptableObject field.
• See Spawners when you need waves, attrition, or maintained populations instead of a single burst.
• Move to Animation and Performance if you are targeting mobile and need 1000+ agents at frame rate.