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 to 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. The generated VAT material has GPU instancing enabled and the per-agent state travels in the instancing buffer, so Unity batches the identical draws automatically. 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. A looping attack clip started with TryPlayAttack repeats forever and locomotion cannot take over, because the attack has no end time to pass. Call StopAttack() to end it. Returning the agent to the pool also clears it.

Advanced Bake Settings (Advanced mode only)

Field	What it does
Sample Rate	Frames sampled per second for each clip. Range 1 to 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 go back to Assets/MSS/VAT. Baked output lands outside the package on purpose, so updating Massive Swarm System never touches it.
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 and amber covers both heavy and oversized for the chosen tier. Red is reserved for a bake the GPU cannot store at all, when the vertex count or frame count exceeds the platform's maximum texture size. 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. That is 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 their shadows on top of Standard. For hero shots and small counts. Reflection probes already work on Standard, so that is not what you are buying here.

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.

After the bake: the SwarmVatAsset inspector

The baker writes a SwarmVatAsset, and selecting it gives you a working panel rather than a dump of serialized data. This is where you go weeks later when you need to know what a bake actually contains, or when the source character has changed.

Stale State is the one to look at first. The asset records what it was baked from, and this box compares that against the project as it is now. Up to date says so plainly; if the source prefab, its clips, or its attachments have moved on since the bake, it turns into a warning that names what changed. It is the difference between "the animation looks wrong" and "the animation is from last Tuesday".

Clip Table lists every baked clip with its role, name, frame range, length in seconds, and whether it loops or plays once. Use it to confirm the baker assigned idle, walk, run and attack to the clips you meant.

Role Playback Multipliers are four editable speed multipliers, one per role. They exist for incomplete bakes. If a character has no walk clip, the baker falls back to the run clip at a 0.5 multiplier so it still reads as walking rather than sprinting on the spot. When any multiplier is not 1, the panel says so, which is your cue that a role is being faked. Tune them to make the substitution look deliberate.

Bake Provenance records completeness, the UTC bake timestamp, the baker version, a summary of the bake settings, and the tracked clips and attachments. Linked Outputs points at the source, material and prefab, each with a Ping button to find it in the Project window.

Actions carries the three buttons that do work:

• Open Baker loads this asset's settings back into the VAT Baker window.
• Rebake In Place re-runs the bake with the recorded settings and overwrites the asset, keeping its GUID. Prefabs, materials and scene references all survive, which is what makes it safe to re-bake a character mid-project.
• Create Or Update VAT Prefab builds the ready-to-use agent prefab from this asset, or refreshes the existing one.

Re-baking many assets at once

A SwarmVatBatch is a saved list of VAT assets, so you do not have to hunt them down one at a time when the character rig changes or you upgrade the package. Create one with right-click → Create → Massive Swarm System → Visuals → VAT Batch and drop your assets into the list. Each row shows its own status, so an asset that cannot be rebaked says so before you press anything.

Two buttons, and the difference matters:

• Rebake All re-runs every asset with the settings each one already recorded, after a confirmation dialog. Asset references stay stable. Assets without complete provenance are skipped rather than guessed at, and the button counts how many will actually run.
• Open Baker With This Batch opens the VAT Baker in batch mode with every row linked to its existing asset. Use this one when you want to change a shared setting first, like sample rate, shader or normals, and then rebake the lot.

It has one other field: Fallback Avatar. Rebaking needs an Animator and an Avatar, and FBX models imported without a rig have neither. Assign a fallback here and those assets borrow it. Assets that already carry their own Animator and Avatar keep using theirs and ignore this field. If any asset in the list needs one, the inspector warns you and offers Auto Fill, which picks an avatar from the rigged prefabs already in the batch.

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 is available under the Source section. In Advanced mode it is always shown. In Simple mode, open Show advanced source details to reach it, since that foldout starts closed. 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, since 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.

• 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 Weapons & Attachments picker prints this running cost as you toggle parts. The Character Parts list does not, so if your character has extra skinned meshes and no bone-parented rigid meshes, read the Extra Draw Calls row in the Advanced mode Memory Estimate card instead.

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 VAT quality LOD changes reach them together with the body. Animated bounds grow to enclose them.

SwarmVatAnimation field reference

The component the baker's prefab ships with. Most of it can be left alone, but two fields decide whether your agents look like they are walking or moonwalking, so read the Locomotion group at least once.

References

Field	What it controls
Renderer	The renderer showing the VAT mesh. Left empty, it takes the first child renderer
Mesh Filter	Optional. Used to assign the VAT mesh on spawn
VAT Asset	The baked asset holding the idle, walk, run and optional attack clips
Shared Vat Material	Optional material override applied on spawn. It has to use the package VAT shader. Use it to share one material across prefabs that were baked separately

Visibility

Field	What it controls
Update Only When Visible	On by default. Skips playback writes while the renderer is off camera
Visibility Grace Time	Seconds of continued updating after the renderer leaves the screen, default 0.15, so agents at the frame edge do not pop

Timing

