Skip to content

Logistics Performance And Screeps Lab Validation

Milestone 0.3.6.4 adds compact route-performance feedback without changing creep action ownership, infrastructure approval, remote-operation policy, or the Screeps Lab snapshot schema.

Runtime Contract

Each persisted route has an additive performance summary below Memory.rooms.[roomName].logisticsNetwork.routes.[routeKey].performance. The stable route ID remains the id property; raw route IDs are not exported as per-route stats paths.

Schema version 6 additionally stores the complete performance summary and current window as versioned tuples, eliminating repeated field-name overhead per route. Schema version 5 compacted three internal representations. Path-cache topology is stored as a versioned 64-bit rt3: signature. Traffic records are version-1 tuples with a canonical cross-room position key and bit flags rather than duplicated key/position objects. Anomalies are version-1 tuples containing health, a typed reason code, and only the numeric evidence needed to reproduce operator text. A bounded per-room migration accepts mixed legacy and compact records, rewrites each room once, and is safe across global resets.

Current-window counters roll up on the existing 25-tick logistics cadence. Longer-term values use an EWMA. Traffic retains at most 24 meaningful tiles per route, health transitions retain at most eight anomalies, and traffic influence decays by 0.85 per rollup. Existing completed/abandoned job TTLs remain bounded.

Only assigned local, link-service, and remote-hauling work is attributed. Scouts, builders, incidental movement, and unassigned creeps do not contribute. Congestion requires repeated same-position samples, no fatigue, a successful move intent, and nearby traffic. Four samples are required for a chokepoint.

Cache eligibility requires a persistent creep/hybrid route, stable endpoints, active policy, 20 traversal samples, two meaningful geometry recalculations, expected throughput of at least one energy/tick, and a current fingerprint. Custom serialized movement reuse is deliberately disabled. Eligible routes report eligible-telemetry-only; existing moveTo reuse and infrastructure geometry caching remain authoritative.

Traffic changes only existing road candidate scores and thresholded on-route candidate positions. It never approves a build order or places a site.

Shared Lab Procedure

The names below are proposed scenario contracts, not implemented Screeps Lab scenario IDs and not claims of passing private-server validation.

For every scenario:

  1. Build the subject branch and reset the world.
  2. Locate routes by origin, transportMethod, rooms, and node roles. Never hardcode current MMO object IDs or creep names.
  3. Capture the initial route, each 25-tick window, final Memory.stats, and debug.logisticsNetwork(), debug.logisticsRoutes(), and debug.logisticsRoute().
  4. Allow one initialization window and three windows/75 ticks before asserting health. Rolling throughput/cycle tolerance is plus or minus 20%; tick counts allow plus or minus one at boundaries.
  5. Assert trafficTiles length is at most 24, anomalies length is at most eight, and no tick-by-tick route history exists.
  6. Capture Memory.stats.rooms.[roomName].logistics.network.performance.

Example operator command shape:

cd ../screeps-lab

npm run scenario:run -- <scenario-id> \
  --subject-path ../screeps \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json \
  --reset \
  --server-tick-duration-ms 100

Use a real scenario ID only after implementing the proposed contract in Lab.

Scenario A — Healthy Road-Backed Route

  • Fixture/roles: owned room, stable source container and consumer/storage, completed road geometry, adequate ordinary-hauler capacity, normal producer and consumer roles, no forced blockers.
  • Duration/route: 100 ticks minimum, 150 preferred; local-hauling creep route located by endpoint roles.
  • Memory/stats/debug: efficiency approaches one, backlog is stable/decreasing, actual cycle is within 20% of estimate, congestion/fatigue are below 0.08, health becomes healthy, actualThroughput is positive, and debug shows no custom cache enabled.
  • Pass: no unnecessary traffic-only road candidate. Existing approval remains unchanged. Suitable for automated Lab assertion.

