Merge pull request #58 from xefensor/fix/ai-behavior-stability

Improve mob combat and movement AI

Author: xefensor

CHANGELOG.md

@@ -126,6 +126,13 @@ false so Retold's defaults and entries from other compatibility packs remain ava
 
 ## Faction Entity Tags
 
+`retold:shared_defense_species` is an additive exact-species defense tag. When a tagged entity takes
+real health damage, nearby adult entities of that same type may protect it if they hear the call at
+close range or see the attacker. Retold defaults this tag to Wolves and Polar Bears. Tamed tagged
+animals cooperate only when both are tame with the same owner; sitting allies remain unavailable.
+Adding an entity type means its ordinary adult mobs can acquire and pursue attackers, so passive
+species that should flee together rather than fight must not be included.
+
 Compatibility datapacks can classify an entity type into one Retold faction by appending it to one
 of these tags:
 
@@ -149,11 +156,20 @@ of these tags:
 | `retold:factions/enders` | Ender faction relationships. |
 | `retold:alliances/illager_loose_allies` | Permanent non-hostile Illager alignment with combat cooperation only while both entities share the same active raid. This does not grant Illager territory membership. |
 
-Faction describes diplomacy, target selection, assistance, retaliation, and configured territory
-membership. It does not assign a Retold mob profile or take over the entity's daily-life AI. A
+Faction describes diplomacy, target selection, retaliation, configured territory membership, and
+shared defense for explicitly cooperative factions. Broad Undead, Enders, Guardians, and other
+specialist identities retain their narrower species, stage, or encounter owners instead of gaining
+generic faction-wide defense. Faction membership does not assign a Retold mob profile or take over
+the entity's daily-life AI. A
 compatibility pack may therefore classify a third-party mob without opting it into hunger,
 foraging, homes, or another profile. Unknown and untagged entity types remain unfactioned.
 
+Target distance remains bounded even when a compatibility pack adds a faction identity. Mobs with
+a Retold profile use that profile's acquisition and retention limits. Unknown or unprofiled mobs
+fall back to their declared `FOLLOW_RANGE`, clamped to 12–48 blocks for acquisition and at most
+64 blocks for retention. A compatibility addon that needs a deliberate longer-range specialist
+should provide a Retold profile or a narrow code integration rather than inflating faction scans.
+
 Add an entity type exactly as for the block example, using the entity-type path. For example, this
 classifies `examplemod:ashen_guard` as an Undead entity:
 

docs/compatibility.md

@@ -35,6 +35,13 @@ Current position:
   Guardians. Explicit Retold-owned retaliation remains available at this generic boundary. The
   focused relationship selector passes; latest exact Cube Mob and Guardian-family TPS peaks are
   4.488, 5.665, 4.580, and 5.040 ms/tick respectively.
+- `RetoldTargetRangePolicy` now applies species/profile-aware acquisition and retention ceilings to
+  raw Mob targets, Brain memories, Retold-owned combat, faction scans, and relayed assistance.
+  Ordinary acquisition is 12–24 blocks; Stage 1/2 Zombies use 12/18 and Skeletons 14/22, urgent
+  defense receives a bounded retention margin, and genuine long-range specialists retain explicit
+  exceptions. Unknown modded mobs use clamped `FOLLOW_RANGE`. The exact boundary and focused
+  adjacent behavior regressions pass; natural mixed combat, multiplayer, and dedicated servers
+  remain unverified.
 - There are 82 data-driven mob profiles. Zombie Nautilus is the newest unmanaged
   `SPECIAL_VANILLA` profile; Skeleton Horse, Zombie Horse, and Camel Husk are the newest
   `UNDEAD_MOUNT` profiles.
@@ -56,6 +63,14 @@ Current position:
   close-range fake-Flint-and-Steel path for Nitwits.
   Every completed Retold feed now stops the mob for two seconds and
   turns it toward the remembered food position, with urgent ownership able to interrupt.
+- Shared urgent flight now keeps aligned eight-tick refreshes in a straight escape corridor without
+  fresh lateral randomness, adopts matching active paths, and updates their speed without rebuilding
+  them. A genuinely rejected direct dry route can try at most two deterministic side detours; work
+  deferral remains neutral. Ordinary prey, wounded predators, Creeper awareness, and Cat retreat
+  clear the shared destination memory when their reaction ends, while water validation and the
+  existing 40-tick stuck recovery remain authoritative. Both exact route regressions and
+  representative Cow/Wolf/Salmon/Cat TPS runs pass with a 6.472 ms/tick peak, but natural obstacle,
+  crowd, and circling-attacker behavior still needs developer verification.
 - `animal_feeder` is a one-slot wooden trough crafted from five planks. Right-click with compatible
   food inserts one item; sneak-right-click with compatible food inserts as much of the held stack
   as fits; sneak-right-click with an empty hand or incompatible item retrieves it. Hungry managed non-monster land animals use
