| name | route-pack-generation |
| description | Generate and validate a static route pack for a long fixed leg, gated by the long-pathing route tests. Use when a frequently-traveled static route should be precomputed and cached. |
| trigger | route pack, static route, long leg, precomputed route, route gate, LongPathingRouteTests, StaticRoutePackCache, validate a route |
Route Pack Generation
Goal
Produce and validate a static route pack for a long, fixed travel leg so the
PathfindingService can serve it from cache, with the long-pathing route test as
the green gate.
The pathfinding freeze applies: route packs are data; do not add new managed
repair phases to Services/PathfindingService/Repository/Navigation.cs. See
docs/physics/README.md.
Inputs
- The leg: start/end anchors, race/gender, route policy.
- Key files (verified):
- Cache/generation:
Services/PathfindingService/RoutePacks/StaticRoutePackCache.cs.
- Route manifests:
tools/scripts/routes/*.json (e.g. og-zeppelin.json).
- Probe:
tools/scripts/probe-routes.ps1, Tools/PathPhysicsProbe/.
- Gate tests:
Tests/PathfindingService.Tests/LongPathingRouteTests.cs.
- Spec:
docs/Spec/06_PATHFINDING.md (§Route-pack manifest — data contract +
validation guards).
- Area rules:
.github/instructions/tools.instructions.md.
Preconditions
- The underlying mesh is correct for the leg (if it clips static geometry, fix the
mesh first via [[pathfinding-bake-iteration]]).
Procedure
- Define the leg in
tools/scripts/routes/<route>.json (start/end, race/gender,
policy).
- Probe it:
tools/scripts/probe-routes.ps1 -Manifest tools/scripts/routes/<route>.json;
confirm every segment resolves with no blocking failure.
- Add a focused route test (or extend
LongPathingRouteTests) asserting the leg
avoids known static blockers.
- Once green, register the pack in
StaticRoutePackCache.cs.
- Confirm the route-pack signature matches the baked mmaps + Navigation.dll +
config (per Spec/06 guards).
Verification
dotnet test Tests/PathfindingService.Tests/PathfindingService.Tests.csproj --filter "FullyQualifiedName~LongPathingRoute".- Probe output shows all segments resolved.
Outputs
tools/scripts/routes/<route>.json manifest, a route gate test, and a
StaticRoutePackCache entry.
Failure modes and recovery
- Caching a route over a broken mesh — fix the mesh first; a cached bad route
is worse than none.
- Signature mismatch after a mesh/Navigation.dll change invalidates packs —
regenerate and re-validate.
- Adding managed repair to force the gate green — forbidden under the freeze.
Related skills
- [[pathfinding-bake-iteration]] — fix the mesh the route runs on.
- [[fg-bg-physics-parity]] — movement parity along the leg.
- Reference:
docs/Spec/06_PATHFINDING.md, docs/physics/README.md.
