Animation

How Massive Swarm System animates agents, and how to pick the right approach for your target hardware.

Choosing an approach

Approach	Best for	Cost
VAT (Vertex Animation Texture)	Mobile, 1000+ agents	Very low
Animator + SwarmAgentAnimation	Richer character animation at lower counts	Medium–high (skinned mesh)
No animation component	Rigid-body enemies, simple shapes	Minimal

VAT Animation

VAT bakes skeletal animation into a texture. At runtime the agent mesh samples the texture to reconstruct vertex positions — no skeleton, no SkinnedMeshRenderer, no per-bone CPU work.

VAT agents use SwarmVatAnimation (added to the prefab), which SwarmVisualManager drives each frame. Each agent keeps its own MeshRenderer. Because the generated VAT material has GPU instancing enabled, Unity batches the identical draws automatically via the SRP Batcher. The VAT baker window is at Tools → Massive Swarm System → VAT Baker.

When to use VAT: targeting mobile, or when skinned mesh cost is visible in the profiler at your target agent count.

When not to use VAT: when you need real-time bone manipulation, IK, or procedural animation that cannot be pre-baked.

VAT bake workflow

1. Assign a source skinned mesh prefab and animation clips in the VAT baker window.
2. Click Bake VAT Prefab. The baker generates a .asset (VAT data), a .mat (VAT material), and a ready-to-use prefab.
3. Assign the generated prefab to the agent archetype.
4. At runtime, SwarmVisualManager updates each agent's SwarmVatAnimation, which writes that agent's clip and tint data into its MeshRenderer through a MaterialPropertyBlock. Because the VAT material has GPU instancing enabled, Unity batches the draws.

VAT Baker field reference

Open the baker at Tools → Massive Swarm System → VAT Baker. The window has a Simple / Advanced toggle and a Single Prefab / Batch toggle at the top.

Simple mode walks you through four numbered sections and hides advanced overrides. Advanced exposes clip loop flags, sample rate, and the normal-bake toggle. Use Simple for everyday bakes; switch to Advanced only when you need to override the preset's defaults.

Single Prefab bakes one source at a time. Batch bakes a list of prefabs that share the same clips, preset, and output folder — each prefab writes its own named VAT asset.

Section 1 — Source Prefabs

Field	What it does
Model Or Prefab	The prefab, model asset, or scene object that contains the source skinned renderer. Drag directly into the drop zone or use the object field.
Source Renderer	The body anchor: the SkinnedMeshRenderer whose material becomes slot 0. Auto-set to the highest-vertex skinned mesh. Other skinned meshes on the character bake in alongside it — see Multi-part characters.
Avatar	Avatar used by the temporary sampling Animator. Required for humanoid clips when the source has no Animator with an Avatar of its own.

Batch mode shows an additional Avatar field labeled Shared / Fallback Avatar. Prefabs in the batch that already carry their own Animator + Avatar use their own; the fallback only applies to prefabs without one (typically FBX models imported without a rig). Use Auto Fill to pick the first available avatar from the batch list.

Section 2 — Animation Clips

Field	What it does
Idle	Looping idle animation. Required for the agent to stand still.
Walk	Looping locomotion clip at walk speed.
Run	Looping locomotion clip at run speed.
Attack (Optional)	Optional one-shot attack clip. When baked, SwarmVatAnimation.TryPlayAttack() plays it at runtime. Leave empty if the archetype has no attack animation.

Use Auto Find Clips to scan the source asset, its Animator Controller, and the current selection for clips named like idle, walk, run, or attack.

In Advanced mode, a Loop toggle appears inline for each clip. Simple mode keeps all locomotion clips looping and the attack clip one-shot, matching the expected runtime behavior for most archetypes.

Attack clip loop flag

The attack clip defaults to non-looping (one-shot). Enable the loop toggle in Advanced mode only for channeled attacks — looping an attack clip with TryPlayAttack will cause the animation to repeat indefinitely until another clip interrupts it.

Advanced Bake Settings (Advanced mode only)

Field	What it does
Sample Rate	Frames sampled per second for each clip. Range 1–60. Lower values reduce texture size; higher values preserve fast motion. For clips used as slower-playback fallbacks (walk/run), the baker automatically raises the effective sample rate proportionally to maintain visual quality.
Bake Normals	Bake animated normals into a second texture for lit shading. Doubles the texture memory cost. Disable this on mobile to reduce GPU bandwidth.

