Skip to content

Screeps

This repository contains the TypeScript source for building and pushing code changes to the game Screeps.

The bot is organized as small modules that compile into Screeps modules under dist/, then npm run deploy:beta uploads those compiled modules to the Screeps beta branch.

High-priority runtime note: Screeps loads modules only from the uploaded module map. If MMO console errors report Unknown module '...', treat it as a deploy packaging bug first: confirm the compiled require("...") name exists in tools/deploy.ts, run npm run check, and redeploy beta after verification.

Setup

Install dependencies:

npm install

Create a local environment file:

cp .env.example .env

Then fill in SCREEPS_TOKEN with a Screeps API token.

Environment

Required:

  • SCREEPS_TOKEN: Screeps API token used to upload code.

Optional:

  • SCREEPS_BRANCH: Screeps branch to upload to when running tools/deploy.ts directly. Defaults to beta; use only beta for repository workflows.

Commands

Build the TypeScript source:

npm run build

Run the full local check:

npm run check

This includes deploy-module verification so compiled Screeps runtime imports do not reference modules missing from the upload map.

Run the deterministic body policy scenarios:

npm run verify:body-policy
npm run verify:cpu-population

Run the offline infrastructure planning invariant checks:

npm run verify:infrastructure

Run the deterministic operator-authorized colony-bootstrap scenarios:

npm run verify:colony-bootstrap

Run the deterministic passive remote-operation scenarios:

npm run verify:remote-operations

Run the deterministic logistics-network foundation scenarios:

npm run verify:logistics-network

Run the deterministic route infrastructure and road-integration scenarios:

npm run verify:infrastructure-cutover
npm run verify:infrastructure-road-integration

Build and deploy to Screeps:

npm run deploy:beta

npm run deploy:beta is the normal development workflow and uploads only to the Screeps beta branch.

The deploy tool also accepts a branch flag for one-off workflows, but repository workflows should use the npm script above:

npm exec -- tsx tools/deploy.ts --branch beta

To test the deployment tooling without uploading code:

npm run build
npm exec -- tsx tools/deploy.ts --branch beta --dry-run

Deployment Workflow

Use feature branches for development. Normal deploys from feature branches go to the Screeps beta branch:

  1. Develop on a feature branch.
  2. Run npm run deploy:beta to upload that branch to Screeps beta.
  3. Test the beta branch in the live world.
  4. If beta is successful, merge the feature branch into master; do not deploy to another Screeps branch from this repository workflow.
  5. If beta is unsuccessful, switch the Screeps client back to the master branch immediately.

Project Layout

  • src/main.ts: main game loop entry point.
  • src/spawnConfig.ts: role spawn priorities and body tech levels.
  • src/cpuPopulationPolicy.ts: persisted bucket posture, commanded tier, completed-tick utilization EWMA, and transition hysteresis.
  • src/resourceGovernor.ts: thin parent coordinator for the sibling CPU and Memory resource signals; Launch Control remains the optional-work authority.
  • src/launchControlEnhancements.ts: separate binary enhancement leases for richer bounded work by every already-admitted Launch Control owner.
  • src/memoryGovernor.ts: slow-cadence serialized-Memory pressure, growth, and owner-controlled reclamation signal.
  • src/actions/: reusable Screeps action wrappers.
  • src/workflows/: reusable behavior composed from actions.
  • src/roles/: creep role behavior.
  • src/managers/: room orchestration, defensive assessment, economy assessment, operator-authorized colony bootstrap and boosted-workforce provisioning, bounded mineral-surplus liquidation policy, passive remote-operation assessment, link and terminal logistics, infrastructure maintenance, and spawning.
  • src/managers/colonyLayoutPlanner.ts: authoritative fixed local geometry for core/Lab structures, hybrid Extension pods, local operational Containers/Extractor/Links, and shared lanes; focused local construction performs bounded execution directly from this geometry.
  • src/utils/colonyRoadPolicy.ts: shared, cached retirement eligibility for Roads obstructing colony-layout Extension geometry while preserving planned lanes and operational infrastructure routes.
  • src/logistics/: shared logistics node and route representation, adapters, route-infrastructure validation, bounded performance and traffic feedback, route-road value indexing, room-owned summaries, debug formatting, and aggregate telemetry.
  • src/config/infrastructure.ts: infrastructure-planning policy, allowlist, dirty-domain bounds, and safety limits.
  • src/config/remoteOperations.ts: remote-operation scoring, lifecycle cadence, blockers, and reason bounds.
  • src/config/externalAllocation.ts: per-home external budget dimensions, concurrency limits, hysteresis, and cooldown policy.
  • src/intelligence/: the CIA room-intelligence backbone. It observes and stores room dossiers, produces advisory strategic assessments, and never makes colony decisions.
  • src/integrations/screepsLab/: MMO-side Screeps Lab snapshot export contract, capture normalizers, and RawMemory segment transport.
  • src/room/: shared room-state and energy policy helpers used by managers and roles.
  • src/structures/: behavior modules for owned room structures.
  • src/stats/: telemetry projected into Memory.stats for downstream exporters, including room economy, harvesting, maintenance, and operational metrics.
  • src/types/: typed memory declarations.
  • tools/deploy.ts: build artifact uploader for Screeps.
  • tools/downloadLabSnapshot.ts: read-only downloader for completed Screeps Lab snapshot artifacts.

