Skip to content

Subjects

A subject is a codebase being tested by Screeps Lab. It may be a Screeps bot, package, fixture project, or other source tree that can be deployed into a private Screeps environment.

Subject repositories remain external so Screeps Lab does not become the owner of colony code. The expected local layout is:

~/projects/
├── screeps/
└── screeps-lab/

Screeps Lab may reference the primary colony checkout with a relative path such as ../screeps.

Implemented Synthetic Subject

Release 0.1.2 adds a synthetic smoke subject used by:

npm run subject:smoke

The synthetic subject is not the primary colony bot. It installs a tiny main module for a local private-world player and writes a deterministic Memory.screepsLab marker after one controlled tick. It does not claim rooms, place spawns, create creeps, or deploy an external repository.

Identity resolution is explicit:

  • CLI options, when provided.
  • .env values.
  • Generated anonymous defaults.

Set both SCREEPS_LAB_SERVER_USERNAME and SCREEPS_LAB_SERVER_PASSWORD to use a named local identity. Leave both empty for anonymous subject smoke testing. A half-configured identity fails before the server starts, and the password is not stored in artifacts or memory.

External Screeps Repository Subject

Release 0.2.4 adds the external-screeps-repository adapter used by:

npm run subject:deploy -- --path ../screeps

The adapter keeps the subject checkout external, resolves the selected path canonically, rejects recursive references into this repository, runs an explicit local build command, collects generated JavaScript modules, records Git provenance, writes deterministic manifests, and returns a normalized prepared subject to the CLI and server adapter.

Default configuration:

build command: npm run build
output:        dist
entry module:  main
server branch: lab
player:        DaelinSolo

Override these with CLI options or environment:

npm run subject:deploy -- --path ../screeps --build-command "npm run build" --output dist --entry main --player DaelinSolo --branch lab

SCREEPS_LAB_SUBJECT_PATH
SCREEPS_LAB_SUBJECT_ID
SCREEPS_LAB_SUBJECT_BUILD_COMMAND
SCREEPS_LAB_SUBJECT_OUTPUT
SCREEPS_LAB_SUBJECT_ENTRY
SCREEPS_LAB_SERVER_USERNAME
SCREEPS_LAB_SERVER_BRANCH

Build behavior is intentionally explicit. Screeps Lab does not infer arbitrary package lifecycle scripts and does not upload to the public MMO. The operator is responsible for choosing a local-only build command.

The entry module is wrapped in place so compiled relative require(...) calls continue to resolve normally. The wrapper writes Memory.screepsLab.externalSubject, then delegates to the original module.exports.loop. Subject loop errors are recorded and rethrown.

Generated artifacts live under artifacts/subject-deploy/. The latest symlink points to the newest run-specific directory. The summary and manifests prove what was built, installed, and verified without copying the whole external repository or storing secrets.

External Subject Scenarios

Release 0.3.2 reuses the same external-screeps-repository adapter inside the scenario runner:

npm run scenario:run -- external-subject-smoke --subject-path ../screeps --ticks 100

The scenario runner does not import subject source into Screeps Lab. It asks the adapter to resolve, build, collect modules, wrap the entry point with the Lab-owned execution marker, and return provenance. The server adapter then bootstraps the private world, installs the complete module map into the scenario branch, activates it, advances controlled ticks, observes Memory.screepsLab.externalSubject, evaluates generic assertions, and writes run artifacts under artifacts/scenarios/runs/<run-id>/.

Subject provenance includes Git branch, revision, dirty status, build command result, module count, and module-manifest checksum. The artifacts do not copy the external repository and do not serialize process environment secrets.

subjects/local/ remains ignored so developers can place local experiments there without committing them. Safe example subjects may be committed under subjects/examples/ for tests and demonstrations.