feat: Replace FastAStarAlgorithm with BitmapAStarAlgorithm (#2446)

## Summary

Replaces `FastAStarAlgorithm` with `BitmapAStarAlgorithm`: one cache lookup per cell expansion (8-direction mask + per-direction destination Z) instead of 8 separate `MovementImpl.CheckMovement` calls. Adds the supporting cache infrastructure to back it.

Public API unchanged — `MovementPath` / `Mobile.Move` / `CalcMoves.Find` return the same shapes; the algorithm swap is internal.

## What's in this PR

- **`BitmapAStarAlgorithm`** — A* that issues one `StepCache.TryGetMask` call per cell expansion. Inline fallthrough to the per-cell slow path for multi-Z, off-map, source-Z mismatch, and non-default walkers.
- **`StepCache`** — singleton chunk store keyed by `(mapId, chunkX, chunkY)`. Lazily built on first query, invalidated by `Sector.MultisVersion` mismatch, memory-bounded by sampled probabilistic LRU.
- **`StepProbe`** — computes static-only walkability for a single cell, mirroring `MovementImpl.Check` minus the item / mobile collision phases.
- **`StepMask` / `StepChunk`** — value / storage types for the per-cell results.
- **`CacheEvictionTimer`** — periodic cap backstop (60s interval; early-returns when not over cap).
- **`Map.Sector.MultisVersion`** promoted to `public` so the cache can detect dynamic-static invalidations cheaply.

## Eviction strategy

Sampled probabilistic LRU (Redis-style). Per eviction, sample 5 random keys from a parallel `List<long>` kept in lockstep with the chunk dictionary; evict the oldest of the sample via swap-and-pop. O(1) per eviction regardless of resident count, so sustained cap pressure has no perpetual perf hit.

## Capability handling (interim)

Non-default walkers (non-GM players, creatures with `CanSwim` / `CanFly` / `CanOpenDoors` / `CanMoveOverObstacles`) route entirely through the per-cell slow path via `BitmapAStarAlgorithm.GetSuccessorsSlowPath`. The 2-pass design (cache + capability overlay + dynamic-obstacle pass) lands in the follow-up PR.

Projects/UOContent/Engines/Pathing/BitmapAStarAlgorithm.cs

@@ -2,7 +2,7 @@
  * ModernUO                                                              *
  * Copyright 2019-2026 - ModernUO Development Team                       *
  * Email: hi@modernuo.com                                                *
- * File: FastAStarAlgorithm.cs                                           *
+ * File: BitmapAStarAlgorithm.cs                                         *
  *                                                                       *
  * This program is free software: you can redistribute it and/or modify  *
  * it under the terms of the GNU General Public License as published by  *
@@ -14,15 +14,24 @@
  ************************************************************************/
 
 using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using Server.Engines.Pathing.Cache;
 using Server.Mobiles;
 using CalcMoves = Server.Movement.Movement;
 using MoveImpl = Server.Movement.MovementImpl;
-using System.Collections.Generic;
-using System.Runtime.CompilerServices;
 
-namespace Server.PathAlgorithms.FastAStar;
+namespace Server.PathAlgorithms.BitmapAStar;
 
-public class FastAStarAlgorithm : PathAlgorithm
+/// <summary>
+/// A* pathfinder with a single bitmap-cache lookup per cell expansion. Default walkers
+/// take one <see cref="StepCache.TryGetMask"/> call returning the 8-direction
+/// mask + per-direction Z. Non-default walkers (non-GM players, creatures with swim/fly/
+/// door/clip capabilities) and per-cell cache fallthroughs route through
+/// <see cref="GetSuccessorsSlowPath"/>, which runs the per-direction
+/// <see cref="CalcMoves.CheckMovement"/> loop for that one cell.
+/// </summary>
+public class BitmapAStarAlgorithm : PathAlgorithm
 {
     private struct PathNode
     {
@@ -40,7 +49,7 @@ public class FastAStarAlgorithm : PathAlgorithm
     private const int PlaneOffset = 128;
     private const int PlaneCount = 13;
     private const int PlaneHeight = 20;
-    public static readonly PathAlgorithm Instance = new FastAStarAlgorithm();
+    public static readonly PathAlgorithm Instance = new BitmapAStarAlgorithm();
 
     private static readonly Direction[] _path = new Direction[AreaSize * AreaSize];
     private static readonly PathNode[] _nodes = new PathNode[NodeCount];
@@ -51,6 +60,10 @@ public class FastAStarAlgorithm : PathAlgorithm
     private static int _xOffset;
     private static int _yOffset;
 
+    // When set, GetSuccessors delegates to the per-cell slow path on every expansion
+    // (preserves player AND-rule and BaseCreature capability overlays). Reset at end of Find.
+    private static bool _currentMobileNeedsSlowPath;
+
     private Point3D _goal;
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -76,6 +89,8 @@ public class FastAStarAlgorithm : PathAlgorithm
             return null;
         }
 
+        _currentMobileNeedsSlowPath = !IsDefaultWalker(m);
+
         Array.Clear(_nodeStates);
 
         _goal = goal;
@@ -120,6 +135,7 @@ public class FastAStarAlgorithm : PathAlgorithm
 
             _nodeStates[bestNode] = 2;
 
+            // Set MovementImpl globals so per-cell slow-path fallthroughs see the right state.
             if (bc != null)
             {
                 MoveImpl.AlwaysIgnoreDoors = bc.CanOpenDoors;
@@ -203,11 +219,13 @@ public class FastAStarAlgorithm : PathAlgorithm
                 }
 
                 _openQueue.Clear();
+                _currentMobileNeedsSlowPath = false;
                 return dirs;
             }
         }
 
         _openQueue.Clear();
