# jdolan/quetoo architecture

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

- Interactive diagram: https://gitdiagram.com/jdolan/quetoo
- Repository: https://github.com/jdolan/quetoo

## Overview

1. **This repository is a full game engine + content pipeline, not a single app.**  
   The top-level build produces multiple runtime artifacts: the playable client, a dedicated server, a map compiler (`quemap`), a master server tool, and test binaries. The code is split so game rules, client presentation, networking, rendering, sound, and offline map building can evolve independently.

2. **The core runtime boundary is “engine host” vs. “game module” vs. “client module.”**  
   The server side hosts authoritative simulation in `src/server` and loads gameplay logic from `src/game/default`. The client side hosts input, prediction, rendering, audio, and UI in `src/client`, and loads presentation/gameplay feedback from `src/cgame/default`. This split is the most important architecture line for a diagram.

3. **The server is authoritative and owns world simulation.**  
   `src/server` handles init, clients, sending snapshots, world state, entity management, admin/console, editor hooks, and master-server registration. It delegates combat, items, AI, physics hooks, and entity behavior to the game module. The server is the source of truth for game state and replicated events.

4. **The game module contains the actual gameplay rules.**  
   `src/game/default` implements movement, entities, triggers, items, combat, weapons, AI, map lists, client view/stats, and entity-specific behavior. It is separated from the server so the server can remain a generic host while game logic stays replaceable. The dedicated server and client both depend on the same gameplay definitions, but only the server executes them authoritatively.

5. **The client is a pipeline from input to prediction to rendering/audio/UI.**  
   `src/client` parses network snapshots, handles input/keys/mouse/binds, runs prediction, manages demo playback, connects to the server, and coordinates the renderer, sound system, and screen/UI layers. The client also has a null backend for non-rendered environments, which reinforces that rendering is a replaceable subsystem rather than the app core.

6. **Rendering is a major subsystem with its own internal pipeline.**  
   `src/client/renderer` is a substantial OpenGL-based renderer with distinct stages for BSP drawing, meshes, sprites, decals, depth prepass, lighting, shadows, occlusion, sky, framebuffer management, materials, and shader programs. Shader source is stored alongside the C code, so render behavior is split between engine code and GLSL assets. The architecture should show this as a dedicated presentation pipeline fed by client state and game snapshots.

7. **Sound is isolated and uses external audio libraries.**  
   `src/client/sound` mixes samples, music, media, and OpenAL extensions, with `libsndfile` and OpenAL provided in the repo packaging. Sound is driven by client/game events rather than directly by the server, so it sits on the client side as an event consumer.

8. **UI is an explicit subsystem with data-driven view/controller assets.**  
   The client UI and the in-game UI/editor UI live under `src/client/ui` and `src/cgame/default/ui`. Many screens are defined with paired `.c`, `.h`, `.json`, and `.css` files, and the repo depends on ObjectivelyMVC-style controllers. This means the UI is not hardcoded as one monolith; it is structured as a controller/view system with external layout/style data.

9. **Collision and shared math/utilities form a reusable engine foundation.**  
   `src/collision` provides BSP, traces, entity collision, model collision, and poly tests. `src/shared` contains vectors, matrices, colors, parsing, byte swapping, and other common primitives. These packages are shared by server, client, game, renderer-adjacent code, and tools, making them the low-level boundary beneath gameplay and presentation.

10. **Networking is its own layer with UDP/TCP/message/channel abstractions.**  
    `src/net` includes message packing, channels, UDP, TCP, and HTTP helpers. That suggests the engine has both real-time game traffic and ancillary network features such as HTTP-based retrieval or updates. In a diagram, this layer sits between client/server logic and the transport, not inside gameplay or rendering.

11. **Offline content generation is a separate toolchain, centered on `quemap`.**  
    `src/tools/quemap` compiles map data through brush/CSG/BSP/portal/tree/voxel/light/write stages, producing runnable level assets. This is not runtime code; it is the content pipeline that converts authoring inputs into BSP-based game assets, including lighting and geometry optimization. The repo also contains helper scripts for texture/heightmap preparation and model conversion.

12. **Server discovery and public hosting are handled outside the match server.**  
    `src/tools/quetoo-master` is a separate master-server process, and `src/server/sv_master.c` integrates with it for server listing/registration. This is an important deployment boundary: one process runs the game world, another coordinates server discovery.