Energy Economy

At RCL 4 and beyond, completed owned storage is the primary room energy reserve. Source containers remain source-side pickup buffers for haulers, and the controller container remains a local upgrade buffer. Harvesters stand on completed source containers and continuously harvest; overflow energy is allowed to enter the container under the creep instead of spending harvest ticks on explicit transfers. Builders prefer storage, upgraders prefer the controller-side reserve, and both keep safe source-container and harvest fallbacks so rooms continue working before storage exists or when it is empty, full, or unreachable.

EconomyManager owns the room's active reserve policy and economy mode. The normal storage policy uses staged absolute reserve targets rather than percentage fullness, so a newly built Storage does not make the room look unhealthy just because its 300,000 capacity is mostly empty. Emergency mode temporarily tightens those permissions while reserve energy recovers. Hauler and container-logistics workflows enforce the active policy by protecting spawn/extension delivery, tower operating energy, minimum storage reserve, controller buffer delivery, tower top-off, and storage overflow in policy order. When gathering, haulers use a generalized acquisition workflow that can withdraw from source/controller containers or pick up qualifying dropped energy. Loose energy is treated as a logistics source rather than a hauler-role exception: small nearby drops may be salvaged cheaply, significant or decaying drops can preempt routine collection, and backed-up source containers remain ahead of ordinary loose-energy cleanup.

Strategic surplus management is the positive side of that policy. EconomyManager persists a separate strategic surplus state: inactive, building, sustained, or overflow. Sustained surplus and overflow are confirmed with persistence and hysteresis from reserve surplus, smoothed energy trend, storage fill, source-container backlog, spawn reserve, and delivery capacity. Active surplus increases upgrader demand through the normal population plan, can permit additional routine maintenance, and helps logistics clear source containers before harvested energy is wasted.

Native-mineral allocation adjusts Storage pressure without pretending energy is missing: actual stored energy still owns emergency and minimum-reserve checks, while effective energy capacity subtracts protected native inventory and other non-energy occupancy. At that effective ceiling, ordinary energy overflow no longer selects Storage, but urgent spawn, extension, tower, and existing reserve permissions keep their established priority.

Committed local construction is essential work for population recovery. While construction progress remains, EconomyManager always permits recovery from zero to one builder even when optional-worker spawn reserve or the ordinary increase cooldown is unavailable. Emergency and starved rooms remain capped at one builder, additional builders retain all reserve/backlog/cooldown gates, and upgrader policy is unchanged.

Spawning And Body Selection

src/spawnConfig.ts owns role priorities, desired-count defaults, and ordered body tiers. src/spawnBodyPolicy.ts owns the economy-aware body-tier approval step. RCL and room energy capacity determine which tiers are technically eligible; economy status, reserve policy, smoothed trend, role pressure, current energy, and recovery state determine which eligible tier is actually approved. SpawnManager executes that approved selection and keeps recovery-safe fallbacks for essential harvesters and haulers.

Explicit boosted-workforce intent is a sibling overlay rather than a permanent role or a final count. E48N13 prepares one compact boost slot at a time, reuses protected hauling, then hands the boosted ordinary-role creep to its target RoomManager. Builders use the ordinary selected body; UO harvesters use a three-WORK source-saturating body. Incoming reservations prevent duplicate builder capacity and defer source replacements only while the source remains covered; emergency local harvester recovery always retains authority, and a delayed boosted handoff reconciles to the oldest eligible source after a safety replacement. The bounded chemistry executor supports U/O to UO and L/H to LH. Boost preparation uses a local enabled recipe when its full raw shortfall is present, otherwise it retains the bounded direct-compound Market fallback.

