# svman4/screeps architecture

> Architecture diagram of the GitHub repository svman4/screeps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/svman4/screeps
- Repository: https://github.com/svman4/screeps

## Overview

This is a Screeps game bot that manages rooms, creeps, construction, defense, expansion, and resource use. Its main operational loop is organized around a tick entry point, with room managers handling distinct domain responsibilities and creep roles executing unit behavior. The excerpts show several internal calls and dependencies, but do not expose the main loop’s dispatch logic; those connections are therefore omitted rather than inferred. Other listed managers and roles represent documented-by-module capabilities whose runtime wiring was not shown.

Main entry points: [`src/manager.construction.js`](https://github.com/svman4/screeps/blob/main/src/manager.construction.js) (Construction Manager), [`src/utils.RoomCache.js`](https://github.com/svman4/screeps/blob/main/src/utils.RoomCache.js) (Room Cache), [`src/manager.logistics.js`](https://github.com/svman4/screeps/blob/main/src/manager.logistics.js) (Energy Logistics), [`src/manager.spawn.js`](https://github.com/svman4/screeps/blob/main/src/manager.spawn.js) (Spawn Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Tick and Room Control"]
  node_main["Tick Entry<br/>[main.js]"]
end

subgraph group_economy["Economy and Spawning"]
  node_market["Market Trading<br/>[manager.market.js]"]
  node_logistics["Energy Logistics"]
  node_spawn["Spawn Manager<br/>[manager.spawn.js]"]
  node_spawnqueue["Spawn Queue"]
  node_population["Population Limits"]
  node_spawnconfig["Spawn Configuration<br/>[spawn.constants.js]"]
  node_link["Link Manager<br/>[manager.link.js]"]
  node_pixels["Pixel Production<br/>[manager.pixels.js]"]
end

subgraph group_units["Creep Behavior"]
  node_movement["Movement Manager"]
  node_rolebase["Shared Creep Behavior<br/>[role.base.js]"]
  node_builder["Builder Role<br/>[role.builder.js]"]
  node_claimer["Claimer Role<br/>[role.claimer.js]"]
  node_ldharvester["Remote Harvester"]
  node_miner["Miner Role<br/>[role.miner.js]"]
  node_recycler["Recycle Role"]
  node_scout["Scout Role<br/>[role.scout.js]"]
  node_simpleharvester["Simple Harvester"]
  node_static_harvester["Static Harvester"]
  node_supporter["Supporter Role<br/>[role.supporter.js]"]
  node_upgrader["Upgrader Role<br/>[role.upgrader.js]"]
  node_rolemanager["Role Manager<br/>[manager.role.js]"]
end

subgraph group_world["World Operations"]
  node_construction["Construction Manager"]
  node_defense["Tower Defense<br/>[manager.defense.js]"]
  node_expansion["Room Expansion"]
  node_military["Military Manager"]
  node_layout["File Layout"]
  node_scorer["Layout Scorer"]
  node_baselayout["Base Layout"]
  node_roadplanner["Road Planner"]
end

subgraph group_shared["Shared Utilities"]
  node_roomcache[("Room Cache<br/>[utils.RoomCache.js]")]
  node_debug["Debug Console"]
  node_rolling["Rolling Average"]
end

node_screeps(("Screeps Runtime"))

node_screeps -.->|"ticks"| node_main
node_spawn -->|"creates"| node_spawnqueue
node_spawn -->|"creates"| node_population
node_population -->|"uses settings"| node_spawnconfig
node_spawn -->|"uses settings"| node_spawnconfig
node_logistics -->|"uses movement"| node_movement
node_logistics -->|"reads link ID"| node_link
node_logistics -->|"reads room data"| node_roomcache
node_rolebase -->|"requests movement"| node_movement
node_rolebase -->|"reads room data"| node_roomcache
node_military -->|"reads room data"| node_roomcache
node_defense -->|"reads room data"| node_roomcache
node_expansion -->|"reads room data"| node_roomcache
node_construction -->|"creates layout"| node_layout
node_construction -->|"reads structures"| node_roomcache
node_construction -.->|"uses scoring"| node_scorer
node_construction -.->|"uses planning"| node_roadplanner
node_construction -.->|"uses base layout"| node_baselayout

click node_main "https://github.com/svman4/screeps/blob/main/src/main.js"
click node_construction "https://github.com/svman4/screeps/blob/main/src/manager.construction.js"
click node_defense "https://github.com/svman4/screeps/blob/main/src/manager.defense.js"
click node_expansion "https://github.com/svman4/screeps/blob/main/src/manager.expansion.js"
click node_military "https://github.com/svman4/screeps/blob/main/src/manager.military.js"
click node_market "https://github.com/svman4/screeps/blob/main/src/manager.market.js"
click node_logistics "https://github.com/svman4/screeps/blob/main/src/manager.logistics.js"
click node_spawn "https://github.com/svman4/screeps/blob/main/src/manager.spawn.js"
click node_spawnqueue "https://github.com/svman4/screeps/blob/main/src/spawn.SpawnQueue.js"
click node_population "https://github.com/svman4/screeps/blob/main/src/spawn.populationManager.js"
click node_spawnconfig "https://github.com/svman4/screeps/blob/main/src/spawn.constants.js"
click node_link "https://github.com/svman4/screeps/blob/main/src/manager.link.js"
click node_pixels "https://github.com/svman4/screeps/blob/main/src/manager.pixels.js"
click node_movement "https://github.com/svman4/screeps/blob/main/src/manager.movement.js"
click node_rolebase "https://github.com/svman4/screeps/blob/main/src/role.base.js"
click node_builder "https://github.com/svman4/screeps/blob/main/src/role.builder.js"
click node_claimer "https://github.com/svman4/screeps/blob/main/src/role.claimer.js"
click node_ldharvester "https://github.com/svman4/screeps/blob/main/src/role.lDHarvester.js"
click node_miner "https://github.com/svman4/screeps/blob/main/src/role.miner.js"
click node_recycler "https://github.com/svman4/screeps/blob/main/src/role.recycleCreep.js"
click node_scout "https://github.com/svman4/screeps/blob/main/src/role.scout.js"
click node_simpleharvester "https://github.com/svman4/screeps/blob/main/src/role.simpleHarvester.js"
click node_static_harvester "https://github.com/svman4/screeps/blob/main/src/role.staticHarvester.js"
click node_supporter "https://github.com/svman4/screeps/blob/main/src/role.supporter.js"
click node_upgrader "https://github.com/svman4/screeps/blob/main/src/role.upgrader.js"
click node_rolemanager "https://github.com/svman4/screeps/blob/main/src/manager.role.js"
click node_roomcache "https://github.com/svman4/screeps/blob/main/src/utils.RoomCache.js"
click node_debug "https://github.com/svman4/screeps/blob/main/src/utils.debugConsole.js"
click node_rolling "https://github.com/svman4/screeps/blob/main/src/utils.RollingAverage.js"
click node_layout "https://github.com/svman4/screeps/blob/main/src/construction.layout.FileLayout.js"
click node_scorer "https://github.com/svman4/screeps/blob/main/src/construction.layout.Scorer.js"
click node_baselayout "https://github.com/svman4/screeps/blob/main/src/construction.layout.BaseLayout.js"
click node_roadplanner "https://github.com/svman4/screeps/blob/main/src/construction.roadPlanner.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_market,node_logistics,node_spawn,node_spawnqueue,node_population,node_spawnconfig,node_link,node_pixels toneAmber
class node_movement,node_rolebase,node_builder,node_claimer,node_ldharvester,node_miner,node_recycler,node_scout,node_simpleharvester,node_static_harvester,node_supporter,node_upgrader,node_rolemanager toneMint
class node_construction,node_defense,node_expansion,node_military,node_layout,node_scorer,node_baselayout,node_roadplanner toneRose
class node_roomcache,node_debug,node_rolling,node_screeps toneIndigo
```

## Components

### Tick and Room Control

- [Tick Entry](https://github.com/svman4/screeps/blob/main/src/main.js): `src/main.js`

### Economy and Spawning

- [Market Trading](https://github.com/svman4/screeps/blob/main/src/manager.market.js): `src/manager.market.js`
- [Energy Logistics](https://github.com/svman4/screeps/blob/main/src/manager.logistics.js): `src/manager.logistics.js`
- [Spawn Manager](https://github.com/svman4/screeps/blob/main/src/manager.spawn.js): `src/manager.spawn.js`
- [Spawn Queue](https://github.com/svman4/screeps/blob/main/src/spawn.SpawnQueue.js): `src/spawn.SpawnQueue.js`
- [Population Limits](https://github.com/svman4/screeps/blob/main/src/spawn.populationManager.js): `src/spawn.populationManager.js`
- [Spawn Configuration](https://github.com/svman4/screeps/blob/main/src/spawn.constants.js): `src/spawn.constants.js`
- [Link Manager](https://github.com/svman4/screeps/blob/main/src/manager.link.js): `src/manager.link.js`
- [Pixel Production](https://github.com/svman4/screeps/blob/main/src/manager.pixels.js): `src/manager.pixels.js`

### Creep Behavior

- [Movement Manager](https://github.com/svman4/screeps/blob/main/src/manager.movement.js): `src/manager.movement.js`
- [Shared Creep Behavior](https://github.com/svman4/screeps/blob/main/src/role.base.js): `src/role.base.js`
- [Builder Role](https://github.com/svman4/screeps/blob/main/src/role.builder.js): `src/role.builder.js`
- [Claimer Role](https://github.com/svman4/screeps/blob/main/src/role.claimer.js): `src/role.claimer.js`
- [Remote Harvester](https://github.com/svman4/screeps/blob/main/src/role.lDHarvester.js): `src/role.lDHarvester.js`
- [Miner Role](https://github.com/svman4/screeps/blob/main/src/role.miner.js): `src/role.miner.js`
- [Recycle Role](https://github.com/svman4/screeps/blob/main/src/role.recycleCreep.js): `src/role.recycleCreep.js`
- [Scout Role](https://github.com/svman4/screeps/blob/main/src/role.scout.js): `src/role.scout.js`
- [Simple Harvester](https://github.com/svman4/screeps/blob/main/src/role.simpleHarvester.js): `src/role.simpleHarvester.js`
- [Static Harvester](https://github.com/svman4/screeps/blob/main/src/role.staticHarvester.js): `src/role.staticHarvester.js`
- [Supporter Role](https://github.com/svman4/screeps/blob/main/src/role.supporter.js): `src/role.supporter.js`
- [Upgrader Role](https://github.com/svman4/screeps/blob/main/src/role.upgrader.js): `src/role.upgrader.js`
- [Role Manager](https://github.com/svman4/screeps/blob/main/src/manager.role.js): `src/manager.role.js`

### World Operations

- [Construction Manager](https://github.com/svman4/screeps/blob/main/src/manager.construction.js): `src/manager.construction.js`
- [Tower Defense](https://github.com/svman4/screeps/blob/main/src/manager.defense.js): `src/manager.defense.js`
- [Room Expansion](https://github.com/svman4/screeps/blob/main/src/manager.expansion.js): `src/manager.expansion.js`
- [Military Manager](https://github.com/svman4/screeps/blob/main/src/manager.military.js): `src/manager.military.js`
- [File Layout](https://github.com/svman4/screeps/blob/main/src/construction.layout.FileLayout.js): `src/construction.layout.FileLayout.js`
- [Layout Scorer](https://github.com/svman4/screeps/blob/main/src/construction.layout.Scorer.js): `src/construction.layout.Scorer.js`
- [Base Layout](https://github.com/svman4/screeps/blob/main/src/construction.layout.BaseLayout.js): `src/construction.layout.BaseLayout.js`
- [Road Planner](https://github.com/svman4/screeps/blob/main/src/construction.roadPlanner.js): `src/construction.roadPlanner.js`

### Shared Utilities

- [Room Cache](https://github.com/svman4/screeps/blob/main/src/utils.RoomCache.js): `src/utils.RoomCache.js`
- [Debug Console](https://github.com/svman4/screeps/blob/main/src/utils.debugConsole.js): `src/utils.debugConsole.js`
- [Rolling Average](https://github.com/svman4/screeps/blob/main/src/utils.RollingAverage.js): `src/utils.RollingAverage.js`

### Other components

- **Screeps Runtime**

## Connections

- Screeps Runtime → Tick Entry: ticks
- Spawn Manager → Spawn Queue: creates (evidence: `src/manager.spawn.js`)
- Spawn Manager → Population Limits: creates (evidence: `src/manager.spawn.js`)
- Population Limits → Spawn Configuration: uses settings (evidence: `src/spawn.populationManager.js`)
- Spawn Manager → Spawn Configuration: uses settings (evidence: `src/manager.spawn.js`)
- Energy Logistics → Movement Manager: uses movement (evidence: `src/manager.logistics.js`)
- Energy Logistics → Link Manager: reads link ID (evidence: `src/manager.logistics.js`)
- Energy Logistics → Room Cache: reads room data (evidence: `src/manager.logistics.js`)
- Shared Creep Behavior → Movement Manager: requests movement (evidence: `src/role.base.js`)
- Shared Creep Behavior → Room Cache: reads room data (evidence: `src/role.base.js`)
- Military Manager → Room Cache: reads room data (evidence: `src/manager.military.js`)
- Tower Defense → Room Cache: reads room data (evidence: `src/manager.defense.js`)
- Room Expansion → Room Cache: reads room data (evidence: `src/manager.expansion.js`)
- Construction Manager → File Layout: creates layout (evidence: `src/manager.construction.js`)
- Construction Manager → Room Cache: reads structures (evidence: `src/manager.construction.js`)
- Construction Manager → Layout Scorer: uses scoring
- Construction Manager → Road Planner: uses planning
- Construction Manager → Base Layout: uses base layout