ModernUO/dev-docs
Kamron Batman 502c3f6aa4
fix(ai): BaseAI.OnAggressiveAction owns the retaliation policy; familiars refuse cleanly (#2662)
> [!IMPORTANT]
> **Breaking change to API to fix NPC AI issues**

## Symptom

`FamiliarAITests.HiddenCaster_FamiliarRefusesRetaliation` fails on main at `Assert.False(wolf.Warmode)`: the familiar's `Combatant` stays null as intended, but it is left in war stance. In-game the familiar of a hidden caster flips into warmode for a tick when struck, until `FamiliarAI.StandDown()` clears it on the next think.

CI never saw it because the familiar tests are `SkippableFact` (they need client tiledata).

## Root cause

#2644 and #2645 landed a day apart and are individually correct but conflict at one seam.

Since #2645, a familiar (`Commandable == false`) is no longer "told to stand down", so `BaseCreature.AggressiveAction` continues past `AIObject.OnAggressiveAction(aggressor)` to its generic fallback:

```cs
else if (Combatant == null && !BardPacified)
{
    Warmode = true;
    Combatant = aggressor;
}
```

`FamiliarAI.OnAggressiveAction` had already declined (caster hidden), but the hook was `void`, so the creature could not tell. The fallback raised `Warmode` before `BaseFamiliar.Combatant` vetoed the target.

## Fix

This is the follow-up agreed in #2645: the retaliation policy moves into a virtual `BaseAI.OnAggressiveAction(aggressor) -> bool`.

- **`BaseAI.OnAggressiveAction`** now holds the stand-down verdict, the closer-aggressor swap (`PreferCloserAggressor`), and the `IssueOrder(Attack)` vs `Combatant =` decision. Returns `false` when the creature stands down.
- **`BaseCreature.AggressiveAction`** keeps only bookkeeping — `ControlMaster.Aggressors` entry, `StopFlee`, `ForceReacquire`, ethics `FinishShield` — keyed off the return, so an AI that declines is never second-guessed.
- **`FamiliarAI`** overrides the whole policy: no orders to stand down on, never fights for a hidden caster or a hidden aggressor.

Behaviour for every other AI is unchanged. Moving the fallback ahead of `StopFlee`/`ForceReacquire` is order-safe: both are pure field resets, `IssueAttack` does not `Think()`, and `OnCombatantChange` only derives `Warmode`.

Two commits: the first is the minimal `bool` hook that alone fixes the test, the second the policy move.

## Not changed (noted for later)

- `Warmode = true; Combatant = x;` (also in `FamiliarAI.Act`, `IssueAttack`) is redundant when the setter accepts — `BaseCreature.OnCombatantChange` derives `Warmode` — and is the dangling-warmode hazard whenever a `Combatant` setter vetoes.
- Since #2614 a stood-down pet skips the ethics `FinishShield`; RunUO ran it unconditionally. Preserved as-is.

## Tests

`HiddenCaster_FamiliarRefusesRetaliation` fails on main and passes here. Full `UOContent.Tests`: 1126 passed, 0 failed, 2 skipped (spawner fixture capture + benchmark).
2026-09-22 18:48:13 -07:00
..
claude-skills fix(ai): BaseAI.OnAggressiveAction owns the retaliation policy; familiars refuse cleanly (#2662) 2026-09-22 18:48:13 -07:00
runuo-migration-docs fix(ai): BaseAI.OnAggressiveAction owns the retaliation policy; familiars refuse cleanly (#2662) 2026-09-22 18:48:13 -07:00
bug-reporting.md docs: upstream bug-reporting process for forks, and comments explain why (#2649) 2026-09-14 23:27:27 -07:00
code-standards.md docs: upstream bug-reporting process for forks, and comments explain why (#2649) 2026-09-14 23:27:27 -07:00
commands-targeting.md fix: TextDefinition was uneditable in the props gump, and where parsed constants its own way (#2624) 2026-09-10 19:36:30 -07:00
configuration.md fix: Fixes Argon2 verify correctness and the password upgrade lockout (#2562) 2026-08-08 00:24:59 -07:00
content-patterns.md fix(ai): BaseAI.OnAggressiveAction owns the retaliation policy; familiars refuse cleanly (#2662) 2026-09-22 18:48:13 -07:00
debugging-event-loop.md fix: stop the idle-sleep backoff tripping on healthy hosts (#2572) 2026-08-13 19:58:03 -07:00
era-expansion.md chore: Adds AI instructions and SKILLs for ModernUO codebase (#2347) 2026-03-01 11:42:19 -08:00
event-scheduler.md chore: Adds AI instructions and SKILLs for ModernUO codebase (#2347) 2026-03-01 11:42:19 -08:00
events.md feat(skills): SkillEvents.SkillUsed for cross-assembly subscribers; InternalsVisibleTo ModernSpawner.Tests (#2636) 2026-09-11 22:58:44 -07:00
generic-commands.md fix: TextDefinition was uneditable in the props gump, and where parsed constants its own way (#2624) 2026-09-10 19:36:30 -07:00
gump-system.md docs(messages): document interpolation anti-patterns and :L format spec (#2441) 2026-05-03 18:23:50 -07:00
ip-bans-and-allowlists.md feat: make the blocklist and manual allowlist opt-in; cut the ban subsystem's on-loop cost (#2577) 2026-08-13 23:22:35 -07:00
networking-packets.md feat: make the blocklist and manual allowlist opt-in; cut the ban subsystem's on-loop cost (#2577) 2026-08-13 23:22:35 -07:00
pathfinding.md fix(ai): FamiliarAI owns familiar movement and combat; herding reaches its tile; ForcedAI read once (#2644) 2026-09-14 23:14:30 -07:00
platform-prerequisites.md fix: Require only runtime packages on Linux, and check ICU and tzdata the way the runtime does (#2561) 2026-08-07 15:03:08 -07:00
property-lists.md fix(opl): refuse property list invalidation raised from inside GetProperties (#2555) 2026-07-28 21:29:03 -07:00
regions.md chore: Adds AI instructions and SKILLs for ModernUO codebase (#2347) 2026-03-01 11:42:19 -08:00
serialization.md docs: update serialization docs and skills for generator v4 (#2588) 2026-08-22 18:29:27 -07:00
server-lifecycle.md refactor(server): unify first-boot prompts into the ConfigurePrompts phase (#2477) 2026-06-08 05:18:46 -07:00
server-requirements.md feat(network): lean base pools (#2641) 2026-09-20 00:24:15 -07:00
string-handling.md docs(messages): document interpolation anti-patterns and :L format spec (#2441) 2026-05-03 18:23:50 -07:00
t2a-crafting.md feat: Pre-Publish 14 Crafting (supersedes #2181, #2381) (#2476) 2026-06-07 20:27:22 -07:00
threading-model.md perf(login): run password hashing on a parked worker thread (#2566) 2026-08-09 00:13:34 -07:00
tick-counts.md perf: Sleep the event loop when idle. Fixes networking micro-stalls. Adds event loop instrumentation. (#2559) 2026-08-09 13:24:59 -07:00
timers.md docs: update serialization docs and skills for generator v4 (#2588) 2026-08-22 18:29:27 -07:00