Enemy Aggro System

Summary

This article covers how enemies decide who to focus on; how they discover players, pick a target, and change targets when someone starts shooting them. It does NOT cover when enemies actually get to attack; that's the Combat Token System, which governs attack pacing and turn-taking.

Every enemy stores its current target in the Enemy blackboard key. All behavior tree distance checks, attack targeting, and positioning decisions reference this key. If you are not an enemy's Enemy, your position is irrelevant to its AI — you could be standing on its head and it won't care unless you're its target.

The system operates in three layers, in order:

1. Detection — How enemies discover players exist (vision, hearing, damage, chain alerts). An enemy can't target what it doesn't know about.

2. Enemy Selection — From known targets, who does the enemy focus on? A utility-based scoring system with decision stickiness that re-evaluates every second.

3. Threat Knowledge — Incoming damage can override the selection system, forcing target swaps via RangeThreat/MeleeThreat interrupts. This is the "aggro stealing" layer — and the part players have the most direct control over.

Detection

Before an enemy can target a player, it must first detect them. The Advanced Enemy Selection pipeline feeds from a set of Sensors and Observers that populate the enemy's known-targets list. An enemy that hasn't detected you will not target you, regardless of distance or damage.

Detection Sensors

The pipeline includes 6 sensor types, defined in {SERVER}/ssl/ai/enemyselection/advancedenemyselection/sensorsobservers/:

Detection Propagation

Once an enemy detects a player, it can spread awareness to allies through two mechanisms:

Aggro Scream — an active alert broadcast:

• Scream Delay: 0.6 seconds after detection

• Scream Duration: 2 seconds

• Cooldown: 20 seconds

When an enemy spots a player, it waits 0.6s then "screams" for 2s, alerting nearby allies. The 20s cooldown prevents constant re-broadcasting. This is the primary chain-detection mechanism — one Termagant spots you, screams, and the whole group turns.

Aggro Brattle — passive ambient awareness:

• Update Period: 1 second

A continuous background check that propagates awareness periodically. Less dramatic than scream but ensures nearby enemies eventually learn about detected players even without an active alert.

Per-Enemy Detection Ranges

From individual enemy writeups, confirmed vision/aggro detection ranges:

Most enemies use default detection ranges that we haven't individually confirmed — the values above are the ones explicitly documented in enemy writeups.

Detection Implications

• You can avoid aggro entirely by staying outside detection range — but the Damage sensor means any shot you take immediately reveals you

• Chain detection means stealth is fragile — one enemy's scream alerts the group within 0.6s

• Bosses can't be hidden from — the Sixth Sense sensor bypasses all stealth

• Detection is prerequisite, not targeting — being detected adds you to the known-targets pool, but Enemy Selection (Layer 2) still decides who the enemy actually focuses on

Enemy Selection

Once detected, potential targets enter the Advanced Enemy Selection pipeline — a utility-based system that scores each known target and picks the highest. The Enemy blackboard key is set to the winner.

Selection Pipeline Components

The pipeline runs through these controllers:

Default Target Scoring

The default enemy selection utility (utilityfunctiondefaultenemyselection.sso) scores each potential target as:

Score = CanBeAiTarget × min(DecisionStickiness, Priority) × TargetDesirability

Where Priority is a weighted average of:

• Base Aggressiveness (weight: 10) — primary factor, based on the UtilityFunctionAggressiveness subfunction

• Player Contribution (weight: 1) — minor factor from UtilityFunctionEnemySelectionPlayerContribution

The heavy 10:1 weight toward aggressiveness means the base scoring dominates over player contribution tracking.

Decision Stickiness

Enemies don't instantly swap to a new target every cycle. The UtilityFunctionDecisionStickiness module provides a bias toward keeping the current target:

• Stickiness Duration: 7 seconds — after selecting a target, that target gets a bonus score for 7s

• Stickiness Fade Duration: 3 seconds — the bonus fades over 3s after the 7s expires