@@ -165,11 +180,26 @@ Current position:
   multiplayer, and dedicated-server behavior remain unverified.
 - Phantom spawning no longer depends on insomnia when Retold handles a still-default NeoForge
   decision. Vanilla retains its hostile-spawn gamerule, 60–120-second cadence, dark-sky gate,
-  spectator exclusion, placement checks, and generated group size; Retold requires open sky,
-  night-or-storm context, local difficulty, and a one-in-eight rarity result. Explicit decisions
-  from other mods remain untouched. Stalking no longer gives players an arbitrary score bonus and
-  keeps Undead diplomacy. Both exact focused tests pass; natural frequency, storms, multiplayer,
+  spectator exclusion, and placement checks; Retold requires open sky, night-or-storm context,
+  local difficulty, and a one-in-sixteen rarity result, then limits its approved attempt to one
+  Phantom. Explicit decisions and spawn counts from other mods remain untouched. Stalking no longer
+  gives players an arbitrary score bonus and keeps Undead diplomacy. Three exact focused tests pass;
+  natural frequency, storms, multiplayer,
   and dedicated servers remain unverified.
+- A target-holding mob now gives its intended mob victim a bounded chance to react before damage.
+  Within 24 blocks and cached victim-to-attacker sight, shared prey flee, healthy ordinary
+  predators defend, eligible combat-faction victims countertarget through `THREAT_RESPONSE`, and
+  Wolves or Polar Bears can warn available members of their exact species. Failed perception is
+  retried at most every five ticks, walls block it, existing duties remain protected, the response
+  cannot counter-rally the original attacker's side, and later real damage promotes the response to
+  `RETALIATION`. This reads real mob target state and does not infer player intent from weapons or
+  crosshairs. The exact pre-hit test and adjacent defense/faction/warning regressions pass.
+- Generic post-hit social defense triggers only after the victim takes real health damage. Wolves and
+  Polar Bears use exact-species membership through `retold:shared_defense_species`; Nether
+  Remnants, Illagers, Spider families, Silverfish, Endermites, Hoglins, Breezes, and Village
+  Defenders use cooperative faction alignment. One cached 32-block scan recruits at most eight
+  idle adult allies with close hearing or sight. The caller, the attacker's side, babies, busy or
+  controlled allies, sitting/differently owned Wolves, and specialist factions are excluded.
 - Zoglins and wild Zombie Nautiluses are explicit members of the data-driven Undead faction;
   taming removes a Zombie Nautilus's generic faction identity. Zombie-horde, Skeleton-ranged,
   Ghast-artillery, and Zoglin-rampage proactive scorers no longer give players an arbitrary bonus.
@@ -187,6 +217,14 @@ Current position:
   25% of its original weight; vanilla caps, placement, and pack sizes remain authoritative. Its
   exact stage-boundary test passes. Stat buffs are intentionally absent; natural spawn composition
   and mixed-crowd balance remain unverified.
+- Skeletons, Strays, and Bogged now hold a real ranged shot when another Undead intersects the
+  shooter-eye-to-target-eye segment. The ranged owner keeps `UNDEAD_RANGED` control and requests a
+  budgeted lateral/back-step route, trying the opposite side only after a genuine unreachable
+  result; moving the ally clear restores vanilla arrow creation. The exact firing-lane test and
+  neighboring coordination, target-parity, and weapon-pose regressions pass. Latest 50-mob
+  Skeleton, Stray, and Bogged reruns peak at 3.512, 3.612, and 3.963 ms/tick. Natural crowded
+  formations, elevation, obstacle-heavy repositioning, modded ranged-attack compatibility,
+  multiplayer, and dedicated servers remain unverified.
 - Withers now use a specialized ten-tick bounded cached selector instead of Retold's generic
   forced-faction loop. Recent attackers and creatures actively targeting the Wither outrank merely
   nearby prey, current-target inertia limits churn, players receive no categorical bonus, and the

docs/internal/design_implementation_status.md

@@ -367,6 +367,22 @@ The later Stage 2 natural-spawn weight hook changes only NeoForge's potential-sp
 does not add loaded-mob tick work, so these eight exact coordination benchmarks were not repeated.
 Its separate exact test covers the stage, tag, category, weight, and preserved-spawn-data boundaries.
 
+### Ranged Undead Firing-Lane Focused Runs
+
+Allied firing-lane avoidance adds a cached bounded entity query and possible lateral/back-step path
+request only to Skeleton, Stray, and Bogged ranged combat. Their three exact selectors were rerun on
+2026-08-30; Zombie-family coordination and shared cache/budget primitives were unchanged, so the
+other profiles were not selected.
+
+| Mob | Idle/rest | Dropped food/forage | Hunt/targeting | Danger/social | Habitat/day-night | Peak |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Skeleton | 3.512 | 2.305 | 3.442 | 2.502 | 1.273 | 3.512 |
+| Stray | 3.575 | 2.344 | 3.612 | 2.819 | 1.443 | 3.612 |
+| Bogged | 3.963 | 2.242 | 3.648 | 2.215 | 1.301 | 3.963 |
+
+All fifteen phases sustained 20 TPS below the 50 ms/tick gate. Bogged idle/rest was the
+3.963 ms/tick overall peak; absolute wall-clock values remain host-load-dependent.
+
 ### Wounded-Predator Flight Focused Runs
 
 The damage phase now lowers all seven wild ordinary predator profiles through their strict 25%