In Simple mode these settings are driven by the selected Preset. Switch to Advanced only when you need to override them.

Section 3 — Output

Field	What it does
Output Folder	Asset-relative folder where the .asset, .mat, and prefab are saved. Use Pick Folder to browse or Use Default to reset to the package default.
Create VAT Material	Create a material wired to the baked VAT asset using the package VAT shader. Disable only if you have a custom material pipeline.
Create Ready Prefab (Simple mode)	Also output a prefab pre-wired to the baked asset and material. Disable to get raw VAT assets for a custom pipeline.
Update Linked Material (rebake only)	Refresh the existing linked material in place so renderers keep their material reference rather than pointing at a new file.

Section 4 — Ready to Bake (Simple mode)

This section shows the estimated GPU cost — total texture size and vertex count — from the baked vertex count (the body plus every included part), sample rate, and total clip duration. The status pill rates that cost against the selected preset's budget, not one fixed limit. Mobile holds a tight budget, the same one that keeps a 1000+ swarm affordable on a phone; Standard and High allow progressively larger bakes for desktop crowds and hero shots. Green means within budget, amber means heavy for the chosen tier, red means oversized for it. The same bake can read oversized on Mobile and green on High, so pick the preset that matches how the character will be used, then check the estimate.

Click Bake VAT Prefab (or Bake VAT if prefab output is disabled) to run the bake. The baker writes the generated assets to the output folder and shows a report in the section below.

Bake presets

The Bake Preset dropdown (collapsed by default in Simple mode) selects from three built-in presets. Each preset sets the sample rate, normal-bake flag, and the tier render shader together. Choose the preset that matches your target platform, then override individual settings in Advanced mode only if the preset is not quite right.

Preset	Description
Mobile	Cheapest tier for the big crowd. Skips the normal texture, so shading is flatter at distance — the right trade for 1000+ swarms and on-device builds.
Standard	Balanced default. Full surface detail (normal, metallic, occlusion) lit by the main light with soft shadows. Good for hundreds of agents on desktop.
High	Showcase tier. Adds dynamic point and spot lights plus reflection-probe blending on top of Standard — for hero shots and small counts.

See VAT Render Quality Tiers for a full breakdown of what each tier costs and when to switch.

Quickstart — typical bake steps

1. Select a preset that matches your target platform.
2. Assign the source prefab (drag into the drop zone).
3. Assign clips — use Auto Find Clips first.
4. Confirm the memory estimate looks reasonable for your target.
5. Click Bake VAT Prefab.

Multi-part characters

Most characters are more than one mesh. The body is often split across several SkinnedMeshRenderers — body, armor, skirt, shoulder pads — and weapons or cosmetics ride the bones as rigid MeshRenderers. The baker folds all of them into one VAT mesh, so the whole character animates from a single texture and renders in one draw, with no objects to sync at runtime.

Skinned parts. When the source has more than one SkinnedMeshRenderer, a Character Parts list appears under the Source section. The highest-vertex mesh is the body anchor (marked Body); every other skinned mesh is listed with an include toggle, on by default. Untick a part to leave it out, or press Use as body to make a different mesh the anchor. They share the source skeleton, so each part deforms with the animation exactly as it does in the original prefab.

Weapons and attachments. A rigid weapon, shield, or cosmetic that sits on (or under) one of the character's bones bakes the same way — it follows the bone for free. These appear in a separate Weapons & Attachments list. A mesh is eligible when it carries a MeshRenderer and MeshFilter and rides a bone of the body anchor. Both lists stay hidden when the character has none.

Materials and draw calls. The anchor's first material is slot 0. Every other distinct material across the baked parts gets its own slot, and parts sharing a material share a slot. The picker shows the cost live:

• A part that uses the same material as the body adds no draw calls.
• A part that needs its own material becomes one extra material slot: one extra draw call per agent. At a thousand agents that is a thousand extra draws, so share materials between parts where you can.

The rest is free. Every part shares the body's position and normal textures and the same per-agent material property block, so tint, damage flash, dissolve, and Importance-LOD changes reach them together with the body. Animated bounds grow to enclose them.

VAT visibility LOD

