Quake Live Reverse Engineering Handbook
March 30, 2026 · View on GitHub
This handbook aggregates the major reverse-engineering stages completed so far and surfaces the artefacts each stage produced. Use it as the single entry point when onboarding contributors, preparing reviews, or scheduling refresh work.
Stage output index
Artefact directory
- Symbol exports: Normalised manifests live in
references/symbol-maps/with alias configuration atreferences/analysis/quakelive_symbol_aliases.json. - Ghidra corpus: Structured retail-binary exports live in
references/reverse-engineering/ghidra/and are generated byscripts/ghidra/run_quakelive_reference.ps1plusscripts/ghidra/ExportQuakeLiveReference.java. - Toolchain captures: Raw dumps sit in
references/analysis/quakelive_toolchain_metadata.json; rebuild containers undertools/containers/. - Asset inventory: Structured list maintained in
docs/reverse-engineering/asset-map.csv; HLIL transcripts referenced in Asset map gaps. - Gameplay prototypes: C99 reconstructions and shims under
src-re/prototypes/with logging output atlogs/re/native-shim.logand syscall contract snapshots inlogs/syscall_contract.log; validate againsttools/tests/validate_syscall_contract.py. - Networking references: Use annotated walkthroughs in
src-re/annotated/net/alongside production sources insrc/code/. - Trace captures: Deterministic artefacts produced by
tools/trace/land beneathartifacts/tests/. - Review tracker: Clean reconstructions and approver list located at
src-re/clean/and Reconstruction Tracker. - Platform services & authentication: Abstraction notes in Steam Platform Abstraction Plan and Online Authentication Lifecycle, credential persistence guidance in Credential persistence and migration, implementations under
src/common/platform/andsrc/common/auth_credentials.c, coverage matrix indocs/qa/credential-matrix.md, and supporting automation viatools/integration/auth_flow_trace.pyandtests/test_platform_services.py. - Windows runtime validation: WOW64 setup, redistributable installation, and troubleshooting steps are tracked in the Windows 32-bit Runtime Guide.
Working glossary
Baseline export – The symbol extraction pass orchestrated by ghidra_scripts/ExportSymbolMap.py to seed references/symbol-maps/ with normalised manifests used across reverse-engineering tasks.
Ghidra reference corpus – The OpenAlice-style committed export set under references/reverse-engineering/ghidra/ that records metadata, imports, exports, analyst-promoted symbols, function size rankings, and top-function decompilations for the retail Quake Live binaries.
GhidrAssistMCP – Optional live MCP bridge configured through scripts/ghidra/setup_ghidrassist_mcp.ps1. Use it for exploration only, then revalidate findings against the committed Ghidra corpus and HLIL dumps.
Build recapture containers – Docker images defined in tools/containers/msvc-2010.Dockerfile and tools/containers/mingw-ld220.Dockerfile that reproduce the MSVC10 and MinGW 2.20 environments inferred from toolchain metadata.
Deterministic trace harness – Python utilities under tools/trace/ that ingest instrumented Quake Live runs, generate JSONL channel streams (SYS, RNG, ENT, META), and replay them to detect divergence.
Frame context shim – Native prototypes in src-re/prototypes/ that wrap CL_Frame/G_RunFrame logic with bindable contexts and structured logging to compare VM and native execution.
Handshake sequence – The client/server timeline documented in Network Handshake Reconstruction covering getchallenge → connectResponse and subsequent netchan setup using headers defined in src/code/qcommon/net_chan.c.
HLIL transcript – Decompiled text exports (for example the _hlil_part*.txt files referenced in Asset map gaps) catalogued under artifacts/ and used to trace asset references.
Behaviour diff ledger – The comparison log in Behaviour Diff Ledger plus underlying harness tools/analysis/behaviour_diff.py that verifies parity between QVM and DLL builds.
Reconstruction tracker – Status board maintained in Reconstruction Tracker to record clean-room source drops, shared header adoption, and pending reviewer sign-offs per subsystem.
Credential abstraction – Typed credential helpers in src/common/auth_credentials.h and src/common/auth_credentials.c that parse, normalise, and dispatch Steam, standalone, and legacy CD-key payloads documented in Online Authentication Lifecycle.
Platform service table – Capability descriptor exposed by src/common/platform/platform_services.c that reports active authentication, matchmaking, workshop, overlay, and statistics providers derived from platform_config.h.
Open Steam Adapter – The fallback authentication backend implemented in src/common/platform/backends/platform_backend_open_steam.c and described in Steam Platform Abstraction Plan to mirror Steamworks flows with open transports.
Auth flow trace – Scripted lifecycle capture driven by tools/integration/auth_flow_trace.py and catalogued in Credential Validation Matrix to document Steam-only, open-only, and hybrid dispatch outcomes.
Hybrid fallback – Steam-first authentication path in src/code/client/ql_auth.c that automatically retries pending Steam tickets against the open adapter, emitting the “Hybrid fallback accepted credential” log noted in Credential Validation Matrix.
Review cadence and ownership
| Subsystem | Owner | Artefacts to review | Cadence | Next session |
|---|---|---|---|---|
| Gameplay reconstruction | Gameplay systems reviewer | src-re/clean/gameplay/frame.c, Gameplay Loop Validation Notes, native shim logs | Monthly | First Tuesday each month |
| Client runtime | Client runtime reviewer | src-re/clean/client/frame.c, Native Prototype Shim Notes, trace captures | Monthly | Second Tuesday each month |
| Networking protocol | Networking protocol reviewer | src-re/clean/net/handshake.c, Network Handshake Reconstruction, Behaviour Diff Ledger | Bi-weekly | Next Thursday following release drop |
| Toolchain recapture | Build infrastructure reviewer | tools/containers/msvc-2010.Dockerfile, tools/containers/mingw-ld220.Dockerfile, Quake Live Build Recapture | Quarterly | First week of each quarter |
| Platform services | Platform integration reviewer | src/common/platform/, Steam Platform Abstraction Plan, Credential Validation Matrix, tests/test_platform_services.py, tools/integration/auth_flow_trace.py | Bi-weekly | Friday following QA matrix refresh |
Schedule review invites on the stated cadence and capture outcomes in the corresponding stage documents. If scope or artefacts shift, update this handbook alongside the source document to keep the index authoritative.