vkQuake2: the original Quake 2 source with a Vulkan renderer

Vanilla as the goal, with a documented list of exceptions

vkQuake2 is the official Quake 2 code v3.21 with Vulkan support and mission packs included, and the stated goal is to maintain as much compatibility as possible with the original game, described as a pure, vanilla Quake 2 experience as it was known in 1997.

What makes this project interesting is that the differences from vanilla are enumerated rather than left to be discovered. The list is short and each entry is a decision rather than an accident.

World colours have been slightly upgraded, and the game's original darker look can be toggled back with the `vk_postprocess` console command. 64-bit support, additional screen resolutions and DPI awareness have been added. An underwater vision warp effect similar to the software renderer has been implemented and enabled by default, and the Vulkan renderer fixes the broken warp texture effect on water, lava and slime that the OpenGL version showed. Antialiasing and sample shading are now natively supported, an anisotropic filtering toggle has been added, and players can change texture filtering modes from within the video menu.

Mouse acceleration has been disabled, console contents can be scrolled with the mouse wheel, and the HUD, menus and console text scale on higher resolutions, overridable with the `hudscale` console command. Viewmodel weapons are no longer hidden when the field of view exceeds 90.

There is also one gameplay change, and it is a backport rather than a new feature: the `aimfix` console command, backported from Berserker@Quake2, and a Nightmare and Hard+ skill added to the game menu.

A more detailed account of the design thinking is in the author's blog post about porting Quake 2 to Vulkan.

No external SDL-like library, and what that costs

The build philosophy is stated plainly, and it is a deliberate constraint rather than an accident of not having gotten around to it.

For extra challenge the author decided to base vkQuake2 on the original id Software code. Because of this, there are no dependencies on external SDL-like libraries and the entire project is mostly self-contained.

The word mostly is doing some work there, and the project is honest about the consequence in the next sentence: this also implies that some of the original bugs could be present. That is the trade of a self-contained port. You avoid the dependency surface of a windowing and input library, but you inherit whatever the original code did badly, and with no upstream to fix it, the fixes are yours to make.

The repository structure shows how much of the original tree is still there. The top level carries the game modules as directories, with client/, game/, server/ and qcommon/ as the engine, and then the mission packs as separate directories: ctf/ for Capture the Flag, rogue/, xatrix/ and zaero/. The renderer directories are ref_gl/ for the OpenGL renderer, ref_soft/ for the software renderer and ref_vk/ for the Vulkan one, and there is a null/ directory. There is also a smd/ directory for the model format, a shaders/ directory with shaders.bat and shaders.sh to compile them, and the client/ directory holds the game client.

The release history confirms the slow cadence. The most recent release is 1.5.10 from 2026-08-26, before that 1.5.9 from 2023-07-08 and 1.5.8 from 2021-07-06. So this is a project that ships when something meaningful changes, which fits a compatibility-focused port.

The software renderer was replaced wholesale

One change in the list is bigger than the rest, and it deserves its own look.

The software renderer has been completely replaced with KolorSoft 1.1, the colored refsoft fork. The two effects of that are named: it adds colored lighting and it fixes severe instabilities of the original implementation.

A software renderer matters for two audiences. For someone running the game on a machine with no usable GPU driver, it is the only path to playing. And a software renderer is the fallback path when no Vulkan-capable driver is available.

The instability point is worth taking seriously. Severe instabilities in a software renderer show up as crashes, corrupted frames or hangs, and in a project that is otherwise a careful port, replacing the renderer rather than patching it was a reasonable call. The cost is that the software path is now a fork of someone else's fork, maintained by a different author, with its own release cadence.

The other renderer-level change worth naming is that triangle fans have been replaced with indexed triangle lists due to Metal and MoltenVK limitations. That is a portability change with a performance implication, because indexed lists are what modern GPUs actually want, and the OpenGL renderer in the same tree still gets to use what it likes.

Linux builds, and why only the Vulkan renderer exists there

The Linux instructions start with an apology, and it is about the original code rather than the port.

The Linux code for Quake 2 has not aged well, and for that reason only the Vulkan renderer is available for use on Linux at this time. So a Linux user gets the Vulkan renderer and nothing else, which is a real limitation compared with the Windows build that carries the OpenGL, software and Vulkan renderers.

The build assumes Ubuntu. The dependency list is a single apt line:

sudo apt install make gcc g++ mesa-common-dev libglu1-mesa-dev libxxf86dga-dev libxxf86vm-dev libasound2-dev libx11-dev libxcb1-dev libxext-dev

