Attack Profile¶

Defines how an enemy type deals damage. Create via right-click → Create → Massive Swarm System → Agents → Attack Profile.

Assign the profile on a SwarmAgentArchetype. Agents with no profile assigned never deal damage, which is fine for passive swarms like ambient wildlife or crowd dressing.

Two damage modes are independent and can both be active on the same profile: Swing Attack and Contact Damage. With neither enabled the profile does nothing, and the inspector says so.

	Swing Attack	Contact Damage
When damage lands	Once per swing, at the end of the windup	Every Contact Hit Interval while the agent is in reach
Can the target dodge it	Yes, by leaving reach during the windup	No
Attack clip	On by default, timed so its blow shows when the damage lands	Off by default; when on, it starts again on every tick
Typical use	Zombies, infantry, anything with a readable strike	Auras, slimes, small biters that should never miss

The mode comes from this profile, never from the agent's animation. Having an attack clip does not switch an agent to Swing, and leaving it out does not switch it to Contact. Damage is applied by a timer in the simulation, so it does not wait for an animation event and does not need one. On a VAT agent the clip follows the damage instead: see Attack animation timing. An agent animated through an Animator and SwarmAgentAnimation deals damage on the same schedule and plays its attack once Attack Trigger is set on that component (see Attack animation on an Animator agent).

Factory defaults¶

Both modes ship off, so a new profile is inert until you enable one. These are the values behind each mode's fields, which is what to return to when a tuning pass gets away from you.

Swing Attack	Default	Contact Damage	Default
Swing Reach	`0.6`	Contact Reach	`0.5`
Swing Damage	`5`	Contact Damage	`1`
Swing Windup	`0.5`	Contact Hit Interval	`0.5`
Swing Recovery	`0.5`	Contact Pushback Strength	`0`
Swing Cooldown	`1`	Contact Play Animation	off
Swing Pushback Strength	`1`
Swing Play Animation	on
Swing Move Speed Multiplier	`0`
Swing Turn Speed Multiplier	`1`

Reaches are in world units and are measured on top of both body radii, so 0.6 does not mean the agent has to get within 0.6 units of the target's pivot. See How Reach Is Measured.

The four times (Swing Windup, Swing Recovery, Swing Cooldown and Contact Hit Interval) are in seconds and can differ per agent, with the same Fixed, Range, Curve and Band modes and the same link icon as the Movement Profile. On the default Shared roll they follow the agent's other Shared fields: give Swing Windup a Range that runs from long to short, 0.9 to 0.45 for example, and the slowest walkers wind up the longest. Each agent reads its values once and keeps them, so every swing of one agent has the same timing.

Swing Attack¶

A targeted melee strike with a three-phase timer: windup → damage tick → recovery. The agent must be within reach to start a swing and again when the damage tick comes, so a target that steps away during the windup dodges the blow. A cooldown prevents immediate repeat swings after recovery ends.

Simple Parameters¶

Start here: most projects only need these four

Swing Enabled¶

Visible effect: Agents perform a discrete melee strike when they reach the target.
Gameplay effect: Enables the windup/tick/recovery cycle. Off means no swing damage even if the profile is assigned.
Increase when: N/A (toggle).
Decrease when: You want purely contact/aura damage.
Technical effect: Gates the entire swing phase state machine for this agent.

Swing Reach¶

Visible effect: How close an agent must be to the target before it starts a swing.
Gameplay effect: Decides how far out a swing can land. It does not move anyone: where the front rank stops is set by Combat Standoff on the behavior profile, so a longer reach means attacks start firing sooner on the way in, not that agents hang back.
Increase when: Agents with long weapon visuals should connect before they visually overlap the target.
Decrease when: Attacks feel like they land too early, before the agent is visually adjacent.
Pitfalls: This is the gap beyond the agent and target bodies, not a center-to-center distance. A reach of 0 means the agent's surface must touch the target's surface to trigger. Set it shorter than the standoff the front rank actually rests at and the agents will stand there pressed against the target without ever swinging. See How Reach Is Measured below.
Technical effect: Swing starts when planar center distance ≤ agent radius + target combat radius + reach. Clamped to ≥ 0 by OnValidate.