When Enable VAT Quality LOD is on in SwarmSettings, each agent's VAT shader quality follows camera frustum visibility, not its simulation importance tier. An on-screen agent renders at full quality no matter how far it is from its target. An off-screen agent renders at cheap quality: frame interpolation is disabled and all shaders snap to the dominant walk/run clip. For the normal-texture: Standard and High keep the per-vertex baked normal off screen so agents stay correctly shaded when they return to view; Mobile drops the normal tap off screen to save GPU bandwidth. The per-pixel normal-map detail (surface Normal Map texture) is not visibility-gated — it is always on or off based on the material keyword, regardless of LOD state.

See VAT Render Quality Tiers for the full breakdown.

Animator-Based Animation (SwarmAgentAnimation)

For agents that need Animator blend trees, transition logic, or per-parameter animation control, add SwarmAgentAnimation to the prefab. It writes speed float parameters to the Animator based on the agent's simulated velocity.

SwarmAgentAnimation is visibility-aware: when the agent's renderer has been off screen past the grace period, it skips Animator.SetFloat calls entirely. This reduces the cost of Animator parameter updates for off-screen agents — no blend-tree evaluation is triggered for values that nobody will see.

Key fields:

Field	What it does
Forward Speed Float	Animator float that receives forward/backward speed. Leave empty to disable.
Strafe Speed Float	Animator float that receives left/right speed. Leave empty to disable.
Use Planar Speed When Strafe Parameter Missing	When no strafe float is configured, writes total planar speed into Forward Speed so 1D blend trees still animate while agents sidestep.
Apply Animator Culling Mode	When on, sets the Animator's culling mode to the value below each time an agent is spawned.
Animator Culling Mode	The culling mode applied to the Animator on spawn. Cull Completely stops Animator evaluation entirely when the agent is off screen, which is the cheapest option for large crowds.
Update Only When Visible	Skips parameter writes when the agent's renderer is off screen.
Visibility Grace Time	Keeps updating briefly after leaving the camera view to prevent pop at the screen edge.

Culling mode: by default, SwarmAgentAnimation applies AnimatorCullingMode.CullCompletely to every spawned agent. This is the cheapest culling mode — the Animator stops evaluating entirely when off screen. Change Animator Culling Mode in the component if you need a different mode.

Camera-keyed animation refresh

SwarmVisualManager keys animation refresh cadence on the camera, not the simulation importance tier. An on-screen agent close to the camera refreshes every visual sync for smooth animation. An on-screen agent farther than Distant Visible Distance from the camera refreshes on the Distant Visible Animation Refresh stride. An off-screen agent refreshes on the Off-Screen Animation Refresh stride — off-screen agents are not drawn, so the stride only controls how current their pose is when they return to view.

Higher stride values reduce Animator.SetFloat calls (for SwarmAgentAnimation agents) and MaterialPropertyBlock writes (for VAT agents). These settings live under Visibility LOD in SwarmSettings.

SwarmVisualManager

SwarmVisualManager owns the agent visual layer. It maintains a pool of visual GameObjects per prefab and updates them every frame from simulation state. Every frame it reads from SwarmManager and updates transforms, Animator parameters, and VAT playback data — visuals follow the simulation, never the other way around.

SwarmManager creates and wires SwarmVisualManager automatically when you add a manager via GameObject → Massive Swarm System → Swarm Manager (or the Scene View overlay). You only need to add or configure it by hand when building a custom setup.

Inspector fields

Field	What it controls
Manager	The SwarmManager that owns the simulation data. Auto-assigned when both components share a GameObject.
Fallback Agent Prefab	Prefab used when a spawn request or archetype supplies no prefab. Assign the built-in MSS Default Agent here for quick testing before your own art is ready.
Agent Root	Parent transform for pooled agent instances. Defaults to this GameObject when left empty.
Initial Pool Size	Per-prefab warm-up count. Pre-allocates this many instances when the first agent of that prefab spawns to reduce spawn spikes. This is not the simulation cap — total live agents are bounded by SwarmSettings → Max Agents, and pools grow past this value on demand.

Mobile prefab checklist

Apply these before releasing on mobile

• Use VAT animation instead of SkinnedMeshRenderer + Animator.
• Use a single material per agent (no multi-material mesh).
• Keep the mesh low-poly.
• Disable shadow casting on the agent renderer.
• Set Animator Culling Mode to Cull Completely if using SwarmAgentAnimation.