feat: event-driven target acquisition with a reaction-time gradient (#2601)

Fixes walk-up aggro latency (up to a full 10 s of obliviousness) and hardens the reacquire gate so no state can silence acquisition, while turning `AcquireOnApproach` into the reaction-time knob for future per-creature intelligence tuning.

### Why

`AcquireFocusMob` re-armed the 10 s `ReacquireDelay` **before** scanning, success or failure. A creature that scanned an empty room was blind for 10 s to a player walking up — walk-up aggro latency was uniform in 0..10 s. Waking from sector sleep stacked the AI timer's 0–3 s construction stagger on top. And `NextReacquireTime` is not serialized: on hosts whose tick counter starts negative (GCP pass-through), the 0 default blocked **all** acquisition shard-wide after a restart until the counter crossed zero.

### What

**Event-driven reaction — `AcquireOnApproachDelay` (the intelligence gradient)**
- The paragon `AcquireOnApproach` bool becomes a `TimeSpan` on every creature: an enemy moving inside `AcquireOnApproachRange` (10 for all creatures — on-screen reactive aggro; the periodic scan keeps the wide `RangePerception` sweep) *clamps* the next scan to at most the delay. Repeated steps cannot shorten it further — one scan per delay period, not per step or think.
- `Zero` (paragons) also prods the AI timer: the ranked scan engages within a wheel turn — the old snap, minus the special-cased engage path. The target now comes from the normal FightMode ranking instead of whichever mobile happened to move, and the `Combatant == null` guard stops re-engage spam.
- The 2 s default reads as "took a beat to notice you"; larger values are dumber; `ReacquireDelay` alone is the oblivious floor. Mover checks are the approach logic's `IsEnemy` + `CanBeHarmful` (so pets count and hidden movers are excluded via `CanSee`), with `IsEnemy` first to cheaply reject same-team wild creatures wandering past. The check rides the `OnMovement` callback every step already pays for — no polling added.

**Gate correctness**
- Every scan re-arms the full `ReacquireDelay`, success or failure (classic semantics; reaction time is the approach path, not the poll).
- Self-healing by construction: a deadline further out than `ReacquireDelay` is an illegal state and reads as open — no wedged or wrapped value can silence acquisition beyond one delay period.
- `NextReacquireTime` is seeded from a live tick on deserialize (the GCP negative-tick blackout).

**AI timer wake**
- Activation (sector wake, spawn, resurrection) starts within a 0–256 ms spread instead of the 0–3 s construction stagger, which read as lag.
- The stagger's real job — keeping same-speed cohorts out of lock-step (the RunUO town artifact) — is now a zero-mean ±period/8 jitter on each **idle** think, so phases random-walk apart within seconds and can never re-lock. Instrumentation showed why a one-shot spread can't do this job: the timer wheel fires within ±1 ms, so with 10 creatures on a 500 ms period some pair collides on nearly the same phase ~75% of the time (birthday paradox) and then steps in the same loop iteration *forever*. Jitter is scoped to passive speed: engaged cadence stays exact, since pursuit timing anchors to real step times.

**Debug**
- The `AcquireFocusMob` scan message no longer re-arms the shared 5 s debug cooldown, which swallowed every AI's "I have detected X" transition line.

**API change** for custom scripts: `AcquireOnApproach` (bool) → `AcquireOnApproachDelay` (TimeSpan). Documented in `content-patterns.md` § Target Acquisition, `runuo-migration-docs/09` + `11`, and the migration skill checklist.

### Tests

`AcquisitionTests`: both scan outcomes honor `ReacquireDelay`; a 60 s-wedged gate still acquires; enemy movement clamps the deadline (same-team wild movers and out-of-range movers ignored); repeated movement cannot shorten below the delay; `Zero` opens the gate and prods without a direct engage. Full suite: 755 UOContent green.
This commit is contained in:
Kamron Batman 2026-09-01 20:42:15 -07:00 • committed by GitHub
parent 547c2ea0fa
commit d3bf283e2d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 340 additions and 43 deletions

View file

@ -0,0 +1,211 @@
using System;
using System.Collections.Generic;
using Server;
using Server.Mobiles;
using Xunit;
namespace UOContent.Tests.Mobiles.AI;
// Pins the reacquire gate and the AcquireOnApproachDelay gradient: every scan re-arms the
// full ReacquireDelay; enemy movement clamps the deadline to the approach delay (Zero =
// prodded scan); an illegal deadline self-heals.
[Collection("Sequential Pathfinding Tests")]
public class AcquisitionTests : IDisposable
{
private readonly List<Mobile> _created = new();
public void Dispose()
{
foreach (var m in _created)
{
m?.Delete();
}
_created.Clear();
}
private sealed class WildStub : BaseCreature
{
public WildStub() : base(AIType.AI_Melee, FightMode.Closest, 16, 1) => Body = 0xC9;
public override void GetSpeeds(out double activeSpeed, out double passiveSpeed)
{
activeSpeed = 0.3;
passiveSpeed = 0.6;
}
}
private sealed class TargetStub : Mobile
{
public TargetStub() => Body = 0x190;
}
private WildStub Spawn(Map map, Point3D loc)
{
var bc = new WildStub();
bc.MoveToWorld(loc, map);
bc.AIObject.AITimer?.Stop();
_created.Add(bc);
return bc;
}
[Fact]
public void EmptyScan_HonorsReacquireDelay()
{
var map = Map.Maps[1];
Assert.NotNull(map);
map.GetAverageZ(1500, 1600, out _, out var z, out _);
var bc = Spawn(map, new Point3D(1500, 1600, (sbyte)z));
bc.NextReacquireTime = Core.TickCount;
Assert.False(bc.AIObject.AcquireFocusMob(bc.RangePerception, FightMode.Closest, false, false, true));
Assert.InRange(bc.NextReacquireTime - Core.TickCount, 5000, 10000);
}
[Fact]
public void WedgedGate_SelfHeals()
{
var map = Map.Maps[1];
Assert.NotNull(map);
map.GetAverageZ(1500, 1600, out _, out var z, out _);
var bc = Spawn(map, new Point3D(1500, 1600, (sbyte)z));
var target = new TargetStub();
target.DefaultMobileInit();
target.MoveToWorld(new Point3D(1497, 1600, (sbyte)z), map);
_created.Add(target);
// Illegal deadline (beyond ReacquireDelay): must read as open, not block forever.
bc.NextReacquireTime = Core.TickCount + 60000;
Assert.True(bc.AIObject.AcquireFocusMob(bc.RangePerception, FightMode.Closest, false, false, true));
Assert.Equal(target, bc.FocusMob);
}
[Theory]
[InlineData(false, 5, true)] // an enemy moving inside approach range (10) clamps the deadline
[InlineData(true, 5, false)] // a same-team wild creature is not an enemy — ignored
[InlineData(false, 12, false)] // inside RangePerception but outside approach range — poll only
[InlineData(false, 20, false)] // outside approach range (10) is ignored
public void MovementClampsScanDeadlineOnlyForEnemiesInRange(bool wildMover, int distance, bool notices)
{
var map = Map.Maps[1];
Assert.NotNull(map);
map.GetAverageZ(1500, 1600, out _, out var z, out _);
var bc = Spawn(map, new Point3D(1500, 1600, (sbyte)z));
bc.NextReacquireTime = Core.TickCount + 8000;
Mobile mover;
if (wildMover)
{
mover = Spawn(map, new Point3D(1500 - distance, 1600, (sbyte)z));
}
else
{
mover = new TargetStub { Player = true };
mover.DefaultMobileInit();
mover.MoveToWorld(new Point3D(1500 - distance, 1600, (sbyte)z), map);
_created.Add(mover);
}
bc.OnMovement(mover, new Point3D(1400, 1600, (sbyte)z));
var remaining = bc.NextReacquireTime - Core.TickCount;
if (notices)
{
// Clamped to the approach delay (2s), never opened outright.
Assert.InRange(remaining, 1, (long)bc.AcquireOnApproachDelay.TotalMilliseconds);
}
else
{
Assert.True(remaining > 5000);
}
}
private sealed class InstantStub : BaseCreature
{
public InstantStub() : base(AIType.AI_Melee, FightMode.Closest, 16, 1) => Body = 0xC9;
public override TimeSpan AcquireOnApproachDelay => TimeSpan.Zero;
public override void GetSpeeds(out double activeSpeed, out double passiveSpeed)
{
activeSpeed = 0.3;
passiveSpeed = 0.6;
}
}
[Fact]
public void ZeroApproachDelay_OpensGateImmediately()
{
var map = Map.Maps[1];
Assert.NotNull(map);
map.GetAverageZ(1500, 1600, out _, out var z, out _);
var bc = new InstantStub();
bc.MoveToWorld(new Point3D(1500, 1600, (sbyte)z), map);
bc.AIObject.AITimer?.Stop();
_created.Add(bc);
bc.NextReacquireTime = Core.TickCount + 8000;
var mover = new TargetStub { Player = true };
mover.DefaultMobileInit();
mover.MoveToWorld(new Point3D(1495, 1600, (sbyte)z), map);
_created.Add(mover);
bc.OnMovement(mover, new Point3D(1400, 1600, (sbyte)z));
// Zero = the gate opens and the AI is prodded to think now; no direct engage.
Assert.True(Core.TickCount - bc.NextReacquireTime >= 0);
Assert.Null(bc.Combatant);
Assert.True(bc.AIObject.AITimer.Running);
}
[Fact]
public void RepeatedMovement_DoesNotShortenBelowApproachDelay()
{
var map = Map.Maps[1];
Assert.NotNull(map);
map.GetAverageZ(1500, 1600, out _, out var z, out _);
var bc = Spawn(map, new Point3D(1500, 1600, (sbyte)z));
bc.NextReacquireTime = Core.TickCount + 8000;
var mover = new TargetStub { Player = true };
mover.DefaultMobileInit();
mover.MoveToWorld(new Point3D(1495, 1600, (sbyte)z), map);
_created.Add(mover);
bc.OnMovement(mover, new Point3D(1400, 1600, (sbyte)z));
var afterFirst = bc.NextReacquireTime;
bc.OnMovement(mover, new Point3D(1496, 1600, (sbyte)z));
Assert.Equal(afterFirst, bc.NextReacquireTime);
}
[Fact]
public void SuccessfulAcquire_HoldsFullDelay()
{
var map = Map.Maps[1];
Assert.NotNull(map);
map.GetAverageZ(1500, 1600, out _, out var z, out _);
var bc = Spawn(map, new Point3D(1500, 1600, (sbyte)z));
var target = new TargetStub();
target.DefaultMobileInit();
target.MoveToWorld(new Point3D(1497, 1600, (sbyte)z), map);
_created.Add(target);
bc.NextReacquireTime = Core.TickCount;
Assert.True(bc.AIObject.AcquireFocusMob(bc.RangePerception, FightMode.Closest, false, false, true));
Assert.Equal(target, bc.FocusMob);
Assert.True(bc.NextReacquireTime - Core.TickCount > 5000);
}
}

View file

@ -17,7 +17,7 @@ public class ArcherAI : BaseAI
if (AcquireFocusMob(Mobile.RangePerception, Mobile.FightMode, false, false, true)) if (AcquireFocusMob(Mobile.RangePerception, Mobile.FightMode, false, false, true))
{ {
this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name} and I will attack"); this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name}, attacking");
Mobile.Combatant = Mobile.FocusMob; Mobile.Combatant = Mobile.FocusMob;
Action = ActionType.Combat; Action = ActionType.Combat;

View file

@ -31,8 +31,8 @@ public sealed class AITimer : Timer
private int _detectHiddenMinDelay; private int _detectHiddenMinDelay;
private int _detectHiddenMaxDelay; private int _detectHiddenMaxDelay;
public AITimer(BaseAI owner) : base(TimeSpan.FromMilliseconds(Utility.Random(3000)), // The initial delay is irrelevant: Activate is the only start path and sets its own.
TimeSpan.FromSeconds(owner.Mobile.CurrentSpeed)) public AITimer(BaseAI owner) : base(TimeSpan.Zero, TimeSpan.FromSeconds(owner.Mobile.CurrentSpeed))
{ {
_owner = owner; _owner = owner;
_owner._nextDetectHidden = Core.TickCount; _owner._nextDetectHidden = Core.TickCount;
@ -48,7 +48,11 @@ public sealed class AITimer : Timer
return; return;
} }
Start(); // keeps the stagger Delay // Short random spread: the creature responds within a think while a sector's
// worth of timers avoids a same-tick burst; the idle think jitter keeps the
// cohort apart from there.
Delay = TimeSpan.FromMilliseconds(Utility.Random(256));
Start();
_nextWake = Core.TickCount + (long)Delay.TotalMilliseconds; _nextWake = Core.TickCount + (long)Delay.TotalMilliseconds;
} }
@ -148,7 +152,18 @@ public sealed class AITimer : Timer
} }
// Cadence from the post-decision speed (decisions may flip active/passive). // Cadence from the post-decision speed (decisions may flip active/passive).
_nextThink = Core.TickCount + (long)(_owner.Mobile.CurrentSpeed * 1000); var period = (long)(_owner.Mobile.CurrentSpeed * 1000);
_nextThink = Core.TickCount + period;
// Idle cadence drifts: a zero-mean jitter random-walks think phases apart, so
// creatures spawned or woken together cannot stay in lock-step (a one-shot
// spread can collide and identical periods never separate). Engaged cadence
// stays exact — pursuit timing anchors to real step times.
if (_owner.Mobile.CurrentSpeed == _owner.Mobile.PassiveSpeed)
{
var jitter = (int)(period >> 3);
_nextThink += Utility.RandomMinMax(-jitter, jitter);
}
} }
else else
{ {

View file

@ -850,22 +850,24 @@ public abstract partial class BaseAI
return false; return false;
} }
if (Core.TickCount - Mobile.NextReacquireTime < 0) var reacquireDelay = (long)Mobile.ReacquireDelay.TotalMilliseconds;
var gateRemaining = Mobile.NextReacquireTime - Core.TickCount;
if (gateRemaining > 0 && gateRemaining <= reacquireDelay)
{ {
Mobile.FocusMob = null; Mobile.FocusMob = null;
return false; return false;
} }
Mobile.NextReacquireTime = Core.TickCount + (int)Mobile.ReacquireDelay.TotalMilliseconds; DebugSay("Acquiring new target...", 0);
DebugSay("Acquiring new target..."); var acquired = AcquireNewFocusMob(Mobile.Map, iRange, acqType, bPlayerOnly, bFacFriend, bFacFoe);
if (Mobile.Map == null) // Reaction time is the approach path (BaseCreature.ScheduleAcquireOnApproach),
{ // not this poll — every scan honors the full delay.
return Mobile.FocusMob != null; Mobile.NextReacquireTime = Core.TickCount + reacquireDelay;
}
return AcquireNewFocusMob(Mobile.Map, iRange, acqType, bPlayerOnly, bFacFriend, bFacFoe); return acquired;
} }
private bool HandleBardProvoked() private bool HandleBardProvoked()
@ -941,8 +943,10 @@ public abstract partial class BaseAI
private bool AcquireNewFocusMob(Map map, int iRange, FightMode acqType, bool bPlayerOnly, bool bFacFriend, bool bFacFoe) private bool AcquireNewFocusMob(Map map, int iRange, FightMode acqType, bool bPlayerOnly, bool bFacFriend, bool bFacFoe)
{ {
Mobile newFocusMob = null, enemySummonMob = null; Mobile newFocusMob = null;
double val = double.MinValue, enemySummonVal = double.MinValue; Mobile enemySummonMob = null;
var val = double.MinValue;
var enemySummonVal = double.MinValue;
foreach (var m in map.GetMobilesInRange(Mobile.Location, iRange)) foreach (var m in map.GetMobilesInRange(Mobile.Location, iRange))
{ {

View file

@ -12,7 +12,7 @@ public class BerserkAI : BaseAI
if (AcquireFocusMob(Mobile.RangePerception, FightMode.Closest, false, true, true)) if (AcquireFocusMob(Mobile.RangePerception, FightMode.Closest, false, true, true))
{ {
this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name} and I will attack"); this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name}, attacking");
Mobile.Combatant = Mobile.FocusMob; Mobile.Combatant = Mobile.FocusMob;
Action = ActionType.Combat; Action = ActionType.Combat;

View file

@ -1,3 +1,5 @@
using System.Runtime.CompilerServices;
namespace Server.Mobiles; namespace Server.Mobiles;
public class MeleeAI : BaseAI public class MeleeAI : BaseAI
@ -14,6 +16,7 @@ public class MeleeAI : BaseAI
if (AcquireFocusMob(Mobile.RangePerception, Mobile.FightMode, false, false, true)) if (AcquireFocusMob(Mobile.RangePerception, Mobile.FightMode, false, false, true))
{ {
this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name}, attacking"); this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name}, attacking");
Mobile.Combatant = Mobile.FocusMob; Mobile.Combatant = Mobile.FocusMob;
Action = ActionType.Combat; Action = ActionType.Combat;
} }
@ -65,13 +68,9 @@ public class MeleeAI : BaseAI
return true; return true;
} }
private bool IsValidCombatant(Mobile combatant) [MethodImpl(MethodImplOptions.AggressiveInlining)]
{ private bool IsValidCombatant(Mobile combatant) =>
return combatant?.Deleted == false combatant?.Deleted == false && combatant.Map == Mobile.Map && combatant.Alive && !combatant.IsDeadBondedPet;
&& combatant.Map == Mobile.Map
&& combatant.Alive
&& !combatant.IsDeadBondedPet;
}
private bool HandleOutOfRangeCombatant(Mobile combatant) private bool HandleOutOfRangeCombatant(Mobile combatant)
{ {
@ -127,7 +126,8 @@ public class MeleeAI : BaseAI
{ {
if (AcquireFocusMob(Mobile.RangePerception, Mobile.FightMode, false, false, true)) if (AcquireFocusMob(Mobile.RangePerception, Mobile.FightMode, false, false, true))
{ {
this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name}, attacking."); this.DebugSayFormatted($"I have detected {Mobile.FocusMob.Name}, attacking");
Mobile.Combatant = Mobile.FocusMob; Mobile.Combatant = Mobile.FocusMob;
Action = ActionType.Combat; Action = ActionType.Combat;
} }

View file

@ -936,21 +936,50 @@ namespace Server.Mobiles
public virtual bool GivesMLMinorArtifact => false; public virtual bool GivesMLMinorArtifact => false;
/* To save on cpu usage, RunUO creatures only reacquire creatures under the following circumstances:
* - 10 seconds have elapsed since the last time it tried
* - The creature was attacked
* - Some creatures, like dragons, will reacquire when they see someone move
*
* This functionality appears to be implemented on OSI as well
*/
public long NextReacquireTime { get; set; } public long NextReacquireTime { get; set; }
public virtual TimeSpan ReacquireDelay => TimeSpan.FromSeconds(10.0); public virtual TimeSpan ReacquireDelay => TimeSpan.FromSeconds(10.0);
public virtual bool ReacquireOnMovement => false;
public virtual bool AcquireOnApproach => m_Paragon; // Reaction-time gradient: an enemy moving inside AcquireOnApproachRange pulls the
// next scan to at most this far away. Zero (paragons) scans on the very next
// think; larger is dumber; pure ReacquireDelay is the oblivious floor.
public virtual TimeSpan AcquireOnApproachDelay => m_Paragon ? TimeSpan.Zero : TimeSpan.FromSeconds(2.0);
// Reactive range is tighter than the periodic scan's RangePerception: approach
// aggro starts on-screen; the ReacquireDelay poll keeps the wide ambient sweep.
public virtual int AcquireOnApproachRange => 10; public virtual int AcquireOnApproachRange => 10;
// Clamps the scan deadline rather than opening the gate: repeated steps cannot
// shorten it further, so an armed creature scans once per delay period.
private void ScheduleAcquireOnApproach()
{
var delay = (long)AcquireOnApproachDelay.TotalMilliseconds;
var deadline = Core.TickCount + delay;
if (deadline - NextReacquireTime < 0)
{
NextReacquireTime = deadline;
}
if (delay <= 0)
{
// Zero: think now — the ranked scan engages within a wheel turn. Prod is
// spam-safe; the Combatant == null guard stops the prods once engaged.
AIObject?.AITimer?.Prod();
}
}
// IsEnemy first — it cheaply rejects the common case (a same-team wild creature
// wandering past); CanBeHarmful covers hidden movers via CanSee.
private bool ShouldAcquireOnApproach(Mobile m) =>
Combatant == null &&
!Controlled && !Summoned && !BardPacified &&
FightMode != FightMode.None && FightMode != FightMode.Aggressor &&
InRange(m.Location, AcquireOnApproachRange) &&
IsEnemy(m) && CanBeHarmful(m, false);
public virtual bool ReacquireOnMovement => false;
public static bool Summoning { get; set; } public static bool Summoning { get; set; }
public virtual bool IsDispellable => Summoned && !IsAnimatedDead; public virtual bool IsDispellable => Summoned && !IsAnimatedDead;
@ -2024,6 +2053,8 @@ namespace Server.Mobiles
{ {
base.Deserialize(reader); base.Deserialize(reader);
NextReacquireTime = Core.TickCount;
var version = reader.ReadInt(); var version = reader.ReadInt();
m_CurrentAI = (AIType)reader.ReadInt(); m_CurrentAI = (AIType)reader.ReadInt();
@ -2855,15 +2886,9 @@ namespace Server.Mobiles
public override void OnMovement(Mobile m, Point3D oldLocation) public override void OnMovement(Mobile m, Point3D oldLocation)
{ {
if (AcquireOnApproach && !Controlled && !Summoned && !BardPacified && FightMode != FightMode.Aggressor) if (ShouldAcquireOnApproach(m))
{ {
if (InRange(m.Location, AcquireOnApproachRange) && !InRange(oldLocation, AcquireOnApproachRange) && ScheduleAcquireOnApproach();
CanBeHarmful(m) && IsEnemy(m))
{
Combatant = FocusMob = m;
AIObject?.MoveTo(m, 1);
DoHarmful(m);
}
} }
else if (ReacquireOnMovement) else if (ReacquireOnMovement)
{ {

View file

@ -30,6 +30,7 @@ description: >
- `Name = "text"` -> `public override string DefaultName => "text";` - `Name = "text"` -> `public override string DefaultName => "text";`
- Expression-bodied overrides: `public override int Meat { get { return 1; } }` -> `public override int Meat => 1;` - Expression-bodied overrides: `public override int Meat { get { return 1; } }` -> `public override int Meat => 1;`
- AI movement calls lose the `run` flag: `MoveTo(m, true, range)` -> `MoveTo(m, range)` (also `WalkMobileRange`, `ApproachTarget`, `MoveToPoint`, `PathFollower.Follow`); the Running bit is derived from step pace -> `dev-docs/runuo-migration-docs/09-items-mobiles-creatures.md` § AI Movement - AI movement calls lose the `run` flag: `MoveTo(m, true, range)` -> `MoveTo(m, range)` (also `WalkMobileRange`, `ApproachTarget`, `MoveToPoint`, `PathFollower.Follow`); the Running bit is derived from step pace -> `dev-docs/runuo-migration-docs/09-items-mobiles-creatures.md` § AI Movement
- `AcquireOnApproach` (bool) -> `AcquireOnApproachDelay` (TimeSpan; `Zero` = old instant behavior) -> same doc § Target Acquisition
## Anti-Patterns ## Anti-Patterns
- Using `_field--` instead of `Property--` (bypasses MarkDirty tracking) - Using `_field--` instead of `Property--` (bypasses MarkDirty tracking)

View file

@ -29,7 +29,9 @@ description: >
overridden). Prefer `npc-speeds.json` buckets (`SpeedClass`); `SetSpeed()` sets think overridden). Prefer `npc-speeds.json` buckets (`SpeedClass`); `SetSpeed()` sets think
AND clears move overrides, `SetMoveSpeed()` sets move only. The client `Running` bit is AND clears move overrides, `SetMoveSpeed()` sets move only. The client `Running` bit is
derived from the step pace (`BaseAI.ShouldRun`); movement APIs take no run argument -- derived from the step pace (`BaseAI.ShouldRun`); movement APIs take no run argument --
see `dev-docs/content-patterns.md` § Creature Speeds see `dev-docs/content-patterns.md` § Creature Speeds. Reaction time to approaching
enemies is `AcquireOnApproachDelay` (TimeSpan gradient; `Zero` = paragon snap, 2s
default, `ReacquireDelay`-only = oblivious) -- see § Target Acquisition
8. **`OnThink` overrides must be excess-call tolerant** -- it fires more often than the 8. **`OnThink` overrides must be excess-call tolerant** -- it fires more often than the
think cadence (player commands prod it; speed-ups reschedule it). Gate consequential think cadence (player commands prod it; speed-ups reschedule it). Gate consequential
work on a tick-count deadline (subtraction form) or make it idempotent; bare per-call work on a tick-count deadline (subtraction form) or make it idempotent; bare per-call

View file

@ -295,6 +295,24 @@ flood the client's step queue. Movement APIs (`MoveTo`, `WalkMobileRange`,
fast. Creatures step at most once per `CurrentMoveSpeed` period, paced from the step just fast. Creatures step at most once per `CurrentMoveSpeed` period, paced from the step just
taken — a stall never banks catch-up steps, so a resumed chase restarts at full pace. taken — a stall never banks catch-up steps, so a resumed chase restarts at full pace.
### Target Acquisition: the reaction-time gradient
Acquisition is event-driven, not polled. The periodic scan (`AcquireFocusMob`) is gated by
`ReacquireDelay` (10 s default) and every scan re-arms it in full, success or failure — it
is target stickiness plus the fallback for what movement cannot signal (reveals, doors,
summons). Reaction time comes from `BaseCreature.OnMovement`: an enemy moving inside
`AcquireOnApproachRange` (10 — on-screen; the periodic scan keeps the wider
`RangePerception`) clamps the next scan to
at most **`AcquireOnApproachDelay`** — the intelligence gradient. `TimeSpan.Zero`
(paragons) also prods the AI, so the ranked scan engages within a timer-wheel turn; the
2 s default reads as "took a beat to notice you"; larger is dumber; a creature that
overrides the delay above `ReacquireDelay` is effectively oblivious to approach. Repeated
steps cannot shorten the clamp, so an armed creature scans once per delay period, not once
per step or think. `ReacquireOnMovement` remains the broader hook (any mover, no enemy
check, scan next think). The gate self-heals: a deadline further out than `ReacquireDelay`
is illegal and reads as open, so no wedged or wrapped value can silence acquisition beyond
one delay period.
### OnThink: the excess-call contract ### OnThink: the excess-call contract
`OnThink()` is a scheduler pass, not an action. The AI timer calls it *at least* at the `OnThink()` is a scheduler pass, not an action. The AI timer calls it *at least* at the

View file

@ -497,6 +497,26 @@ An isolated step (after the creature stood for at least a walk interval) goes ou
walk regardless of pace — only a continuing cadence, or a pace faster than the run walk regardless of pace — only a continuing cadence, or a pace faster than the run
interpolation, flags run. interpolation, flags run.
## Target Acquisition: `AcquireOnApproach` Is a Delay
RunUO's `AcquireOnApproach` bool (paragon insta-aggro on approach) is now
`AcquireOnApproachDelay`, a `TimeSpan` reaction-time gradient that applies to every
creature — enemy movement inside `AcquireOnApproachRange` schedules a scan within the
delay instead of waiting out the 10 s `ReacquireDelay` poll:
```csharp
// RunUO
public override bool AcquireOnApproach => true;
// ModernUO — Zero is the old instant behavior; larger values are dumber
public override TimeSpan AcquireOnApproachDelay => TimeSpan.Zero;
```
`AcquireOnApproachRange` stays 10 for all creatures (reactive aggro is on-screen; the
periodic `ReacquireDelay` scan still sweeps the full `RangePerception`). The
acquired target comes from the normal FightMode-ranked scan, not from whichever mobile
happened to move. See `content-patterns.md` § Target Acquisition.
## Item Name Changes ## Item Name Changes
```csharp ```csharp

View file

@ -133,6 +133,7 @@ Alphabetical by RunUO API name. Use Ctrl+F / Cmd+F to search.
| `MoveTo(m, run, range)` | `MoveTo(m, range)` | `run` removed; the Running bit is derived from the step pace (`BaseAI.ShouldRun`) | | `MoveTo(m, run, range)` | `MoveTo(m, range)` | `run` removed; the Running bit is derived from the step pace (`BaseAI.ShouldRun`) |
| `WalkMobileRange(m, steps, run, min, max)` | `WalkMobileRange(m, steps, min, max)` | Same | | `WalkMobileRange(m, steps, run, min, max)` | `WalkMobileRange(m, steps, min, max)` | Same |
| `PathFollower.Follow(run, range)` | `Follow(range)` | Same | | `PathFollower.Follow(run, range)` | `Follow(range)` | Same |
| `AcquireOnApproach` (bool) | `AcquireOnApproachDelay` (TimeSpan) | Reaction-time gradient; `Zero` = old instant behavior |
## Networking ## Networking