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.

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 — Controls engagement distance. Shorter reach concentrates attackers tightly against the target body; longer reach lets attacks land from a visible gap.
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. 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 IDamageableWithContext.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.
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, so a short animation with a long windup means damage fires after the clip has looped.
Technical effect — Phase 1 countdown. When it expires, damage is applied and the agent enters Phase 2 (recovery).

Swing Recovery Seconds¶

Visible effect — Lockout after the damage tick before the agent returns to Idle.
Gameplay effect — Keeps agents committed to their swing briefly — prevents instant retarget or movement after hitting.
Increase when — Agents snap back to movement too quickly after a hit.
Decrease when — Agents feel stuck or slow to re-engage after attacking.
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 IDamageableWithContext.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.
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), MeshCollider (planar bounds extents), and CharacterController (on the same GameObject). 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.

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.
Enable Contact Damage 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.

Contact Damage does not replace Close-Range Pressure. That behavior controls positioning; this profile controls damage. Combine them when you want a melee pack that positions smartly and lands damage correctly.

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.