feat(pathfinding): JSONL recorder + public bake helpers (#2449)

## Summary

Adds two pieces of pathfinding tooling on top of PR #2448's lazy `.swb` infrastructure:

- **`PathfindRecorder`** — admin-toggled JSONL telemetry capture; one record per `BitmapAStarAlgorithm.Find` call. Output format matches the BDN harness corpus, so production traffic can be captured and replayed in benchmarks without an adapter.
- **Public bake helpers on `StepCache`** — `ComputeLiveTileDataHash`, `TryReadTileDataHashFromFile`, `BakeMap`, `ClearResidentChunks`. Lets the benchmark project (and any future bake utility) drive cache fill + persist without exposing internal types.

The companion BDN harness update lives in [ModernUO-Benchmarks#kb/pathfinding-pr4-bench](https://github.com/modernuo/ModernUO-Benchmarks/tree/kb/pathfinding-pr4-bench): porting `Benchmarks/PathfindInGame/` from the `kb/ai_pathfinding` branch to the API shipped in #2446–#2448.

## What's in this PR

### `PathfindRecorder` (`PathfindRecorder.cs`)
- Holds a single `StreamWriter` open while recording; its internal buffer absorbs per-record writes without per-call `File.AppendAllText`.
- Single `bool` check on the hot path; cheap when disabled.
- Disabling flushes + disposes; an IO failure during write also disables the recorder.
- Server config:
  - `pathfinding.recorder.enable` — bool, default `false`. Read on boot via `GetOrUpdateSetting`.
  - `pathfinding.recorder.path` — default `<basedir>/Data/Pathfinding/recordings/pathfinds.jsonl`.
- Hooked into `BitmapAStarAlgorithm.Find` — runs once per call, does nothing when disabled.
- Admin command: `[PathRecord [on|off|flush|status]` (default `status`).

### Public cache helpers
- `static ulong StepCache.ComputeLiveTileDataHash()` — wraps the file module's hash function for staleness checks.
- `static bool StepCache.TryReadTileDataHashFromFile(string, out ulong)` — peeks at a `.swb` file's hash field (20 bytes).
- `int StepCache.BakeMap(int, string)` — walks every chunk in the map, populates resident set, saves. Offline / fixture use; blocks for many seconds on a full-map walk.
- `void StepCache.ClearResidentChunks()` — drops chunks + zeros counters but keeps lazy readers open. Lets benchmark loops measure "first query after boot" cost across iterations without the lazy-reader reopen overhead.
This commit is contained in:
Kamron Batman 2026-05-06 13:06:28 -07:00 • committed by GitHub
parent 7c9215d97c
commit a8ca82738d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 587 additions and 27 deletions

View file

@ -9,6 +9,7 @@ namespace Server.Engines.Pathing;
/// [PathCacheClear — drop all cached chunks, close lazy readers, zero counters.
/// [PathCacheSave — persist resident chunks per map to Data/Pathfinding/&lt;mapId&gt;.swb.
/// [PathCacheLoad — open those files as lazy backing stores. Also runs at startup.
/// [PathRecord — toggle JSONL telemetry capture for replay / benchmark corpora.
/// </summary>
public static class PathCacheCommands
{
@ -25,10 +26,13 @@ public static class PathCacheCommands
8192
);
PathfindRecorder.Configure();
CommandSystem.Register("PathCacheStats", AccessLevel.Administrator, OnPathCacheStats);
CommandSystem.Register("PathCacheClear", AccessLevel.Administrator, OnPathCacheClear);
CommandSystem.Register("PathCacheSave", AccessLevel.Administrator, OnPathCacheSave);
CommandSystem.Register("PathCacheLoad", AccessLevel.Administrator, OnPathCacheLoad);
CommandSystem.Register("PathRecord", AccessLevel.Administrator, OnPathRecord);
AutoLoadAtStartup();
}
@ -120,4 +124,43 @@ public static class PathCacheCommands
$"StepCache: opened {openedMaps} map(s) for lazy loading (total readers open: {StepCache.Instance.OpenLazyReaderCount})."
);
}
[Usage("PathRecord [on|off|flush|status]")]
[Description("Toggles PathfindRecorder. With no arg, reports state. 'on' enables JSONL capture of every Find call; 'off' disables and flushes; 'flush' forces a buffer flush without disabling.")]
private static void OnPathRecord(CommandEventArgs e)
{
var arg = (e.Arguments.Length > 0 ? e.Arguments[0] : "status").ToLowerInvariant();
var from = e.Mobile;
switch (arg)
{
case "on":
{
PathfindRecorder.SetEnabled(true);
from.SendMessage(PathfindRecorder.Enabled
? $"PathRecord: ON, writing to {PathfindRecorder.OutputPath}"
: "PathRecord: enable failed (see server log)");
break;
}
case "off":
{
PathfindRecorder.SetEnabled(false);
from.SendMessage("PathRecord: OFF");
break;
}
case "flush":
{
PathfindRecorder.Flush();
from.SendMessage($"PathRecord: flushed ({PathfindRecorder.RecordsWritten} records this session)");
break;
}
default:
{
from.SendMessage(
$"PathRecord: {(PathfindRecorder.Enabled ? "ON" : "OFF")}, "
+ $"path={PathfindRecorder.OutputPath}, records={PathfindRecorder.RecordsWritten}"
);
break;
}
}
}
}