@@ -456,8 +472,9 @@ work. The complete profile matrix was not selected because only the Villager sto
 ### Dry-Land Flight Focused Rerun
 
 The exact `retold:mob_tps_cow` and `retold:mob_tps_wolf` selectors were rerun on 2026-08-23 after
-urgent ground flight began using bounded land-position sampling and rejecting paths that enter
-water when the mob starts on land. These profiles cover a passive grazer and a predator using the
+the initial urgent-ground-flight implementation added bounded land-position sampling and rejected
+paths that enter water when the mob starts on land. The later stable flee-route rerun below
+supersedes that selector with straight corridors and deterministic detours. These profiles cover a passive grazer and a predator using the
 shared flight adapter; the complete matrix was not selected because ordinary movement, shared scan
 caches, and work-budget primitives did not change.
 
@@ -466,6 +483,51 @@ dropped-food/forage, 2.638 hunt/targeting, 5.806 danger/social, and 3.083 habita
 ms/tick. Wolf averaged 4.624, 4.549, 5.476, 4.753, and 2.921 ms/tick in the same phase order.
 Cow danger/social was the combined 5.806 ms/tick peak.
 
+### Visible Attack-Intent Complete Matrix Rerun
+
+The complete 83-profile matrix was selected on 2026-08-30 because visible attack-intent
+perception adds a bounded check to the shared target-holding `PathfinderMob` tick path rather than
+to one species-local dispatcher. All 83 tests and 415 phases passed in 2.675 minutes, every phase
+remained below the 50 ms/tick gate, and all results reported sustainable 20 TPS. Bat
+habitat/day-night was the 8.311 ms/tick overall peak; Villager idle/rest and danger/social followed
+at 7.747 and 7.711 ms/tick. The exact pre-hit behavior test and adjacent defense, flight, faction,
+village-defender, and territory-warning regressions remain the correctness evidence; this matrix
+establishes only the isolated 50-mob performance boundary.
+
+### Species-Aware Target-Distance Focused Runs
+
+The exact Zombie, Skeleton, Piglin, Ghast, Phantom, Wither, Warden, Ender Dragon, and Wildfire selectors were run
+separately on 2026-08-30 after the shared target hook gained profile-aware assignment checks and a
+staggered five-tick retention cleanup. These deliberately cover both Mob and Brain targeting,
+Stage-scaled Undead, managed and unmanaged profiles, and every current long-range specialist
+category touched by the policy. The complete matrix was not selected because the maintained
+strategy requires exact representative selectors for shared changes.
+
+All 45 phases sustained 20 TPS and remained below 50 ms/tick. Peak phases were Zombie 5.037,
+Skeleton 4.802, Piglin 8.178, Ghast 5.604, Phantom 4.807, Wither 6.638, Warden 5.111, Ender Dragon
+2.480, and Wildfire 6.194 ms/tick. Piglin hunt/targeting was the combined 8.178 ms/tick peak. The exact target-distance test and the
+focused Undead, Phantom, Wildfire, Wither, faction, visible-intent, village-defender, territory,
+and threat-retargeting tests remain the correctness evidence.
+
+### Stable Flee-Route Focused Runs
+
+The exact Cow, Wolf, Salmon, and Cat selectors were run separately on 2026-08-30 after the
+developer confirmed that destination commitment alone still allowed consecutive randomized
+segments to alternate sides. Shared urgent flight now uses a straight escape corridor on clear
+ground, retains matching active paths across speed updates, and tests only bounded deterministic
+detours after actual route rejection. They represent land prey, wounded-predator continuation,
+aquatic prey, and Cat/Creeper retreat. The complete matrix was not selected because the change adds
+no scan, dispatcher cadence, LOD, or work-budget expansion and the maintained strategy calls for
+these exact representatives.
+
+All 20 phases sustained 20 TPS and remained below 50 ms/tick. Cow averaged 4.269 idle/rest, 4.918
+dropped-food/forage, 2.909 hunt/targeting, 6.472 danger/social, and 3.376 habitat/day-night ms/tick.
+Wolf averaged 5.287, 4.403, 5.996, 5.932, and 3.782; Salmon averaged 5.552, 3.561, 5.141,
+5.577, and 2.592; Cat averaged 4.194, 4.036, 5.350, 5.859, and 2.875 ms/tick in the same phase
+order. Cow danger/social was the combined 6.472 ms/tick peak. The two exact stability tests and
+focused damage, water, visible-intent, Creeper, Cat, wounded-predator, and stuck-recovery regressions
+remain the correctness evidence.
+
 ## Results
 
 The table below records the original clean baseline described above; later rerun summaries are