How jdolan/quetoo works
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: cl_main.c Client core · sv_main.c Server core · net.c Networking · filesystem.c Filesystem
Components 18
Runtime
Playable engine processes and their host boundaries
- Client app · Playable client entrypoint and process host
src/main/main.c - Dedicated server · Headless server entrypoint
src/main/main.c
Presentation
Client-side input, prediction, rendering, sound, and UI
- Client core · Connects to servers, parses snapshots, manages input and demos
src/client/cl_main.c - Renderer · OpenGL presentation pipeline for 3D and 2D drawing
src/client/renderer/r_main.c - Sound · Client-side mixing and playback driven by game events
src/client/sound/s_main.c - UI system · Client screens and editor UI with data-driven views
src/client/ui/ui_main.c - CGame 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 · Owns world state, clients, snapshots, admin, and registration
src/server/sv_main.c - Game 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 · Message, channel, UDP/TCP, and HTTP abstractions
src/net/net.c - Shared core · Math, parsing, console, filesystem, memory, sys, and threading support
src/shared/shared.c - Collision · BSP traces, model/entity collision, and poly tests
src/collision/cm_trace.c - Filesystem · PhysicsFS-backed asset loading and package mounting
src/common/filesystem.c - External libs · Packaged OpenAL, libsndfile, PhysFS, XML, GLib, and other third-party libraries
deps/rapidjson/rapidjson/rapidjson.h
Tools
Offline content generation and deployment helpers
- quemap · Offline BSP/map compilation pipeline
src/tools/quemap/main.c - Master server · Public server listing and discovery process
src/tools/quetoo-master/main.c - Content tools · Texture, heightmap, and model conversion helpers
src/tools/heightmap-fu/README.md - Game data · Mounted runtime assets, maps, shaders, sounds, and UI resources
apple/Quetoo.app/Contents/Resources/default/icons/quetoo.icns
Connections 25
- 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