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.

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 Seconds	`0.25`	Contact Interval	`0.5`
Swing Recovery Seconds	`0.15`	Contact Pushback Strength	`0`
Swing Cooldown Seconds	`1`	Contact Play Animation	off
Swing Pushback Strength	`1`
Swing Play Animation	on

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.

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 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 Seconds¶

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.25 + 0.15 + 1.0, one swing every 1.4 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 Seconds¶

Visible effect: Delay between the swing starting and damage being applied.
Gameplay effect: Readable tell before damage. Lets the player see the attack coming.
Increase when: Attacks feel cheap or instant; a longer tell improves fairness.
Decrease when: The animation commits to damage faster than the windup timer allows.
Pitfalls: Windup is independent of the VAT animation length. The baked attack clip does not loop: it plays once and blends back to locomotion. Give a short clip a long windup and the damage lands after the agent has already returned to its walk.
Technical effect: Phase 1 countdown. When it expires, damage is applied and the agent enters Phase 2 (recovery).

Swing Recovery Seconds¶

Visible effect: Pause after the damage tick before the agent can start its cooldown.
Gameplay effect: Sets how much of the swing cycle sits after the hit. It does not hold the agent still: steering and movement carry on through the whole swing, so recovery only delays the next one.
Increase when: 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.
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: Triggers the baked attack clip on the agent's visual when a swing starts.
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 SwarmVisualManager.TryPlayAgentAttack. Silently no-ops if the archetype has no baked attack clip. Culled visuals skip the call but damage still applies.

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 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 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.
Technical effect: contactNextApplyTime is set to Time.fixedTime + interval after each tick.

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.

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):

Auto Detect (default) picks the largest planar radius among SphereCollider, CapsuleCollider, BoxCollider (inscribed = the smaller of half-width on X / Z), and CharacterController (on the same GameObject, never a child). Any other collider type, MeshCollider included, is measured as the smaller of its X and Z world-space bounds extents. When Include Child Colliders is on (default), children are also walked.
Manual: uses the explicit Manual Body Radius value (default 0.5).

The Detected Radius readout in the SwarmTarget inspector shows the resolved value. A warning appears when Auto Detect found no collider source.

Trigger colliders are skipped

Auto Detect ignores every collider with Is Trigger ticked. A target whose only collider is a trigger, which is common on pickups and objective volumes, measures as nothing, falls back to 0.5 units, and raises that no-source warning. Either give it a non-trigger collider or switch Body Radius Source to Manual and type the radius in.

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 Seconds 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 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.