Snapshot inspection and import

Screeps Lab owns the import-side screeps-lab.snapshot schema-v1 contract in @screeps-lab/snapshots. Snapshot JSON remains the boundary between an external Screeps exporter and the Lab; the Lab does not import exporter modules or inspect arbitrary Memory to discover rooms.

Terrain catalog

Schema version 1 has an additive optional top-level terrainRooms field:

{
  "terrainRooms": [
    {
      "roomName": "E48N13",
      "encoding": "rows-v1",
      "width": 50,
      "height": 50,
      "rows": ["50 terrain cells per row"]
    },
    {
      "roomName": "E48N14",
      "encoding": "rows-v1",
      "width": 50,
      "height": 50,
      "rows": ["50 terrain cells per row"]
    }
  ]
}

Every entry requires a valid Screeps room name, rows-v1, width and height 50, exactly 50 string rows, exactly 50 cells per row, and only p, s, and w cells. Room names must be unique and the primary room.name must occur exactly once. Input order is not significant; the neutral import plan sorts entries by room name. Invalid entries are rejected rather than dropped.

room.terrain remains the primary-room terrain copy. A legacy snapshot without terrainRooms derives a one-entry effective catalog from room.name and room.terrain, so existing schema-v1 exporters remain compatible. Checksums are verified against the original artifact exactly as before; the schema version and checksum algorithm do not change.

Reconstruction boundary

The primary snapshot room continues to own the controller, ownership, sources, mineral, structures, construction sites, object-ID remapping, and raw Memory rewrite. An auxiliary terrain entry carries terrain only. It does not synthesize objects, controllers, ownership, users, room Memory, or exported visibility. Terrain presence is not evidence that the source player could see or owned the room.

The official private-server adapter clears the reset-authorized world, writes a minimal room record and authoritative terrain record for every effective entry, and publishes the complete compressed terrain catalog before the first subject tick. Only the primary room is placed in active/accessibility metadata and only the primary room receives map-view metadata. Terrain-only room records carry a non-expiring nextForceUpdateTime, preventing the official roomsForceUpdate cron from activating an otherwise empty normal room. This is the minimum distinction needed for remote route and road-planning code to load auxiliary terrain through Game.map.getRoomTerrain(roomName) without turning the auxiliary room into an owned or visible room.

After persistence, the adapter re-reads official storage and verifies every room and terrain payload, the published runtime terrain catalog, primary object IDs and ownership, absence of auxiliary objects and ownership, primary-only accessibility/map-view metadata, and absence of auxiliary or unexpected active rooms. The runtime may transiently report no active rooms while applying a restart; verification records primary activation but does not mistake that transition for auxiliary activation. Any missing or mismatched terrain fails import before subject installation or execution and identifies the affected room where possible.

sandbox:inspect, sandbox:import, scenario provenance, scenario summaries, and suite consumers report the primary terrain room, sorted terrain room names, total and auxiliary counts, and verification result. Routine terminal and JSON summaries do not duplicate the 50×50 row payloads; the checksum-validated source snapshot remains the detailed terrain artifact.