perf(pathing): pool the StepCache strata buffer, then clean up the pathing engine around it (#2523)
Started as an allocation pass over `StepCache` and grew into a cleanup of the surrounding pathing engine. Four commits, each independently reviewable; net **−560 lines**. Build clean (0 warnings). All 122 `Server.Tests.Pathfinding` tests pass. --- ## 1. `perf`: pool the strata buffer, cut a hot-path dictionary lookup **The headline is that `TryGetMask` — the actual hot path — was already allocation-free.** `StepMask` is a readonly struct, `StaticTileEnumerable` is a `ref struct`, `ChunkMissState` is a struct in a `Dictionary`. So most of this is a bake-throughput and GC-churn win, with one exception noted below. `BuildChunk` accumulated packed multi-Z strata into a `List<byte>` that grew by doubling (256 → 512 → 1024 → …) and then paid a final `ToArray()`. A full map bake runs it ~114k times. It now writes into a `byte[]` rented from `STArrayPool<byte>.Shared` through a span writer, and hands the chunk one exact-size copy. **This required fixing a latent out-of-bounds guard.** The record-fit check reserved headroom for **8** strata (`StratumByteLength * 8`) while `ComputeStandableSurfaceZs` can return up to **16** — so a cell could write 305 bytes starting from a 65,383-byte offset. Against a `List` that was benign (it just grew past 64 KB, and emitted offsets stayed under the `NoStrata` sentinel). Against a fixed-size rented buffer it is an out-of-bounds write, so tightening it was a *prerequisite* for the pooling, not a drive-by. The guard is now exact, which additionally proves no emitted offset can collide with `NoStrata == ushort.MaxValue`. **One genuine query-path win:** `ShouldPromoteAfterMiss` did *two* dictionary lookups per miss — a `TryGetValue`, then an indexer assignment that re-hashes and re-probes. It now mutates in place via `CollectionsMarshal.GetValueRefOrNullRef`. This runs on every uncached chunk touch during A* expansion. The window-expiry branch keeps its explicit early return, so `MissPromotionThreshold == 1` still resets rather than promoting. Also dropped `StepProbe.ComputeStrataAt` / `ComputedStratum` (dead code, zero callers) and collapsed six 18-argument `new StepMask(0, 0, …, kind)` blocks into `Fallthrough(kind)`. **Considered and rejected:** pooling the `Direction[]` that `Find` returns. It *escapes* the call — `MovementPath` holds it across ticks while `PathFollower` walks `m_Index` through it — so it cannot be rented-and-returned, and it cannot be borrowed from the shared `BitmapAStarAlgorithm.Instance` without one creature clobbering another's in-flight path. `CheckPath` rate-limits repaths to one per 2s per creature, putting this at roughly 60 KB/sec at 1,000 pathing creatures. Not worth a public API break plus a use-after-return footgun. ## 2. `docs`: rewrite the comments for publication The comments had accumulated as development notes: internal phase jargon (`Tier 4`, `the Phase-2 synthesizer`), change narration aimed at a reviewer (`which the old ComputeStandingZ anchor missed`, `legacy behavior`), benchmark anecdotes (`benchmarked as near-optimal`, `a ~20 ns lookup`), and paragraphs restating the code. Rewritten to keep the rationale you cannot recover by reading the code — why the source-Z guard cannot be widened, why multis fall through with a halo, why the promotion gate counts Finds rather than calls, why `ComputeFingerprint` must hash the *files* and not the live tile tables — and drop the history that got us there. Three comments were **factually wrong**, not just wordy: - `CacheEvictionTimer` and `CacheStats` documented a class called `StaticWalkabilityCache`. No such class exists — it is `StepCache`. - `StepCacheFile` declared `File layout v8` while `FormatVersion` is 9, and called the current record layout "the v6 layout" in four places. The layout descriptions are now unversioned so they cannot drift again. - `StepProbe.ComputeStandingZ` claimed `StepCache` uses it to bake `SourceZ`. It has not since the baker moved to the clearance-aware `ComputeStandableSurfaceZs`; only a parity test calls it. ## 3. `refactor`: simplify `StepCacheFile.Write`, consolidate the format tests `SaveToFile` walked `_keysList` **twice** — once to count the map's chunks, then again through a `ChunkEnumerator` closure to emit them — because `Write` needed the count up front to size its index array. Both loops had the same root cause. Passing a **span** collapses them: the count is just `span.Length`. That deletes the `ChunkEnumerator` delegate, the closure over the list enumerator, and **both `InvalidOperationException` throws**, which existed only to police the delegate's "yield exactly `chunkCount` chunks" contract — a contract a span makes unrepresentable. `Write` now patches the header's `IndexOffset` by seeking back to it rather than reaching into the writer's live buffer with `BinaryPrimitives`. That also retires `IndexOffsetFieldPosition`, a hand-maintained byte offset that had to track the header layout, and sidesteps the stale-array hazard that motivated the manual patch (`BufferWriter` reallocates on growth). **Tests:** `StepCacheFileV6/V7/V8Tests` were named for the format version that introduced each transform — and the format is now **v9**, so all three names described formats the loader rejects outright. Beyond triplicated builders and plumbing, two things were actually broken: - The three near-identical rejection tests each cited a `MinSupportedVersion` that had since moved (`"version 5 < MinSupportedVersion 6"`, `"6 < 7"`, `"7 < 8"`). They passed for the wrong reason. - `AssertBaseEqual` (used by V7 and V8) **silently skipped the swim and strata trailers**. A regression dropping either would not have failed those tests. Now one `StepCacheFileFormatTests`, named for behavior — predictive-Z elision, compression, compact index — with a single `AssertIdentical` that does check both trailers, the three rejection tests folded into one theory that also covers a future version, and a zero-chunk case the delegate-based writer never had coverage for. ## 4. `test`: consolidate the parity and lifecycle tests Three files tested "parity" and none of the names said *which*. They were three different layers, and the seams are the useful part, so they are now one `StepCacheParityTests` that names them: | Test | Compares | Answers | |---|---|---| | `ProbeMatchesSlowPath` | StepProbe vs MovementImpl | Is the bake right? | | `CacheMatchesProbe` | StepCache vs StepProbe | Is it stored and returned intact? | | `CacheServesReachableWalkStates` | StepCache vs MovementImpl | End to end, over the states A* visits | Merging removed a duplicated stub `Mobile`, duplicated region seeds, and a filename/class mismatch (`StepProbeParityTests.cs` declared `StaticWalkabilityParityTests`). `SwimBake_ProducesWetCells` moved with it — it lived in the cache parity file but never touched the cache. Tests reached into `StepCache._chunks` via `GetField` in **9 places**, each rebuilding the key encoding and cell-index arithmetic by hand. `StepCache` now exposes `GetResidentChunk` and `ResidentIndexInSync` alongside the internal test hooks it already had (`LazyReaderHasChunk`, `CurrentFindGeneration`), and the shared arithmetic moved to `PathingTestSupport`. All 9 reflection blocks are gone. `StepCacheLifecycleTests` is regrouped by what it covers — promotion gate, fallthrough routes, strata, swim layer, eviction — with the `Tier4*` names dropped. Removed `Singleton_IsAvailable`, which asserted an inline-initialized static property was not null; that is the entire 123 → 122 test-count delta. --- ## Verification Tests were mutation-checked rather than just run, since round-trip and parity tests can pass while a transform silently no-ops: - Injecting an off-by-one into the `IndexOffset` patch fails **15 of 123** — the format tests are load-bearing. - Offsetting the cache's cell index by one fails **7 of 10** parity cases, and the 3 that stay green are exactly the ones that do not touch the cache. The layering localizes a fault rather than just reporting one.
This commit is contained in:
Kamron Batman
GitHub
parent
e035768ef8
commit
b852bca41e
23 changed files with 1663 additions and 2223 deletions
|
|
@ -6,13 +6,19 @@ using Server.Multis;
|
|||
namespace Server.Engines.Pathing.Cache;
|
||||
|
||||
/// <summary>
|
||||
/// Warm, in-memory cache of per-multiID local-frame walkability masks for INTERIOR multi cells
|
||||
/// (cell + all 8 neighbours covered by the multi → terrain-neighbour-free → position-invariant).
|
||||
/// Wraps the Phase-2 synthesizer (StepProbe.ComputeMultiMaskAt). Cleanliness is decided ONCE per
|
||||
/// instance (BaseMulti.PathInteriorCacheState, via ComputeFootprintClean): a clean instance — whole
|
||||
/// footprint terrain below the floor — serves interior cells from the shared per-multiID cache;
|
||||
/// dirty instances, boats (movers), and HouseFoundation (runtime-mutable) fall back to live-synth.
|
||||
/// Keyed by multiID & 0x3FFF.
|
||||
/// Caches walkability masks for the interior cells of a multi, shared across every instance of the
|
||||
/// same multiID.
|
||||
///
|
||||
/// An interior cell — one whose 8 neighbours are all covered by the multi — has no terrain
|
||||
/// neighbour, so its mask depends only on the multi's own component tiles and is identical at every
|
||||
/// position the design is placed. That makes it cacheable in the multi's local frame and reusable
|
||||
/// across instances; perimeter cells are not, and fall back to <see cref="StepProbe.ComputeMultiMaskAt"/>.
|
||||
///
|
||||
/// The catch is terrain intruding into the multi's floor envelope, which would make a cell's mask
|
||||
/// position-dependent after all. <see cref="ComputeFootprintClean"/> rules that out per instance,
|
||||
/// once: if the whole footprint's terrain sits below the lowest floor, no interior cell can see it.
|
||||
/// A dirty instance, or a <see cref="HouseFoundation"/> (whose design mutates at runtime), always
|
||||
/// synthesizes live rather than risk serving a wrong mask.
|
||||
/// </summary>
|
||||
public sealed class MultiMaskCache
|
||||
{
|
||||
|
|
@ -25,26 +31,20 @@ public sealed class MultiMaskCache
|
|||
public void Clear() => _byMultiId.Clear();
|
||||
|
||||
/// <summary>
|
||||
/// Returns the multi-aware StepMask for a covered cell (x,y,sourceZ). Serves a cached interior
|
||||
/// mask when available and the guards pass (counted as a MultiMaskCacheHit); otherwise falls
|
||||
/// back to the Phase-2 live synthesizer ComputeMultiMaskAt (counted as a MultiLocalHit), caching
|
||||
/// the result if the cell is interior and clean. Always returns a usable mask (HitKind == Hit).
|
||||
/// The multi-aware mask for a covered cell, always usable (HitKind is always Hit). Served from
|
||||
/// the shared cache when the cell is a clean interior one, synthesized live otherwise.
|
||||
/// </summary>
|
||||
public StepMask GetMask(Map map, int x, int y, sbyte sourceZ)
|
||||
{
|
||||
if (!TryResolveCoveringMulti(map, x, y, out var multi, out var lx, out var ly)
|
||||
|| multi is HouseFoundation) // runtime-mutable per-instance DesignState MCL
|
||||
|| multi is HouseFoundation) // its DesignState MCL changes at runtime
|
||||
{
|
||||
return LiveSynth(map, x, y, sourceZ);
|
||||
}
|
||||
|
||||
// Boats are cached too: their per-multiID deck masks are movement-invariant (built once per
|
||||
// heading), and the per-instance clean gate below + the ItemID/location/map resets keep a
|
||||
// moving/turning boat correct. Narrow boats have little interior; wide galleons gain a lot.
|
||||
// Boats are cached despite moving: a deck mask is built in the local frame and is invariant
|
||||
// under translation, and the clean gate plus the ItemID/location/map resets cover turning.
|
||||
|
||||
// Per-instance footprint cleanliness (computed once, stored on the multi; reset on move).
|
||||
// Clean ⇒ no terrain intrusion anywhere in the footprint ⇒ interior cells are exact from the
|
||||
// shared per-multiID cache. Dirty ⇒ degrade to the live synthesizer (never serve a wrong mask).
|
||||
if (multi.PathInteriorCacheState == MultiInteriorCacheState.Unknown)
|
||||
{
|
||||
multi.PathInteriorCacheState =
|
||||
|
|
@ -62,7 +62,7 @@ public sealed class MultiMaskCache
|
|||
|
||||
if (state == MultiLocalMask.CellState.Cached)
|
||||
{
|
||||
// Footprint is clean, so only the source-Z match matters (terrain can't intrude).
|
||||
// A clean footprint rules terrain out, so the source-Z match is the only guard left.
|
||||
var worldFloorZ = local.FloorZAt(lx, ly) + multi.Z;
|
||||
if (Math.Abs(sourceZ - worldFloorZ) <= StepHeight)
|
||||
{
|
||||
|
|
@ -78,8 +78,7 @@ public sealed class MultiMaskCache
|
|||
return LiveSynth(map, x, y, sourceZ);
|
||||
}
|
||||
|
||||
// Unknown → classify + (if interior) build & cache. No per-cell terrain guard needed: the
|
||||
// instance is clean, so every interior cell's 3x3 terrain is below the floor.
|
||||
// First touch of this cell: synthesize, then classify and cache if it's interior.
|
||||
var mask = LiveSynth(map, x, y, sourceZ);
|
||||
if (IsInteriorLocalCell(mcl, lx, ly)
|
||||
&& TryToLocalZ(mask, multi.Z, out var localMask)
|
||||
|
|
@ -113,8 +112,7 @@ public sealed class MultiMaskCache
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// Finds the multi covering (x,y) and the local cell indices into its MCL. Mirrors
|
||||
/// Map.StaticTileEnumerator / BaseMulti.Contains. Returns false if no multi covers the cell.
|
||||
/// Finds the multi covering (x,y) and the cell's indices into its MCL, or false if none does.
|
||||
/// </summary>
|
||||
public static bool TryResolveCoveringMulti(Map map, int x, int y, out BaseMulti multi, out int lx, out int ly)
|
||||
{
|
||||
|
|
@ -138,9 +136,9 @@ public sealed class MultiMaskCache
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// True iff local cell (lx,ly) and all 8 neighbours are covered by the multi (have MCL tiles).
|
||||
/// Such a cell's 8-direction transition is fully determined by the multi (no terrain neighbour),
|
||||
/// so its mask is position-invariant. A pure function of the MCL.
|
||||
/// True when (lx,ly) and all 8 of its neighbours carry MCL tiles. Such a cell has no terrain
|
||||
/// neighbour, so the multi alone determines its transitions and its mask is position-invariant.
|
||||
/// A pure function of the MCL.
|
||||
/// </summary>
|
||||
public static bool IsInteriorLocalCell(MultiComponentList mcl, int lx, int ly)
|
||||
{
|
||||
|
|
@ -161,9 +159,9 @@ public sealed class MultiMaskCache
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// Converts a world-frame mask's per-direction Zs to local Z (subtract multiZ). Returns false
|
||||
/// if any local Z doesn't fit sbyte (caller must then NOT cache the cell — rare; only when
|
||||
/// |multiZ| is large enough to push a world Z out of range). Mask (walk/wet) bits are copied.
|
||||
/// Rebases a world-frame mask's per-direction Zs into the multi's local frame. Returns false
|
||||
/// when a local Z overflows sbyte — only reachable at extreme |multiZ| — and the caller must
|
||||
/// then leave the cell uncached.
|
||||
/// </summary>
|
||||
public static bool TryToLocalZ(StepMask world, int multiZ, out StepMask local)
|
||||
{
|
||||
|
|
@ -191,9 +189,8 @@ public sealed class MultiMaskCache
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// True iff all terrain (land + statics) at (x,y) sits strictly below <paramref name="floorZ"/>,
|
||||
/// so a creature standing on the multi floor never sees terrain in its envelope and the cached
|
||||
/// (terrain-free) mask is exact. Cheap: one land-top read + the cell's static-tile array scan.
|
||||
/// True when all terrain (land + statics) at (x,y) sits strictly below <paramref name="floorZ"/>,
|
||||
/// so a creature standing on the multi's floor never sees terrain in its envelope.
|
||||
/// </summary>
|
||||
public static bool TerrainTopBelow(Map map, int x, int y, sbyte floorZ)
|
||||
{
|
||||
|
|
@ -216,7 +213,7 @@ public sealed class MultiMaskCache
|
|||
return true;
|
||||
}
|
||||
|
||||
/// <summary>Highest terrain (land + statics) top at (x,y). Building block for the cleanliness check.</summary>
|
||||
/// <summary>Highest terrain (land + statics) top at (x,y).</summary>
|
||||
public static int TerrainTop(Map map, int x, int y)
|
||||
{
|
||||
map.GetAverageZ(x, y, out _, out _, out var top);
|
||||
|
|
@ -234,10 +231,10 @@ public sealed class MultiMaskCache
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// True iff the multi's WHOLE footprint terrain sits below its lowest standable floor — i.e.
|
||||
/// maxTerrain < minFloor over all covered cells. When true, no covered cell's terrain (nor any
|
||||
/// neighbour's) can intrude into a creature's floor envelope, so interior cells of this design are
|
||||
/// safe to serve from the shared per-multiID cache for THIS instance. One-time per instance.
|
||||
/// True when the multi's entire footprint terrain sits below its lowest standable floor. No
|
||||
/// covered cell's terrain — nor any neighbour's — can then intrude into a creature's floor
|
||||
/// envelope, which is what makes this instance's interior cells safe to serve from the shared
|
||||
/// per-multiID cache. Evaluated once per instance and cached on the multi.
|
||||
/// </summary>
|
||||
public static bool ComputeFootprintClean(Map map, BaseMulti multi)
|
||||
{
|
||||
|
|
@ -252,7 +249,7 @@ public sealed class MultiMaskCache
|
|||
var col = mcl.Tiles[lx][ly];
|
||||
if (col.Length == 0)
|
||||
{
|
||||
continue; // uncovered local cell
|
||||
continue;
|
||||
}
|
||||
|
||||
foreach (var tile in col)
|
||||
|
|
@ -278,7 +275,7 @@ public sealed class MultiMaskCache
|
|||
|
||||
if (minFloorLocal == int.MaxValue)
|
||||
{
|
||||
return false; // no standable floor anywhere → don't cache (defensive)
|
||||
return false; // no standable floor anywhere; refuse to cache rather than guess
|
||||
}
|
||||
|
||||
return maxTerrain < minFloorLocal + multi.Z;
|
||||
|
|
@ -304,8 +301,9 @@ public sealed class MultiMaskCache
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per-multiID lazily-filled grid of interior-cell masks. Cell state: Unknown (not yet classified),
|
||||
/// Cached (interior + clean → mask valid), NonInterior (perimeter/edge/terrain-dirty → live-synth).
|
||||
/// One multiID's grid of interior-cell masks, filled in as cells are first touched. A cell is
|
||||
/// Unknown until classified, then either Cached (interior — the mask is valid) or NonInterior
|
||||
/// (perimeter — synthesize live).
|
||||
/// </summary>
|
||||
internal sealed class MultiLocalMask
|
||||
{
|
||||
|
|
@ -314,8 +312,8 @@ internal sealed class MultiLocalMask
|
|||
private readonly int _width;
|
||||
private readonly int _height;
|
||||
private readonly CellState[] _state;
|
||||
private readonly StepMask[] _mask; // local-Z mask, valid when state == Cached
|
||||
private readonly sbyte[] _floorZ; // local floor Z, valid when state == Cached
|
||||
private readonly StepMask[] _mask; // local-frame mask, valid only when state == Cached
|
||||
private readonly sbyte[] _floorZ; // local floor Z, valid only when state == Cached
|
||||
|
||||
public MultiLocalMask(int width, int height)
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue