# tmewett/broguece architecture

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

- Interactive diagram: https://gitdiagram.com/tmewett/broguece
- Repository: https://github.com/tmewett/broguece

## Overview

#### Purpose and entry points
Brogue CE is a native C, single-player roguelike with procedurally generated dungeon runs, turn-based strategy, persistent recordings, and selectable graphical/terminal front ends. Process startup is `src/platform/main.c`, which selects platform services and enters core gameplay in `src/brogue/RogueMain.c`. Shared game declarations and global state contracts center on `src/brogue/Rogue.h` and `src/brogue/Globals.h`.

#### Platform abstraction and rendering
The core does not directly own OS/UI implementation. `src/platform/platform.h` defines the platform boundary; implementations include SDL2 graphics in `src/platform/sdl2-platform.c`, curses terminal support in `src/platform/curses-platform.c`, browser support in `src/platform/web-platform.c`, and headless/null behavior in `src/platform/null-platform.c`. Tile rendering and bundled tile asset handling are in `src/platform/tiles.c` and `bin/assets/tiles.bin`. Linux releases require SDL2 and SDL2_image.

#### Game lifecycle and turn control
`src/brogue/RogueMain.c` coordinates menus, new or resumed games, command processing, per-turn updates, and win/death end states. User-facing title/menu flow is separated in `src/brogue/MainMenu.c`; input/output mediation is in `src/brogue/IO.c`. Time/turn semantics are handled by `src/brogue/Time.c`, while global mutable run state is organized through `src/brogue/Globals.c` and `src/brogue/GlobalsBase.c`.

#### Dungeon generation and spatial simulation
Dungeon construction is concentrated in `src/brogue/Architect.c`, producing level geometry, rooms, terrain, machines, and placements. Grid-level state and cell operations live in `src/brogue/Grid.c`. `src/brogue/Dijkstra.c` supplies distance-map/pathing calculations used by movement and AI; `src/brogue/Light.c` updates visibility and illumination. These systems form the primary spatial boundary consumed by player movement, monsters, and rendering.

#### Entities, player actions, and combat
Player movement and interaction resolve through `src/brogue/Movement.c`; creature state, AI, spawning, and ally behavior through `src/brogue/Monsters.c`; and attack/damage/status resolution through `src/brogue/Combat.c`. Items, inventory, consumables, equipment, and generated loot are owned by `src/brogue/Items.c`. Core flows are: input → action validation → map/entity mutation → combat or item effects → lighting/pathing/turn advancement → platform redraw.

#### Content tables, variants, and developer modes
Static game rules and probability/power data are represented in `src/brogue/PowerTables.c`. Variant-specific global configurations allow Brogue, Bullet Brogue, and Rapid Brogue builds without replacing core systems: `src/variants/GlobalsBrogue.c`, `src/variants/GlobalsBulletBrogue.c`, and `src/variants/GlobalsRapidBrogue.c`. Debug/developer controls are isolated in `src/brogue/Wizard.c`.

#### Persistence, replayability, and delivery
Run recordings/replay data are managed by `src/brogue/Recordings.c`; curated deterministic seeds are handled by `src/brogue/SeedCatalog.c`. This supports regression validation of procedural generation and gameplay outcomes. Builds are Make-based, with common rules in `make/brogue.mk` and OS-specific targets in `make/windows.mk` and `make/o.mk`; CI is defined in `.github/workflows/build.yml` and `.github/workflows/test.yml`.