Field	What it controls
Use Unscaled Time	Off by default, so Time.timeScale drives playback and a slow motion or hit stop effect reaches the animation, the way it would an Animator. Turn it on to keep agents animating at full speed while the game is paused

Flip it from code with the UseUnscaledTime property rather than by writing the serialized field, since the property re-anchors the playback clock. Switching directly leaves the agent's timestamps on the clock it just left.

Locomotion

Field	What it controls
Walk Match Speed	The planar speed at which the walk clip is a perfect match. Default 1.25
Run Match Speed	The planar speed at which the run clip is a perfect match. Default 3.5
Idle Speed Threshold	Below this speed a moving agent blends back to idle. Default 0.05
Idle Exit Speed Threshold	Above this speed an idle agent blends into locomotion. Default 0.1. Keep it above the threshold above or agents flicker between the two near zero
Idle Blend Duration	Crossfade in and out of idle, default 0.12 seconds. The shader only pays for the extra blend sample during the transition
Playback Speed Scale	A blanket multiplier on the computed playback speed. Default 1. Reach for it last
Min Moving Playback Speed	A floor so a very slow agent still animates instead of looking frozen. Default 0.35
Reset To Idle On Spawn	Writes idle state when a pooled agent is reused, so it does not inherit the previous occupant's pose. On by default
Randomize Phase On Spawn	Offsets each agent's playback phase so a crowd does not march in lockstep. On by default, and worth leaving on

Moonwalking, or running in place

Both symptoms come from the same mismatch. Walk Match Speed and Run Match Speed describe how fast the source clips were authored to move, and the component compares them against how fast the agent is actually travelling. They do not set how fast anything moves. If your Movement Profile's Max Speed is 7 and Run Match Speed here is 3.5, agents outrun their own animation and slide. Set the two match speeds to the clips you baked, then tune Max Speed for the feel you want.

Attack

Field	What it controls
Attack Blend In Duration	Crossfade from locomotion into the attack clip, default 0.1 seconds
Attack Blend Out Duration	Crossfade back when the attack ends, default 0.1 seconds

Both do nothing unless the assigned VAT asset actually has an attack clip baked into it.

Previewing in the inspector

The component's inspector has a preview toolbar: Idle, Walk, Run, Attack and Stop. It plays the baked clips in the Scene view without entering Play mode, which is the fastest way to confirm a bake came out right. Attack is greyed out, with a tooltip saying why, when the VAT asset has no attack clip.

The Preview Speed slider is the useful part. It runs the same idle threshold and walk-to-run blending the runtime uses, so dragging it up from zero shows you exactly where your agents will switch gait and whether the transition looks right at the speeds your Movement Profile actually produces. Auto Refresh keeps the preview animating in edit mode; it switches itself on when you press a button and off when you press Stop.

The whole section is replaced by a hint until both a renderer and a VAT asset are assigned.

VAT visibility LOD

When Enable VAT Quality LOD is on in SwarmSettings, each agent's VAT shader quality follows whether the agent is being drawn at all, not its simulation importance tier. An agent on screen renders at full quality no matter how far it is from its target, and so does one that has left the frustum but still casts a visible shadow, because its silhouette has to stay right. An agent that is drawn nowhere 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, because 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.
Animator	The Animator to write to. Left empty, it takes the first Animator on this object or its children.
Visibility Renderer	The renderer used to decide whether the agent is on screen. Left empty, it takes the first SkinnedMeshRenderer, or failing that the first Renderer. Set it by hand when the agent's largest renderer is not the one you want driving visibility.
Disable Root Motion	On by default. Turns the Animator's root motion off so the swarm simulation keeps control of where agents actually go. Leave it on unless you know why you want it off, because root motion fighting the simulation is a hard problem to diagnose.
Speed Parameter Scale	Multiplies both speed values before they reach the Animator. Default 1. Use it when your blend tree was authored against a different speed range than your Movement Profile produces, instead of re-authoring the tree.
Min Parameter Change	How much a speed has to move before a new value is written, default 0.01. This is a real saving at high counts: it skips SetFloat calls for agents whose speed is barely changing. 0 writes on every visible sync.
Reset Parameters On Spawn	On by default. Zeroes the speed floats when a pooled agent is reused, so a fresh agent does not inherit the previous occupant's running pose.

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 agent stops refreshing once Visibility Grace Time runs out, provided Update Only When Visible is on. Visible here means Unity still has to draw the agent, and that includes drawing only its shadow while the body sits just outside the camera view. Under a directional light, a shadow crossing the ground belongs to a body that is still animating. Nothing is lost by not refreshing an agent that is drawn nowhere: VAT playback advances on elapsed time rather than on frame count, so a returning agent resumes at the pose it would have reached, and SwarmAgentAnimation agents are already halted by Cull Completely. Uncheck Update Only When Visible and the agent falls back to the Off-Screen Animation Refresh stride instead.

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

Two questions, three cadences. Worth holding next to the Importance LOD matrix, because they look alike and measure different things: this one asks how far the agent is from the camera, while the importance tier asks how far it is from its target. An agent can be simulated cheaply and still animate every frame, or the other way round.

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.