The X11 and XCB development packages, the Mesa GLU package, the Xxf86dga and Xxf86vm packages and the ALSA development package are all in that list, and the presence of libasound2-dev is the visible sign of the other change on the list: on Linux, sound is now handled by ALSA instead of OSS.

Then the Vulkan SDK has to be installed, and the documentation points at the LunarG Ubuntu Packages as the path with no additional steps. For a manual installation it gives the environment variables to add to your shell configuration:

export VULKAN_SDK=/home/user/VulkanSDK/1.4.350.0/x86_64
export PATH=$VULKAN_SDK/bin:$PATH
export LD_LIBRARY_PATH=$VULKAN_SDK/lib:$LD_LIBRARY_PATH
export VK_LAYER_PATH=$VULKAN_SDK/etc/explicit_layer.d

You also have to check that your graphics drivers support Vulkan, by running vulkaninfo, and if they do not, the mesa-vulkan-drivers package provides them. The build itself is a make in the linux directory, with a release and a debug variant, and the binaries land in linux/releasex64 and linux/debugx64.

macOS, MoltenVK, and the loader rather than the framework

The macOS build has a detail that tells you how the author thinks about debugging, and it is the opposite of the usual macOS port shortcut.

This project uses the Vulkan loader bundled with the SDK, rather than directly linking against MoltenVK.framework. The reason given is that this is done so that validation layers are available for debugging.

That is a real trade. Linking MoltenVK directly is simpler and is what most ports do, but then the validation layers are unavailable, and validation layers are the tool that catches out-of-bounds writes, missing barriers and invalid API use. Given that a Vulkan port of twenty-nine-year-old code is a prime candidate for those mistakes, the author chose the noisier path on purpose.

The build instructions say to install the latest Vulkan SDK, install XCode 10.1 or later and add the VULKAN_SDK environment variable under Locations and Custom Paths, pointing it at the downloaded SDK. Then you open macos/vkQuake2.xcworkspace and it builds without further steps. A command line alternative is also given, with its own environment variables:

export VULKAN_SDK=/home/user/VulkanSDK/1.4.350.1
export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json
export VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d

The VK_ICD_FILENAMES pointing at the MoltenVK ICD JSON is the piece that tells the Vulkan loader which driver to use on Apple hardware.

The make targets differ between the two routes. make release-xcode and make debug-xcode put the output in macos/vkQuake2, while make release and make debug, for the Command Line Developer Tools route, put it in macos/release and macos/debug. The builds have been tested on macOS 10.14.2.

Windows is the simplest case by comparison: install the Vulkan SDK, install Visual Studio Community 2022 with the Windows SDK and C++ MFC, open quake2.sln, pick x86 or x64 and it builds. The presence of CI badges for Linux, macOS and Windows shows all three are built automatically.

The audio changes and the mission pack layout

The audio work is a bigger change than the list makes it look, and it is where a modern user will notice the difference most.

Support for OGG, FLAC, MP3 and WAV music has been added in addition to standard CD audio, and a music volume slider has been added for those formats, with CD music still playing at full volume as originally intended.

The mission pack directories are a good structural guide to the game's content. ctf/, rogue/, xatrix/ and zaero/ sit alongside the engine directories, and the project ships Quake 2 with its mission packs included.

Those directories are also where the engine's data-driven content lives. The game module in game/ is the mission pack code, and the ctf/ directory has its own game code, so a mission pack in Quake 2 is a full module with its own entities, rules and maps rather than a set of assets.

On the FreeBSD side the instructions are the shortest, since the package manager handles the Vulkan pieces:

pkg install vulkan-tools vulkan-validation-layers

and then the build is the same make release or make debug in the linux directory, since the FreeBSD build reuses it. Raspberry Pi 4 is supported as well, with a note crediting Igalia and their V3DV driver.

Editorial conclusion

vkQuake2 is a good pick for someone who wants the 1997 Quake 2 look on a modern Vulkan stack, or a Vulkan reference implementation with a real game attached, because the project keeps the original id Software code as its base rather than a reimplementation, and the mission packs are included; it is the wrong pick if you need a maintained engine with an active modding community or a renderer maintained daily, since the tagged release line is slow and some of the original bugs are knowingly carried over, and before you build you should check whether your distribution still ships the X11 and ALSA development packages the Linux build expects.

Frequently asked questions

Official sources

1. Issues
2. kondrak/vkQuake2 on GitHub
3. License: GPL-2.0
4. README
5. Releases