# votetz/pocket-empire architecture

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

- Interactive diagram: https://gitdiagram.com/votetz/pocket-empire
- Repository: https://github.com/votetz/pocket-empire

## Overview

Pocket Empire is a turn-based 4X strategy simulation. The principal workflow starts the game, sets up a hex world and factions, advances turns through player/AI actions and game systems, then reports the evolving game through console rendering and victory outcomes. Major documented branches include city economy and research, unit FSM tactics and combat, diplomacy, and environmental events. Relationships below are limited to README statements and source-index references; unsampled subsystems are represented at their supported directory paths.

Main entry points: [`src/main/java/com/pocketempire/simulation/TurnManager.java`](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/TurnManager.java) (Turn Manager), [`src/main/java/com/pocketempire/Main.java`](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/Main.java) (Game Entry), [`src/main/java/com/pocketempire/world/World.java`](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/World.java) (World State), [`src/main/java/com/pocketempire/fsm`](https://github.com/votetz/pocket-empire/tree/main/src/main/java/com/pocketempire/fsm) (Unit FSM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_main["Game Entry<br/>[Main.java]"]
  node_setup["Game Setup<br/>[GameSetup.java]"]
  node_runner["Game Runner<br/>[GameRunner.java]"]
  node_turns["Turn Manager<br/>[TurnManager.java]"]
  node_controller["Player Controller"]
  node_render["Console Renderer<br/>[ConsoleRender.java]"]
  node_batch["Batch Simulation"]
end

subgraph group_world["World and Units"]
  node_worldgen["Hex World<br/>[MapGenerator.java]"]
  node_world["World State<br/>[World.java]"]
  node_map["Hex Map<br/>[Map.java]"]
  node_fog["Fog of War<br/>[FogMap.java]"]
  node_path["Pathfinding<br/>[Pathfinder.java]"]
  node_units["Unit Models<br/>[Unit.java]"]
  node_unitai["Unit FSM"]
  node_combat["Tactical Combat"]
end

subgraph group_strategy["Faction Strategy"]
  node_factions["Factions and Cities<br/>[Faction.java]"]
  node_economy["City Economy"]
  node_tech["Technology Tree<br/>[TechTree.java]"]
  node_diplomacy["Diplomacy"]
  node_victory["Victory Conditions"]
end

subgraph group_systems["Game Systems"]
  node_events["World Events<br/>[EventManager.java]"]
  node_eventbus["Game Event Bus<br/>[GameEventBus.java]"]
  node_config["Game Configuration"]
end

node_player(("Player"))

node_player -->|"starts game"| node_main
node_main -->|"initializes"| node_setup
node_main -->|"runs simulation"| node_runner
node_runner -.->|"advances turns"| node_turns
node_turns -->|"invokes actions"| node_controller
node_controller -->|"renders console"| node_render
node_turns -->|"updates relations"| node_diplomacy
node_turns -->|"updates events"| node_events
node_turns -->|"advances research"| node_tech
node_turns -->|"uses world state"| node_world
node_setup -.->|"creates world"| node_worldgen
node_worldgen -.->|"generates terrain"| node_map
node_world -->|"holds map"| node_map
node_world -->|"checks hostility"| node_diplomacy
node_fog -->|"reads terrain bounds"| node_map
node_fog -->|"reveals from units"| node_units
node_units -->|"delegates AI updates"| node_unitai
node_unitai -->|"resolves engagements"| node_combat
node_unitai -->|"requests paths"| node_path
node_economy -->|"updates resources"| node_factions
node_turns -->|"processes factions"| node_factions
node_diplomacy -->|"publishes events"| node_eventbus
node_events -->|"publishes events"| node_eventbus
node_victory -->|"publishes outcomes"| node_eventbus
node_turns -->|"checks outcomes"| node_victory
node_config -.->|"configures gameplay"| node_economy
node_batch -.->|"runs games"| node_runner

click node_main "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/Main.java"
click node_setup "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/GameSetup.java"
click node_runner "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/GameRunner.java"
click node_turns "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/TurnManager.java"
click node_controller "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/player/PlayerController.java"
click node_render "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/display/ConsoleRender.java"
click node_worldgen "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/MapGenerator.java"
click node_world "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/World.java"
click node_map "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/Map.java"
click node_fog "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/FogMap.java"
click node_path "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/pathfinding/Pathfinder.java"
click node_units "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/entities/Unit.java"
click node_unitai "https://github.com/votetz/pocket-empire/tree/main/src/main/java/com/pocketempire/fsm"
click node_combat "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/CombatResolver.java"
click node_factions "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/entities/Faction.java"
click node_economy "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/economy/EconomyManager.java"
click node_tech "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/tech/TechTree.java"
click node_diplomacy "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/diplomacy/DiplomacyManager.java"
click node_victory "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/objective/VictoryManager.java"
click node_events "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/events/EventManager.java"
click node_eventbus "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/events/GameEventBus.java"
click node_config "https://github.com/votetz/pocket-empire/tree/main/src/main/java/com/pocketempire/config"
click node_batch "https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/tools/BatchSimulator.java"

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,node_setup,node_runner,node_turns,node_controller,node_render,node_batch toneBlue
class node_worldgen,node_world,node_map,node_fog,node_path,node_units,node_unitai,node_combat toneAmber
class node_factions,node_economy,node_tech,node_diplomacy,node_victory toneMint
class node_events,node_eventbus,node_config toneRose
class node_player toneIndigo
```

## Components

### Game Runtime

- [Game Entry](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/Main.java): `src/main/java/com/pocketempire/Main.java`
- [Game Setup](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/GameSetup.java): `src/main/java/com/pocketempire/simulation/GameSetup.java`
- [Game Runner](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/GameRunner.java): `src/main/java/com/pocketempire/simulation/GameRunner.java`
- [Turn Manager](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/TurnManager.java): `src/main/java/com/pocketempire/simulation/TurnManager.java`
- [Player Controller](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/player/PlayerController.java): `src/main/java/com/pocketempire/player/PlayerController.java`
- [Console Renderer](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/display/ConsoleRender.java): `src/main/java/com/pocketempire/display/ConsoleRender.java`
- [Batch Simulation](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/tools/BatchSimulator.java): `src/main/java/com/pocketempire/tools/BatchSimulator.java`

### World and Units

- [Hex World](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/MapGenerator.java): `src/main/java/com/pocketempire/world/MapGenerator.java`
- [World State](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/World.java): `src/main/java/com/pocketempire/world/World.java`
- [Hex Map](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/Map.java): `src/main/java/com/pocketempire/world/Map.java`
- [Fog of War](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/world/FogMap.java): `src/main/java/com/pocketempire/world/FogMap.java`
- [Pathfinding](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/pathfinding/Pathfinder.java): `src/main/java/com/pocketempire/pathfinding/Pathfinder.java`
- [Unit Models](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/entities/Unit.java): `src/main/java/com/pocketempire/entities/Unit.java`
- [Unit FSM](https://github.com/votetz/pocket-empire/tree/main/src/main/java/com/pocketempire/fsm): `src/main/java/com/pocketempire/fsm`
- [Tactical Combat](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/simulation/CombatResolver.java): `src/main/java/com/pocketempire/simulation/CombatResolver.java`

### Faction Strategy

- [Factions and Cities](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/entities/Faction.java): `src/main/java/com/pocketempire/entities/Faction.java`
- [City Economy](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/economy/EconomyManager.java): `src/main/java/com/pocketempire/economy/EconomyManager.java`
- [Technology Tree](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/tech/TechTree.java): `src/main/java/com/pocketempire/tech/TechTree.java`
- [Diplomacy](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/diplomacy/DiplomacyManager.java): `src/main/java/com/pocketempire/diplomacy/DiplomacyManager.java`
- [Victory Conditions](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/objective/VictoryManager.java): `src/main/java/com/pocketempire/objective/VictoryManager.java`

### Game Systems

- [World Events](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/events/EventManager.java): `src/main/java/com/pocketempire/events/EventManager.java`
- [Game Event Bus](https://github.com/votetz/pocket-empire/blob/main/src/main/java/com/pocketempire/events/GameEventBus.java): `src/main/java/com/pocketempire/events/GameEventBus.java`
- [Game Configuration](https://github.com/votetz/pocket-empire/tree/main/src/main/java/com/pocketempire/config): `src/main/java/com/pocketempire/config`

### Other components

- **Player**

## Connections

- Player → Game Entry: starts game
- Game Entry → Game Setup: initializes (evidence: `src/main/java/com/pocketempire/Main.java`)
- Game Entry → Game Runner: runs simulation (evidence: `src/main/java/com/pocketempire/Main.java`)
- Game Runner → Turn Manager: advances turns
- Turn Manager → Player Controller: invokes actions (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Player Controller → Console Renderer: renders console (evidence: `src/main/java/com/pocketempire/player/PlayerController.java`)
- Turn Manager → Diplomacy: updates relations (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Turn Manager → World Events: updates events (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Turn Manager → Technology Tree: advances research (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Turn Manager → World State: uses world state (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Game Setup → Hex World: creates world (evidence: `src/main/java/com/pocketempire/simulation/GameSetup.java`)
- Hex World → Hex Map: generates terrain
- World State → Hex Map: holds map (evidence: `src/main/java/com/pocketempire/world/World.java`)
- World State → Diplomacy: checks hostility (evidence: `src/main/java/com/pocketempire/world/World.java`)
- Fog of War → Hex Map: reads terrain bounds (evidence: `src/main/java/com/pocketempire/world/FogMap.java`)
- Fog of War → Unit Models: reveals from units (evidence: `src/main/java/com/pocketempire/world/FogMap.java`)
- Unit Models → Unit FSM: delegates AI updates (evidence: `src/main/java/com/pocketempire/entities/Unit.java`)
- Unit FSM → Tactical Combat: resolves engagements (evidence: `src/main/java/com/pocketempire/fsm/SkirmishState.java`)
- Unit FSM → Pathfinding: requests paths (evidence: `src/main/java/com/pocketempire/fsm/SkirmishState.java`)
- City Economy → Factions and Cities: updates resources (evidence: `src/main/java/com/pocketempire/economy/EconomyManager.java`)
- Turn Manager → Factions and Cities: processes factions (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Diplomacy → Game Event Bus: publishes events (evidence: `src/main/java/com/pocketempire/diplomacy/DiplomacyManager.java`)
- World Events → Game Event Bus: publishes events (evidence: `src/main/java/com/pocketempire/events/EventManager.java`)
- Victory Conditions → Game Event Bus: publishes outcomes (evidence: `src/main/java/com/pocketempire/objective/VictoryManager.java`)
- Turn Manager → Victory Conditions: checks outcomes (evidence: `src/main/java/com/pocketempire/simulation/TurnManager.java`)
- Game Configuration → City Economy: configures gameplay
- Batch Simulation → Game Runner: runs games
