Skip to content

Repository Layout

Screeps Lab is a monorepo for the lab system itself. It does not contain the primary Screeps colony repository.

Top-Level Areas

apps/

Independently runnable processes.

  • overlord/: future orchestration service for scenarios, agents, server state, deployments, observations, assertions, and artifacts.
  • private-server/: future private-server configuration and lifecycle management.
  • operator-cli/: future human-facing command interface.

packages/

Reusable internal libraries. These are conceptual boundaries for now and do not yet define stable APIs.

  • screeps-client/: future Screeps deployment, console, memory, world inspection, and server-control API.
  • agent-protocol/: future contracts for commands, events, tasks, observations, responses, failures, and capabilities.
  • scenario-sdk/: future scenario declarations, fixtures, hooks, actions, assertions, and success conditions.
  • test-runner/: future scenario execution, polling, limits, assertions, and report generation.
  • shared/: cross-cutting types and utilities. It should stay intentionally small and not become a dumping ground.

scenarios/

Committed test and simulation definitions, grouped by domain. Future scenarios may define room state, terrain, sources, controllers, structures, creeps, hostiles, setup actions, tick limits, assertions, and cleanup behavior.

subjects/

Documentation, committed examples, and ignored local subject workspaces. Real subject repositories remain external.

config/

Checked-in default configuration and future schemas. Secrets and machine-specific values do not belong here.

scripts/

Repository-level development and operational scripts. Future scripts may cover bootstrap, validation, context export, start, stop, or reset workflows.

docs/

Detailed architecture and user or developer guides that would make the root documentation too large.

artifacts/

Generated run output such as reports, logs, screenshots, and replays. Runtime output is ignored by default unless intentionally retained as a fixture.

tests/

Repository-wide integration and end-to-end tests. Package-level unit tests stay near their packages.