{"id":13423418,"url":"https://github.com/kondrak/vkQuake2","last_synced_at":"2025-03-15T17:31:45.378Z","repository":{"id":37390635,"uuid":"149264967","full_name":"kondrak/vkQuake2","owner":"kondrak","description":"id Software's Quake 2 v3.21 with mission packs and Vulkan support (Windows, Linux, macOS, FreeBSD, Raspberry Pi 4)","archived":false,"fork":false,"pushed_at":"2025-01-04T22:48:23.000Z","size":6555,"stargazers_count":931,"open_issues_count":1,"forks_count":91,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-10T00:24:05.293Z","etag":null,"topics":["3d-graphics","freebsd","gpu","hardware-acceleration","linux","macos","moltenvk","quake","quake2","vkquake","vkquake2","vkquake3","vulkan","vulkan-api","vulkan-game-engine","vulkan-renderer"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kondrak.png","metadata":{"files":{"readme":"README.md","changelog":"changes.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-18T09:46:00.000Z","updated_at":"2025-03-06T01:20:11.000Z","dependencies_parsed_at":"2023-02-16T04:01:09.323Z","dependency_job_id":"1663fa9a-6b7f-40cd-ad88-deb11aa9e425","html_url":"https://github.com/kondrak/vkQuake2","commit_stats":{"total_commits":891,"total_committers":16,"mean_commits":55.6875,"dds":"0.026936026936026924","last_synced_commit":"d7762ebac82fcc242c177ec5deac75d8f7d4ba20"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kondrak%2FvkQuake2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kondrak%2FvkQuake2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kondrak%2FvkQuake2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kondrak%2FvkQuake2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kondrak","download_url":"https://codeload.github.com/kondrak/vkQuake2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243766849,"owners_count":20344824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-graphics","freebsd","gpu","hardware-acceleration","linux","macos","moltenvk","quake","quake2","vkquake","vkquake2","vkquake3","vulkan","vulkan-api","vulkan-game-engine","vulkan-renderer"],"created_at":"2024-07-31T00:00:34.127Z","updated_at":"2025-03-15T17:31:43.847Z","avatar_url":"https://github.com/kondrak.png","language":"C","funding_links":[],"categories":["C","Apps"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"vkQuake2.png\"\u003e\u003c/p\u003e\n\n### Build status\n[![Linux](https://github.com/kondrak/vkQuake2/actions/workflows/linux.yml/badge.svg)](https://github.com/kondrak/vkQuake2/actions/workflows/linux.yml)\n[![MacOS](https://github.com/kondrak/vkQuake2/actions/workflows/macos.yml/badge.svg)](https://github.com/kondrak/vkQuake2/actions/workflows/macos.yml)\n[![Windows](https://github.com/kondrak/vkQuake2/actions/workflows/windows.yml/badge.svg)](https://github.com/kondrak/vkQuake2/actions/workflows/windows.yml)\n\nOverview\n===\nThis is the official Quake 2 code v3.21 with Vulkan support and mission packs included. The goal of this project is to maintain as much compatibility as possible with the original game - just pure, vanilla Quake 2 experience as we knew it back in 1997. There are, however, a few notable differences that made the cut for various reasons:\n\n- world colors have been slightly upgraded - the game's original, darker look can be toggled with the `vk_postprocess` console command\n- 64-bit support, additional screen resolutions and DPI awareness have been added\n- underwater vision warp effect similar to software renderer has been implemented and enabled by default\n- antialiasing and sample shading is now natively supported\n- anisotropic filtering toggle has been added\n- players can now change texture filtering modes from within the video menu\n- mouse acceleration has been disabled\n- console contents can be scrolled with a mouse wheel\n- HUD elements, menus and console text are now scaled accordingly on higher screen resolutions (can be overridden with the `hudscale` console command)\n- viewmodel weapons are no longer hidden when FOV \u003e 90\n- Vulkan renderer fixes broken warp texture effect (water, lava, slime) seen in OpenGL\n- software renderer has been completely replaced with [KolorSoft 1.1](https://github.com/qbism/Quake2-colored-refsoft) - this adds colored lighting and fixes severe instabilities of the original implementation\n- triangle fans have been replaced with indexed triangle lists due to Metal/MoltenVK limitations\n- on Linux, sound is now handled by ALSA instead of OSS\n- support for OGG/FLAC/MP3/WAV music has been added in addition to standard CD audio\n- music volume slider has been added (OGG/FLAC/MP3/WAV only, CD music still plays at full volume as originally intended)\n- game menus have been slightly improved\n- added Nightmare/Hard+ skill to the game menu\n- added the `aimfix` console command, backported from Berserker@Quake2\n\nA more detailed description of the thought process behind this project can be found in my [blog post](https://kondrak.github.io/posts/2020-09-20-porting-quake2-to-vulkan/), where I explain the overall design, how I attacked some of the problems and also how things developed after the initial release.\n\nBuilding\n===\nFor extra challenge I 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. This also implies that some of the original bugs could be present.\n\n## Windows\n- download and install the latest [Vulkan SDK](https://vulkan.lunarg.com/)\n- install [Visual Studio Community 2022](https://www.visualstudio.com/products/free-developer-offers-vs) with the latest Windows SDK and C++ MFC for build tools\n- open `quake2.sln` and choose the target architecture (x86/x64) - it should build without any additional steps\n\n## Linux\nUnfortunately, Linux code for Quake 2 has not aged well and for that reason only the Vulkan renderer is available for use at this time. Build steps assume that Ubuntu is the target distribution:\n- install required dependencies:\n```\nsudo apt install make gcc g++ mesa-common-dev libglu1-mesa-dev libxxf86dga-dev libxxf86vm-dev libasound2-dev libx11-dev libxcb1-dev\n```\n- Install the latest [Vulkan SDK](https://vulkan.lunarg.com/) - the easiest way is to use [LunarG Ubuntu Packages](https://vulkan.lunarg.com/sdk/home#linux) - just follow the instructions and there will be no additional steps required. If you decide for a manual installation, make sure that proper environment variables are set afterwards by adding the following section to your `.bashrc` file (replace SDK version and location with the ones corresponding to your system):\n```\nexport VULKAN_SDK=/home/user/VulkanSDK/1.3.224.1/x86_64\nexport PATH=$VULKAN_SDK/bin:$PATH\nexport LD_LIBRARY_PATH=$VULKAN_SDK/lib:$LD_LIBRARY_PATH\nexport VK_LAYER_PATH=$VULKAN_SDK/etc/explicit_layer.d\n```\n- make sure your graphics drivers support Vulkan (run `vulkaninfo` to verify) - if not, you can get them with:\n```\nsudo apt install mesa-vulkan-drivers\n```\n- enter the `linux` directory and type `make release` or `make debug` depending on which variant you want to build - output binaries will be placed in `linux/releasex64` and `linux/debugx64` subdirectories respectively\n\n## MacOS\n- download and extract the latest [Vulkan SDK](https://vulkan.lunarg.com/)\n- install XCode 10.1 (or later) and add the `VULKAN_SDK` environment variable to Locations/Custom Paths - make it point to the downloaded SDK\n- open `macos/vkQuake2.xcworkspace` - it should build without any additional steps\n- alternatively, you can compile the game from the command line - modify your `.bash_profile` and add the following entries (replace SDK version and location with the ones corresponding to your system):\n```\nexport VULKAN_SDK=/home/user/VulkanSDK/1.3.224.1\nexport VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json\nexport VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d\n```\n- enter the `macos` directory and run `make release-xcode` or `make debug-xcode` depending on which variant you want to build - output binaries will be placed in `macos/vkQuake2` subdirectory\n- it is also possible to build the game with Command Line Developer Tools if you have them installed: enter the `macos` directory and run `make release` or `make debug` - output binaries will be placed in `macos/release` and `macos/debug` subdirectories respectively\n\nThis project uses the Vulkan loader bundled with the SDK, rather than directly linking against `MoltenVK.framework`. This is done so that validation layers are available for debugging. Builds have been tested using MacOS 10.14.2.\n\n## FreeBSD\n- install required Vulkan packages:\n```\npkg install vulkan-tools vulkan-validation-layers\n```\n- make sure your graphics drivers support Vulkan (run `vulkaninfo` to verify) - if not, you should either update them or find a package that is best suited for your hardware configuration\n- enter the `linux` directory and type `make release` or `make debug` depending on which variant you want to build - output binaries will be placed in `linux/releasex64` and `linux/debugx64` subdirectories respectively\n\n## Raspberry Pi 4\nThanks to the effort of [Igalia](https://www.igalia.com/) and their [V3DV Driver](https://blogs.igalia.com/itoral/2020/07/23/v3dv_vulkan_driver_update/), it is possible to compile and run vkQuake2 on Raspberry Pi 4. Same build instructions as for Linux apply.\n\nRunning\n===\n## Windows\nThe Visual Studio C++ Redistributable is required to run the application: [32-bit](https://aka.ms/vs/16/release/vc_redist.x86.exe) or [64-bit](https://aka.ms/vs/16/release/vc_redist.x64.exe) depending on the chosen architecture. These are provided automatically if you have Visual Studio installed.\n\n## All platforms\nThe [release package](https://github.com/kondrak/vkQuake2/releases) comes only with the Quake 2 Demo content to showcase Vulkan functionality. For full experience, copy retail `.pak`, model and video files into the `baseq2` directory and run the executable. For mission packs, copy necessary data to `rogue` (\"Ground Zero\"), `xatrix` (\"The Reckoning\"), `zaero` (\"Quake II: Zaero\") and `smd` (\"Slight Mechanical Destruction\") directories respectively. You can then start the game with either `./quake2 +set game rogue`, `./quake2 +set game xatrix`, `./quake2 +set game zaero` or `./quake2 +set game smd`.\n\n## Music\nThis project uses [Miniaudio](https://github.com/dr-soft/miniaudio) for music playback if the original game CD is not available. For standard Quake 2, copy all tracks into the `baseq2/music` directory following the `trackXX.[ogg,flac,mp3,wav]` naming scheme (so track02.ogg, track03.ogg... for OGG files etc.). For \"Ground Zero\" and \"The Reckoning\", copy the tracks to `rogue/music` and `xatrix/music` directories respectively. For additional control over the playback, use the `miniaudio [on,off,play [X],loop [X],stop,pause,resume,info]` console command.\n\nConsole commands\n===\n\nThe following commands are available when using the Vulkan renderer:\n\n| Command                 | Action                                                  |\n|-------------------------|:--------------------------------------------------------|\n| `vk_validation`         | Toggle validation layers:\u003cbr\u003e`0` - disabled (default in Release)\u003cbr\u003e `1` - only errors and warnings\u003cbr\u003e`2` - full validation (default in Debug)\u003cbr\u003e`3` - enables `VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT` |\n| `vk_strings`            | Print some basic Vulkan/GPU information.                                    |\n| `vk_mem`                | Print dynamic vertex/index/uniform/triangle fan buffer memory and descriptor set usage statistics.          |\n| `vk_device`             | Specify index of the preferred Vulkan device on systems with multiple GPUs:\u003cbr\u003e`-1` - prefer first DISCRETE_GPU (default)\u003cbr\u003e`0..n` - use device #n (full list of devices is returned by `vk_strings` command) |\n| `vk_msaa`               | Toggle MSAA ([multisampling](https://en.wikipedia.org/wiki/Multisample_anti-aliasing)):\u003cbr\u003e`0` - off (default)\u003cbr\u003e`1` - MSAAx2\u003cbr\u003e`2` - MSAAx4\u003cbr\u003e`3` - MSAAx8\u003cbr\u003e`4` - MSAAx16 |\n| `vk_sampleshading`      | Toggle sample shading ([supersampling](https://en.wikipedia.org/wiki/Supersampling)) for MSAA. (default: `0`) |\n| `vk_mode`               | Vulkan video mode (default: `11`). Setting this to `-1` uses a custom screen resolution defined by `r_customwidth` (default: `1024`) and `r_customheight` (default: `768`) console variables. |\n| `vk_flashblend`         | Toggle the blending of lights onto the environment. (default: `0`)            |\n| `vk_polyblend`          | Blend fullscreen effects: blood, powerups etc. (default: `1`)                 |\n| `vk_skymip`             | Toggle the usage of mipmap information for the sky graphics. (default: `0`)   |\n| `vk_finish`             | Inserts a `vkDeviceWaitIdle()` call on frame render start (default: `0`).\u003cbr\u003eDon't use this, it's there just for the sake of having a `gl_finish` equivalent! |\n| `vk_point_particles`    | Toggle between using POINT_LIST and textured triangles for particle rendering. (default: `1`) |\n| `vk_particle_size`      | Rendered particle size. (default: `40`)                    |\n| `vk_particle_att_a`     | Intensity of the particle A attribute. (default: `0.01`)   |\n| `vk_particle_att_b`     | Intensity of the particle B attribute. (default: `0`)      |\n| `vk_particle_att_c`     | Intensity of the particle C attribute. (default: `0.01`)   |\n| `vk_particle_min_size`  | The minimum size of a rendered particle. (default: `2`)    |\n| `vk_particle_max_size`  | The maximum size of a rendered particle. (default: `40`)   |\n| `vk_lockpvs`            | Lock current PVS table. (default: `0`)                     |\n| `vk_clear`              | Clear the color buffer each frame. (default: `0`)          |\n| `vk_modulate`           | Texture brightness modifier. (default: `1`)                |\n| `vk_shadows`            | Draw experimental entity shadows. (default: `0`)           |\n| `vk_picmip`             | Shrink factor for the textures. (default: `0`)             |\n| `vk_round_down`         | Toggle the rounding of texture sizes. (default: `1`)       |\n| `vk_log`                | Log frame validation data to file. (default: `0`)          |\n| `vk_dynamic`            | Use dynamic lighting. (default: `1`)                       |\n| `vk_showtris`           | Display mesh triangles. (default: `0`)                     |\n| `vk_lightmap`           | Display lightmaps. (default: `0`)                          |\n| `vk_aniso`              | Toggle anisotropic filtering. (default: `1`)               |\n| `vk_vsync`              | Toggle vertical sync. (default: `0`)                       |\n| `vk_postprocess`        | Toggle additional color/gamma correction. (default: `1`)   |\n| `vk_underwater`         | Toggle player vision warp when underwater. (default: `1`)  |\n| `vk_restart`            | Recreate entire Vulkan subsystem.                          |\n| `vk_mip_nearfilter`     | Use nearest-neighbor filtering for mipmaps. (default: `0`) |\n| `vk_texturemode`        | Change current texture filtering mode:\u003cbr\u003e`VK_NEAREST` - nearest-neighbor interpolation, no mipmaps\u003cbr\u003e`VK_LINEAR` - linear interpolation, no mipmaps\u003cbr\u003e`VK_MIPMAP_NEAREST` - nearest-neighbor interpolation with mipmaps\u003cbr\u003e`VK_MIPMAP_LINEAR` - linear interpolation with mipmaps (default) |\n| `vk_lmaptexturemode`    | Same as `vk_texturemode` but applied to lightmap textures. |\n| `vk_fullscreen_exclusive` | Windows only: toggle usage of exclusive fullscreen mode (default: `1`). Note that when this option is enabled, there is no guarantee that exclusive fullscreen can be acquired on your system. |\n\nAcknowledgements\n===\n- Sascha Willems for his [Vulkan Samples](https://github.com/SaschaWillems/Vulkan)\n- Adam Sawicki for [Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator) and tips on how to use it as efficiently as possible\n- Axel Gneiting for [vkQuake](https://github.com/Novum/vkQuake) which was a great inspiration and a rich source of knowledge\n- LunarG team and the Khronos Group for their invaluable help and resources\n- Dorian Apanel and the Intel team for technical support, inspiring email discussions and blazing-fast reaction to driver bug reports!\n\nSee also\n===\n- [SauRay](https://github.com/HonestGamingInc/vkQuake2_SauRay) - a server-side anti-wallhack solution using hardware accelerated ray-tracing, using vkQuake2 as a PoC\n- [yquake2/ref_vk](https://github.com/yquake2/ref_vk) - Vulkan Renderer Library for Yamagi Quake 2 based on vkQuake2\n- [vkQuake2 Miniaudio](https://github.com/mackron/vkQuake2) - vkQuake2 fork with added spacialized audio using [Miniaudio](https://github.com/dr-soft/miniaudio) library\n\nKnown Issues\n===\n- some Intel GPUs may ignore texture filtering settings in video menu if anisotropic filtering is enabled - this is the result of anisotropic texture filtering being implementation-dependent\n- macOS using Vulkan SDK 1.2.162 or higher: the application may hang on some MacBooks if `vk_sampleshading` is enabled due to a potential bug in the Metal driver causing a deadlock during shader compilation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkondrak%2FvkQuake2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkondrak%2FvkQuake2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkondrak%2FvkQuake2/lists"}