Scenario B — Frequently Traveled Unroaded Route

  • Fixture/roles: persistent local route over plain/swamp tiles without roads; assigned hauler plus unrelated scout and builder as contamination controls.
  • Duration/route: 150 ticks/six windows; local creep route by endpoint roles.
  • Memory/stats/debug: only assigned route gains traffic; unroaded/fatigue weights rise; thresholded on-route tiles enter existing routeRoadIntents; unrelated positions do not. Health reflects measured impairment after confidence.
  • Pass: candidate score may rise, but no site appears without approval. Operator-run if proposal cadence makes the fixture long.

Scenario C — Destination Blockage

  • Fixture/roles: source energy and assigned transport remain available while exact destination cannot accept energy; restore it after three windows.
  • Duration/route: 75 blocked ticks plus 100 recovery; local or remote route.
  • Memory/stats/debug: destination blockage rises without mirrored source blockage; backlog stays elevated/grows; efficiency falls; reason names destination blockage; route recovers after capacity returns.
  • Pass: recovery preserves route identity and unrelated evidence. Suitable for automated phase assertions.
  • Fixture/roles: source/storage links and source container; receiver lacks capacity for three windows then is drained; conventional fallback available.
  • Duration/route: 175 ticks; exact link-logistics source-link/storage-link route.
  • Memory/stats/debug: receiver blockage and missed opportunities rise; actual post-loss received energy differs from expected; fallback rate rises when used and later recovers; broad debug.links telemetry remains compatible.
  • Pass: compact state explains blockage, fallback, throughput loss, and idle receiver capacity without a per-tick ledger. Suitable for automation.

Scenario E — Congestion Chokepoint

  • Fixture/roles: multiple assigned logistics creeps repeatedly cross a narrow tile/room transition; fatigue controlled separately.
  • Duration/route: 150–250 ticks on an active creep/hybrid route.
  • Memory/stats/debug: one-tick blockage remains below threshold; repeated delay raises congestion weight to four and chokepoint=true; fatigue stays separate; debug reason names congestion.
  • Pass: road priority changes only after threshold evidence; workflows still own movement. Operator-run because collision timing may vary by two ticks.

Scenario F — Fatigue-Heavy Route

  • Fixture/roles: under-MOVE hauler or swamp-heavy unroaded route with traffic clear; optional second road-backed phase through normal approval.
  • Duration/route: 150 ticks per phase; assigned creep route.
  • Memory/stats/debug: fatigue rises while congestion stays low; reason names fatigue/slow movement; road phase improves cycle and throughput within 25%.
  • Pass: fatigue and congestion remain distinct. Suitable for automation with 25% cycle tolerance.

Scenario G — Cache Invalidation

  • Fixture/roles: persistent assigned route meeting thresholds, followed by an endpoint or relevant topology/revision change.
  • Duration/route: normally 200+ ticks for eligibility plus two post-change windows.
  • Memory/stats/debug: status becomes eligible-telemetry-only while enabled stays false; endpoint, lifecycle, infrastructure-component, or road-coverage fingerprint change becomes invalidated; existing bounded infrastructure geometry recalculates and path-recalculation stats increase.
  • Pass: no obsolete custom geometry is followed because custom caching is disabled. Operator-run until deterministic topology mutation hooks exist.

Scenario H — Low-Value Route Decay

  • Fixture/roles: accumulate route traffic, then deactivate/retire the route and remove assigned work.
  • Duration/route: 100-tick warmup plus eight windows/200 ticks decay.
  • Memory/stats/debug: weights multiply by 0.85 per rollup, low-weight tiles disappear, arrays stay bounded, and retired route loses road-score influence.
  • Pass: historical traffic does not permanently preserve priority. Suitable for automated long-duration assertion or operator-run under runtime constraints.

Fresh Snapshot And Run Order

No snapshot schema change is required: snapshots already include raw player Memory and normal world reconstruction. A fresh MMO snapshot is optional. If used, prefer an owned room with a source container, active hauler, route-road geometry, and source/storage links. Fixtures must discover their own IDs.

Recommended order: A, C, D, F, B, E, G, H. A/C/D/F should be automated first. E/G remain intentionally operator-run until deterministic collision and topology-mutation fixture support is added in the sibling repository.