4bbc4589e7
The pathing and step-cache comments had accumulated as development notes rather
than documentation: 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 multi-paragraph blocks restating what the code says.
Rewritten to keep the rationale a reader cannot derive from the code - why the
source-Z guard cannot be loosened, why multis fall through, why the promotion gate
counts Finds instead of calls, why the fingerprint hashes files rather than the
live tile tables - and to drop the history that got us there.
Also corrects comments that had gone stale:
- CacheEvictionTimer and CacheStats documented a class named
StaticWalkabilityCache, which no longer exists; it is StepCache.
- StepCacheFile's header said "File layout v8" while FormatVersion is 9, and the
body called the current record layout "the v6 layout" throughout. The layout
descriptions are now unversioned, since they describe whatever FormatVersion
currently is.
- StepProbe.ComputeStandingZ claimed StepCache uses it to bake SourceZ. It hasn't
since the baker moved to the clearance-aware ComputeStandableSurfaceZs; only a
parity test calls it now.
Two small code changes came along with the comment work, both behavior-preserving:
_lazyReaders now uses a collection expression like its neighbours, and
TryLoadFromLazyReader collapses to an expression body once its inline comment moved
to the doc comment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
18 lines
1 KiB
C#
18 lines
1 KiB
C#
namespace Server.Engines.Pathing.Cache;
|
|
|
|
/// <summary>
|
|
/// Outcome of <see cref="StepCache.TryGetMask"/>. Drives both telemetry and the caller's
|
|
/// decision to fall back to the slow path. Ordering is load-bearing: 0-2 are usable answers,
|
|
/// 3+ are fallthroughs, and <see cref="StepMask.IsHit"/> tests that boundary.
|
|
/// </summary>
|
|
public enum CacheHitKind : byte
|
|
{
|
|
Hit = 0, // served from the resident chunk
|
|
Miss_NotBuilt = 1, // chunk wasn't resident; built and returned
|
|
Miss_DirtyRebuild = 2, // chunk was stale; rebuilt and returned
|
|
Fallthrough_MultiZ = 3, // stacked walkable surfaces, none matching the query Z
|
|
Fallthrough_OffMap = 4, // out of bounds
|
|
Fallthrough_SourceZMismatch = 5, // |query Z - baked SourceZ| > StepHeight; a cached answer would diverge
|
|
Fallthrough_NotBuilt = 6, // first touch of an unbuilt chunk; the promotion gate defers the build
|
|
Fallthrough_Multi = 7, // a multi (house/boat) covers this cell or its halo
|
|
}
|