Skip to content

FAQ

Common questions about buying, integrating, and customizing Massive Swarm System.

Can't find it here?

The Troubleshooting page covers first-run symptoms and their fixes. This page focuses on questions — not symptoms.

Before you buy

Does it require DOTS, ECS, or Burst?

No. The simulation is plain C# running in a single SwarmManager component. There are no references to com.unity.burst, com.unity.collections, or any ECS package in the runtime assembly, so it drops into a standard Unity project without any additional packages.

One nuance, since "plain C#" can read as "nothing is ever threaded": the optional Batched and Batched Deferred grounding modes gather ground casts into a SpherecastCommand buffer and let Unity run them on worker threads. That uses NativeArray and JobHandle from UnityEngine's own core modules, not the Jobs or Collections packages, so it adds no dependency. Grounding ships on Immediate, so nothing is threaded until you opt in.

Does it use Unity's NavMesh? Do I have to bake one?

No NavMesh and no NavMeshAgent. Agents route using behavior steering, obstacle physics queries, and — optionally — the built-in Surface Flow Field. The Surface Flow Field is off by default. When you enable it, it bakes its own grid at Play time (or via Bake Now on SwarmManager). No NavMesh bake needed.

See Navigation for when to enable it and how to set it up.

Which render pipelines does it support?

URP. The simulation core is render-pipeline-agnostic, but every visual that ships in the package is not: the VAT shaders (SwarmVatStandard, SwarmVatMobile, SwarmVatHigh) declare "RenderPipeline"="UniversalPipeline" in their SubShaders, and the sample and default agent materials are URP materials.

Open the package under the Built-in Render Pipeline or HDRP and agents render magenta. The editor warns you about this on import. Switching to the Animator plus SwarmAgentAnimation path does not fix it, because that path only drives an Animator and changes nothing about materials. What does fix it is supplying your own materials for the pipeline you are on. The simulation itself runs correctly either way, and agents move as they should behind the magenta.

Which Unity versions are supported?

Unity 2022.3 LTS and Unity 6 LTS.

How many agents can I realistically run?

The short answer: the bottleneck is almost always rendering, not the simulation.

On a test device at 1000 agents, the simulation cost approximately 10 ms on its own. Swapping a SkinnedMeshRenderer agent for a simple capsule on that same device raised frame rate from around 16 fps to around 60 fps. Your actual ceiling depends heavily on your agent prefab.

See Performance for how to measure your specific case, and the Troubleshooting mobile section for the fix-priority list.

Does it run on mobile?

Yes, with the right prefab setup. Use a VAT agent (the Mobile or Standard shader tier), a single material per mesh, a low-poly mesh, and shadow casting off. The simulation itself is not the bottleneck on mobile — the agent prefab is.

See Performance — Mobile for the ordered fix list and Animation for the VAT bake workflow.

Can I use my own character models?

Yes. Any prefab works as an agent — assign it to a SwarmAgentArchetype and the swarm uses it. For high counts, the VAT Baker (Tools → Massive Swarm System → VAT Baker) converts a skinned character into a VAT prefab so the crowd renders without skeleton overhead.

See Animation — VAT bake workflow for the step-by-step.

Does it include health, damage, or combat logic?

The core simulation has no health system. What it does provide:

  • Per-agent attack state (tracking which agents are in range and firing).
  • IDamageable and IDamageableWithContext interfaces in the runtime assembly that the swarm calls when a melee hit lands.

Implement IDamageableWithContext on anything you want the swarm to be able to hurt. The manager caches one damageable per target slot and always calls the context overload, so a script that implements only IDamageable registers fine as a target and then never takes a point of contact damage. IDamageable is still the right minimum for your own weapons hitting the swarm; it is the swarm-hits-you direction that needs the context version. Subclassing the ready-made sample components gets you there without thinking about it.

The swarm does not manage your player's HP or death — that stays in your own code.

See Combat Integration for the full contract reference.

Does it require the new Input System package?

The core runtime does not. There is a separate optional assembly, MassiveSwarmSystem.InputSystem, that wraps the new Input System for the player-movement helpers in the sample scenes. It compiles only when com.unity.inputsystem is present and declares a versionDefines constraint on that package, so it has no effect on a project that doesn't have it.

Can the swarm chase multiple targets?

Yes. SwarmTarget components register automatically with SwarmManager on enable, and registration is unbounded — you can have as many targets as you like in the scene. Each simulation tick, the manager selects the closest Max Active Target Count registered targets (default 10, configurable on SwarmManager) and routes agents toward them. Agents use per-agent hysteresis when switching between targets to avoid constant thrashing.

Is full C# source included?

Yes. There are no precompiled DLLs in the package — everything ships as C# source.

Integration and customization

Can I add my own steering behaviors?

Not by subclassing a base class or dropping in a component — the steering pipeline is a set of static methods in SwarmBehaviorRuntime that SwarmManager calls in a fixed sequence. Adding a new behavior today means editing that file and wiring the call into the step loop. The SwarmBehaviorProfile ScriptableObject controls which built-in behaviors are active and their weights.

If custom behaviors are important for your project, budget time for that code change before buying.

How do I read or drive agent data at runtime?

SwarmManager exposes stable handles for spawning and despawning:

  • TrySpawnAgent(...) — several overloads. Each returns bool, false when the swarm is at capacity, and hands back the handle through an out SwarmAgentHandle parameter. Two of the overloads skip the handle entirely for fire-and-forget spawns.
  • DespawnAgent(handle) — removes an agent immediately.
  • TryGetAgentPosition(handle, out Vector3) — reads the simulation position by handle.

For bulk reads, use ReadAgentPositions — it reads without copying the internal arrays. There is no way to reach SwarmAgentData from your own code and that is deliberate: the class and the manager's property that exposes it are both internal, and internals are shared only with the editor assembly and the tests. Even the shipped samples go through the public handle-keyed getters and bulk readers, which is how those stay honest.

See the SwarmManager reference for the full API list.

Why doesn't it use Jobs or Burst — wouldn't that be faster?

The simulation was measured. Threading the core sim loop through Burst saved less than 1.5 ms at typical agent counts — modest compared to the effort involved and the compatibility risk across Unity versions. The real cost at high counts is the visual sync: moving hundreds of GameObjects each frame. That is where future optimization work is targeted.

The one place work already runs off the main thread is optional grounding: see the batching note under Does it require DOTS, ECS, or Burst? above.

Is the simulation deterministic?

No guarantee. The simulation runs on a fixed timestep in FixedUpdate, which is repeatable frame to frame, but body blocking physics queries depend on Unity's physics engine and spatial hash order, both of which can vary with collider ordering and frame timing. Do not rely on replay-exact determinism.

Can obstacles move at runtime?

Yes for blocking, no for routing. Each agent runs its obstacle physics query every other fixed step by default (Obstacle Blocking Query Interval, default 2), so agents collide with and are pushed around moving colliders on the obstacle layer without any extra setup. Set the interval to 1 if a fast-moving hazard slips past on the off step. An agent that body blocking just relocated is re-queried the same step regardless.

The Surface Flow Field is a baked grid and does not follow moving geometry. Physics sampling happens once, when you press Bake Now or when the field initializes at Play time. Which cells are walkable is fixed from that moment. Surface Flow Runtime Rebake (on by default) recomputes the route to a target as that target moves, but it works from the map that was already baked and never re-scans colliders, so moving an obstacle does not change the routes. Re-bake to pick up the new layout.

In practice: put moving hazards and physics props on the obstacle layer and let blocking handle them, and keep the baked field for the static level. For fully dynamic environments, body blocking and obstacle blocking handle containment on their own, though routing around complex geometry is limited.

Does it work for multiplayer?

There is no built-in networking. The simulation is fully local and manager-driven — positions live in flat arrays on SwarmManager, not in networked objects. You can synchronize swarm state over the network by driving SwarmManager on the authoritative peer and broadcasting positions, but the system does not provide that infrastructure. It is not designed as a networked simulation out of the box.

Can I make flying or non-grounded agents?

Yes. Grounding is a setting, not a requirement. Turn off Enable Grounding on SwarmSettings — and, if you use the Surface Flow Field, set Surface Flow Grounding Mode to Disabled too, since it grounds agents on its own — and agents move at whatever Y position they were spawned at, driven by steering alone. There is no gravity — they stay at that height unless you push them externally. For agents that should track terrain height while airborne, leave grounding on and tune Ground Layer Mask to the surface you want them to follow; a visual offset in the prefab makes them float above it.

Still have questions?