Skip to content

Screeps Lab Snapshot Export

This repository owns the MMO-side exporter for portable Screeps Lab snapshots. Screeps Lab is a separate sibling repository; this bot does not import Lab code, write into Lab paths, or assume Lab private-server storage internals.

Contract

Current schema:

  • format: screeps-lab.snapshot
  • version: 1
  • exporter schema version: 1
  • checksum: fnv1a-32, non-cryptographic
  • terrain encoding: rows-v1

The checksum is calculated over the serialized snapshot after normalizing manifest.checksum to 00000000. This lets the artifact include its own checksum without pretending the weak in-game checksum is cryptographic.

Schema version 1 is backward-conscious:

  • optional additive fields may remain version 1
  • consumers should ignore unknown fields where possible
  • changing required fields or field meaning requires deliberate versioning
  • removing fields requires coordination with Screeps Lab consumers
  • every snapshot should remain self-describing through its manifest

Captured Data

The first exporter captures one visible owned room in one game tick:

  • snapshot metadata
  • room terrain, 50 by 50 cells
  • controller state
  • sources
  • mineral
  • visible structures
  • construction sites
  • resource stores and safe capacity metadata
  • player username and GCL
  • complete raw player Memory from RawMemory.get()
  • snapshot-local object references
  • public source object ID index for later Memory reference rewriting
  • manifest, byte length, chunk count, counts, and checksum

Public MMO object IDs are source metadata only. Snapshot-local refs are the portable identity, for example source:E48N13:9:7 or structure:storage:E48N13:7:8.

Deferred Data

Version 1 intentionally does not export live creeps, power creeps, tombstones, ruins, dropped resources, hostile creep state, NPC state, market orders, inter-shard memory, global map reconstruction, invisible rooms, pending intents, private engine bookkeeping, exact server database IDs, replay history, screenshots, telemetry history, or automatic upload into Screeps Lab.

The importer is responsible for reconstructing private-server objects, remapping IDs, and deciding how to mutate a reconstructed world.

Segment Reservation

The exporter reserves RawMemory segments 70-79.

No other subsystem in this repository should use those segments without updating this document and the exporter constants. Each segment stores one deterministic snapshot chunk. The exporter publishes at most one chunk per tick and marks the snapshot complete only after all chunks are written.

If the global runtime resets before publication finishes, the status changes to failed because the serialized payload is intentionally not stored in normal Memory.

Operator Commands

After the feature branch is deployed manually to the MMO beta branch, use:

debug.beginLabSnapshot("E48N13")
debug.labSnapshotStatus()
debug.cancelLabSnapshot()
debug.clearLabSnapshot()

debug.beginLabSnapshot(roomName) validates that the room is visible and owned by the current player, captures immediately, reserves segments, and starts publication. It never prints the full snapshot.

debug.labSnapshotStatus() returns the small exporter status in Memory.screepsLabSnapshot, including snapshot ID, room, captured tick, segment IDs, chunk progress, byte count, checksum, and any error.

debug.cancelLabSnapshot() stops an active publication and leaves completed segments alone.

debug.clearLabSnapshot() clears exporter-owned status and writes empty strings to the exporter-owned segments. Run it only after downloading the artifact.

Download

Download a completed snapshot with:

npm run lab:snapshot:download -- --room E48N13

or:

npm run lab:snapshot:download -- --snapshot-id shard3-E48N13-81480000

The downloader reads Memory.screepsLabSnapshot, fetches the listed RawMemory segments, reassembles the payload, verifies byte length and checksum, validates schema invariants, and writes:

artifacts/screeps-lab-snapshots/<snapshot-id>/
  snapshot.json
  retrieval-summary.json

Generated artifacts are ignored by git and must not be committed.

Offline validation is available for an already downloaded snapshot:

npm run lab:snapshot:download -- --offline-file artifacts/screeps-lab-snapshots/<snapshot-id>/snapshot.json

Logistics Performance Validation

Milestone 0.3.6.4 does not change the snapshot schema. Raw player Memory already carries route performance summaries and Memory.stats, while normal world reconstruction supplies structures, creeps, and terrain. The proposed Lab scenario contracts, tolerances, tick windows, capture fields, and operator command shape are documented in docs/LOGISTICS_PERFORMANCE_VALIDATION.md.

Live Test Sequence

  1. Review and deploy this feature branch manually to the Screeps beta branch.
  2. Run debug.beginLabSnapshot("E48N13").
  3. Poll debug.labSnapshotStatus() until status is complete.
  4. Run npm run lab:snapshot:download -- --room E48N13.
  5. Inspect snapshot.json and retrieval-summary.json.
  6. Provide the artifact to Screeps Lab.
  7. Only after successful live verification consider merging.