# cryptocode/terminal-doom architecture

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

- Interactive diagram: https://gitdiagram.com/cryptocode/terminal-doom
- Repository: https://github.com/cryptocode/terminal-doom

## Overview

Terminal Doom adapts the Doom engine for play in modern terminals: the engine advances gameplay and produces pixel frames, while the terminal-facing layer presents them and handles input. The README documents libvaxis as the renderer/input handler and miniaudio as the playback backend; the source tree shown here contains the Doom engine and miniaudio bridge, but not the Zig application layer. Gameplay, rendering, WAD resources, menus, and sound are represented as distinct subsystems. Some connections are documented only in the README or inferred from SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`src/doomgeneric/g_game.c`](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/g_game.c) (Game state), [`src/doomgeneric/w_wad.c`](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/w_wad.c) (WAD resources), [`src/doomgeneric/d_main.c`](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/d_main.c) (Engine startup), [`src/doomgeneric/d_loop.c`](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/d_loop.c) (Doom loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Engine runtime"]
  node_doom_startup["Engine startup<br/>[d_main.c]"]
  node_doom_loop["Doom loop<br/>[d_loop.c]"]
end

subgraph group_gameplay["Gameplay"]
  node_game_rules["Game state<br/>[g_game.c]"]
  node_level_setup["Level setup<br/>[p_setup.c]"]
  node_world_sim["World simulation<br/>[p_tick.c]"]
  node_combat["Combat and AI<br/>[p_enemy.c]"]
  node_savegames["Save and load<br/>[p_saveg.c]"]
end

subgraph group_render["Rendering and UI"]
  node_menus["Menus and options<br/>[m_menu.c]"]
  node_hud["HUD and status<br/>[st_stuff.c]"]
  node_renderer["World renderer<br/>[r_main.c]"]
  node_pixel_video["Pixel buffer<br/>[v_video.c]"]
end

subgraph group_assets["Game resources"]
  node_wad_resources[("WAD resources<br/>[w_wad.c]")]
end

subgraph group_audio["Sound playback"]
  node_audio_mixer["Sound interface<br/>[s_sound.c]"]
  node_miniaudio_bridge["Miniaudio bridge"]
  node_miniaudio["Miniaudio<br/>[miniaudio.h]"]
end

node_player(("Player"))
node_terminal_app["Terminal app"]
node_libvaxis["libvaxis"]

node_player -->|"provides input"| node_terminal_app
node_terminal_app -->|"uses for input"| node_libvaxis
node_libvaxis -->|"renders frames"| node_terminal_app
node_doom_startup -.->|"starts"| node_doom_loop
node_doom_startup -->|"loads resources"| node_wad_resources
node_doom_startup -->|"initializes sound"| node_audio_mixer
node_doom_loop -.->|"ticks game"| node_game_rules
node_game_rules -->|"sets up levels"| node_level_setup
node_game_rules -->|"saves and loads"| node_savegames
node_level_setup -.->|"reads map data"| node_wad_resources
node_world_sim -.->|"updates actors"| node_combat
node_game_rules -->|"handles events"| node_menus
node_renderer -->|"reads graphics"| node_wad_resources
node_renderer -->|"draws pixels"| node_pixel_video
node_doom_loop -->|"presents each frame"| node_terminal_app
node_terminal_app -->|"encodes frame"| node_pixel_video
node_audio_mixer -.->|"dispatches playback"| node_miniaudio_bridge
node_miniaudio_bridge -->|"reads sound data"| node_wad_resources
node_miniaudio_bridge -->|"uses playback API"| node_miniaudio

click node_doom_startup "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/d_main.c"
click node_doom_loop "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/d_loop.c"
click node_game_rules "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/g_game.c"
click node_level_setup "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_setup.c"
click node_world_sim "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_tick.c"
click node_combat "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_enemy.c"
click node_savegames "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_saveg.c"
click node_menus "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/m_menu.c"
click node_hud "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/st_stuff.c"
click node_renderer "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/r_main.c"
click node_pixel_video "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/v_video.c"
click node_wad_resources "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/w_wad.c"
click node_audio_mixer "https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/s_sound.c"
click node_miniaudio_bridge "https://github.com/cryptocode/terminal-doom/blob/main/src/miniaudio/doom_miniaudio_sound_bridge.c"
click node_miniaudio "https://github.com/cryptocode/terminal-doom/blob/main/src/miniaudio/miniaudio.h"

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_doom_startup,node_doom_loop toneBlue
class node_game_rules,node_level_setup,node_world_sim,node_combat,node_savegames toneAmber
class node_menus,node_hud,node_renderer,node_pixel_video toneMint
class node_wad_resources toneRose
class node_audio_mixer,node_miniaudio_bridge,node_miniaudio,node_player,node_terminal_app,node_libvaxis toneIndigo
```

## Components

### Engine runtime

- [Engine startup](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/d_main.c): `src/doomgeneric/d_main.c`
- [Doom loop](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/d_loop.c): `src/doomgeneric/d_loop.c`

### Gameplay

- [Game state](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/g_game.c): `src/doomgeneric/g_game.c`
- [Level setup](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_setup.c): `src/doomgeneric/p_setup.c`
- [World simulation](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_tick.c): `src/doomgeneric/p_tick.c`
- [Combat and AI](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_enemy.c): `src/doomgeneric/p_enemy.c`
- [Save and load](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/p_saveg.c): `src/doomgeneric/p_saveg.c`

### Rendering and UI

- [Menus and options](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/m_menu.c): `src/doomgeneric/m_menu.c`
- [HUD and status](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/st_stuff.c): `src/doomgeneric/st_stuff.c`
- [World renderer](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/r_main.c): `src/doomgeneric/r_main.c`
- [Pixel buffer](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/v_video.c): `src/doomgeneric/v_video.c`

### Game resources

- [WAD resources](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/w_wad.c): `src/doomgeneric/w_wad.c`

### Sound playback

- [Sound interface](https://github.com/cryptocode/terminal-doom/blob/main/src/doomgeneric/s_sound.c): `src/doomgeneric/s_sound.c`
- [Miniaudio bridge](https://github.com/cryptocode/terminal-doom/blob/main/src/miniaudio/doom_miniaudio_sound_bridge.c): `src/miniaudio/doom_miniaudio_sound_bridge.c`
- [Miniaudio](https://github.com/cryptocode/terminal-doom/blob/main/src/miniaudio/miniaudio.h): `src/miniaudio/miniaudio.h`

### Other components

- **Player**
- **Terminal app**
- **libvaxis**

## Connections

- Player → Terminal app: provides input
- Terminal app → libvaxis: uses for input
- libvaxis → Terminal app: renders frames
- Engine startup → Doom loop: starts
- Engine startup → WAD resources: loads resources (evidence: `src/doomgeneric/d_main.c`)
- Engine startup → Sound interface: initializes sound (evidence: `src/doomgeneric/d_main.c`)
- Doom loop → Game state: ticks game
- Game state → Level setup: sets up levels (evidence: `src/doomgeneric/g_game.c`)
- Game state → Save and load: saves and loads (evidence: `src/doomgeneric/g_game.c`)
- Level setup → WAD resources: reads map data
- World simulation → Combat and AI: updates actors
- Game state → Menus and options: handles events (evidence: `src/doomgeneric/g_game.c`)
- World renderer → WAD resources: reads graphics
- World renderer → Pixel buffer: draws pixels
- Doom loop → Terminal app: presents each frame
- Terminal app → Pixel buffer: encodes frame
- Sound interface → Miniaudio bridge: dispatches playback
- Miniaudio bridge → WAD resources: reads sound data (evidence: `src/miniaudio/doom_miniaudio_sound_bridge.c`)
- Miniaudio bridge → Miniaudio: uses playback API (evidence: `src/miniaudio/doom_miniaudio_sound_bridge.c`)
