healer-man/docs/ENEMY_FEAR_MOVEMENT_2026-10-06.md

# Enemy fear movement follow-up — 2026-10-06

This pass integrates source-informed movement for the pinned enemy shout fear
auras into player, party and mobile owned-summon consumers. Voluntary movement,
jumping, attacks and casts remain suppressed while fear controls the actor.
Movement requires reviewed navigation and collision/LOS approval. Missing or
blocked spatial support safely holds the actor. Other controls retain their
existing policy; this does not claim exact historical-server path or RNG parity.

## Historical core behavior

The read-only historical source is AzerothCore commit
`e822d718322289dd036fb2daf8867ba41283bf9a`, specifically
`src/server/game/Movement/MovementGenerators/FleeingMovementGenerator.cpp`,
`src/server/game/Movement/MotionMaster.cpp`,
`src/server/game/Entities/Unit/Unit.cpp`, and
`src/server/game/Spells/Auras/SpellAuraEffects.cpp` under
`../wow-pvt-server-backups-2/azerothcore-wotlk`.

`HandleModFear` passes the live aura caster to `Unit::SetControlled`; that
passes it to `SetFeared`, then `MotionMaster::MoveFleeing`. The generator looks
up the caster GUID when it chooses each new destination. It does not preserve
the caster's cast-time position. If that lookup fails, it picks a random angle
and follows its near-source distance branch with a source distance of zero. A
dead caster can still resolve while its unit remains in-world; after removal,
the source-less fallback applies.

The source's exact movement bounds and retries are:

| Core rule | Source value |
| --- | ---: |
| Quiet-range lower bound | 28 yd |
| Quiet-range upper bound | 43 yd |
| Minimum accepted path | 2 yd |
| Path length limit | 30 yd |
| Retry after destination LOS failure | 200 ms |
| Retry after failed, short, or invalid path | 100 ms |
| Repath wait after spline travel | random 800–1500 ms |

Below 28 yards, the server picks a distance between `0.4` and `1.3` times the
remaining distance to 28 yards and a heading within ±π/8 of the direction away
from the source. Above 43 yards, it picks `0.4`–`1.0` times the 15-yard band
width and heads partly back toward the source, within ±π/4. Inside the quiet
band, it picks `0.6`–`1.2` times the band width in a random direction. A source
distance at or below 0.2 yards uses a random base angle. The core constrains the
candidate with `MovePositionToFirstCollision`, checks LOS to the resulting
point, then asks `PathGenerator` for a path and rejects shortcuts, no-path,
far-from-poly, paths shorter than 2 yards, and paths beyond the 30-yard limit.
After five failed paths it stops looking up the source and uses the
source-less random fallback.

`SetControlled` does not start fear while stun or confusion already owns the
unit. When the higher-priority control ends, it rechecks active fear auras and
resolves their caster GUID. This helper accepts the actor's active stun end time
and holds fear movement until that higher-priority control expires.

## Planner boundary

[`src/game/enemyFearMovement.ts`](../src/game/enemyFearMovement.ts) carries the
source distance bands, steering ranges, LOS/path retries, and path length
limits. Its hash-based choices are simulator decisions: they reproduce the
source's ranges with stable values derived from actor ID, source ID, aura
application time, and decision index. They do not reproduce the core's global
random-number stream. `worldUnitsPerYard` is required input because imported map
coordinates can have a different scale. The estimated time to the next choice
uses approved path length divided by this actor's current effective speed,
then adds a seeded wait from the core's 800–1500 ms range.

Each actor supplies its own fear expiry, stun expiry, base movement speed, and
source speed multiplier. The shout's +25% speed is therefore applied only when
that target has the still-active source speed aura. The current adapters are
limited to tagged source fear. `getSourcePosition` runs once per repath so
the goal uses the live caster location at that decision; the caller should
cache the resulting goal until `nextDecisionAtMs` instead of recomputing it
every frame.

The planner requires three map adapters: a projection that rejects excessive
snaps and floor changes, an LOS test, and a complete actor-safe path-length
query. Missing map support, an unsafe projection, blocked LOS, or an invalid
route yields a hold with the source retry timing. The destination is a route
goal only. The caller must move through actor collision and approved navigation
waypoints; it must never assign the destination directly to an actor position.
`stepEnemyFearTowardDestination` only computes a bounded request and does not
replace those checks.

## Integration seams before this pass

- `PlayerRig` resolves the player's shout control near its frame movement step.
  `enemyControlPreventsMovement` currently blocks all fear before movement, and
  `Rapier`'s character controller checks the player's capsule against terrain.
  For a tagged source fear with no active stun, the frame can use the cached
  flee goal to set the autonomous world movement vector, then submit its bounded
  delta through the existing character controller. The goal must not be
  derived from camera input or change camera yaw.
- `PartyPopulation` similarly blocks fear before companion route planning. It
  already has the reviewed navigation graph, `planPartyRoute`, direct-segment
  collision checks, and route-segment clearance validation. A fear goal should
  use those route helpers and hold when no safe route exists.
- The summon loop in `combatStore.ts` returns early when `controlledUntil` is
  active, before movement and actions. `CombatSummon` currently keeps a control
  expiry but no control mechanic. A source fear adapter needs to preserve the
  per-summon fear and stun state, move only when fear is the active control,
  and continue to suppress actions. `CombatSpatialProvider` provides live actor
  positions, LOS, ground projection, and the reviewed navigation graph; the
  adapter still needs to validate a complete route before advancing a summon.
- The shout control resolver currently returns only mechanic and expiry. The
  integration must identify the active tagged `ActiveAura` per actor to retain
  its source ID and `appliedAt` for live source lookup and deterministic seeding.
  That lookup can use the mob runtime position while the caster exists; when
  the source ID no longer resolves, pass `null` and use the source-less branch.

The existing hostile NPC fear path is separate. `MobPopulation` already calls
`stepFearedMobAway` and clamps that direct step to the home leash, using the
current aggro target as the threat. That helper does not perform LOS or route
validation for the flee step. This follow-up leaves it unchanged and does not
claim it matches the historical generator.

## Integrated consumers and verification

`enemyFearMovementRuntime.ts` retains the selected aura's source/application,
caches each goal and implements the five-failure source fallback. Concurrent
tagged stun and generic stun/confuse/root/sleep auras hold movement even when
the actor's longest control timer belongs to fear. Expiry or purge clears the
per-actor goal; a refreshed aura starts a new decision sequence.

PlayerRig follows approved route waypoints through its existing Rapier character
controller, including gravity. Keyboard movement and jumping do not steer fear.
PartyPopulation uses its reviewed graph and capsule route validators, normal
party speed with actor-local source modifiers, and follows forced fear even
under Stop. Fear never enables catch-up speed or stuck-recovery relocation.
Camera look retains its ordinary hold-and-drag behavior.

`enemyFearSummonMovement.ts` requires a loaded graph and validates projection,
LOS, path segments and each bounded step. The actual combat tick consumes it
before summon actions, holds concurrent controls, and preserves the pet's Prowl
movement modifier. Totems and stationary zones remain stationary. Remote actor
authority and hostile-NPC flee policy remain outside this bounded integration.

Focused planner/cache/summon verification passes 20 tests, including actual pet
ticks, blocked/missing navigation and simultaneous stun expiry. Input regressions
pass 33 tests. Final build/live evidence is recorded in the combined follow-up report.