This means an enemy typically holds its current target for ~7-10 seconds before being open to swapping, unless a threat module (Layer 3) forces an override.

Melee Enemy Selection

Melee-specialized enemies use utilityfunctionmeleeenemyselection.sso, which adds:

• Path validation — target must have a valid navigation path (unreachable targets score 0)

• Melee Aggressiveness override — replaces base aggressiveness with UtilityFunctionAggressivenessMelee

Power-Level-Based Selection

Some enemies use utilityfunctionenemyselectionbypowerlevel.sso, which factors in:

• Target power level — spline from 0→0.1 to 100→1.0, meaning higher-power targets are preferred

• Distance decay — "Decay Closer" spline from 0→0.1 to 80→1.0 (closer = lower score, favoring distant targets)

• Decision stickiness — 7s duration, 3s fade (same as default)

• Player contribution — inverted (NOT player contribution), meaning enemies using this profile are LESS likely to target the player who's been contributing most

Threat Knowledge

This is the "aggro stealing" layer. While Layer 2 runs its selection cycle every second, Layer 3 can interrupt that process — incoming damage sets blackboard keys (RangeThreat, MeleeThreat) that force target swaps mid-cycle.

Every enemy includes one or more AI Knowledge Modules that track incoming damage and fire when thresholds are exceeded. These are the core defaults — individual enemies can (and frequently do) override every parameter.

Default RangeThreat

When an enemy takes 2+ qualifying damage within 2 seconds from a player within 30m, the RangeThreat blackboard key is set to that player. This is the primary mechanism for "stealing aggro" with ranged fire.

Key exclusions from the default filter: Melee damage, fire/burn damage, generic explosive damage, and player perk damage (dmgtypeplayer_perk) do NOT trigger RangeThreat by default. Shooting is the intended trigger.

Default RangeFarThreat

A separate module for players engaging from farther away. Higher threshold (4 vs 2) — you need to deal more sustained damage from range to register as a threat. No damage type filter is specified (only distance filtering), which means it may accept all damage types at this range.

Default MeleeThreat

Melee threat requires substantially more damage (6 vs 2 for ranged) in a shorter window (1.5s vs 2s). This makes ranged fire significantly more effective at pulling aggro than melee attacks. The high threshold means weak melee hits won't trigger a target swap.

TopDamageThreat

A global module that tracks who is dealing the most damage overall within a 1-second rolling window. Used by some enemy selection utility functions as a factor in target prioritization (not directly tied to a blackboard key like the others).

Per-Enemy Overrides

Most enemies override the default thresholds. Here's a compiled reference of every enemy whose threat parameters we've confirmed differ from defaults:

"Raw" vs "Modified" damage: Some enemies check checkRawDamage = true, meaning pre-mitigation damage counts. Others check post-mitigation. This matters when enemies have damage sensitivity states active — raw-checking enemies are easier to trigger threat on while they're in damage reduction states.

Threat Density

The floatvalueproviderthreatdensity.sso assigns threat weights by enemy classification. This is used by the AI to evaluate how dangerous a group of enemies is in an area:

Fodder enemies (Hormagaunts, Cultists) contribute very little to threat density. Elites (Terminators, Warriors) contribute half. Specials, Minibosses, and Bosses all have equal maximum weight.

Recovery

When a threat module sets RangeThreat or MeleeThreat, the enemy's behavior tree enters its Recovery subtree. Recovery is an interrupt system; it can pause the enemy's current action (if AllowInterruptions is true) and execute a response.

Recovery responses vary wildly by enemy, but common patterns include:

Critical insight: Recovery often makes enemies MORE dangerous, not less. The Helbrute's ranged threat response reduces its shooting cooldown. The Hierophant gets faster. Triggering recovery carelessly can escalate the fight.

Player Manipulation

Avoiding Detection

• Stay outside an enemy's vision radius to avoid being added to its known-targets list

• But the Damage sensor means any shot reveals you instantly — there's no stealth sniping

• Chain detection (Player Got Detected sensor + Aggro Scream) means one alert spreads to the group in ~0.6s