Harvesters keep the four-WORK RCL 4 body as the constrained-economy production fallback. A five-WORK source-saturating harvester can fully harvest a normal source. In mature rooms with completed owned Storage at or above the configured healthy reserve ratio, local harvesters are treated as source-side capital investments: transient low spawn energy, strained status, negative trend, or temporarily protected optional spending do not down-tier the approved local harvester body. Normal replacements wait briefly for the approved target body before falling back; emergency, starved, no-storage, low-reserve, or zero-harvester recovery still spawns an affordable fallback immediately.

Mature rooms scale useful body capacity before creep count. A process-wide Resource Governor coordinates sibling CPU and Memory signals without owning gameplay policy. Its existing CPU bucket branch commands the existing abundant, healthy, constrained, or critical tier. Open reserve remains available above 5,000, with Launch Control numeric reopening capacity progressively limiting optional work when the bucket drains. Recovery holds until 9,000 before reopening from capacity zero one observed level at a time. Recovery also pauses optional managers and staggers already-alive optional, remote, and bootstrap creeps; local harvesting, hauling, spawning, towers, and controller work remain available. The prior completed-tick utilization EWMA and observed CPU offset remain advisory recovery inputs. RCL4+ builders and upgraders normally cap at one. Real committed construction or sustained strategic surplus can permit a second while CPU is healthy or abundant. Constrained and critical modes cap both roles at one and cap combined local, route-driven, and remote hauler demand at three.

Launch Control extends that governor with bounded subsystem applications and sticky leases for scouting, CIA assessment, logistics, infrastructure, mineral development, and remote development. A moderate work horizon permits one lease; an extended horizon permits one urgency-driven lease plus up to three rotation leases. Those autonomous limits are zero, one, and four for brief, moderate, and extended horizons. A bounded operator target may temporarily replace that target simultaneous leases without changing class eligibility or normal governor completion, and experimental excess capacity is discarded when that override ends. Local logistics and infrastructure outrank the remote group; bounded eligible wait and the rotation lane prevent a continuously urgent class from starving other applicants. Remote development requires a recent scouting report and a CIA assessment matching that observation before it can apply. Ordinary builders require infrastructure admission; critical defense repair and colony-bootstrap continuity are the only automatic builder exceptions. One local-service hauler remains protected, while every additional local hauler requires a logistics lease plus two fresh low-idle route evaluations before one additional lifetime commitment is authorized. Optional hauler authorizations are paced colony-wide. Living optional haulers finish normally after lease expiry, but replacement above the protected floor waits for another active logistics lease. Local harvesters and the minimum controller upgrader remain outside Launch Control.

Base Launch Control leases grant permission to perform optional work. Enhancement leases separately allocate additional work quality and are valid only while the same subsystem has an active base lease and reports useful marginal work. Resource abundance does not require the two-slot enhancement pool to be filled. All six existing owners can now compete: Infrastructure and Logistics retain their Part 1 budgets; Intelligence may perform up to four early strategic reassessments at a 25-tick threshold; Scouting may compare up to four already-authorized frontier targets; Remote Development may reconsider multiple existing candidates after 25 rather than 50 ticks; and Mineral Development may summarize up to four changed existing prerequisite planning records. These modes never change frontier, creep, operation, construction, economy, safety, or execution authority.

The Memory branch samples the incoming serialized RawMemory length every 250 ticks, reports healthy/elevated/critical pressure, and retains only one sample plus a growth EWMA and compact reclamation counters. It never recursively scans Memory or deletes manager state itself. Under pressure it may give a bounded reclamation budget to an explicit owner; CIA is the first participant and may discard only sufficiently old ciaEvents history. Current dossiers and strategic facts remain protected. Long-term operational history belongs in the Memory.stats → Graphite/Grafana pipeline rather than unbounded game Memory.

The mature local body ladder replaces count with capacity: RCL5–RCL8 builders carry 6/8/12/15 WORK, local road haulers carry 12/16/24/30 CARRY, and upgraders carry 6/10/15/15 WORK. These tiers remain subject to RCL energy capacity, normal stable-or-surplus economy health, reserve permission, and role-specific work or supply pressure. Starved, emergency, and zero-essential-role recovery continue to use affordable conservative bodies. Harvesters remain one per source and never exceed the useful five-WORK source-saturating tier. Remote hauling retains its workload-specific road-confidence body selection.