13. **The filesystem and packaged data layer are runtime dependencies, not an implementation detail.**  
    The engine relies on PhysicsFS and a separate game-data package (`quetoo-data`) mounted into the expected target path. That means assets, maps, UI resources, shaders, sounds, and other content are externalized from the binaries and loaded through a virtual filesystem abstraction.

14. **Testing and build infrastructure are first-class.**  
    `src/tests` contains unit tests for common utilities, collision, filesystem, threading, renderer media, command parsing, and editor/map behavior. Build support spans GNU Autotools, Visual Studio, Xcode, Linux packaging, and cross-compilation. For architecture purposes, this means the project is organized around many independently buildable modules rather than one compile unit.

15. **The most accurate high-level diagram is layered and event-driven.**  
    A good diagram should show: input/UI on the client side; client prediction and rendering/audio as presentation; network channels carrying snapshots, commands, and events; authoritative server simulation using game rules; collision/shared utilities underneath both; and `quemap` plus asset packages feeding the runtime through the filesystem. That is the central architecture of the repo.

Main entry points: [`src/client/cl_main.c`](https://github.com/jdolan/quetoo/blob/main/src/client/cl_main.c) (Client core), [`src/server/sv_main.c`](https://github.com/jdolan/quetoo/blob/main/src/server/sv_main.c) (Server core), [`src/net/net.c`](https://github.com/jdolan/quetoo/blob/main/src/net/net.c) (Networking), [`src/common/filesystem.c`](https://github.com/jdolan/quetoo/blob/main/src/common/filesystem.c) (Filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_client["Client app<br/>runtime binary<br/>[main.c]"]
  node_main_dedicated["Dedicated server<br/>runtime binary<br/>[main.c]"]
end

subgraph group_presentation["Presentation"]
  node_client_core["Client core<br/>client host<br/>[cl_main.c]"]
  node_client_render["Renderer<br/>render pipeline<br/>[r_main.c]"]
  node_client_sound["Sound<br/>audio mixer<br/>[s_main.c]"]
  node_client_ui["UI system<br/>mvc ui<br/>[ui_main.c]"]
  node_cgame_module["CGame module<br/>presentation module<br/>[cg_main.c]"]
end

subgraph group_simulation["Simulation"]
  node_server_core["Server core<br/>authoritative host<br/>[sv_main.c]"]
  node_game_module["Game module<br/>rules module<br/>[g_main.c]"]
end

subgraph group_foundation["Foundation"]
  node_net_layer["Networking<br/>protocol layer<br/>[net.c]"]
  node_shared_core["Shared core<br/>common utilities<br/>[shared.c]"]
  node_collision_core["Collision<br/>[cm_trace.c]"]
  node_filesystem["Filesystem<br/>vfs layer<br/>[filesystem.c]"]
  node_deps_libs["External libs<br/>vendored deps<br/>[rapidjson.h]"]
end

subgraph group_tools["Tools"]
  node_quemap_tool["quemap<br/>map compiler<br/>[main.c]"]
  node_master_tool["Master server<br/>discovery tool<br/>[main.c]"]
  node_asset_tools["Content tools<br/>prep scripts<br/>[README.md]"]
  node_assets_pkg[("Game data<br/>content package<br/>[quetoo.icns]")]
end

node_main_client -->|"runs"| node_client_core
node_main_client -->|"mounts"| node_filesystem
node_main_dedicated -->|"runs"| node_server_core
node_client_core -->|"snapshots"| node_net_layer
node_client_core -->|"loads"| node_cgame_module
node_client_core -->|"drives"| node_client_render
node_client_core -->|"drives"| node_client_sound
node_client_core -->|"hosts"| node_client_ui
node_cgame_module -->|"uses"| node_client_ui
node_client_render -->|"uses"| node_shared_core
node_client_render -->|"culls"| node_collision_core
node_client_sound -->|"links"| node_deps_libs
node_server_core -->|"loads"| node_game_module
node_server_core -->|"sends"| node_net_layer
node_server_core -->|"queries"| node_collision_core
node_game_module -->|"uses"| node_shared_core
node_game_module -->|"uses"| node_collision_core
node_net_layer -->|"uses"| node_shared_core
node_filesystem -->|"backed by"| node_deps_libs
node_quemap_tool -->|"builds"| node_collision_core
node_quemap_tool -->|"uses"| node_shared_core
node_quemap_tool -->|"reads"| node_filesystem
node_master_tool -->|"announces"| node_net_layer
node_assets_pkg -->|"loaded by"| node_filesystem
node_asset_tools -->|"prepares"| node_assets_pkg

click node_main_client "https://github.com/jdolan/quetoo/blob/main/src/main/main.c"
click node_main_dedicated "https://github.com/jdolan/quetoo/blob/main/src/main/main.c"
click node_client_core "https://github.com/jdolan/quetoo/blob/main/src/client/cl_main.c"
click node_client_render "https://github.com/jdolan/quetoo/blob/main/src/client/renderer/r_main.c"
click node_client_sound "https://github.com/jdolan/quetoo/blob/main/src/client/sound/s_main.c"
click node_client_ui "https://github.com/jdolan/quetoo/blob/main/src/client/ui/ui_main.c"
click node_cgame_module "https://github.com/jdolan/quetoo/blob/main/src/cgame/default/cg_main.c"
click node_server_core "https://github.com/jdolan/quetoo/blob/main/src/server/sv_main.c"
click node_game_module "https://github.com/jdolan/quetoo/blob/main/src/game/default/g_main.c"
click node_net_layer "https://github.com/jdolan/quetoo/blob/main/src/net/net.c"
click node_shared_core "https://github.com/jdolan/quetoo/blob/main/src/shared/shared.c"
click node_collision_core "https://github.com/jdolan/quetoo/blob/main/src/collision/cm_trace.c"
click node_filesystem "https://github.com/jdolan/quetoo/blob/main/src/common/filesystem.c"
click node_quemap_tool "https://github.com/jdolan/quetoo/blob/main/src/tools/quemap/main.c"
click node_master_tool "https://github.com/jdolan/quetoo/blob/main/src/tools/quetoo-master/main.c"
click node_asset_tools "https://github.com/jdolan/quetoo/blob/main/src/tools/heightmap-fu/README.md"
click node_assets_pkg "https://github.com/jdolan/quetoo/blob/main/apple/Quetoo.app/Contents/Resources/default/icons/quetoo.icns"
click node_deps_libs "https://github.com/jdolan/quetoo/blob/main/deps/rapidjson/rapidjson/rapidjson.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_main_client,node_main_dedicated toneBlue
class node_client_core,node_client_render,node_client_sound,node_client_ui,node_cgame_module toneAmber
class node_server_core,node_game_module toneMint
class node_net_layer,node_shared_core,node_collision_core,node_filesystem,node_deps_libs toneRose
class node_quemap_tool,node_master_tool,node_asset_tools,node_assets_pkg toneIndigo
```

## Components

### Runtime

Playable engine processes and their host boundaries

- [Client app](https://github.com/jdolan/quetoo/blob/main/src/main/main.c): runtime binary · Playable client entrypoint and process host · `src/main/main.c`
- [Dedicated server](https://github.com/jdolan/quetoo/blob/main/src/main/main.c): runtime binary · Headless server entrypoint · `src/main/main.c`

### Presentation

Client-side input, prediction, rendering, sound, and UI

- [Client core](https://github.com/jdolan/quetoo/blob/main/src/client/cl_main.c): client host · Connects to servers, parses snapshots, manages input and demos · `src/client/cl_main.c`
- [Renderer](https://github.com/jdolan/quetoo/blob/main/src/client/renderer/r_main.c): render pipeline · OpenGL presentation pipeline for 3D and 2D drawing · `src/client/renderer/r_main.c`
- [Sound](https://github.com/jdolan/quetoo/blob/main/src/client/sound/s_main.c): audio mixer · Client-side mixing and playback driven by game events · `src/client/sound/s_main.c`
- [UI system](https://github.com/jdolan/quetoo/blob/main/src/client/ui/ui_main.c): mvc ui · Client screens and editor UI with data-driven views · `src/client/ui/ui_main.c`
- [CGame module](https://github.com/jdolan/quetoo/blob/main/src/cgame/default/cg_main.c): presentation module · Client gameplay feedback, HUD, prediction, effects, and view logic · `src/cgame/default/cg_main.c`

### Simulation

Authoritative server and replaceable game logic

- [Server core](https://github.com/jdolan/quetoo/blob/main/src/server/sv_main.c): authoritative host · Owns world state, clients, snapshots, admin, and registration · `src/server/sv_main.c`
- [Game module](https://github.com/jdolan/quetoo/blob/main/src/game/default/g_main.c): rules module · Replaceable gameplay rules, entities, AI, combat, and physics hooks · `src/game/default/g_main.c`

### Foundation

Shared low-level systems used across runtime and tools

- [Networking](https://github.com/jdolan/quetoo/blob/main/src/net/net.c): protocol layer · Message, channel, UDP/TCP, and HTTP abstractions · `src/net/net.c`
- [Shared core](https://github.com/jdolan/quetoo/blob/main/src/shared/shared.c): common utilities · Math, parsing, console, filesystem, memory, sys, and threading support · `src/shared/shared.c`
- [Collision](https://github.com/jdolan/quetoo/blob/main/src/collision/cm_trace.c): physics collision · BSP traces, model/entity collision, and poly tests · `src/collision/cm_trace.c`
- [Filesystem](https://github.com/jdolan/quetoo/blob/main/src/common/filesystem.c): vfs layer · PhysicsFS-backed asset loading and package mounting · `src/common/filesystem.c`
- [External libs](https://github.com/jdolan/quetoo/blob/main/deps/rapidjson/rapidjson/rapidjson.h): vendored deps · Packaged OpenAL, libsndfile, PhysFS, XML, GLib, and other third-party libraries · `deps/rapidjson/rapidjson/rapidjson.h`

### Tools

Offline content generation and deployment helpers

- [quemap](https://github.com/jdolan/quetoo/blob/main/src/tools/quemap/main.c): map compiler · Offline BSP/map compilation pipeline · `src/tools/quemap/main.c`
- [Master server](https://github.com/jdolan/quetoo/blob/main/src/tools/quetoo-master/main.c): discovery tool · Public server listing and discovery process · `src/tools/quetoo-master/main.c`
- [Content tools](https://github.com/jdolan/quetoo/blob/main/src/tools/heightmap-fu/README.md): prep scripts · Texture, heightmap, and model conversion helpers · `src/tools/heightmap-fu/README.md`
- [Game data](https://github.com/jdolan/quetoo/blob/main/apple/Quetoo.app/Contents/Resources/default/icons/quetoo.icns): content package · Mounted runtime assets, maps, shaders, sounds, and UI resources · `apple/Quetoo.app/Contents/Resources/default/icons/quetoo.icns`

## Connections

- Client app → Client core: runs · Client executable hosts the client runtime
- Client app → Filesystem: mounts · Client process loads game data through the virtual filesystem
- Dedicated server → Server core: runs · Dedicated server executable hosts the authoritative server
- Client core → Networking: snapshots · Client exchanges commands and world snapshots over networking
- Client core → CGame module: loads · Client delegates game presentation and HUD feedback to cgame
- Client core → Renderer: drives · Client state feeds the rendering pipeline
- Client core → Sound: drives · Client events feed audio playback
- Client core → UI system: hosts · Client owns menus, editor UI, and screen flow
- CGame module → UI system: uses · In-game UI integrates with the client UI system
- Renderer → Shared core: uses · Renderer depends on shared math and helpers
- Renderer → Collision: culls · Renderer relies on spatial/collision data for visibility and world interaction
- Sound → External libs: links · Audio uses OpenAL and libsndfile
- Server core → Game module: loads · Server executes gameplay rules authoritatively
- Server core → Networking: sends · Server replicates state and communicates with clients
- Server core → Collision: queries · Server uses collision for world interaction and traces
- Game module → Shared core: uses · Gameplay code shares primitives and utilities
- Game module → Collision: uses · Gameplay movement and physics hooks depend on collision
- Networking → Shared core: uses · Networking shares common types and utilities
- Filesystem → External libs: backed by · Filesystem abstraction is powered by packaged third-party libraries
- quemap → Collision: builds · Map compiler produces BSP and collision-ready level data
- quemap → Shared core: uses · Tooling shares parsing, math, and utility code
- quemap → Filesystem: reads · Map compiler consumes source assets through the filesystem layer
- Master server → Networking: announces · Master server supports discovery and registration traffic
- Game data → Filesystem: loaded by · Runtime content is externalized and mounted at launch
- Content tools → Game data: prepares · Scripts transform source art into packaged game data