• Bosses have Sixth Sense — they can't be hidden from at all

Stealing Aggro (Layer 3 Overrides)

1. Ranged fire is king — RangeThreat has a lower threshold (2 damage) than MeleeThreat (6 damage). A few shots steal aggro faster than sustained melee

2. Stay within 30m for default RangeThreat. Beyond 30m you hit the RangeFarThreat module which requires double the damage (4 threshold)

3. Use the right damage types — bullet, plasma, melta, laser, volkite all work. Fire and generic explosive do NOT trigger RangeThreat by default

4. Enemies hold targets for ~7-10 seconds (decision stickiness). Brief damage won't instantly pull an enemy off a teammate — you need to sustain pressure or deal enough to force a threat module override

Off-Screen Safety

The frustum aggro penalty (0.6x for enemies behind you) means enemies you can't see are 40% less likely to get attack tokens. See the Combat Token System for the full scoring breakdown and how forced tokens bypass this entirely.

High-Value Target Enemies

Some enemies using power-level-based selection actively prefer higher-power targets. Players running high power-level loadouts will attract more aggro from these enemies.

Per-Enemy Threat Exploitation

• Biovore (20 dmg/5s): Extremely hard to pull aggro with ranged fire alone. Close to 25m and stay there for 2s to force unanchor instead

• Helbrute (15 dmg/6s with age requirement): The first-event-age requirement (>=3s old) means burst damage won't trigger threat — you need sustained fire over 3+ seconds

• Tzaangor (1 raw melee): Absurdly sensitive to melee; any melee contact pulls aggro immediately

• Zoanthrope/Neurothrope (3 dmg/1.5s): Sensitive but ONLY to ranged weapon types. Melee, fire, and explosive don't trigger shield swap

• Lesser Sorcerer: Has NO RangeThreat module. You cannot pull aggro by shooting — only melee (9 damage in 1.5s) triggers recovery

• Hormagaunt/Termagant/Cultist: No recovery at all. Threat modules may still update the Enemy key through the selection pipeline, but there's no behavioral interrupt

The Recovery Trap

Forcing recovery can backfire:

• Don't trigger Helbrute ranged threat recovery carelessly — it reduces its shooting cooldown by 15s

• Hierophant recovery makes it shoot faster

• Neurothrope recovery leads to a forced HEAVY counter-attack (Psychic Leech or Warp Ball)

• Tzaangor Spearman: every 3rd recovery triggers Explosive Throw or Taunt (escalation)

Plan your threat-pulling around whether the recovery response is something your team can handle.

Game Files

• {SERVER}/ssl/ai/enemy_selection/advanced_enemy_selection/sensors_observers/ — all detection sensors (vision, hearing, damage, ai_target, boss_sixth_sense, player_got_detected)

• {SERVER}/ssl/ai/detection/rules/server/detection_rule_aggro_scream.sso — aggro scream propagation

• {SERVER}/ssl/ai/detection/rules/server/detection_rule_aggro_brattle.sso — aggro brattle (ambient detection)

• {SERVER}/ssl/ai/enemy_selection/advanced_enemy_selection/ — full enemy selection pipeline (controllers, sensors, utility functions)

• {SERVER}/ssl/ai/behaviour/value_providers/object_value_provider_enemy.sso — the Enemy blackboard binding

• {SERVER}/ssl/ai/knowledge/damage/ai_knowldege_module_range_threat.sso — default RangeThreat module

• {SERVER}/ssl/ai/knowledge/damage/ai_knowldege_module_range_far_threat.sso — RangeFarThreat module (30-50m band)

• {SERVER}/ssl/ai/knowledge/damage/ai_knowldege_module_melee_threat.sso — default MeleeThreat module

• {SERVER}/ssl/ai/knowledge/damage/ai_knowledge_module_top_damage_threat.sso — TopDamageThreat (who's dealing the most overall)

• {SERVER}/ssl/ai/behaviour/value_providers/float_value_provider_threat_density.sso — threat density by enemy classification