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
|
|
@ -3,20 +3,19 @@ using System;
|
|||
namespace Server.Engines.Pathing.Cache;
|
||||
|
||||
/// <summary>
|
||||
/// Per-chunk storage backing StepCache. Holds raw walk + swim masks and destination Z
|
||||
/// values for each of 256 cells in a 16x16 chunk, plus build-time metadata (multis version, multi-Z strata)
|
||||
/// and LRU bookkeeping.
|
||||
/// Per-chunk storage backing <see cref="StepCache"/>: walk + swim masks and destination Zs for
|
||||
/// each of the 256 cells in a 16x16 chunk, plus the optional multi-Z strata and swim layers and
|
||||
/// the LRU timestamp.
|
||||
/// </summary>
|
||||
internal sealed class StepChunk
|
||||
{
|
||||
public const int CellsPerChunk = 256; // 16 x 16
|
||||
|
||||
/// <summary>Bit i of WalkMask[c] = "default walker can step from cell c to neighbor (Direction)i".
|
||||
/// Raw — no diagonal corner-cut applied here.</summary>
|
||||
/// <summary>Bit i of WalkMask[c]: a default walker can step from cell c to neighbour (Direction)i.
|
||||
/// Raw — no diagonal corner-cut applied, so callers must AND the partner bits themselves.</summary>
|
||||
public readonly byte[] WalkMask = new byte[CellsPerChunk];
|
||||
|
||||
/// <summary>Bit i of WetMask[c] = "swim-only mob can step from cell c to neighbor (Direction)i".
|
||||
/// Layered with WalkMask via canSwim/cantWalk capability flags.</summary>
|
||||
/// <summary>Bit i of WetMask[c]: a swim-only mob can step from cell c to neighbour (Direction)i.</summary>
|
||||
public readonly byte[] WetMask = new byte[CellsPerChunk];
|
||||
|
||||
public readonly sbyte[] SourceZ = new sbyte[CellsPerChunk];
|
||||
|
|
@ -40,14 +39,13 @@ internal sealed class StepChunk
|
|||
public readonly sbyte[] SwimZNW = new sbyte[CellsPerChunk];
|
||||
|
||||
/// <summary>
|
||||
/// Swim layer — populated only for chunks containing at least one shore cell (a cell
|
||||
/// with both a walkable land surface and a water surface separated by > StepHeight).
|
||||
/// On shore cells, queries from the swim source Z miss the primary source-Z guard;
|
||||
/// the swim layer carries the correct wetMask + per-direction destination Zs computed
|
||||
/// from the water surface's perspective. For non-shore cells in a chunk that has the
|
||||
/// layer, <see cref="SwimSourceZ"/>[cell] = <see cref="NoSwimLayerCell"/> sentinel.
|
||||
/// All swim-layer arrays are null on chunks with no shore cells (~90% of map chunks
|
||||
/// on Trammel) — zero memory cost on the common case.
|
||||
/// Marks a cell with no swim-layer entry, in a chunk that has the layer.
|
||||
///
|
||||
/// The swim layer exists only on chunks holding at least one shore cell — a cell with both a
|
||||
/// walkable surface and a water surface more than StepHeight apart. A swim query there sits
|
||||
/// too far from the primary SourceZ to pass the source-Z guard, so the layer carries a second
|
||||
/// mask and destination-Z set computed from the water surface instead. Chunks with no shore
|
||||
/// cells leave every swim-layer array null.
|
||||
/// </summary>
|
||||
public const sbyte NoSwimLayerCell = sbyte.MinValue;
|
||||
|
||||
|
|
@ -79,9 +77,8 @@ internal sealed class StepChunk
|
|||
public sbyte[] SwimZNW_Layer => _swimZNW_extra;
|
||||
|
||||
/// <summary>
|
||||
/// Lazily allocates the swim-layer arrays and seeds <see cref="SwimSourceZ"/> with
|
||||
/// the <see cref="NoSwimLayerCell"/> sentinel. Called at bake time the first time a
|
||||
/// shore cell is detected in this chunk.
|
||||
/// Allocates the swim-layer arrays and seeds <see cref="SwimSourceZ"/> with
|
||||
/// <see cref="NoSwimLayerCell"/>. Called on the first shore cell found in this chunk.
|
||||
/// </summary>
|
||||
internal void AllocateSwimLayer()
|
||||
{
|
||||
|
|
@ -105,28 +102,30 @@ internal sealed class StepChunk
|
|||
}
|
||||
}
|
||||
|
||||
/// <summary>Sentinel: cell has no strata — single-Z, use the main Walk/Wet arrays.</summary>
|
||||
/// <summary>
|
||||
/// Marks a single-Z cell: no strata, read the main Walk/Wet arrays instead. Because this
|
||||
/// takes ushort.MaxValue, a real strata offset is at most NoStrata - 1, which bounds
|
||||
/// <see cref="StrataData"/> to NoStrata bytes.
|
||||
/// </summary>
|
||||
public const ushort NoStrata = ushort.MaxValue;
|
||||
|
||||
/// <summary>
|
||||
/// Length-256 offset table: <c>StrataOffsetByCell[cell] = byte offset</c> into
|
||||
/// <see cref="StrataData"/> where this cell's strata begin, or <see cref="NoStrata"/>
|
||||
/// for cells without multi-Z. Null when the chunk has zero multi-Z cells.
|
||||
/// Length-256 table mapping a cell to the byte offset in <see cref="StrataData"/> where its
|
||||
/// strata begin, or <see cref="NoStrata"/>. Null when no cell in the chunk is multi-Z.
|
||||
/// </summary>
|
||||
private ushort[] _strataOffsetByCell;
|
||||
|
||||
/// <summary>
|
||||
/// Packed per-cell strata. For each cell with strata:
|
||||
/// u8 stratumCount, then stratumCount × Stratum (19 bytes each):
|
||||
/// sbyte zCenter, byte walkMask, byte wetMask,
|
||||
/// sbyte walkZ_N..NW (8), sbyte swimZ_N..NW (8)
|
||||
/// Packed strata for the multi-Z cells. Per cell: u8 stratumCount, then stratumCount records
|
||||
/// of <see cref="StratumByteLength"/> bytes — sbyte zCenter, byte walkMask, byte wetMask,
|
||||
/// sbyte walkZ_N..NW (8), sbyte swimZ_N..NW (8).
|
||||
/// </summary>
|
||||
private byte[] _strataData;
|
||||
|
||||
/// <summary>Snapshot of Sector.MultisVersion at the time this chunk was built.</summary>
|
||||
/// <summary>Reserved. Chunks are static-only, so this is always 0.</summary>
|
||||
public int BuiltMultisVersion;
|
||||
|
||||
/// <summary>Updated on every cache hit/miss. Used by LRU fallback eviction.</summary>
|
||||
/// <summary>Refreshed on every query that reaches this chunk. Drives LRU eviction.</summary>
|
||||
public long LastTouchedTicks;
|
||||
|
||||
/// <summary>Size in bytes of one Stratum record in StrataData.</summary>
|
||||
|
|
@ -140,10 +139,8 @@ internal sealed class StepChunk
|
|||
_strataData == null ? ReadOnlySpan<byte>.Empty : _strataData.AsSpan();
|
||||
|
||||
/// <summary>
|
||||
/// Single-shot setter for the chunk's strata. Pass null/null to clear (chunk becomes
|
||||
/// "no multi-Z"). Otherwise <paramref name="offsetByCell"/> must be length 256 with
|
||||
/// <see cref="NoStrata"/> for cells without strata, and <paramref name="data"/> the
|
||||
/// packed strata records.
|
||||
/// Sets the chunk's strata in one shot. <paramref name="offsetByCell"/> must be length 256,
|
||||
/// carrying <see cref="NoStrata"/> for single-Z cells. Pass null/null to clear.
|
||||
/// </summary>
|
||||
internal void SetStrata(ushort[] offsetByCell, byte[] data)
|
||||
{
|
||||
|
|
@ -151,18 +148,17 @@ internal sealed class StepChunk
|
|||
_strataData = data;
|
||||
}
|
||||
|
||||
/// <summary>Serialization hook: returns the raw offset array (or null if no strata).</summary>
|
||||
/// <summary>Serialization hook: the raw offset array, or null if the chunk has no strata.</summary>
|
||||
internal ushort[] GetStrataOffsetByCellForSerialization() => _strataOffsetByCell;
|
||||
|
||||
/// <summary>Serialization hook: returns the raw data array (or null if no strata).</summary>
|
||||
/// <summary>Serialization hook: the raw data array, or null if the chunk has no strata.</summary>
|
||||
internal byte[] GetStrataDataForSerialization() => _strataData;
|
||||
|
||||
/// <summary>
|
||||
/// True when every cell shares one value across WalkMask, WetMask, SourceZ, and all 16
|
||||
/// directional-Z arrays, and the chunk has neither multi-Z strata nor a swim layer. Such a
|
||||
/// chunk serializes to a ~28-byte uniform record (StepCacheFile v5) instead of the full
|
||||
/// record. Chunks with a swim layer (shore cells) are never uniform — their per-cell swim
|
||||
/// data must be preserved via the Full record.
|
||||
/// True when all 256 cells share one value across WalkMask, WetMask, SourceZ and every
|
||||
/// directional-Z array, with no strata and no swim layer — open water or solid rock, mostly.
|
||||
/// <see cref="StepCacheFile"/> collapses such a chunk to a ~28-byte record. A swim layer
|
||||
/// disqualifies a chunk outright: its per-cell shore data would not survive the collapse.
|
||||
/// </summary>
|
||||
internal bool IsUniform() => _strataOffsetByCell == null
|
||||
&& !HasSwimLayer
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue