Skip to content

Pulling MMO snapshots from OCI

npm run snapshot:pull copies one complete Screeps MMO snapshot artifact from the development machine configured by the oci-screeps SSH alias into the local Screeps Lab snapshot inbox. It is a one-way operator workflow; it does not generate snapshots, synchronize source code, run scenarios, or deploy to the MMO.

Prerequisites

  • Run the command from a WSL checkout of Screeps Lab.
  • Configure a working oci-screeps host in the operator's SSH configuration. The alias supplies the remote host, username, and identity; none are stored in this repository.
  • Install ssh and rsync locally and ensure both are on PATH.

The default workflow is:

npm run snapshot:pull

It inspects /home/ubuntu/projects/screeps/artifacts/screeps-lab-snapshots through oci-screeps, considers only directories that directly contain snapshot.json, and selects the newest such file by modification time. Equal timestamps are resolved deterministically by directory name. A newer unrelated file under the artifact root is not considered.

Select a known artifact or preview the selected artifact and rsync plan:

npm run snapshot:pull -- --snapshot-id shard3-E48N13-81484621
npm run snapshot:pull -- --dry-run
npm run snapshot:pull -- --help

Machine-local configuration can use environment variables. Explicit CLI values take precedence over environment values, which take precedence over defaults:

export SCREEPS_LAB_SNAPSHOT_SSH_HOST=oci-screeps
export SCREEPS_LAB_SNAPSHOT_REMOTE_ROOT=/home/ubuntu/projects/screeps/artifacts/screeps-lab-snapshots
export SCREEPS_LAB_SNAPSHOT_DESTINATION=artifacts/incoming/screeps/snapshots

npm run snapshot:pull -- \
  --host oci-screeps \
  --remote-root /home/ubuntu/projects/screeps/artifacts/screeps-lab-snapshots \
  --destination artifacts/incoming/screeps/snapshots

Local layout and validation

Transfers enter an ignored staging directory. Screeps Lab then validates the transferred snapshot.json with the @screeps-lab/snapshots contract before finalizing it:

artifacts/incoming/screeps/snapshots/
├── shard3-E48N13-81484621/
│   ├── snapshot.json
│   └── retrieval-summary.json
└── latest -> shard3-E48N13-81484621

latest changes only after rsync and validation both succeed. Failed or interrupted transfers cannot replace it, existing snapshots are preserved, and pulling the same snapshot ID again is safe. A validation failure prints its diagnostics and leaves the staging location available for inspection. Dry runs make no local snapshot-directory changes and do not validate or update latest.

After a successful pull:

npm run sandbox:inspect -- \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json

npm run scenario:run -- mmo-snapshot-smoke \
  --subject-path ../screeps \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json \
  --ticks 100 \
  --reset