warrentyexpired/ModernUO
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: expand cache to nearly all mobiles + dynamic-obstacle pass (#2447)

Browse source 
## Summary

Builds on PR #2446's cache-direct A*. The previous PR conservatively routed players + creatures with capability flags entirely through the slow path. This PR pushes that line: most mobile classes now use the cache, with the right rule set layered on top per-mobile, and the cache fast-path now does the dynamic items / mobiles check that PR #2446 had silently skipped.

## What changed

- **Non-GM players** now use the cache. Diagonal corner-cut applies the strict AND-rule (BOTH cardinal partners walkable) by reading the same source-cell mask byte the creature OR-rule reads — both rules are evaluable from one byte.
- **Creatures with `CanOpenDoors` / `CanMoveOverObstacles`** now use the cache. Reading `MovementImpl` confirmed those flags only affect dynamic items, never static tiles, so they were over-conservatively excluded before.
- **Swim creatures** now use the cache via a capability overlay. `StepProbe` bakes a second rule set (`canSwim=true, cantWalk=true`) producing `WetMask` + `SwimZ_*`. The algorithm composes `effectiveMask = (walkMask & !cantWalk) | (wetMask & canSwim)` per direction; walk Z preferred when both apply.
- **Dynamic-obstacle pass.** Cache fast-path now mirrors `MovementImpl`'s per-cell items + mobiles collision check (`GetItemsAt` / `GetMobilesAt` at the target cell, with `CanOpenDoors` / `CanMoveOverObstacles` / spell-field overrides). This closes a correctness gap from PR #2446 — the cache fast-path was silently skipping dynamic obstacles entirely.
- **`StepCache.TryGetMask` returns `StepMask` struct** instead of 11 out parameters. `HitKind` rolls into the struct with an `IsHit` accessor. Sets up wet/swim without ballooning the call site.
- **`StepChunk.MultiZCells` is lazy-init.** Most chunks are entirely single-Z; allocating the 32-byte bitmap up-front wasted ~256KB at full cap.
- **Admin commands.** `[PathCacheStats` (resident chunks + hit/miss/eviction counters) and `[PathCacheClear` (drop everything, zero counters).
- **Feature flag.** `bitmap_pathfinding_cache` (default true) gates the cache fast-path. Flipped off, every cell expansion routes to `MovementImpl` — equivalent to PR #2446's slow-path-only behavior. Safety net for shipping the new behavior.

`RequiresSlowPath` shrinks to just `CanFly` — flying creatures Z-jump arbitrarily, which the cache's static-Z model can't accommodate.
This commit is contained in:
Kamron Batman 2026-05-06 00:14:08 -07:00 • committed by GitHub
parent 6a3804addc
commit 9066e8fd00
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 856 additions and 290 deletions
Download patch file Download diff file Expand all files Collapse all files

311
Projects/UOContent.Tests/Tests/Engines/Pathing/BitmapAStarAlgorithmTests.cs
View file

@ -1,6 +1,7 @@
using Server.Engines.Pathing.Cache;
using Server.Mobiles;
using Server.PathAlgorithms.BitmapAStar;
using Server.Systems.FeatureFlags;
using Xunit;
using Xunit.Abstractions;
@ -54,7 +55,7 @@ public class BitmapAStarAlgorithmTests
[Theory]
[InlineData(1500, 1600, 1498, 1598)] // NW, 2 cells diagonal
[InlineData(1500, 1600, 1497, 1599)] // NW-ish, 3 W + 1 N
public void CapabilityCreature_FindsPath_ViaInlineSlowPath(int sx, int sy, int gx, int gy)
public void SwimCreature_FindsPath_ViaCacheCapabilityOverlay(int sx, int sy, int gx, int gy)
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
@ -62,27 +63,270 @@ public class BitmapAStarAlgorithmTests
var stub = new SwimmingStub(World.NewMobile);
stub.DefaultMobileInit();
stub.CanSwim = true; // forces non-default-walker → inline GetSuccessorsSlowPath
stub.CanSwim = true; // overlay route — cache + (walkMask | wetMask&canSwim)
map.GetAverageZ(sx, sy, out _, out var startZ, out _);
var start = new Point3D(sx, sy, (sbyte)startZ);
var goal = new Point3D(gx, gy, (sbyte)startZ);
stub.MoveToWorld(start, map);
var statsBefore = StepCache.Instance.GetStats();
var result = BitmapAStarAlgorithm.Instance.Find(stub, map, start, goal);
var statsAfter = StepCache.Instance.GetStats();
stub.Delete();
// Capability creature: assert reachability — exact length depends on terrain and
// tie-breaking, but a swimmer should always reach a goal a default walker reaches
// on dry land (CanSwim is permissive, never restrictive).
Assert.NotNull(result);
Assert.NotEmpty(result);
Assert.True(statsAfter.BuildsTotal > statsBefore.BuildsTotal,
"CanSwim creature should use the cache via capability overlay, not the slow path");
_output.WriteLine($"swimmer ({sx},{sy})->({gx},{gy}): {result.Length} steps");
}
[Fact]
public void DynamicObstaclePass_RejectsCellOccupiedByLivingMobile()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
Assert.NotNull(map);
// (1500, 1600) walks N/W/NW only (mask=0xC1). Path NW two cells; plant a blocker
// on the direct NW step so the algorithm must route via N→W or W→N around it.
var sx = 1500;
var sy = 1600;
var gx = 1498;
var gy = 1598;
var blockX = 1499;
var blockY = 1599;
map.GetAverageZ(sx, sy, out _, out var startZ, out _);
var start = new Point3D(sx, sy, (sbyte)startZ);
var goal = new Point3D(gx, gy, (sbyte)startZ);
var walker = new DefaultWalkerStub();
walker.MoveToWorld(start, map);
// Living blocker on the only direct-line cell. CanMoveOver returns false for an
// alive non-staff mobile, so the dynamic-obstacle pass must reject this cell.
map.GetAverageZ(blockX, blockY, out _, out var blockZ, out _);
var blocker = new DefaultWalkerStub();
blocker.MoveToWorld(new Point3D(blockX, blockY, (sbyte)blockZ), map);
var result = BitmapAStarAlgorithm.Instance.Find(walker, map, start, goal);
// Path may exist via an alternate route, but must NOT pass through the blocker.
Assert.NotNull(result);
var x = sx;
var y = sy;
foreach (var dir in result)
{
Server.Movement.Movement.Offset(dir, ref x, ref y);
Assert.False(x == blockX && y == blockY,
$"path traversed blocker cell ({blockX},{blockY})");
}
walker.Delete();
blocker.Delete();
}
[Fact]
public void DynamicObstaclePass_RejectsCellOccupiedByImpassableItem()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
Assert.NotNull(map);
// Same NW-around-blocker scenario as the mobile-blocker test, but with an item.
var sx = 1500;
var sy = 1600;
var gx = 1498;
var gy = 1598;
var blockX = 1499;
var blockY = 1599;
// Find any ItemID whose TileData has ImpassableSurface so the dynamic pass
// rejects the cell. Pinning to a specific ID would couple the test to UO art data.
ushort blockerItemId = 0;
for (ushort id = 1; id < TileData.MaxItemValue; id++)
{
if (TileData.ItemTable[id].ImpassableSurface)
{
blockerItemId = id;
break;
}
}
Assert.NotEqual<ushort>(0, blockerItemId);
map.GetAverageZ(sx, sy, out _, out var startZ, out _);
var start = new Point3D(sx, sy, (sbyte)startZ);
var goal = new Point3D(gx, gy, (sbyte)startZ);
var walker = new DefaultWalkerStub();
walker.MoveToWorld(start, map);
map.GetAverageZ(blockX, blockY, out _, out var blockZ, out _);
var blocker = new Item(World.NewItem)
{
ItemID = blockerItemId,
Map = map,
Location = new Point3D(blockX, blockY, (sbyte)blockZ)
};
var result = BitmapAStarAlgorithm.Instance.Find(walker, map, start, goal);
Assert.NotNull(result);
var x = sx;
var y = sy;
foreach (var dir in result)
{
Server.Movement.Movement.Offset(dir, ref x, ref y);
Assert.False(x == blockX && y == blockY,
$"path traversed item-blocker cell ({blockX},{blockY})");
}
walker.Delete();
blocker.Delete();
}
[Fact]
public void FeatureFlagDisabled_RoutesToSlowPath_NoCacheUse()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
Assert.NotNull(map);
var stub = new DefaultWalkerStub();
map.GetAverageZ(1500, 1600, out _, out var startZ, out _);
var start = new Point3D(1500, 1600, (sbyte)startZ);
var goal = new Point3D(1498, 1598, (sbyte)startZ);
stub.MoveToWorld(start, map);
var statsBefore = StepCache.Instance.GetStats();
var prevFlag = ContentFeatureFlags.BitmapPathfindingCache;
try
{
ContentFeatureFlags.BitmapPathfindingCache = false;
var result = BitmapAStarAlgorithm.Instance.Find(stub, map, start, goal);
Assert.NotNull(result);
Assert.NotEmpty(result);
}
finally
{
ContentFeatureFlags.BitmapPathfindingCache = prevFlag;
}
var statsAfter = StepCache.Instance.GetStats();
stub.Delete();
Assert.Equal(statsBefore.BuildsTotal, statsAfter.BuildsTotal);
}
[Fact]
public void FlyCreature_RoutesToSlowPath_NoCacheUse()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
var stub = new FlyingStub(World.NewMobile);
stub.DefaultMobileInit();
map.GetAverageZ(1500, 1600, out _, out var startZ, out _);
var start = new Point3D(1500, 1600, (sbyte)startZ);
var goal = new Point3D(1498, 1598, (sbyte)startZ);
stub.MoveToWorld(start, map);
var statsBefore = StepCache.Instance.GetStats();
var result = BitmapAStarAlgorithm.Instance.Find(stub, map, start, goal);
var statsAfter = StepCache.Instance.GetStats();
stub.Delete();
Assert.NotNull(result);
Assert.NotEmpty(result);
Assert.Equal(statsBefore.BuildsTotal, statsAfter.BuildsTotal);
}
[Fact]
public void NonGmPlayer_UsesCache_WithStrictDiagonalRule()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
Assert.NotNull(map);
var stub = new PlayerStub();
map.GetAverageZ(1500, 1600, out _, out var startZ, out _);
var start = new Point3D(1500, 1600, (sbyte)startZ);
var goal = new Point3D(1498, 1598, (sbyte)startZ);
stub.MoveToWorld(start, map);
var statsBefore = StepCache.Instance.GetStats();
var result = BitmapAStarAlgorithm.Instance.Find(stub, map, start, goal);
var statsAfter = StepCache.Instance.GetStats();
stub.Delete();
Assert.NotNull(result);
Assert.NotEmpty(result);
// BuildsTotal increments on every chunk build, which happens only when the cache
// is queried. Slow path never touches the cache.
Assert.True(statsAfter.BuildsTotal > statsBefore.BuildsTotal,
"Non-GM player should use the cache, not the slow path");
}
[Fact]
public void DoorCreature_UsesCache_NotSlowPath()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
var stub = new DoorOpenerStub(World.NewMobile);
stub.DefaultMobileInit();
map.GetAverageZ(1500, 1600, out _, out var startZ, out _);
var start = new Point3D(1500, 1600, (sbyte)startZ);
var goal = new Point3D(1498, 1598, (sbyte)startZ);
stub.MoveToWorld(start, map);
var statsBefore = StepCache.Instance.GetStats();
var result = BitmapAStarAlgorithm.Instance.Find(stub, map, start, goal);
var statsAfter = StepCache.Instance.GetStats();
stub.Delete();
Assert.NotNull(result);
Assert.NotEmpty(result);
Assert.True(statsAfter.BuildsTotal > statsBefore.BuildsTotal,
"CanOpenDoors creature should use the cache (doors are dynamic items)");
}
[Fact]
public void ObstacleCreature_UsesCache_NotSlowPath()
{
StepCache.Instance.Clear();
var map = Map.Maps[1];
var stub = new ObstacleClimberStub(World.NewMobile);
stub.DefaultMobileInit();
map.GetAverageZ(1500, 1600, out _, out var startZ, out _);
var start = new Point3D(1500, 1600, (sbyte)startZ);
var goal = new Point3D(1498, 1598, (sbyte)startZ);
stub.MoveToWorld(start, map);
var statsBefore = StepCache.Instance.GetStats();
var result = BitmapAStarAlgorithm.Instance.Find(stub, map, start, goal);
var statsAfter = StepCache.Instance.GetStats();
stub.Delete();
Assert.NotNull(result);
Assert.NotEmpty(result);
Assert.True(statsAfter.BuildsTotal > statsBefore.BuildsTotal,
"CanMoveOverObstacles creature should use the cache (movables are dynamic items)");
}
/// <summary>
/// Plain Mobile — IsDefaultWalker returns true, the bitmap algorithm uses the cache
/// Plain Mobile — RequiresSlowPath returns false, the bitmap algorithm uses the cache
/// fast path on every expansion.
/// </summary>
private sealed class DefaultWalkerStub : Mobile
@ -94,10 +338,23 @@ public class BitmapAStarAlgorithmTests
}
/// <summary>
/// BaseCreature with CanSwim=true — IsDefaultWalker returns false, the bitmap
/// algorithm short-circuits GetSuccessors to GetSuccessorsSlowPath on every cell.
/// Use the Serial constructor (deserialization path) to bypass NPCSpeeds init,
/// which requires the npc-speeds.json table loaded — not available in tests.
/// Mobile with Player=true and default AccessLevel (Player). Triggers the strict
/// AND-rule for diagonal corner-cut while still using the cache.
/// </summary>
private sealed class PlayerStub : Mobile
{
public PlayerStub()
{
Body = 0xC9;
Player = true;
}
}
/// <summary>
/// BaseCreature with CanSwim=true — uses the cache via capability overlay (walk OR
/// (wet AND canSwim)). Use the Serial constructor (deserialization path) to bypass
/// NPCSpeeds init, which requires the npc-speeds.json table loaded — not available
/// in tests.
/// </summary>
private sealed class SwimmingStub : BaseCreature
{
@ -106,4 +363,38 @@ public class BitmapAStarAlgorithmTests
Body = 0xC9;
}
}
/// <summary>
/// BaseCreature with CanFly=true — RequiresSlowPath returns true (Z-jumping is beyond
/// the cache's static-only scope), so GetSuccessors short-circuits to the slow path.
/// </summary>
private sealed class FlyingStub : BaseCreature
{
public FlyingStub(Serial serial) : base(serial)
{
Body = 0xC9;
}
public override bool CanFly => true;
}
private sealed class DoorOpenerStub : BaseCreature
{
public DoorOpenerStub(Serial serial) : base(serial)
{
Body = 0xC9;
}
public override bool CanOpenDoors => true;
}
private sealed class ObstacleClimberStub : BaseCreature
{
public ObstacleClimberStub(Serial serial) : base(serial)
{
Body = 0xC9;
}
public override bool CanMoveOverObstacles => true;
}
}