Squad-coordinated anomaly avoidance + anti-freeze hardening

[gwalls]

Squad-coordinated anomaly avoidance + anti-freeze hardening

Follow-up to #1. That merge kept the restriction-routing core and the loot/heal guards, but
not the squad-coordination layer — the part that prevents the multi-NPC engine freezes and
keeps a squad from walking through a field after its scout dies. This PR restores that layer
on top of current main, then refines it from several sessions of play-testing in the dense
Zaton (zat_b100) electric clusters and Rostok thermals.

Everything here is in zz_allc0r3_mai_main.script. The post-merge work — interaction bubble,
walking/standing immunity, combat-only damage, kill-rate limiter, restored per-instance
ignores, MAX_RESTRICTIONS tuning, and the loot/heal guards — is preserved; this only swaps
out the avoidance/feel core they sit on top of.

Important

Best on engine 2026.6.1+ (MT exes). Uses npc:invalidate_restrictions() to reroute an
NPC before it commits to a path through a freshly detected anomaly. On older builds it still
loads — NPCs just lean harder on the sprint-through fallback when the timing slips.

Behavior pipeline

Each online stalker is evaluated on a ~2-second tick:

flowchart TD
    Tick([MAI tick - every 2s, per online stalker]) --> Bubble{Within interaction<br/>bubble of player?}
    Bubble -- No --> OutB[Disable anomaly damage<br/>clear avoidance state] --> Done([done])
    Bubble -- Yes --> Job{Guard / camper / sleeper<br/>scheme, and safe?}
    Job -- Yes --> Skip[Skip - leave it at its post] --> Done
    Job -- No --> Cfg[Enable damage per<br/>community / rank rules]

    Cfg --> Near{Anomaly within<br/>detection radius?}
    Near -- No --> Idle[Walk normally<br/>decay anomaly memory] --> Done
    Near -- Yes --> Safe[Safety net: force movement<br/>enabled if standing in damage]

    Safe --> Push{Already<br/>pushing through?}
    Push -- "Yes - clear of damage AoE" --> Exit[End push-through<br/>return to walk] --> Detect
    Push -- "Yes - still inside" --> Maintain["Maintain: restrictions/feel off<br/>+ DIRECT run every tick<br/>(self-propel, even squadmates)"]
    Maintain --> StuckP{No net progress<br/>for ~50s?}
    StuckP -- Yes --> KeepRun[Log stuck, keep running<br/>memory persists] --> Done
    StuckP -- No --> Done

    Push -- No --> Hit{Took anomaly<br/>damage this tick?}
    Hit -- Yes --> Request
    Hit -- No --> Detect[Detection roll per anomaly<br/>rank x movement-state, + memory]

    Detect --> Feel[FEEL election -<br/>one feeler per 10m wins]
    Feel --> Any{Detected<br/>any?}
    Any -- No --> ClearR[Clear restrictions] --> Done
    Any -- Yes --> Route["Route around: restrict closest <=30<br/>(invalidate only on NEW threat)<br/>elected feeler throws bolts"]
    Route --> StuckR{Stuck routing<br/>for ~50s?}
    StuckR -- Yes --> Request[request push-through]
    StuckR -- No --> Done

    Request --> Admit{Other squad pushing<br/>nearby? in-contact exempt}
    Admit -- Denied --> Hold[Hold this tick] --> Done
    Admit -- OK --> Defer{Mid bolt-throw?}
    Defer -- Yes --> Delay[Defer 1.5s so the<br/>bolt animation finishes] --> Rush
    Defer -- No --> Rush["Sprint through:<br/>drop restrictions + feel<br/>· pull squadmates in<br/>· all run via maintain loop"] --> Done

Loading

Always-on guards (independent of the tick, monkey-patched onto the AI):

flowchart LR
    A[NPC AI wants to...] --> L{...loot a corpse<br/>inside an anomaly?}
    L -- Yes --> LB[LOOT GUARD:<br/>blacklist corpse, break the action,<br/>suppressed while pushing through]
    A --> H{...heal self or teammate<br/>inside an anomaly?}
    H -- Yes --> HB[HEAL GUARD:<br/>block the heal, unlock movement]

Loading

What players will notice

• Rarer multi-NPC freezes around busy anomaly fields (the CKinematics skeleton-mutex
  deadlock from several NPCs throwing bolts or moving through an anomaly at once).
• NPCs caught in a field sprint out instead of standing in the burn — and a whole squad
  clears together rather than stringing in one by one.
• A squad doesn't get stranded when its scout dies mid-field — every member self-propels.
• No 2-second "thrash" where an NPC near a cycling field re-paths every tick.

What changed vs main

Feel becomes a squad-scout role, not a per-NPC consequence of detection

main turns engine feel on only for an NPC that detected something in a sparse field. This
PR elects one feeler per 10 m (SQUAD_CONTENTION_RADIUS, lowest-id wins) independent of
the detection roll. Two reasons:

• Anti-deadlock: multiple NPCs rendering thrown-bolt CMissiles in the same frame contest
  the skeleton/IK locks and freeze the game. One feeler per 10 m removes the contention.
• No blind squads: under the old coupling, a squad where everyone misses their roll has
  nobody scouting. The election guarantees a scout.

The two avoidance layers are now cleanly split: rank-gated restrictions = preventive
(route around before contact); election-gated feel = reactive (run in, take a hit, bolt
and reroute). A missed roll correctly yields "blundered in, then reacted," not free avoidance.