RCL 5 adds mature hauler, upgrader, and builder bodies, but reaching RCL 5 does not automatically select them. bulk-logistics haulers require surplus logistics pressure, surplus-controller upgraders require surplus controller supply, and heavy-construction builders require meaningful build or repair pressure.

At RCL 6+, a narrow local mineral pilot can operate an already completed, operator-approved extractor and adjacent container. A single optional mineralMiner uses a fixed 10 WORK / 1 CARRY / 5 MOVE body and deposits only into that container. New mineral production is suppressed during economy emergency, essential-workforce recovery, emergency CPU austerity, and constrained or critical CPU population modes, and while Launch Control has not granted mineralDevelopment. When completed primary Storage also exists, the room protects one density-derived native deposit cycle from further energy occupancy and at most one ordinary local hauler incrementally moves that exact container's native mineral into Storage while another hauler preserves local energy service. Actual free capacity and remaining target inventory bound every assignment. Existing-hauler mineral service may continue in constrained mode, but remains blocked in critical mode and never increases hauler population. General terminal balancing, persistent Market orders, broad industry, remote minerals, and a dedicated mineral-hauler role remain unimplemented. The narrow operator UO workflow may authorize O mining and E48N14→E48N13 Terminal transfer; bounded immediate Market deals may stage or bank their exact resource through ordinary protected-service haulers.

Operator boost provisioning reuses these same bounded chemistry, Market, and hauling surfaces. It does not introduce general resource solving, autonomous boost ROI, persistent Market orders, or a new boosted creep role.

At RCL 5 and beyond, owned links are treated as structure-level logistics only when completed topology supports it. Visible links are classified by position as source, storage, controller, or unclassified. Source links feed storage links first, storage links feed controller links only when economy policy allows controller-buffer spending, and direct source-to-controller transfers are a conservative fallback when no storage link exists. Haulers can perform load-source-link and unload-receiver-link jobs around completed source-to-storage routes, while urgent spawn, extension, and tower delivery continues to preempt optional link service. Source containers and the controller container remain fallback buffers, so rooms with no links, incomplete routes, partial source coverage, blocked receivers, or emergency demand continue conventional hauling.

Colony layout owns fixed-local desired geometry. Focused local construction reads that geometry directly, merges local Roads through logistics-owned intent, and performs bounded live-safe placement without local plan/order/package copies. Manual authority uses exact current fingerprints; autonomous authority authorizes current desired intent while preserving all execution validation.

The generic infrastructure planner now serves only remote source Containers and defensive Walls/Ramparts. Remote Roads retain their dedicated route lifecycle. infrastructureCutoverCleanupVersion = 1 surgically removes obsolete local records once while preserving colony layout, local-construction state, logistics-road state, remote infrastructure, and defenses.

Persistent logistics routes can now annotate planned endpoints and road plans with the stable route IDs they support. Each persisted route summary separately reports whether its infrastructure is fully supported, partially supported, degraded, or blocked, plus bounded endpoint and road-completion details. Plans, approvals, and construction sites remain intent: runtime support is counted only after current visible structures are revalidated for exact type, position, accessibility, and health. A link route may therefore report degraded preferred infrastructure while its ordinary creep fallback remains usable.

Active local hauling routes supply bounded cached road geometry to unified local-road intent. Shared tiles retain all supporting route IDs without a second persistent geometry copy. Focused construction places local Roads with the existing two-new/six-outstanding bounds, while fixed structures retain their one-new-site pacing. Remote routes continue to reuse their approved remote-road representation. Route value affects ordering, but never places an unauthorized site, bypasses RCL checks, loosens remote safety, or changes economy permissions. This is aggregate execution for established doctrine, not a permanent bunker or base-layout planner.

RCL 6+ rooms fit one reusable ten-slot lab-cluster topology around completed Storage. Rotations and reflections preserve two reagent inputs, eight outputs, and internal service lanes without room-specific coordinates. The complete future footprint is reserved immediately while current RCL capacity controls progressive site placement. If only Labs or Extensions block a safe fit, debug.labCluster() exposes bounded exact relocation options; reserving one is non-destructive and requires the operator to remove the listed blockers.

New obstacle structures remain at least range 2 from Storage. The only adjacent exceptions are walkable Roads, Ramparts, and Containers, one Storage Link, and one Tower. Existing adjacent structures are not destroyed by this policy.

Extension cluster planning and placement use a transient obstacle view to preserve established roads, local choke points, and at least one adjacent service tile around operational anchors. Terrain and constructed walls, structures, construction sites, and active reservations are included without persisting a path or cost matrix in Memory.