Swing Damage¶

Visible effect: Amount subtracted from the target's health on the damage tick.
Gameplay effect: Base lethality per swing cycle.
Increase when: Enemies feel too weak.
Decrease when: High-density swarms kill too fast.
Technical effect: Passed directly to IDamageable.ApplyDamage.

Swing Cooldown¶

Visible effect: Pause between an agent finishing recovery and being able to swing again.
Gameplay effect: Controls aggression tempo. Long cooldowns make strikes feel deliberate; short cooldowns produce rapid flurries.
Increase when: Agents feel spammy; DPS is too high despite low damage per swing.
Decrease when: Agents hesitate too long between attacks.
Pitfalls: This is the gap after a swing, not the interval between swings. The cooldown starts once recovery ends, so the full period is windup + recovery + cooldown. At the defaults that is 0.5 + 0.5 + 1.0, one swing every 2 seconds. The inspector spells the total out when you set a cooldown shorter than windup + recovery.
Technical effect: Countdown begins when the agent returns to Idle after recovery. Swing is only allowed when the countdown reaches zero.

Advanced Parameters¶

Power-user knobs: leave at defaults unless you have a reason

Swing Windup¶

Visible effect: Delay between the swing starting and damage being applied. The attack clip is sped up or slowed down so its blow lands at the same moment, so the hit you see and the hit that hurts stay together whatever value you pick.
Gameplay effect: How long the player sees the attack coming. The longer the windup, the more time the target has to step out of reach and make the swing miss.
Increase when: Attacks feel cheap or instant; a longer tell improves fairness.
Decrease when: Attacks feel sluggish, or the attack clip looks slowed down.
Pitfalls: The timing needs the Hit Time on the agent's VAT asset, which the baker measures for you. Without one the clip plays at its own speed and its blow shows wherever the clip puts it. The clip is held between half and four times its speed, so a windup far shorter or longer than the clip's own hit cannot be matched; the archetype's Combat section says so, for both ends of a Range, and offers the nearest value when the windup is Fixed. See Attack animation timing.
Technical effect: Phase 1 countdown. When it expires, reach is tested again: damage is applied only if the target is still within Swing Reach. Hit or miss, the agent then enters Phase 2 (recovery).

Swing Recovery¶

Visible effect: How long the agent stays held after the damage tick. It stands still only while Swing Move Speed Multiplier is 0, the default. Above that it keeps that share of its speed. When it ends, the attack clip gives way to the walk as soon as the agent moves; an agent that stays where it is plays the clip out.
Gameplay effect: Sets how much of the swing cycle sits after the hit. The agent stays held at Swing Move Speed Multiplier until recovery ends, so a long recovery also keeps it planted longer before it chases again.
Increase when: The attack clip looks cut short when agents chase after swinging, or enemies chain swings faster than the animation reads.
Decrease when: Enemies feel slow to re-engage after attacking.
Pitfalls: Recovery does not protect an in-flight swing from a change of target. If the agent retargets mid-swing, the swing is cancelled outright so a windup aimed at the old target cannot land instantly on the new one. The cooldown keeps running. If the target instead dies or stops taking damage mid-swing (invulnerability frames, for example), the swing plays out with no damage and the agent moves again when recovery ends.
Technical effect: Phase 2 countdown. When it expires, the agent returns to Idle and the cooldown timer starts.

Swing Pushback Strength¶

Visible effect: Target is pushed away from the attacker on each swing damage tick.
Gameplay effect: Crowd can slowly drive a player back even against their movement.
Increase when: Swings should feel physically weighty.
Decrease when: Pushback interferes with player control in a way that feels unfair.
Pitfalls: Clamped to ≥ 0. A value of 0 applies no pushback.
Technical effect: Passed as pushbackStrength to SwarmDamageContext.FromHit. The target's damage handler interprets this value.

Swing Play Animation¶