+        _currentMobileNeedsSlowPath = false;
         return null;
     }
 
@@ -221,6 +239,13 @@ public class FastAStarAlgorithm : PathAlgorithm
         return x + y * AreaSize + z * AreaSize * AreaSize;
     }
 
+    /// <summary>
+    /// One <see cref="StepCache.TryGetMask"/> call returns the 8-direction
+    /// walkable mask + destination Zs. Diagonal corner-cut applies the lenient creature
+    /// OR-rule using partner bits in the same mask byte — no neighbor-chunk lookup needed.
+    /// On cache fallthrough or for non-default walkers, defers to
+    /// <see cref="GetSuccessorsSlowPath"/> for THIS cell only.
+    /// </summary>
     private static int GetSuccessors(int p, Mobile m, Map map)
     {
         var px = p % AreaSize;
@@ -230,50 +255,94 @@ public class FastAStarAlgorithm : PathAlgorithm
         var p3D = new Point3D(px + _xOffset, py + _yOffset, pz);
 
         var vals = _successors;
+
+        if (_currentMobileNeedsSlowPath)
+        {
+            return GetSuccessorsSlowPath(m, map, px, py, p3D, vals);
+        }
+
+        var count = 0;
+
+        StepCache.Instance.TryGetMask(
+            map, p3D.X, p3D.Y, (sbyte)p3D.Z,
+            out var mask,
+            out var dN, out var dNE, out var dE, out var dSE,
+            out var dS, out var dSW, out var dW, out var dNW,
+            out var hitKind
+        );
+
+        if (hitKind is CacheHitKind.Fallthrough_MultiZ
+            or CacheHitKind.Fallthrough_OffMap
+            or CacheHitKind.Fallthrough_SourceZMismatch)
+        {
+            return GetSuccessorsSlowPath(m, map, px, py, p3D, vals);
+        }
+
+        for (var i = 0; i < 8; ++i)
+        {
+            var x = px;
+            var y = py;
+            CalcMoves.Offset((Direction)i, ref x, ref y);
+
+            if (x is < 0 or >= AreaSize || y is < 0 or >= AreaSize)
+            {
+                continue;
+            }
+
+            if ((mask & (1 << i)) == 0)
+            {
+                continue;
+            }
+
+            // Diagonal corner-cut (creature OR-rule): partner bits live in the same mask byte.
+            if ((i & 1) == 1)
+            {
+                var leftBit = 1 << ((i - 1) & 0x7);
+                var rightBit = 1 << ((i + 1) & 0x7);
+                if ((mask & leftBit) == 0 && (mask & rightBit) == 0)
+                {
+                    continue;
+                }
+            }
+
+            var z = i switch
+            {
+                0 => dN,
+                1 => dNE,
+                2 => dE,
+                3 => dSE,
+                4 => dS,
+                5 => dSW,
+                6 => dW,
+                7 => dNW,
+                _ => (sbyte)0
+            };
+
+            var idx = GetIndex(x + _xOffset, y + _yOffset, z);
+
+            if (idx >= 0 && idx < NodeCount)
+            {
+                _nodes[idx].z = z;
+                vals[count++] = idx;
+            }
+        }
+
+        return count;
+    }
+
+    /// <summary>
+    /// Per-direction <see cref="CalcMoves.CheckMovement"/> loop for a single source cell.
+    /// Runs on cache fallthrough or when <see cref="_currentMobileNeedsSlowPath"/> is set.
+    /// </summary>
+    private static int GetSuccessorsSlowPath(Mobile m, Map map, int px, int py, Point3D p3D, int[] vals)
+    {
         var count = 0;
 
         for (var i = 0; i < 8; ++i)
         {
-            int x;
-            int y;
-            switch (i)
-            {
-                default: // 0
-                    x = 0;
-                    y = -1;
-                    break;
-                case 1:
-                    x = 1;
-                    y = -1;
-                    break;
-                case 2:
-                    x = 1;
-                    y = 0;
-                    break;
-                case 3:
-                    x = 1;
-                    y = 1;
-                    break;
-                case 4:
-                    x = 0;
-                    y = 1;
-                    break;
-                case 5:
-                    x = -1;
-                    y = 1;
-                    break;
-                case 6:
-                    x = -1;
-                    y = 0;
-                    break;
-                case 7:
-                    x = -1;
-                    y = -1;
-                    break;
-            }
-
-            x += px;
-            y += py;
+            var x = px;
+            var y = py;
+            CalcMoves.Offset((Direction)i, ref x, ref y);
 
             if (x is < 0 or >= AreaSize || y is < 0 or >= AreaSize)
             {
@@ -294,4 +363,24 @@ public class FastAStarAlgorithm : PathAlgorithm
 
         return count;
     }
+
+    /// <summary>
+    /// Default walker = the cache's baked rules apply directly (lenient OR-rule for
+    /// diagonal corner-cut, no capability overlays). Non-GM players (strict AND-rule)
+    /// and creatures with swim/fly/door/clip capabilities require the slow path.
+    /// </summary>
+    private static bool IsDefaultWalker(Mobile m)
+    {
+        if (m.Player && m.AccessLevel < AccessLevel.GameMaster)
+        {
+            return false;
+        }
+
+        if (m is not BaseCreature bc)
+        {
+            return true;
+        }
+
+        return !bc.CanSwim && !bc.CanFly && !bc.CanOpenDoors && !bc.CanMoveOverObstacles;
+    }
 }

Projects/UOContent/Engines/Pathing/Cache/CacheEvictionTimer.cs

@@ -0,0 +1,31 @@
+using System;
+
+namespace Server.Engines.Pathing.Cache;
+
+/// <summary>
+/// Periodic backstop that enforces the StaticWalkabilityCache resident-chunk cap.
+/// Steady-state cost is a single early-return; only fires real work when the cache
+/// has overflowed MaxResidentChunks. Runs on the game thread; no locking required.
+/// </summary>
+public class CacheEvictionTimer : Timer
+{
+    private static CacheEvictionTimer _instance;
+
+    public static void Configure()
+    {
+        if (_instance != null)
+        {
+            return;
+        }
+
+        _instance = new CacheEvictionTimer();
+        _instance.Start();
+    }
+
+    private CacheEvictionTimer() : base(TimeSpan.FromSeconds(60), TimeSpan.FromSeconds(60)) { }
+
+    protected override void OnTick()
+    {
+        StepCache.Instance.EnforceLruCap();
+    }
+}

Projects/UOContent/Engines/Pathing/Cache/CacheHitKind.cs

@@ -0,0 +1,15 @@
+namespace Server.Engines.Pathing.Cache;
+
+/// <summary>
+/// Outcome categories for StaticWalkabilityCache.TryGetMask. Used for telemetry
+/// and to drive the slow-path fallthrough decision in callers.
+/// </summary>
+public enum CacheHitKind : byte
+{
+    Hit = 0,                         // clean default-walker answer from the resident chunk
+    Miss_NotBuilt = 1,               // chunk wasn't resident; built and returned
+    Miss_DirtyRebuild = 2,           // version mismatch; rebuilt and returned
+    Fallthrough_MultiZ = 3,          // cell has multiple walkable surfaces; caller must use slow path
+    Fallthrough_OffMap = 4,          // out of bounds
+    Fallthrough_SourceZMismatch = 5, // |loc.Z - BakedSourceZ| > StepHeight; cache answer would diverge
+}

Projects/UOContent/Engines/Pathing/Cache/CacheStats.cs

@@ -0,0 +1,28 @@
+namespace Server.Engines.Pathing.Cache;
+
+/// <summary>
+/// Snapshot of StaticWalkabilityCache counters. Returned by GetStats() and consumed
+/// by the [PathCacheStats admin command. All counters are monotonic except ResidentChunks.
+/// </summary>
+public readonly struct CacheStats(
+    int residentChunks,
+    long hits,
+    long missesNotBuilt,
+    long missesDirtyRebuild,
+    long fallthroughMultiZ,
+    long fallthroughOffMap,
+    long fallthroughSourceZMismatch,
+    long evictionsByLruCap,
+    long buildsTotal
+)
+{
+    public readonly int ResidentChunks = residentChunks;
+    public readonly long Hits = hits;
+    public readonly long MissesNotBuilt = missesNotBuilt;
+    public readonly long MissesDirtyRebuild = missesDirtyRebuild;
+    public readonly long FallthroughMultiZ = fallthroughMultiZ;
+    public readonly long FallthroughOffMap = fallthroughOffMap;
+    public readonly long FallthroughSourceZMismatch = fallthroughSourceZMismatch;
+    public readonly long EvictionsByLruCap = evictionsByLruCap;
+    public readonly long BuildsTotal = buildsTotal;
+}

Projects/UOContent/Engines/Pathing/Cache/StepCache.cs

@@ -0,0 +1,355 @@
+using System;
+using System.Collections.Generic;
+using Server.Logging;
+
+namespace Server.Engines.Pathing.Cache;
+
+/// <summary>
+/// Singleton store of per-chunk static walkability data. Chunks correspond to
+/// Map.SectorSize = 16; key encoding packs (mapId, chunkX, chunkY) into a long.
+/// Lazily built on first query; invalidated by version-check vs Sector.MultisVersion;
+/// memory bounded by MaxResidentChunks via probabilistic LRU eviction.
+///
+/// Default-walker scope only. Cells with multi-Z surfaces and queries for non-default
+/// walkers route to the MovementImpl slow path via the Fallthrough_* hit kinds.
+/// </summary>
+public sealed class StepCache
+{
+    private static readonly ILogger logger = LogFactory.GetLogger(typeof(StepCache));
+
+    public static StepCache Instance { get; } = new();
+
+    private readonly Dictionary<long, StepChunk> _chunks = new();
+    // Parallel list of keys for O(1) random sampling during eviction. Kept in lockstep
+    // with _chunks: append on Miss_NotBuilt, swap-and-pop on eviction.
+    private readonly List<long> _keysList = new();
+
+    // Telemetry counters
+    private long _hits;
+    private long _missesNotBuilt;
+    private long _missesDirtyRebuild;
+    private long _fallthroughMultiZ;
+    private long _fallthroughOffMap;
+    private long _fallthroughSourceZMismatch;
+    private long _evictionsByLruCap;
+    private long _buildsTotal;
+
+    private StepCache() { }
+
+    /// <summary>Hard cap on resident chunk count. Default 8192. Override for tests / ops.</summary>
+    public int MaxResidentChunks { get; set; } = 8192;
+
+    /// <summary>
+    /// Pack (mapId, chunkX, chunkY) into a single long key.
+    /// Layout: [reserved 16][mapId 16][chunkX 16][chunkY 16].
+    /// </summary>
+    internal static long EncodeKey(int mapId, int chunkX, int chunkY) =>
+        ((long)(mapId & 0xFFFF) << 32) | ((long)(chunkX & 0xFFFF) << 16) | (long)(chunkY & 0xFFFF);
+
+    public CacheStats GetStats() => new CacheStats(
+        residentChunks: _chunks.Count,
+        hits: _hits,
+        missesNotBuilt: _missesNotBuilt,
+        missesDirtyRebuild: _missesDirtyRebuild,
+        fallthroughMultiZ: _fallthroughMultiZ,
+        fallthroughOffMap: _fallthroughOffMap,
+        fallthroughSourceZMismatch: _fallthroughSourceZMismatch,
+        evictionsByLruCap: _evictionsByLruCap,
+        buildsTotal: _buildsTotal
+    );
+
+    /// <summary>
+    /// Drop all cached chunks AND zero every telemetry counter. Used by tests and
+    /// benchmarks that need a known cold-start state. Counter reset is intentional —
+    /// counters are since-last-clear, not since-startup.
+    /// </summary>
+    public void Clear()
+    {
+        _chunks.Clear();
+        _keysList.Clear();
+        _hits = 0;
+        _missesNotBuilt = 0;
+        _missesDirtyRebuild = 0;
+        _fallthroughMultiZ = 0;
+        _fallthroughOffMap = 0;
+        _fallthroughSourceZMismatch = 0;
+        _evictionsByLruCap = 0;
+        _buildsTotal = 0;
+    }
+
+    /// <summary>
+    /// Probabilistic LRU sample size — picks SampleSize random resident chunks per
+    /// eviction and evicts the oldest of that sample. Approximates true LRU at a tiny
+    /// fraction of the cost (no full sort). Redis uses the same approach (`maxmemory-samples`).
+    /// 5 yields ~quality-of-true-LRU for cache eviction; higher values trade speed for accuracy.
+    /// </summary>
+    private const int LruSampleSize = 5;
+
+    /// <summary>
+    /// If resident chunk count exceeds MaxResidentChunks, evict via probabilistic LRU
+    /// until the count is at or below the cap. Per-eviction cost is O(LruSampleSize),
+    /// independent of resident count — sustained cap pressure has no perpetual perf hit.
+    /// Called from CacheEvictionTimer; also callable directly from tests.
+    /// </summary>
+    public void EnforceLruCap()
+    {
+        var overflow = _chunks.Count - MaxResidentChunks;
+        if (overflow <= 0)
+        {
+            return;
+        }
+
+        while (overflow-- > 0 && _keysList.Count > 0)
+        {
+            var oldestIdx = -1;
+            long oldestTouched = long.MaxValue;
+            long oldestKey = 0;
+
+            // Sample LruSampleSize random keys; track the oldest by LastTouchedTicks.
+            // With replacement is fine — collisions are rare and don't break correctness.
+            var samples = Math.Min(LruSampleSize, _keysList.Count);
+            for (var s = 0; s < samples; s++)
+            {
+                var idx = Utility.Random(_keysList.Count);
+                var k = _keysList[idx];
+                var touched = _chunks[k].LastTouchedTicks;
+                if (touched < oldestTouched)
+                {
+                    oldestTouched = touched;
+                    oldestKey = k;
+                    oldestIdx = idx;
+                }
+            }
+
+            _chunks.Remove(oldestKey);
+            // Swap-and-pop _keysList[oldestIdx] with the tail; O(1) regardless of position.
+            var last = _keysList.Count - 1;
+            if (oldestIdx != last)
+            {
+                _keysList[oldestIdx] = _keysList[last];
+            }
+            _keysList.RemoveAt(last);
+            _evictionsByLruCap++;
+        }
+    }
+
+    internal static void DecodeKey(long key, out int mapId, out int chunkX, out int chunkY)
+    {
+        mapId  = (int)((key >> 32) & 0xFFFF);
+        chunkX = (int)((key >> 16) & 0xFFFF);
+        chunkY = (int)(key & 0xFFFF);
+    }
+
+    private const int ChunkSize = 16;
+
+    /// <summary>
+    /// Hot-path query. Returns the cached mask + 8 destination Z values for (map, x, y, sourceZ).
+    /// Returns false on off-map or multi-Z fallthrough; the caller should use the slow path.
+    /// </summary>
+    public bool TryGetMask(
+        Map map, int x, int y, sbyte sourceZ,
+        out byte mask,
+        out sbyte destZN, out sbyte destZNE, out sbyte destZE, out sbyte destZSE,
+        out sbyte destZS, out sbyte destZSW, out sbyte destZW, out sbyte destZNW,
+        out CacheHitKind hitKind
+    )
+    {
+        mask = 0;
+        destZN = destZNE = destZE = destZSE = destZS = destZSW = destZW = destZNW = 0;
+
+        if (map == null || map == Map.Internal || x < 0 || y < 0 || x >= map.Width || y >= map.Height)
+        {
+            hitKind = CacheHitKind.Fallthrough_OffMap;
+            _fallthroughOffMap++;
+            return false;
+        }
+
+        var chunkX = x >> 4;
+        var chunkY = y >> 4;
+        var key = EncodeKey(map.MapID, chunkX, chunkY);
+
+        var hitKindResult = CacheHitKind.Hit;
+        if (!_chunks.TryGetValue(key, out var chunk))
+        {
+            chunk = ResolveMissingChunk(map, chunkX, chunkY);
+            _chunks[key] = chunk;
+            _keysList.Add(key);
+            hitKindResult = CacheHitKind.Miss_NotBuilt;
+        }
+        else
+        {
+            var sector = map.GetRealSector(chunkX, chunkY);
+            if (chunk.BuiltMultisVersion != sector.MultisVersion)
+            {
+                chunk = BuildChunk(map, chunkX, chunkY);
+                _chunks[key] = chunk;
+                hitKindResult = CacheHitKind.Miss_DirtyRebuild;
+                // _missesDirtyRebuild++ moved into the success switch below to
+                // preserve the mutual-exclusivity invariant (a multi-Z fallthrough
+                // on a freshly dirty-rebuilt chunk must NOT count both counters).
+            }
+        }
+
+        chunk.LastTouchedTicks = Core.TickCount;
+
+        var cellIndex = ((y - (chunkY << 4)) << 4) | (x - (chunkX << 4));
+
+        if (chunk.IsCellMultiZ(cellIndex))
+        {
+            hitKind = CacheHitKind.Fallthrough_MultiZ;
+            _fallthroughMultiZ++;
+            return false;
+        }
+
+        // Source-Z guard: the cache stores one answer per cell baked at SourceZ.
+        // StepHeight tolerance accepts incremental Z jitter; loosening it breaks parity
+        // because tile reachability shifts at step-height boundaries.
+        if (Math.Abs(sourceZ - chunk.SourceZ[cellIndex]) > StepHeight)
+        {
+            hitKind = CacheHitKind.Fallthrough_SourceZMismatch;
+            _fallthroughSourceZMismatch++;
+            return false;
+        }
+
+        mask = chunk.Mask[cellIndex];
+        destZN  = chunk.DestZN[cellIndex];
+        destZNE = chunk.DestZNE[cellIndex];
+        destZE  = chunk.DestZE[cellIndex];
+        destZSE = chunk.DestZSE[cellIndex];
+        destZS  = chunk.DestZS[cellIndex];
+        destZSW = chunk.DestZSW[cellIndex];
+        destZW  = chunk.DestZW[cellIndex];
+        destZNW = chunk.DestZNW[cellIndex];
+
+        switch (hitKindResult)
+        {
+            case CacheHitKind.Miss_NotBuilt:
+                {
+                    _missesNotBuilt++;
+                    break;
+                }
+            case CacheHitKind.Miss_DirtyRebuild:
+                {
+                    _missesDirtyRebuild++;
+                    break;
+                }
+            case CacheHitKind.Hit:
+                {
+                    _hits++;
+                    break;
+                }
+        }
+        hitKind = hitKindResult;
+
+        return true;
+    }
+
+    /// <summary>
+    /// Chunk-miss resolution: build the chunk via the runtime baker.
+    /// </summary>
+    private StepChunk ResolveMissingChunk(Map map, int chunkX, int chunkY) =>
+        BuildChunk(map, chunkX, chunkY);
+
+    private StepChunk BuildChunk(Map map, int chunkX, int chunkY)
+    {
+        var chunk = new StepChunk();
+        var sector = map.GetRealSector(chunkX, chunkY);
+        chunk.BuiltMultisVersion = sector.MultisVersion;
+
+        var baseX = chunkX << 4;
+        var baseY = chunkY << 4;
+
+        for (var dy = 0; dy < ChunkSize; dy++)
+        {
+            for (var dx = 0; dx < ChunkSize; dx++)
+            {
+                var x = baseX + dx;
+                var y = baseY + dy;
+                var cell = (dy << 4) | dx;
+
+                map.GetAverageZ(x, y, out _, out var avgZ, out _);
+
+                // Bake from the slow path's "standing Z" (the surface Z a creature actually
+                // stands at, not the ground avg). A* tracks newZ as standing Z, so SourceZ
+                // must match for the source-Z guard not to over-fire.
+                var standingZ = (sbyte)StepProbe.ComputeStandingZ(map, x, y, avgZ);
+
+                var result = StepProbe.ComputeMaskAt(map, x, y, standingZ);
+
+                chunk.Mask[cell] = result.Mask;
+                chunk.SourceZ[cell] = standingZ;
+                chunk.DestZN[cell]  = result.DestZ_N;
+                chunk.DestZNE[cell] = result.DestZ_NE;
+                chunk.DestZE[cell]  = result.DestZ_E;
+                chunk.DestZSE[cell] = result.DestZ_SE;
+                chunk.DestZS[cell]  = result.DestZ_S;
+                chunk.DestZSW[cell] = result.DestZ_SW;
+                chunk.DestZW[cell]  = result.DestZ_W;
+                chunk.DestZNW[cell] = result.DestZ_NW;
+
+                // Multi-Z = ≥2 surfaces reachable from standingZ. Mirrors the baker's
+                // CheckStaticStep filter so we don't over-mark.
+                if (CountReachableSurfaces(map, x, y, standingZ) > 1)
+                {
+                    chunk.MarkCellMultiZ(cell);
+                }
+            }
+        }
+
+        _buildsTotal++;
+        return chunk;
+    }
+
+    private const int PersonHeight = 16;
+    private const int StepHeight = 2;
+
+    /// <summary>
+    /// Counts walkable surfaces actually reachable from a creature standing at sourceZ.
+    /// Mirrors <see cref="StepProbe"/>.CheckStaticStep so cells flagged multi-Z
+    /// here are exactly those where the baker would have multiple candidate destinations.
+    /// Reachable when: surface and !impassable; stepTop ≥ itemTop; vertical overlap with
+    /// the creature's PersonHeight envelope.
+    /// </summary>
+    internal static int CountReachableSurfaces(Map map, int x, int y, sbyte sourceZ)
+    {
+        var startTop = sourceZ + PersonHeight;
+        var stepTop = startTop + StepHeight;
+        var count = 0;
+
+        foreach (var tile in map.Tiles.GetStaticAndMultiTiles(x, y))
+        {
+            var data = TileData.ItemTable[tile.ID & TileData.MaxItemValue];
+            if (!data.Surface || data.Impassable)
+            {
+                continue;
+            }
+
+            var itemZ = tile.Z;
+            var itemTop = data.Bridge ? itemZ : itemZ + data.Height;
+
+            if (stepTop < itemTop)
+            {
+                continue;
+            }
+
+            if (sourceZ + PersonHeight > itemZ && itemZ + data.Height > sourceZ)
+            {
+                count++;
+            }
+        }
+
+        // Land surface check — same shape, but use GetAverageZ for the land's effective top.
+        var landTile = map.Tiles.GetLandTile(x, y);
+        var landFlags = TileData.LandTable[landTile.ID & TileData.MaxLandValue].Flags;
+        if (!landTile.Ignored && (landFlags & TileFlag.Impassable) == 0)
+        {
+            map.GetAverageZ(x, y, out var landZ, out _, out var landTop);
+            if (stepTop >= landZ && sourceZ + PersonHeight > landZ && landTop > sourceZ)
+            {
+                count++;
+            }
+        }
+
+        return count;
+    }
+}

Projects/UOContent/Engines/Pathing/Cache/StepChunk.cs

@@ -0,0 +1,50 @@
+namespace Server.Engines.Pathing.Cache;
+
+/// <summary>
+/// Per-chunk storage backing StepCache. Holds raw walkability masks and
+/// destination Z values for each of 256 cells in a 16x16 chunk, plus build-time
+/// metadata (multis version, multi-Z bitmap) and LRU bookkeeping.
+/// </summary>
+internal sealed class StepChunk
+{
+    public const int CellsPerChunk = 256; // 16 x 16
+
+    /// <summary>Bit i of Mask[c] = "can step from cell c to neighbor (Direction)i". Raw — no diagonal corner-cut applied here.</summary>
+    public readonly byte[] Mask = new byte[CellsPerChunk];
+
+    public readonly sbyte[] SourceZ = new sbyte[CellsPerChunk];
+
+    public readonly sbyte[] DestZN  = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZNE = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZE  = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZSE = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZS  = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZSW = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZW  = new sbyte[CellsPerChunk];
+    public readonly sbyte[] DestZNW = new sbyte[CellsPerChunk];
+
+    /// <summary>
+    /// 32 bytes = 256 bits. Bit set = cell has &gt;1 walkable surface; route to slow path.
+    /// TODO(PR2): lazy-init this. The vast majority of chunks are entirely single-Z, so
+    /// allocating 32 bytes per chunk wastes ~256KB at full cap. Make nullable; allocate
+    /// on first MarkCellMultiZ; IsCellMultiZ short-circuits to false when null.
+    /// </summary>
+    public readonly byte[] MultiZCells = new byte[32];
+
+    /// <summary>Snapshot of Sector.MultisVersion at the time this chunk was built.</summary>
+    public int BuiltMultisVersion;
+
+    /// <summary>Updated on every cache hit/miss. Used by LRU fallback eviction.</summary>
+    public long LastTouchedTicks;
+
+    /// <summary>True if any cell in this chunk has more than one walkable surface (set during build).</summary>
+    public bool HasAnyMultiZ;
+
+    public bool IsCellMultiZ(int cellIndex) => (MultiZCells[cellIndex >> 3] & (1 << (cellIndex & 7))) != 0;
+
+    public void MarkCellMultiZ(int cellIndex)
+    {
+        MultiZCells[cellIndex >> 3] |= (byte)(1 << (cellIndex & 7));
+        HasAnyMultiZ = true;
+    }
+}

Projects/UOContent/Engines/Pathing/Cache/StepMask.cs

@@ -0,0 +1,39 @@
+namespace Server.Engines.Pathing.Cache;
+
+public readonly struct StepMask(
+    byte mask,
+    sbyte destZn,
+    sbyte destZne,
+    sbyte destZe,
+    sbyte destZse,
+    sbyte destZs,
+    sbyte destZsw,
+    sbyte destZw,
+    sbyte destZnw
+)
+{
+    public readonly byte Mask = mask;
+    public readonly sbyte DestZ_N = destZn;
+    public readonly sbyte DestZ_NE = destZne;
+    public readonly sbyte DestZ_E = destZe;
+    public readonly sbyte DestZ_SE = destZse;
+    public readonly sbyte DestZ_S = destZs;
+    public readonly sbyte DestZ_SW = destZsw;
+    public readonly sbyte DestZ_W = destZw;
+    public readonly sbyte DestZ_NW = destZnw;
+
+    public bool IsWalkable(Direction d) => (Mask & (1 << (int)d)) != 0;
+
+    public sbyte GetDestZ(Direction d) => d switch
+    {
+        Direction.North => DestZ_N,
+        Direction.Right => DestZ_NE,
+        Direction.East  => DestZ_E,
+        Direction.Down  => DestZ_SE,
+        Direction.South => DestZ_S,
+        Direction.Left  => DestZ_SW,
+        Direction.West  => DestZ_W,
+        Direction.Up    => DestZ_NW,
+        _ => 0
+    };
+}

Projects/UOContent/Engines/Pathing/Cache/StepProbe.cs

@@ -0,0 +1,280 @@
+using System;
+using CalcMoves = Server.Movement.Movement;
+
+namespace Server.Engines.Pathing.Cache;
+
+/// <summary>
+/// Computes static-only walkability for a single cell — the per-cell, per-direction
+/// "can step" mask and destination Z, based purely on land + statics + multis. Mirrors
+/// <see cref="MovementImpl"/>.Check minus the item and mobile collision phases.
+/// </summary>
+/// <remarks>
+/// Default-walker scope: assumes CanSwim=false, CanFly=false, CanOpenDoors=false,
+/// CantWalk=false. Single source-Z per cell. Diagonal corner-cut is NOT applied here;
+/// callers must AND the partner-cell results at query time per the creature rule
+/// (one cardinal partner walkable suffices).
+/// </remarks>
+public static class StepProbe
+{
+    private const int PersonHeight = 16;
+    private const int StepHeight = 2;
+
+    public static StepMask ComputeMaskAt(Map map, int x, int y, sbyte sourceZ)
+    {
+        if (map == null || map == Map.Internal)
+        {
+            return default;
+        }
+
+        GetStaticStartZ(map, x, y, sourceZ, out var startZ, out var startTop, out _);
+
+        byte mask = 0;
+        Span<sbyte> destZs = stackalloc sbyte[8];
+
+        for (var d = 0; d < 8; d++)
+        {
+            var dx = x;
+            var dy = y;
+            CalcMoves.Offset((Direction)d, ref dx, ref dy);
+
+            if (CheckStaticStep(map, dx, dy, startZ, startTop, out var newZ))
+            {
+                mask |= (byte)(1 << d);
+                destZs[d] = (sbyte)newZ;
+            }
+        }
+
+        return new StepMask(
+            mask,
+            destZs[0], destZs[1], destZs[2], destZs[3],
+            destZs[4], destZs[5], destZs[6], destZs[7]
+        );
+    }
+
+    /// <summary>
+    /// Returns the slow path's standing-Z for a default walker at (x, y) with hint locZ.
+    /// This is the Z the creature ends up STANDING AT — typically the topmost walkable
+    /// surface that's reachable from locZ (paver Z+1 for paver-over-ground; landCenter
+    /// for bare land). Mirrors MovementImpl.Check's surface-selection logic for the
+    /// destination cell, distilled to "what Z value does the slow path return as newZ
+    /// when stepping ONTO this cell". Used by StepCache to bake SourceZ
+    /// correctly so A*'s tracked-per-cell Z matches the cache's bake-time assumption.
+    /// </summary>
+    public static int ComputeStandingZ(Map map, int x, int y, int locZ)
+    {
+        GetStaticStartZ(map, x, y, locZ, out _, out _, out var zCenter);
+        return zCenter;
+    }
+
+    /// <summary>
+    /// Mirrors GetStartZ from MovementImpl, but static-only (no item list).
+    /// Assumes default walker: CanSwim=false, CantWalk=false.
+    /// </summary>
+    private static void GetStaticStartZ(Map map, int x, int y, int locZ, out int zLow, out int zTop, out int zCenter)
+    {
+        var landTile = map.Tiles.GetLandTile(x, y);
+        var flags = TileData.LandTable[landTile.ID & TileData.MaxLandValue].Flags;
+        var impassable = (flags & TileFlag.Impassable) != 0;
+
+        // CantWalk=false, CanSwim=false → landBlocks = impassable
+        var landBlocks = impassable;
+
+        map.GetAverageZ(x, y, out var landZ, out var landCenter, out var landTop);
+
+        var considerLand = !landTile.Ignored;
+
+        zCenter = zLow = zTop = 0;
+        var isSet = false;
+
+        if (considerLand && !landBlocks && locZ >= landCenter)
+        {
+            zLow = landZ;
+            zCenter = landCenter;
+            zTop = landTop;
+            isSet = true;
+        }
+
+        foreach (var tile in map.Tiles.GetStaticAndMultiTiles(x, y))
+        {
+            var id = TileData.ItemTable[tile.ID & TileData.MaxItemValue];
+            var calcTop = tile.Z + id.CalcHeight;
+
+            // CanSwim=false → only check Surface; CantWalk=false
+            if (isSet && calcTop < zCenter || locZ < calcTop || !id.Surface)
+            {
+                continue;
+            }
+
+            zLow = tile.Z;
+            zCenter = calcTop;
+
+            var top = tile.Z + id.Height;
+
+            if (!isSet || top > zTop)
+            {
+                zTop = top;
+            }
+
+            isSet = true;
+        }
+
+        if (!isSet)
+        {
+            zLow = zTop = locZ;
+        }
+        else if (locZ > zTop)
+        {
+            zTop = locZ;
+        }
+    }
+
+    /// <summary>
+    /// Mirrors MovementImpl.Check for static tiles only.
+    /// Assumes default walker: CanSwim=false, CanFly=false, CantWalk=false,
+    /// AlwaysIgnoreDoors=false. Items and mobile collision phases are omitted.
+    /// </summary>
+    private static bool CheckStaticStep(Map map, int x, int y, int startZ, int startTop, out int newZ)
+    {
+        newZ = 0;
+
+        if (x < 0 || y < 0 || x >= map.Width || y >= map.Height)
+        {
+            return false;
+        }
+
+        var landTile = map.Tiles.GetLandTile(x, y);
+        var flags = TileData.LandTable[landTile.ID & TileData.MaxLandValue].Flags;
+        var impassable = (flags & TileFlag.Impassable) != 0;
+
+        // CantWalk=false, CanSwim=false → landBlocks = impassable
+        var landBlocks = impassable;
+
+        var considerLand = !landTile.Ignored;
+
+        map.GetAverageZ(x, y, out var landZ, out var landCenter, out _);
+
+        var moveIsOk = false;
+
+        var stepTop = startTop + StepHeight;
+        var checkTop = startZ + PersonHeight;
+
+        int testTop;
+
+        foreach (var tile in map.Tiles.GetStaticAndMultiTiles(x, y))
+        {
+            var itemData = TileData.ItemTable[tile.ID & TileData.MaxItemValue];
+
+            // CanSwim=false, CantWalk=false:
+            // Skip if not a passable surface (no swim path either)
+            if (!itemData.Surface || itemData.Impassable)
+            {
+                continue;
+            }
+
+            var itemZ = tile.Z;
+            var itemTop = itemZ;
+            var ourZ = itemZ + itemData.CalcHeight;
+            testTop = checkTop;
+
+            // Pick the candidate closest to startZ; ties broken by higher ourZ
+            if (moveIsOk)
+            {
+                var cmp = Math.Abs(ourZ - startZ) - Math.Abs(newZ - startZ);
+
+                if (cmp > 0 || cmp == 0 && ourZ > newZ)
+                {
+                    continue;
+                }
+            }
+
+            if (ourZ + PersonHeight > testTop)
+            {
+                testTop = ourZ + PersonHeight;
+            }
+
+            if (!itemData.Bridge)
+            {
+                itemTop += itemData.Height;
+            }
+
+            if (stepTop < itemTop)
+            {
+                continue;
+            }
+
+            var landCheck = itemZ + Math.Min(itemData.Height, StepHeight);
+
+            if (considerLand && landCheck < landCenter && landCenter > ourZ && testTop > landZ)
+            {
+                continue;
+            }
+
+            // IsOk equivalent: check static tiles don't block (ourZ, testTop) space
+            if (StaticsBlockAt(map, x, y, ourZ, testTop))
+            {
+                continue;
+            }
+
+            newZ = ourZ;
+            moveIsOk = true;
+        }
+
+        // Land surface fallback (mirrors Check's land block at the bottom)
+        if (!considerLand || landBlocks || stepTop < landZ)
+        {
+            return moveIsOk;
+        }
+
+        testTop = checkTop;
+
+        if (landCenter + PersonHeight > testTop)
+        {
+            testTop = landCenter + PersonHeight;
+        }
+
+        var shouldCheck = true;
+
+        if (moveIsOk)
+        {
+            var cmp = Math.Abs(landCenter - startZ) - Math.Abs(newZ - startZ);
+
+            if (cmp > 0 || cmp == 0 && landCenter > newZ)
+            {
+                shouldCheck = false;
+            }
+        }
+
+        if (shouldCheck && !StaticsBlockAt(map, x, y, landCenter, testTop))
+        {
+            newZ = landCenter;
+            moveIsOk = true;
+        }
+
+        return moveIsOk;
+    }
+
+    /// <summary>
+    /// Mirrors the static-tile portion of IsOk: returns true if any static tile at (x,y)
+    /// has ImpassableSurface and overlaps the vertical range (ourZ, testTop).
+    /// </summary>
+    private static bool StaticsBlockAt(Map map, int x, int y, int ourZ, int testTop)
+    {
+        foreach (var check in map.Tiles.GetStaticAndMultiTiles(x, y))
+        {
+            var itemData = TileData.ItemTable[check.ID & TileData.MaxItemValue];
+
+            if (itemData.ImpassableSurface)
+            {
+                var checkZ = check.Z;
+                var checkTop = checkZ + itemData.CalcHeight;
+
+                if (checkTop > ourZ && testTop > checkZ)
+                {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+}

Projects/UOContent/Engines/Pathing/MovementPath.cs

@@ -1,8 +1,9 @@
 using System;
 using System.Diagnostics;
+using Server.Engines.Pathing.Cache;
 using Server.Items;
 using Server.PathAlgorithms;
-using Server.PathAlgorithms.FastAStar;
+using Server.PathAlgorithms.BitmapAStar;
 using Server.Spells;
 using Server.Targeting;
 
@@ -31,7 +32,7 @@ namespace Server
 
             try
             {
-                var alg = OverrideAlgorithm ?? FastAStarAlgorithm.Instance;
+                var alg = OverrideAlgorithm ?? BitmapAStarAlgorithm.Instance;
 
                 if (alg?.CheckCondition(m, map, start, goal) == true)
                 {
@@ -59,6 +60,7 @@ namespace Server
         public static void Configure()
         {
             CommandSystem.Register("Path", AccessLevel.GameMaster, Path_OnCommand);
+            CacheEvictionTimer.Configure();
         }
 
         [Usage("Path")]
@@ -111,7 +113,7 @@ namespace Server
 
             SpellHelper.GetSurfaceTop(ref p);
 
-            Path(from, p, FastAStarAlgorithm.Instance, "Fast", 0);
+            Path(from, p, BitmapAStarAlgorithm.Instance, "Bitmap", 0);
             OverrideAlgorithm = null;
         }
     }