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).
This commit is contained in:
Kamron Batman 2026-09-22 18:48:13 -07:00 • committed by GitHub
parent 29a3ab1bd4
commit 502c3f6aa4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 96 additions and 31 deletions

View file

@ -131,21 +131,51 @@ public abstract partial class BaseAI
}
}
public virtual void OnAggressiveAction(Mobile aggressor)
/// <summary>
/// The retaliation policy: how the creature answers <paramref name="aggressor"/>. Returns false when it
/// stands down, and <see cref="BaseCreature.AggressiveAction"/> then skips its combat bookkeeping.
/// </summary>
public virtual bool OnAggressiveAction(Mobile aggressor)
{
// Only a creature somebody can command has been told anything; wild creatures rest on None.
var toldToStandDown = Mobile.Controlled && Mobile.ControlMaster != null && Mobile.Commandable &&
IsStandDownOrder(Mobile.ControlOrder);
if (Mobile.StandsDownOnCommand && toldToStandDown)
{
DebugSay("I'm being attacked but my master told me not to fight.");
Mobile.Warmode = false;
return false;
}
PreferCloserAggressor(aggressor);
if (aggressor.ChangingCombatant && toldToStandDown)
{
// With stand-down off, a resting pet answers a direct attack with a full Attack order.
Mobile.IssueOrder(OrderType.Attack, null, aggressor);
}
else if (Mobile.Combatant == null && !Mobile.BardPacified)
{
Mobile.Warmode = true;
Mobile.Combatant = aggressor;
}
return true;
}
// A visible aggressor closer than the current combatant takes over.
protected void PreferCloserAggressor(Mobile aggressor)
{
if (aggressor.Hidden)
{
return;
}
var currentCombat = Mobile.Combatant;
var current = Mobile.Combatant;
if (currentCombat == null || currentCombat == aggressor)
{
return;
}
if (Mobile.GetDistanceToSqrt(aggressor) < Mobile.GetDistanceToSqrt(currentCombat))
if (current != null && current != aggressor &&
Mobile.GetDistanceToSqrt(aggressor) < Mobile.GetDistanceToSqrt(current))
{
Mobile.Combatant = aggressor;
}

View file

@ -47,21 +47,25 @@ public class FamiliarAI : BaseAI
return Mobile.Controlled ? OrderType.Come : OrderType.None;
}
public override void OnAggressiveAction(Mobile aggressor)
// No orders to stand down on; never fights for a hidden caster.
public override bool OnAggressiveAction(Mobile aggressor)
{
if (!Familiar.AssistsMaster || aggressor.Hidden || Familiar.ControlMaster?.Hidden == true)
{
return;
return false;
}
if (Mobile.Combatant == null)
{
Mobile.Warmode = true;
Mobile.Combatant = aggressor;
return;
}
else
{
PreferCloserAggressor(aggressor);
}
base.OnAggressiveAction(aggressor);
return true;
}
private bool Act()

View file

@ -2735,18 +2735,12 @@ namespace Server.Mobiles
aggressor.Aggressors.Add(AggressorInfo.Create(this, aggressor, true));
}
var toldToStandDown = _controlled && _controlMaster != null && Commandable &&
BaseAI.IsStandDownOrder(_controlOrder);
if (StandsDownOnCommand && toldToStandDown)
// The AI owns the retaliation policy; a creature that stands down keeps its flee and acquire state.
if (AIObject?.OnAggressiveAction(aggressor) != true)
{
AIObject?.DebugSay("I'm being attacked but my master told me not to fight.");
Warmode = false;
return;
}
AIObject?.OnAggressiveAction(aggressor);
StopFlee();
ForceReacquire();
@ -2760,17 +2754,6 @@ namespace Server.Mobiles
pl.FinishShield();
}
}
// Only reachable when the pet does not stand down: the orders above returned early.
if (aggressor.ChangingCombatant && toldToStandDown)
{
IssueOrder(OrderType.Attack, null, aggressor);
}
else if (Combatant == null && !BardPacified)
{
Warmode = true;
Combatant = aggressor;
}
}
public override bool OnMoveOver(Mobile m)