Visible effect: Plays the attack on the agent's visual when a swing starts: the baked attack clip on a VAT agent, the Attack Trigger on an Animator agent.
Gameplay effect: Provides visual attack telegraphing.
Increase when: N/A (toggle).
Decrease when: The archetype has no attack clip, or you want damage without an animation tell.
Technical effect: Calls VatAnimator.TryPlayAttackTimedToHit with the windup, so the clip's Hit Time lands on the damage tick. When recovery ends it calls VatAnimator.ReleaseAttackToLocomotion. Silently no-ops if the archetype has no baked attack clip. On an Animator agent it sets the Attack Trigger of SwarmAgentAnimation when the swing starts, and takes it back when recovery ends if the controller never consumed it. Culled visuals skip the call but damage still applies.

Swing Move Speed Multiplier¶

Visible effect: How far the agent keeps walking while it swings. At 0 it stops for the attack, so the attack clip plays in place instead of sliding across the ground.
Gameplay effect: A planted attacker can be dodged: step out of reach during the windup and the blow misses. The crowd and knockback can still push it. How it turns while planted is Swing Turn Speed Multiplier.
Increase when: The attack is a lunge or a charge that should carry the agent forward.
Decrease when: Agents glide into you while their attack clip plays.
Pitfalls: Applies from swing start until recovery ends, not during the cooldown, when the agent chases normally. Contact damage has no swing phases, so an agent using Contact Play Animation keeps walking through its clip whatever this is set to.
Technical effect: Scales the agent's own desired velocity (steering times max speed) while the swing is in windup or recovery. Knockback and the body-blocking passes are not scaled. At a multiplier of 0 the agent slows at its Movement Profile's braking acceleration, not in one step. Above 0 it moves toward the scaled speed at the Movement Profile's Max Acceleration. Range 0 to 1, default 0.

Swing Turn Speed Multiplier¶

Visible effect: Whether a swinging agent keeps turning to face its target. At 1 it follows a target that runs around it; at 0 it keeps the facing it had when the swing started and strikes that way.
Gameplay effect: None on damage. The blow lands when the target is within Swing Reach at the end of the windup, whichever way the agent faces, so this changes what the player sees rather than what hits them. Out-running a swing works the same at any value.
Increase when: Agents swing at empty air while the player circles them.
Decrease when: You want a committed attack that visibly keeps its aim, or a slow, heavy enemy that should not spin on the spot.
Pitfalls: Applies from swing start until recovery ends. Outside the swing the agent turns the way its Movement Profile's Orientation Mode says. During the swing it faces its target at any quality tier and in every Orientation Mode, Face Velocity included. It faces the obstacle instead when it is swinging at a door or barricade, and an agent that is searching keeps its normal facing.
Technical effect: While the swing is in windup or recovery, the facing goal becomes the planar direction to the target (or to the obstacle being struck) and the Movement Profile's Max Turn Speed is multiplied by this value (turn acceleration is unchanged). 0 holds the current facing. Range 0 to 1, default 1.

Attack animation timing¶

The swing's damage and the attack clip's blow land on the same step, and you only choose when with Swing Windup. Three things make that work, and none of them needs setting by hand in the common case.

Hit Time on the VAT asset. When the baker bakes an attack clip it measures when the blow lands: the frame where some part of the character has travelled furthest forward from where it started, with forward read from the walk clip. It is stored as Hit Time in the VAT asset's Attack Hit section. Correct it there if the guess is wrong, or press Detect on an asset baked before this existed. A rebake of the same clip keeps a value you typed.
The clip is timed to the windup. A swing plays the clip at whatever speed puts its Hit Time at the end of that agent's windup, between 0.5x and 4x. Cooldown and recovery do not change that speed, so tuning the rate of attack never moves the visible blow.
The clip lets go when the swing does. Until recovery ends the clip plays through any movement, so a lunge set up with Swing Move Speed Multiplier keeps its clip. After that the clip blends into the walk as soon as the agent moves off.