Known persistent routes also retain bounded performance windows for delivered throughput, route-job timing, blocked and unavailable time, fallback use, capacity utilization, backlog trend, fatigue, congestion, and weighted traffic tiles. The feedback can reorder already-eligible road intent but cannot approve or place construction. Custom path reuse remains disabled; route summaries only report conservative cache eligibility for later validation. See docs/LOGISTICS_PERFORMANCE_VALIDATION.md for the deterministic and Screeps Lab acceptance matrix. Colony bootstrap is a separate, explicitly operator-authorized workflow. debug.colonize(target, bootstrapper) creates durable intent under the bootstrapper room; it does not consult or mutate CIA recommendations. A narrow manager coordinates controller acquisition, bounded pioneer-builder demand, a stable first-spawn position, selective clearance, site recovery, downgrade protection, and handoff. After the completed target spawn has participated in ordinary owned-room management, parent support stops and surviving pioneers become target-owned builders. See docs/COLONY_BOOTSTRAP.md.

Remote operations support multiple home-owned remote rooms through independently admitted source objectives and a bounded per-home allocator. RemoteOperationsManager evaluates adjacent known rooms from CIA dossiers, combines that advisory intelligence with the owned room's economy readiness, stores compact assessments under Memory.rooms[homeRoomName].remoteOperations, and exposes debug plus numeric telemetry. Each admitted source may spawn one exactly assigned remote harvester, request its own operator-approved source-container plan, place the approved site after revalidation, use ordinary builders for that exact infrastructure, and retain a distinct hauling and road route. The room shares safety, reservation, CIA context, and home economic authorization. Remote hauling demand is distance-aware and source-specific: the bot estimates production per tick, route length, round-trip cycle time, required carry capacity, replacement lead time, desired hauler count, and a workload-aware remote logistics hauler body. Ordinary haulers may serve either source without one assignment being counted against both routes. Remote energy and transient deposits compete through separate rank and multidimensional capacity contracts; shared reservation overhead is charged once per remote room. Local recovery, reserve, defense, CPU, and final-hauler protections remain hard gates. Combat, colony-wide optimization, and arbitrary remote construction remain deferred.

Highway deposits use a separate transient DepositOperationsManager. Deposit authority defaults to bounded autonomy: after a fresh intelligence assessment, an active remoteDevelopment lease may authorize the highest-value viable opportunity under the per-home transient-operation cap. Actual-body economics, home economy, workforce recovery, CPU emergency, visible danger, lifetime, and cooldown are revalidated before and during execution. Operators can inspect or switch policy with debug.depositAuthority() and retain exact manual approval through debug.approveDepositOperation(...).

Terminal logistics retain their conservative readiness layer. The only automatic send is the active UO order's bounded O shortfall from configured E48N14 to E48N13; this does not enable room balancing. Operator Market deals execute against existing counterparties under explicit price, credit-reserve, capacity, and transaction-energy bounds. Persistent orders, speculative trade, general industry autonomy, remote mining, and multi-room link behavior remain deferred.

Infrastructure Maintenance

RoomManager creates one room-owned maintenance plan each tick through MaintenanceManager. The plan classifies maintainable infrastructure into critical, important, normal, or disabled classes, applies configurable start/target repair thresholds from src/config/maintenance.ts, gates routine maintenance by economy health, and scores eligible repair jobs before builders receive work.

Builders execute maintenance assignments but do not scan the whole room or own repair thresholds. Critical source/controller containers can preempt ordinary construction when they are in emergency condition; routine road maintenance stays behind construction and only runs when the room can afford it.

Maintenance now builds one compact room-scoped lookup for roads supporting operational logistics routes. Those roads enter the existing important class with a capped route-value bonus, so critical or urgent local supply and active remote production can outrank incidental roads. Suspended, retired, blocked, policy-denied, and inactive-remote routes do not retain the bonus. Route value does not create a critical road class: emergency containers, approved construction ordering, and the existing reserve and maintenance budget gates remain authoritative.

