Oblivion Reconstructed

An accurate reconstruction of the original Oblivion Quake II mod source code, bugs and all.

Project Goal  ·  Cross-Platform  ·  Installation  ·  Build From Source  ·  Repository Layout

---

Project Goal

Oblivion Reverse exists to recover the original Oblivion mod source code as faithfully as possible from the retail binaries, reverse-engineering artifacts, and reference data. The target is not a cleaned-up reinterpretation of Oblivion. The target is the original gameplay, original behaviors, and original quirks, reconstructed into a working source tree.

That means this repository prioritizes retail parity over modernization. When the retail mod had rough edges, timing oddities, or gameplay bugs, the reconstruction aims to preserve them unless there is direct evidence that the current code diverged from retail unintentionally.

At this point the project is in a well-developed state: the reconstruction work appears substantially in place from current reverse-engineering coverage and limited gameplay testing, while broader playthrough validation and edge-case confirmation remain ongoing.

What This Repository Contains

• The reconstructed Quake II game module source under src/game/ and shared support code under src/common/.
• Reverse-engineering notes, symbol maps, and parity evidence under docs/ and docs-dev/.
• Regression tests that lock recovered retail behavior under tests/.
• Packaging assets and runtime configuration, including pack/oblivion.cfg.

Platform Support

Cross-Platform And Cross-Arch Builds

The original retail release of Oblivion shipped for Windows only. This reconstruction project extends that recovered codebase to documented build and runtime support on Windows, Linux, and macOS, with architecture-specific binaries published per platform.

The release automation packages platform-and-architecture-specific binaries so an existing Oblivion install can be updated for cross-platform use without guessing which module belongs to which target.

Platform	Produced Module	Notes
Windows	gamex86.dll / gamex86_64.dll	Nightly archives publish both Win32 and x64 Windows binaries with explicit DLL names.
Linux	gamei386.so / gamex86_64.so	Nightly archives publish both Linux x86 and x64 binaries with explicit architecture suffixes.
macOS	gamearm64.dylib / gamex86_64.dylib	Nightly archives publish Apple Silicon and Intel macOS binaries with explicit architecture suffixes.

Installation

Install From A Release Archive

1. Install the original Oblivion mod first from the original Oblivion release page.
2. Locate the Quake II installation that already contains the installed oblivion/ game directory.
3. Download the matching archive for your platform from this repository's releases.
4. Extract the release archive directly into that Quake II installation so its bundled oblivion/ folder merges with the existing one.
5. Allow the extraction to replace the existing game binary and oblivion.cfg.
6. Launch Quake II with +set game oblivion or point your source port at the installed Oblivion game directory.

Every release archive now includes:

• the platform game module binary
• oblivion.cfg
• a standalone README.html release document

These release files are not a standalone Oblivion install. They are drop-in replacements for the binary and configuration inside an existing retail Oblivion setup.

In other words: retail Oblivion remains the required Windows-origin mod install, while this project supplies replacement binaries that let that codebase run across platforms.

Expected Layout After Extraction

oblivion/
  gamex86.dll or gamex86_64.dll
  gamei386.so or gamex86_64.so
  gamearm64.dylib or gamex86_64.dylib
  oblivion.cfg
  README.html

Build From Source

Detailed build notes are maintained in docs/building.md. The short version is below.

Prerequisites

• A C11-capable compiler.
• CMake 3.16 or newer.
• A Quake II installation to run the produced module.
• Python if you want to run the regression suite.

Linux / macOS

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

The resulting module will be placed in build/ as game.so on Linux or game.dylib on macOS.

Architecture-specific output names are used for cross-platform builds: Linux emits gamei386.so or gamex86_64.so, and macOS emits gamearm64.dylib or gamex86_64.dylib.

To force a 32-bit Linux build on an x64 host, add -DCMAKE_C_FLAGS=-m32 -DCMAKE_SHARED_LINKER_FLAGS=-m32 when configuring and make sure your toolchain has multilib support installed.

To force an x64 macOS build on Apple Silicon, add -DCMAKE_OSX_ARCHITECTURES=x86_64 when configuring.

Windows

cmake -S . -B build -A Win32 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

The Win32 module will be emitted as build/Release/gamex86.dll for Visual Studio generators, or build/gamex86.dll for single-config generators.

To produce the x64 Windows build, configure with -A x64; it will emit gamex86_64.dll by default. Set -DOBLIVION_WINDOWS_OUTPUT_NAME=<name> only if your target source port expects a different DLL name.

Install A Local Build

1. Build the module for your platform.
2. Install the original Oblivion mod from the original release page if it is not already present.
3. Copy the produced binary into that existing Quake II oblivion/ game directory.
4. Copy pack/oblivion.cfg to replace the installed configuration if you want the repository's current default bindings and settings.
5. Launch Quake II with +set game oblivion.

Nightly Releases

Nightly release automation builds Linux, macOS, and Windows artifacts from the top-level semantic version stored in VERSION. Archive names include both platform and architecture, for example oblivion-windows-x64-v1.0.0-nightly.20260316.zip. Scheduled nightly tags use the format v<base-version>-nightly.YYYYMMDD. Manual workflow dispatches append a UTC time suffix such as v1.0.0-nightly.20260316.205724 so each dispatch creates a distinct release.

The current base version is 1.0.0, reflecting a mature reconstruction state rather than an early bootstrap snapshot.

Repository Layout

Path	Purpose
src/	Reconstructed game-module source code.
pack/	Runtime configuration and packaged game data.
docs/	User-facing notes and technical documentation.
docs-dev/	Reverse-engineering and parity mapping notes.
references/	Reference-only reverse-engineering exports and preserved source material.
tests/	Regression coverage for recovered retail behavior.

Credits And Attribution

The key creative credit remains with the original Oblivion release by Lethargy Software. This repository is a reconstruction effort focused on preservation, analysis, and faithful source recovery.

As tribute to the original release, the core Oblivion team credits are preserved here in a cleaner modern form.

Discipline	Original Oblivion Team
Programming	Mike "Gripp" Ruete; Tim "Argh" Wright
Level Design	Dan "Infliction" Haigh; Alex "MonkeyDonut" Gingell; Dan "Trebz" Nolan; Sean "Spider" Soucy
Artwork	John "MetalSlime" Fitzgibbons; Tyler "Witz" Wilson; Eli "Dunan" Karney; SmokyG
Models	Andrew "Betlog" Eglington; Matt Hasselman; John "Jonny" Gorden; Rorshach
Music	Carl "Dill" Bown
Website / Manual	Ryan "BabelFish" Freebern

Additional contributor credit remains warranted where reconstruction-era code, research, or testing remnants may still be present in the repository history and current tree.

• Konig Varorson for earlier monster recreation code that may have inadvertently helped guide parts of the reverse-engineering process. Repository: github.com/Konig-Varorson
• Nicco for testing support and feedback that remains directly relevant to the project.
• Shaun "Cyberslash" Wilson for QuakeActor Beta Source Code that may still have remnants reflected in misc_actor and therefore warrants acknowledgment.

License

This repository is distributed under the GNU General Public License v2. See LICENSE for details.