The archetype's Combat section is the one place that sees both the profile and the clip, so it reports what the swing will actually do: the clip's speed, when it ends and how long the agent is held. It offers Set Windup when the windup is outside what the clip can be timed to, Set Recovery when agents would cut the end of the clip by moving off early, and Detect Hit Time when the VAT asset has none. When the windup or recovery differs per agent it checks both ends of the range and reports the worst agent, and it leaves the fix to you, because picking a new spread is a choice rather than a correction: the two Set buttons appear only while the field they write is Fixed. It also warns when a reach is shorter than the behavior profile's Combat Standoff, where the front rank would stand at the target without ever attacking.

Contact Damage (Aura / Touch)¶

Repeating damage applied on a timer while the agent is within reach of the target. There is no windup or recovery; damage ticks as long as the agent stays in range. Use this for passive aura types (poison clouds, fire elementals, thorny hazards) or fast-moving swarms that should never "miss" in a swing window.

Simple Parameters¶

Start here: most projects only need these three

Contact Enabled¶

Visible effect: Agents passively deal damage while adjacent to the target.
Gameplay effect: Enables the repeating damage tick. Can be combined with Swing Enabled for a hybrid: contact drains health while the agent is within reach, and swing delivers burst damage on its own timer.
Increase when: N/A (toggle).
Decrease when: You want swing-only damage.
Technical effect: Gates the contact tick path in StepAttacks.

Contact Reach¶

Visible effect: How close the agent must be to keep dealing contact damage.
Gameplay effect: Effective aura radius beyond body surfaces. A small value means damage only applies when the agent is nearly touching; a larger value gives a standing damage field.
Increase when: Contact damage should continue while the agent is slightly separated from the target.
Decrease when: Contact feels like it fires too early, before the agent is visually on top of the target.
Pitfalls: Like Swing Reach, this is a surface gap, not a center-to-center distance. See How Reach Is Measured.
Technical effect: Contact tick fires when planar center distance ≤ agent radius + target combat radius + reach. Clamped to ≥ 0.

Contact Damage¶

Visible effect: Health drained per tick while in reach.
Gameplay effect: Combined with Contact Hit Interval, this sets the damage-per-second rate.
Increase when: Aura damage feels too slow.
Decrease when: Fast ticks are consuming too much health per second.
Technical effect: Passed directly to IDamageable.ApplyDamage on each tick.

Advanced Parameters¶

Power-user knobs: leave at defaults unless you have a reason

Contact Hit Interval¶

Visible effect: Time between damage ticks, in seconds.
Gameplay effect: Controls tick frequency. Lower intervals produce smoother health drain at the cost of more frequent damage calls.
Increase when: Tick rate is too granular for your health system (e.g., whole-number health values get fractional damage).
Decrease when: Damage feels jumpy or inconsistent.
Pitfalls: Below 0.05 the tick fires on nearly every fixed step, and that cost scales with the number of agents in reach. The inspector warns at that point, and on a Range, Curve or Band it looks at the shortest interval any agent gets.
Technical effect: contactNextApplyTime is set to Time.fixedTime + interval after each tick, with the interval that agent gets.

Contact Pushback Strength¶

Visible effect: Target is pushed away on each contact tick.
Gameplay effect: Applies sustained outward pressure while the agent is adjacent. Combines with swing pushback if both are active.
Increase when: The aura should physically push the target.
Decrease when: Rapid ticks at high pushback strength make the target jitter.
Pitfalls: Clamped to ≥ 0. Contact ticks can fire much more frequently than swings, so even a small pushback value can add up quickly.
Technical effect: Passed as pushbackStrength to SwarmDamageContext.FromHit.

Contact Play Animation¶

Visible effect: Plays the attack animation on each contact tick.
Gameplay effect: Off by default because frequent ticks would spam the swing pose.
Increase when: N/A (toggle).
Decrease when: N/A (toggle, off by default).
Technical effect: Calls SwarmVisualManager.TryPlayAgentAttack on each contact tick when enabled. A VAT agent plays its baked clip, and an Animator agent has the Attack Trigger of SwarmAgentAnimation set.

Obstacles¶