Planning And Decisions

  • ROADMAP.md: versioned project roadmap and milestone planning.
  • TODO.md: short tactical task list; keep it aligned with the roadmap.
  • DECISIONS.md: architecture decisions and rationale.
  • docs/DEBUG.md: debugging helpers, console commands, and diagnostics.
  • docs/DEFENSE.md: defensive postures, authority boundaries, adequacy, ramparts, defender demand, safe mode, and CPU behavior.
  • docs/STATS.md: canonical Memory.stats telemetry contract for downstream StatsD, Graphite, and Grafana consumers.
  • docs/INFRASTRUCTURE_PLANNING.md: general room-scoped infrastructure planning, build-order approval, doctrines, memory schema, scoring, events, and future logistics route data.
  • docs/REMOTE_OPERATIONS.md: passive remote-operation lifecycle, scoring, blockers, memory ownership, debug commands, stats, limitations, and next milestone boundaries.
  • docs/LINK_LOGISTICS.md: completed-link runtime logistics, hauler service jobs, mixed-mode fallbacks, telemetry, and debug workflow.
  • docs/LOGISTICS_NETWORK.md: shared logistics representation, identifiers, infrastructure support states, ownership boundaries, memory, debug, and telemetry.
  • docs/LIVE_API.md: live Screeps API research, integration architecture, and implementation roadmap.
  • docs/LOGISTICS_PERFORMANCE_VALIDATION.md: deterministic fixtures, Screeps Lab scenarios, exact observation windows, assertions, tolerances, and operator-run procedure for route performance and traffic feedback.
  • docs/SCREEPS_LAB_SNAPSHOT.md: Screeps Lab snapshot export contract, operator commands, segment reservation, downloader usage, limitations, and compatibility policy.

Live Console Tools

These tools let this repository connect to the live Screeps MMO console from the Codex cloud environment. They use the existing SCREEPS_TOKEN; never commit a .env file, token, console transcript containing secrets, or generated build output.

See docs/LIVE_API.md for the full live API investigation, including confirmed HTTP endpoints, WebSocket subscriptions, authentication behavior, caveats, and the recommended local-service/MCP integration architecture.

Environment Variables

Required:

  • SCREEPS_TOKEN: Screeps API token with console access. The tools redact this value from their own error messages, but you should still treat all terminal output as sensitive.

Optional:

  • SCREEPS_SHARD: shard used for console commands when the Screeps API needs a shard argument. Defaults to shard3.
  • SCREEPS_ROOM: room inspected by npm run live:check. Defaults to E48N13.

Command Examples

Run a harmless console expression and exit after the matching result arrives:

npm run console -- "Game.time"
npm run console -- "Game.shard.name"

Watch the live console stream until interrupted:

npm run console:watch

Run the structured read-only colony health check:

npm run live:check

The console command evaluates arbitrary JavaScript in the live Screeps MMO console. Expressions such as Game.spawns.Spawn1.destroy() or Memory writes can mutate the live game. Prefer harmless read-only expressions unless you are intentionally operating the colony.

Remote console execution is asynchronous: the API queues an expression, then the result arrives on the user console WebSocket stream on a later tick. Use unique markers or the existing tooling when correlating command results with console output.

Existing debug globals can be called directly after the deployed bot has registered them:

npm run console -- "debug.room()"
npm run console -- "debug.spawn()"
npm run console -- "debug.economy()"
npm run console -- "debug.links()"
npm run console -- "debug.buildOrders()"
npm run console -- 'debug.infrastructurePlan("E48N13")'
npm run console -- "debug.terminal()"
npm run console -- "debug.intents()"
npm run console -- 'debug.colonization("E48N14")'
npm run console -- 'debug.creep("Harvester-123")'

Download a completed Screeps Lab snapshot after the live exporter reports complete:

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

The downloader writes generated artifacts under artifacts/screeps-lab-snapshots/, which is gitignored. It does not deploy code, clear the remote snapshot, or upload anything to Screeps Lab.

Token Security

  • Use environment injection or a local untracked .env; do not add credentials to the repository.
  • Do not paste SCREEPS_TOKEN into console expressions.
  • Rotate the token immediately if it appears in logs, screenshots, shell history, commits, or pull request text.
  • Grant only the token scopes needed for console/deploy workflows where possible.

Troubleshooting

  • Authentication failures: confirm SCREEPS_TOKEN is present in the runtime environment, has not expired, and has the permissions needed for console API access.
  • Timeouts: Screeps console results are delivered on the WebSocket stream on later ticks. Retry harmless checks such as Game.time; if the shard is paused or the service is slow, the command may time out even after submission.
  • WebSocket failures: verify network egress is available from the current environment. The tools subscribe only to the user console stream and avoid printing raw WebSocket protocol frames.
  • No debug global output: deploy the current bot branch first if the live branch does not yet include the debug helpers. The console tools themselves do not deploy gameplay code.