Main entry points: [`src/brogue/RogueMain.c`](https://github.com/tmewett/broguece/blob/master/src/brogue/RogueMain.c) (Game coordinator), [`src/brogue/Movement.c`](https://github.com/tmewett/broguece/blob/master/src/brogue/Movement.c) (Player actions), [`src/platform/sdl2-platform.c`](https://github.com/tmewett/broguece/blob/master/src/platform/sdl2-platform.c) (SDL, curses, web & null), [`make/brogue.mk`](https://github.com/tmewett/broguece/blob/master/make/brogue.mk) (Make build targets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform &amp; front ends"]
  node_main(("Process startup<br/>C entry point<br/>[main.c]"))
  node_platform_api["Platform boundary<br/>platform API<br/>[platform.h]"]
  node_platform_backends["SDL, curses, web &amp; null<br/>platform backends<br/>[sdl2-platform.c]"]
  node_tiles["Tile renderer<br/>rendering<br/>[tiles.c]"]
  node_tile_assets["Tile assets<br/>binary asset<br/>[tiles.bin]"]
end

subgraph group_core["Game lifecycle"]
  node_rogue_main{{"Game coordinator<br/>game loop<br/>[RogueMain.c]"}}
  node_menu["Title &amp; menus<br/>UI flow<br/>[MainMenu.c]"]
  node_io["Input/output mediation<br/>game I/O<br/>[IO.c]"]
  node_globals[("Run state contracts<br/>global state<br/>[Globals.c]")]
  node_rogue_headers["Core declarations<br/>C headers<br/>[Rogue.h]"]
  node_time["Turn scheduler<br/>turn semantics<br/>[Time.c]"]
end

subgraph group_world["Dungeon &amp; simulation"]
  node_architect{{"Dungeon generator<br/>procedural generation<br/>[Architect.c]"}}
  node_grid["Grid &amp; cell state<br/>spatial model<br/>[Grid.c]"]
  node_spatial["Pathing &amp; lighting<br/>spatial simulation<br/>[Dijkstra.c]"]
  node_movement["Player actions<br/>movement &amp; interaction<br/>[Movement.c]"]
  node_monsters["Creatures &amp; AI<br/>entity simulation<br/>[Monsters.c]"]
  node_combat["Combat &amp; status<br/>resolution<br/>[Combat.c]"]
  node_items["Items &amp; inventory<br/>loot system<br/>[Items.c]"]
  node_rules["Rule tables<br/>static content<br/>[PowerTables.c]"]
end

subgraph group_persistence["Replay &amp; delivery"]
  node_recordings[("Recordings &amp; seeds<br/>deterministic replay<br/>[Recordings.c]")]
  node_variants["Game variants<br/>build-time globals<br/>[GlobalsBrogue.c]"]
  node_build["Make build targets<br/>build system<br/>[brogue.mk]"]
  node_ci["Build &amp; test CI<br/>CI workflows<br/>[build.yml]"]
end

node_main -->|"selects services"| node_platform_api
node_main -->|"enters"| node_rogue_main
node_platform_backends -->|"implements"| node_platform_api
node_tiles -->|"loads"| node_tile_assets
node_platform_backends -->|"uses for graphics"| node_tiles
node_rogue_main -->|"drives"| node_menu
node_rogue_main -->|"processes commands through"| node_io
node_io -->|"mediates I/O"| node_platform_api
node_rogue_main -->|"advances turns"| node_time
node_rogue_main -->|"coordinates state"| node_globals
node_rogue_headers -.->|"declares contracts for"| node_globals
node_rogue_main -->|"creates levels"| node_architect
node_architect -->|"constructs"| node_grid
node_movement -->|"mutates"| node_grid
node_movement -->|"queries paths and visibility"| node_spatial
node_monsters -->|"uses pathing"| node_spatial
node_movement -->|"triggers"| node_combat
node_combat -->|"updates creatures"| node_monsters
node_movement -->|"interacts with"| node_items
node_rules -.->|"governs generation"| node_architect
node_rules -.->|"governs effects"| node_items
node_rogue_main -->|"records and replays runs"| node_recordings
node_variants -->|"supplies selected configuration"| node_globals
node_build -->|"builds targets"| node_platform_backends
node_build -->|"selects variant"| node_variants
node_ci -->|"runs"| node_build

click node_main "https://github.com/tmewett/broguece/blob/master/src/platform/main.c"
click node_platform_api "https://github.com/tmewett/broguece/blob/master/src/platform/platform.h"
click node_platform_backends "https://github.com/tmewett/broguece/blob/master/src/platform/sdl2-platform.c"
click node_tiles "https://github.com/tmewett/broguece/blob/master/src/platform/tiles.c"
click node_tile_assets "https://github.com/tmewett/broguece/blob/master/bin/assets/tiles.bin"
click node_rogue_main "https://github.com/tmewett/broguece/blob/master/src/brogue/RogueMain.c"
click node_menu "https://github.com/tmewett/broguece/blob/master/src/brogue/MainMenu.c"
click node_io "https://github.com/tmewett/broguece/blob/master/src/brogue/IO.c"
click node_globals "https://github.com/tmewett/broguece/blob/master/src/brogue/Globals.c"
click node_rogue_headers "https://github.com/tmewett/broguece/blob/master/src/brogue/Rogue.h"
click node_time "https://github.com/tmewett/broguece/blob/master/src/brogue/Time.c"
click node_architect "https://github.com/tmewett/broguece/blob/master/src/brogue/Architect.c"
click node_grid "https://github.com/tmewett/broguece/blob/master/src/brogue/Grid.c"
click node_spatial "https://github.com/tmewett/broguece/blob/master/src/brogue/Dijkstra.c"
click node_movement "https://github.com/tmewett/broguece/blob/master/src/brogue/Movement.c"
click node_monsters "https://github.com/tmewett/broguece/blob/master/src/brogue/Monsters.c"
click node_combat "https://github.com/tmewett/broguece/blob/master/src/brogue/Combat.c"
click node_items "https://github.com/tmewett/broguece/blob/master/src/brogue/Items.c"
click node_rules "https://github.com/tmewett/broguece/blob/master/src/brogue/PowerTables.c"
click node_recordings "https://github.com/tmewett/broguece/blob/master/src/brogue/Recordings.c"
click node_variants "https://github.com/tmewett/broguece/blob/master/src/variants/GlobalsBrogue.c"
click node_build "https://github.com/tmewett/broguece/blob/master/make/brogue.mk"
click node_ci "https://github.com/tmewett/broguece/blob/master/.github/workflows/build.yml"

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_platform_api,node_platform_backends,node_tiles,node_tile_assets toneBlue
class node_rogue_main,node_menu,node_io,node_globals,node_rogue_headers,node_time toneAmber
class node_architect,node_grid,node_spatial,node_movement,node_monsters,node_combat,node_items,node_rules toneMint
class node_recordings,node_variants,node_build,node_ci toneRose
```

## Components

### Platform & front ends

- [Process startup](https://github.com/tmewett/broguece/blob/master/src/platform/main.c): C entry point · `src/platform/main.c`
- [Platform boundary](https://github.com/tmewett/broguece/blob/master/src/platform/platform.h): platform API · `src/platform/platform.h`
- [SDL, curses, web & null](https://github.com/tmewett/broguece/blob/master/src/platform/sdl2-platform.c): platform backends · Selectable graphics, terminal, browser, and headless implementations. · `src/platform/sdl2-platform.c`
- [Tile renderer](https://github.com/tmewett/broguece/blob/master/src/platform/tiles.c): rendering · `src/platform/tiles.c`
- [Tile assets](https://github.com/tmewett/broguece/blob/master/bin/assets/tiles.bin): binary asset · `bin/assets/tiles.bin`

### Game lifecycle

- [Game coordinator](https://github.com/tmewett/broguece/blob/master/src/brogue/RogueMain.c): game loop · Coordinates menus, runs, commands, turns, and end states. · `src/brogue/RogueMain.c`
- [Title & menus](https://github.com/tmewett/broguece/blob/master/src/brogue/MainMenu.c): UI flow · `src/brogue/MainMenu.c`
- [Input/output mediation](https://github.com/tmewett/broguece/blob/master/src/brogue/IO.c): game I/O · `src/brogue/IO.c`
- [Run state contracts](https://github.com/tmewett/broguece/blob/master/src/brogue/Globals.c): global state · `src/brogue/Globals.c`
- [Core declarations](https://github.com/tmewett/broguece/blob/master/src/brogue/Rogue.h): C headers · `src/brogue/Rogue.h`
- [Turn scheduler](https://github.com/tmewett/broguece/blob/master/src/brogue/Time.c): turn semantics · `src/brogue/Time.c`

### Dungeon & simulation

- [Dungeon generator](https://github.com/tmewett/broguece/blob/master/src/brogue/Architect.c): procedural generation · `src/brogue/Architect.c`
- [Grid & cell state](https://github.com/tmewett/broguece/blob/master/src/brogue/Grid.c): spatial model · `src/brogue/Grid.c`
- [Pathing & lighting](https://github.com/tmewett/broguece/blob/master/src/brogue/Dijkstra.c): spatial simulation · Distance maps drive navigation; lighting updates visibility. · `src/brogue/Dijkstra.c`
- [Player actions](https://github.com/tmewett/broguece/blob/master/src/brogue/Movement.c): movement & interaction · `src/brogue/Movement.c`
- [Creatures & AI](https://github.com/tmewett/broguece/blob/master/src/brogue/Monsters.c): entity simulation · `src/brogue/Monsters.c`
- [Combat & status](https://github.com/tmewett/broguece/blob/master/src/brogue/Combat.c): resolution · `src/brogue/Combat.c`
- [Items & inventory](https://github.com/tmewett/broguece/blob/master/src/brogue/Items.c): loot system · `src/brogue/Items.c`
- [Rule tables](https://github.com/tmewett/broguece/blob/master/src/brogue/PowerTables.c): static content · `src/brogue/PowerTables.c`

### Replay & delivery

- [Recordings & seeds](https://github.com/tmewett/broguece/blob/master/src/brogue/Recordings.c): deterministic replay · Run recordings and curated seeds support reproducible validation. · `src/brogue/Recordings.c`
- [Game variants](https://github.com/tmewett/broguece/blob/master/src/variants/GlobalsBrogue.c): build-time globals · Brogue, Bullet Brogue, and Rapid Brogue select variant state configuration. · `src/variants/GlobalsBrogue.c`
- [Make build targets](https://github.com/tmewett/broguece/blob/master/make/brogue.mk): build system · Common and OS-specific Make targets build platform and variant combinations. · `make/brogue.mk`
- [Build & test CI](https://github.com/tmewett/broguece/blob/master/.github/workflows/build.yml): CI workflows · `.github/workflows/build.yml`

## Connections

- Process startup → Platform boundary: selects services
- Process startup → Game coordinator: enters
- SDL, curses, web & null → Platform boundary: implements
- Tile renderer → Tile assets: loads
- SDL, curses, web & null → Tile renderer: uses for graphics
- Game coordinator → Title & menus: drives
- Game coordinator → Input/output mediation: processes commands through
- Input/output mediation → Platform boundary: mediates I/O
- Game coordinator → Turn scheduler: advances turns
- Game coordinator → Run state contracts: coordinates state
- Core declarations → Run state contracts: declares contracts for
- Game coordinator → Dungeon generator: creates levels
- Dungeon generator → Grid & cell state: constructs
- Player actions → Grid & cell state: mutates
- Player actions → Pathing & lighting: queries paths and visibility
- Creatures & AI → Pathing & lighting: uses pathing
- Player actions → Combat & status: triggers
- Combat & status → Creatures & AI: updates creatures
- Player actions → Items & inventory: interacts with
- Rule tables → Dungeon generator: governs generation
- Rule tables → Items & inventory: governs effects
- Game coordinator → Recordings & seeds: records and replays runs
- Game variants → Run state contracts: supplies selected configuration
- Make build targets → SDL, curses, web & null: builds targets
- Make build targets → Game variants: selects variant
- Build & test CI → Make build targets: runs