Swing and Contact damage both cross over to an obstacle: a Swarm Flow Modifier an agent is blocked by, with something that can take damage sitting on it, almost always a Swarm Breakable. Obstacle Damage Scale is the one field on this profile that decides how hard this archetype hits that kind of target instead of a living one.

Obstacle Damage Scale: multiplies the swing and contact damage this archetype deals to an obstacle it is attacking. 1 hits it as hard as a target. 2 makes a brute that breaks doors fast. 0 means the archetype never swings at an obstacle at all, whatever is blocking it, and it presses instead. It never changes damage against a living target, and it has no effect on crowd pressure, which reads the Swarm Breakable's own rate regardless of who is attacking.

Archetype-wide, not per-object

Obstacle Damage Scale governs every obstacle this archetype can reach, so 0 here turns it into an archetype that never individually strikes anything blocking it, everywhere that profile is used. To make one specific door or fence take hits differently while the rest of the level behaves normally, use that object's own Strike Damage Scale on its Swarm Breakable instead. See Breakable Obstacles for the full formula and worked setups.

How Reach Is Measured¶

Both Swing Reach and Contact Reach are a surface gap (the open space between the attacker and target bodies) not a raw center-to-center distance.

Reach is the surface gap (the open space between the two bodies) not the center-to-center distance. With agent radius 0.5, target combat radius 0.5, and Swing Reach 0.6, the attack fires once the centers close to 1.6 world units, leaving a visible 0.6-unit gap.

The runtime checks: planar center distance ≤ agent radius + target combat radius + reach

Rearranged: surface gap = planar center distance − agent radius − target combat radius

An attack fires when that gap drops to or below the configured reach value.

Example. Agent radius 0.5, target combat radius 0.5, Swing Reach 0.6:

Attack starts when center distance ≤ 0.5 + 0.5 + 0.6 = 1.6 world units.
At that moment, the visible gap between the two bodies is 0.6 world units.

This avoids the common problem where an agent visually touching the target still cannot attack because body blocking holds their centers apart.

Target Body Radius¶

The target body radius tells the swarm how wide the target's body is for reach calculations. It lives on the SwarmTarget component (see Targets).

Body Radius Source on SwarmTarget is Auto Detect or Manual. Targets lists exactly which colliders Auto Detect measures, and that it skips trigger colliders, so a target whose only collider is a trigger falls back to 0.5 units until you add a solid collider or switch to Manual. The Detected Radius readout in the SwarmTarget inspector shows the resolved value.

If a Transform is registered as a swarm target without a SwarmTarget component (the manual SwarmManager.RegisterTarget(transform) path), the defensive fallback is 0.5 units.

Quickstart: set up attack reach in this order

Check the agent archetype's Agent Radius: this is half of the equation.
Make sure the target has a SwarmTarget component, and that its Detected Radius matches the visible body.
Set Swing Reach to the visible gap you want between bodies at swing start (not a center distance).
Set Swing Damage and Swing Cooldown to match your intended DPS.
Tick Contact Enabled only if you also want passive aura damage; keep Contact Reach ≤ Swing Reach to avoid contact firing when the agent is out of swing range.

Practical Usage Guidance¶

Use Swing Attack for enemies with discrete melee strikes: infantry, zombies, sword-wielders. The windup/recovery cycle gives players a readable tell and prevents the attack from feeling like pure DPS drip.

Use Contact Damage for passive aura types: acid slimes, fire elementals, or any enemy that should drain health on proximity without a swing. It also works as a supplement to swing damage on tank-type enemies that are dangerous to stand near.

Avoid stacking both modes with a short Contact Hit Interval and high Contact Pushback Strength. Frequent pushback ticks at close range make targets jitter.

Gameplay Interpretation¶

Short Swing Windup and high Swing Pushback Strength make a crowd feel relentless. Long cooldowns with a longer windup make individual enemies feel weighty and readable.

Contact Damage alone works best for enemies that punish lingering rather than rewarding careful timing. Raising Contact Reach beyond body clearance creates a "hot zone" the player must actively exit.

A small positive Swing Reach value, just enough for the visual to look connected, is usually more satisfying than zero, because body blocking holds agents slightly outside exact surface contact.