Push-through (sprint-out) with squad coordination

• Two modes: single (took a hit — exits as soon as clear of the damage AoE) and field
  (stuck routing — exits only when the whole cluster is clear). Stuck-detection escalates
  single → field.
• Admission control: a stuck/field commit is denied if another squad is already pushing
  through within 10 m (prevents the multi-squad pile-up that re-triggers the lock). In-contact
  commits are exempt — a burning NPC always gets out.
• FEEL→rush deferral: if the committer was mid bolt-throw, the whole commit waits 1.5 s so
  the bolt's render finishes before the movement transition.
• Squad propagation + direct run: when one member commits, eligible squadmates commit too
  (otherwise a follower keeps its restrictions, can't path to the bolting leader, and the
  engine enclosure-crashes). Every committed NPC gets a direct set_movement_type(run) each
  tick — not just the squad rush flag, which is inert for NPCs off xr_reach_task. Without
  this, propagated squadmates walked through fields defenseless and died after the leader fell.
• On-death cleanup: a dead NPC's push_through state is cleared immediately, so its corpse
  doesn't block live commits in the area until it despawns.

Restriction-set stabilization

• Re-issue the restriction set only when it changes, and only force an immediate reroute
  (invalidate_restrictions) when a genuinely new anomaly enters — shrinks, reshuffles, and
  dynamic zones blinking back on don't rebuild the path. Removes the ~2 s restriction "thrash"
  on NPCs near cycling fields.
• Memory persists a dynamic anomaly through its off-phase so its re-enable reads as a known
  zone, not a new threat.

Code cleanup

• Renamed the commit pair to read request → commit → enter (request_push_through gates;
  commit_push_through does the work).
• Extracted stuck_since() — one displacement-anchor stall check shared by the routing and
  push-through stalls — and exit_push_through / reset_avoidance_state for the teardown
  paths.
• A force-evict mechanism for scheme-pinned NPCs was tried and removed — play-testing
  showed no benefit (a 2 s-tick destination poke can't beat a scheme that re-anchors every
  frame), and MIN_RESTRICT_DISTANCE already prevents the enclosure crash it was guarding.
• Removed a dead Feel Density Limit MCM option (superseded by the feeler election) and
  reworded the engine-feel option text to match.

Test plan

• Dense zat_b100 electric cluster with several squads — no freeze, no setup_movement_params crash.
• Only one NPC per ~10 m throws bolts (check [MAI][FEEL] spacing).
• An NPC that takes a hit sprints out and clears; its squad follows and survives a scout death.
• Stationary NPC near a cycling field shows [MAI][RESTRICT] applies without (grew) on blink-back ticks (no reroute, no thrash).
• NPCs still die in lethal anomalies; rookies still misjudge fields.
• Bubble / immunity / kill-limiter / guards from Squad-coordinated anomaly avoidance + anti-freeze hardening #1 unaffected.

Notes

Two engine-side issues sit under this layer. The CKinematics skeleton-mutex deadlock — the
-mt engine's parallel CalculateBonesThread cross-locking two NPCs' skeletons during IK — is
fixed upstream in themrdemonized/xray-monolith#576,
validated against this mod. The script mitigations here (feeler spacing + rush deferral) stay as
a fallback and become removable once that lands. The enclosure u32(-1) sentinel in
setup_movement_params is still only dodged by MIN_RESTRICT_DISTANCE rather than guarded
engine-side.

[gwalls]

This is dead code in main. Refactored to use our SQAUD_CONTENTION_RADIUS constant.

[gwalls]

Handles state as part of the push_through family of functions: request_push_through -> commit_push_through -> enter_push_through -> exit_push_through

[gwalls]

Redundant given the new 2 second tick

[gwalls]

Consider making this a recursive function that continuously defers until we're in the correct state

[gwalls]

I'm not seeing in freezes during my recent tests so I'm going to avoid the added complexity and leave this as a one-shot

[gwalls]

Moved to a single helper function for resetting state

[gwalls]

This now clears, escalates, or maintains the push-through attempt. An NPC distinguishes between rushing through a single anomaly or an entire field. It's also important to handle the entire squad or solo members will continue in their squad stance (likely walking).
The key fix is forcing move.run every tick. "free NPCs maintain run automatically" and "scheme-driven squad NPCs revert to walking between ticks anyway." - that'd be nice, but the walking revert is really the bug. An NPC that reverts to walking inside the field will just take continuous damage and die (I observed this on main). It seems like the squad rush flag only moves xr_reach_task NPCs, so I set run directly on every committed member, leader and squadmates both.

No animation flicker from my tests

[gwalls]

This is what actually removes the flicker and why keeping a larger (unlimited?) MAX_RESTRICTIONS_PER_NPC is important - a lot of restriction list churn (just additions really) creates the flicker seen in NPCs.

[gwalls]

We don't save much by keeping this small and, in fact, a smaller value adversely affects the NPC's behavior. Smaller values result in the restriction list changing more frequently and I believe those changing restrictions cause the NPC animation "flicker" that we've seen.

The enclosure risk should be mitigated through the new rush/clear restrictions behavior.

[gwalls]

Once the deadlock issue is fixed in the MT exe's these mitigations can be removed or at least reduced.

[gwalls]

actually, we should still disable feel in this case. We don't want the NPC to feel for anomalies it never detected.

[gwalls]

Superseded by #2 — the same avoidance layer rebased onto Priler's NDA v3.0 (clean diff against the NDA base).