{"id":45625471,"url":"https://github.com/themuffinator/openq4","last_synced_at":"2026-04-16T01:01:18.399Z","repository":{"id":336946439,"uuid":"1149948783","full_name":"themuffinator/OpenQ4","owner":"themuffinator","description":"The definitive source-port and game binary replacement to run QUAKE 4 on modern systems.","archived":false,"fork":false,"pushed_at":"2026-04-10T07:57:42.000Z","size":508304,"stargazers_count":10,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-10T09:37:38.363Z","etag":null,"topics":["action-game","fps","fps-gaming","idtech","idtech4","quake","quake4","quake4doom","rbdoom3bfg","shooter-game","source-port"],"latest_commit_sha":null,"homepage":"https://www.darkmatter-quake.com","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/themuffinator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"themuffinator"}},"created_at":"2026-02-04T17:53:55.000Z","updated_at":"2026-04-10T06:17:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"01a0a9fa-7705-4c1d-9741-82f143f737aa","html_url":"https://github.com/themuffinator/OpenQ4","commit_stats":null,"previous_names":["themuffinator/openq4"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/themuffinator/OpenQ4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themuffinator%2FOpenQ4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themuffinator%2FOpenQ4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themuffinator%2FOpenQ4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themuffinator%2FOpenQ4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/themuffinator","download_url":"https://codeload.github.com/themuffinator/OpenQ4/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themuffinator%2FOpenQ4/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31866357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["action-game","fps","fps-gaming","idtech","idtech4","quake","quake4","quake4doom","rbdoom3bfg","shooter-game","source-port"],"created_at":"2026-02-23T20:02:04.163Z","updated_at":"2026-04-16T01:01:18.327Z","avatar_url":"https://github.com/themuffinator.png","language":"C++","funding_links":["https://github.com/sponsors/themuffinator"],"categories":[],"sub_categories":[],"readme":"\u003ca id=\"top\"\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/img/banner.png\" alt=\"OpenQ4 banner\"\u003e\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](https://github.com/themuffinator/OpenQ4)\n[![Architecture](https://img.shields.io/badge/arch-x64-orange.svg)](https://github.com/themuffinator/OpenQ4)\n[![Build System](https://img.shields.io/badge/build-Meson%20%2B%20Ninja-yellow.svg)](https://mesonbuild.com/)\n\n**Open-source Quake 4 engine and game-code replacement built for stock assets on modern systems**\n\n[Quick Start](#quick-start) | [Highlights](#highlights) | [Compatibility](#compatibility-and-scope) | [Building](BUILDING.md) | [Documentation](#documentation) | [Credits](#credits)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n**OpenQ4** is a complete open-source replacement for the Quake 4 engine and game binaries. The project keeps official Quake 4 asset compatibility as its guiding constraint while modernizing rendering, display handling, input, packaging, and the build pipeline for current hardware and operating systems.\n\nSingle-player and multiplayer live under one `openq4/` directory with `game-sp` and `game-mp`. SDK-derived game code is maintained in the companion [OpenQ4-GameLibs](https://github.com/themuffinator/OpenQ4-GameLibs) repository, while BSE is treated as first-party source under `src/bse/` and linked directly into the client executable.\n\n\u003e [!NOTE]\n\u003e OpenQ4 does not include Quake 4 assets. You need a legitimate copy of Quake 4 from Steam or GOG to play.\n\n\u003e [!NOTE]\n\u003e OpenQ4 uses its own engine and game modules. It does not target compatibility with the proprietary Quake 4 DLLs and is not a drop-in runtime for legacy mods.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/img/shot1.png\" alt=\"OpenQ4 gameplay screenshot showing stock Quake 4 assets running in OpenQ4\" width=\"92%\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003eOpenQ4 running against stock Quake 4 content.\u003c/sub\u003e\u003c/p\u003e\n\n---\n\n## Highlights\n\n### Engine and compatibility\n\n- Complete engine and game-code replacement for Quake 4\n- Unified `openq4/` game directory for both single-player and multiplayer\n- Startup auto-discovery for Steam and GOG installs\n- Official `q4base` PK4 validation enabled by default\n- In-tree BSE runtime integrated into `OpenQ4-client_\u003carch\u003e`\n- Canonical SDK-derived game-library source kept in [OpenQ4-GameLibs](https://github.com/themuffinator/OpenQ4-GameLibs)\n\n### Rendering and presentation\n\n- Multi-scale bloom with luminance-based extraction\n- FP16 HDR scene targets, filmic tone mapping, color controls, and log-average auto exposure\n- SSAO and optional CRT post-processing\n- Experimental shadow mapping for projected and point lights, projected-light CSM, alpha-tested transparency shadows, and optional translucent shadow accumulation\n- Screen-fraction scaling, supersample-style presets, MSAA, and SMAA\n\n### Modern usability\n\n- Automatic aspect-ratio, FOV, zoom, and view-weapon framing from live render size\n- Single-player weapon wheel currently under development, including slow-motion audio/presentation treatment on hold\n- Multi-monitor targeting plus borderless, desktop fullscreen, and exclusive fullscreen paths\n- Controller hotplug and analog input support\n- SDL3-first Linux runtime with an explicit `OpenQ4-steamdeck` launcher/profile for Steam Deck\n- Meson-based builds, `builddir/` for local artifacts, and `.install/` for staged runtime packages\n- Windows, Linux, and macOS targets with x64 as the current active baseline\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/img/shot2.png\" alt=\"OpenQ4 gameplay screenshot showing combat and bloom\" width=\"49%\"\u003e\n  \u003cimg src=\"assets/img/shot3.png\" alt=\"OpenQ4 gameplay screenshot showing environment lighting and shadow detail\" width=\"49%\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003eModern renderer upgrades layered onto the original game assets.\u003c/sub\u003e\u003c/p\u003e\n\n---\n\n## Quick Start\n\n1. Install **Quake 4** from [Steam](https://store.steampowered.com/app/2210/Quake_4/) or [GOG](https://www.gog.com/en/game/quake_4).\n2. Download the latest OpenQ4 package from the [Releases page](https://github.com/themuffinator/OpenQ4/releases).\n3. Extract the archive to a folder of your choice.\n4. Launch `OpenQ4-client_x64` (`OpenQ4-client_x64.exe` on Windows).\n5. On Steam Deck, launch `OpenQ4-steamdeck` instead of the generic client entrypoint.\n\nOpenQ4 will try to locate your Quake 4 install automatically. If detection fails, set `fs_basepath` manually or see [TECHNICAL.md](TECHNICAL.md#advanced-configuration).\n\n\u003e [!TIP]\n\u003e Windows release packages are intended to be self-contained.\n\n\u003e [!TIP]\n\u003e As of March 30, 2026, Linux packages default to the SDL3 backend. On Steam Deck and other Wayland sessions where both `WAYLAND_DISPLAY` and `DISPLAY` are present, `OpenQ4-steamdeck` prefers XWayland unless you already set `SDL_VIDEODRIVER` yourself.\n\n---\n\n## Compatibility and Scope\n\nOpenQ4 is developed against the shipped Quake 4 assets, not replacement repo-side content. Current compatibility work already covers several engine paths that stock content depends on:\n\n- BSE reconstruction and client-side effect execution\n- Effect-driven sound shader behavior\n- BSE screen and camera effect paths\n- Material and shader compatibility work needed to reduce custom override dependence\n- Modern display handling for widescreen, ultrawide, and multi-monitor setups\n- Official asset validation through `fs_validateOfficialPaks 1`\n\nProject scope is intentionally explicit:\n\n- `openq4/` remains the single game directory for SP and MP\n- BSE stays integrated in-tree under `src/bse/`\n- Dedicated server builds keep the disabled BSE manager path unless that changes by design\n- Canonical SDK/game-library edits belong in `../OpenQ4-GameLibs`, not a mirrored `src/game` tree\n- Compatibility with proprietary Quake 4 game DLLs is a non-goal\n\nGameplay parity work is still ongoing. For current follow-up items, see [TODO.md](TODO.md) and [docs-dev/release-completion.md](docs-dev/release-completion.md).\n\n---\n\n## Building from Source\n\nFull setup instructions live in [BUILDING.md](BUILDING.md). The short version:\n\n- Keep [OpenQ4-GameLibs](https://github.com/themuffinator/OpenQ4-GameLibs) checked out beside this repo at `../OpenQ4-GameLibs`\n- Use `builddir/` for local Meson builds\n- Use `.install/` as the staged runtime package root\n- On Windows, call `tools/build/meson_setup.ps1` instead of raw `meson` from an arbitrary shell\n- When staging `.install/`, use `meson install -C builddir --no-rebuild --skip-subprojects` or the wrapper equivalent\n\n```powershell\npowershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 setup --wipe builddir . --backend ninja --buildtype=debug --wrap-mode=forcefallback\npowershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 compile -C builddir\npowershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 install -C builddir --no-rebuild --skip-subprojects\n```\n\nSet `OPENQ4_BUILD_GAMELIBS=1` if you want the wrapper to trigger game-library builds during `compile`. For local runtime validation, launch from `.install/` so `fs_cdpath` points at the staged OpenQ4 overlay.\n\n---\n\n## Documentation\n\n- [BUILDING.md](BUILDING.md) - platform requirements and build workflow\n- [TECHNICAL.md](TECHNICAL.md) - advanced configuration, file layout, dependencies, and compatibility notes\n- [docs-user/display-settings.md](docs-user/display-settings.md) - display, fullscreen, and multi-monitor behavior\n- [docs-user/steam-deck.md](docs-user/steam-deck.md) - Steam Deck launcher, controls, and asset discovery notes\n- [docs-user/shadow-mapping.md](docs-user/shadow-mapping.md) - shadow-map settings, presets, and troubleshooting\n- [docs-user/multiplayer-networking.md](docs-user/multiplayer-networking.md) - multiplayer networking and lag compensation\n- [docs-dev/platform-support.md](docs-dev/platform-support.md) - platform roadmap and backend status\n- [docs-dev/official-pk4-checksums.md](docs-dev/official-pk4-checksums.md) - official asset validation reference\n- [docs-dev/input-key-matrix.md](docs-dev/input-key-matrix.md) - keyboard and controller input reference\n- [docs-dev/release-completion.md](docs-dev/release-completion.md) - current release checklist and open work\n- [TODO.md](TODO.md) - tracked issues and planned tasks\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/img/shot4.png\" alt=\"OpenQ4 gameplay screenshot showing atmospheric environment\" width=\"92%\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003eBuilt to preserve the original game feel on modern displays and GPUs.\u003c/sub\u003e\u003c/p\u003e\n\n---\n\n## Contributing\n\nOpenQ4 welcomes code, documentation, testing, and compatibility reports. Keep stock-asset compatibility in mind, prefer engine-side fixes over shipping replacement content, and update documentation when behavior or workflow changes.\n\n---\n\n## Credits\n\n### Project\n\n- **themuffinator** - OpenQ4 development and maintenance\n- **DarkMatter Productions** - project stewardship and website\n\n### Upstream and reference work\n\n- **Justin Marshall** - [Quake4Doom](https://github.com/jmarshall23/Quake4Doom) and initial BSE reverse engineering\n- **Robert Backebans** - renderer modernization reference work\n- **id Software** - idTech 4 engine and Quake 4\n- **Raven Software** - Quake 4 game development\n\n### Community and third-party libraries\n\n- **Map-Center community** - feedback and playtesting, especially Papaya, JohnnyBoy, and coffee009\n- **Sean Barrett** - [stb_vorbis](https://github.com/nothings/stb) audio codec\n- **GLEW Team** - Nigel Stewart, Milan Ikits, Marcelo E. Magallon, and Lev Povalahev\n- **OpenAL Soft contributors** - 3D audio implementation\n- **SDL contributors** - cross-platform framework\n- **SMAA authors** - Jorge Jimenez, Jose I. Echevarria, Belen Masia, Fernando Navarro, and Diego Gutierrez\n\n---\n\n## License\n\nOpenQ4 engine code is licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0). See [LICENSE](LICENSE) for the full text.\n\nThe game-library code in [OpenQ4-GameLibs](https://github.com/themuffinator/OpenQ4-GameLibs) is derived from the Quake 4 SDK and remains subject to id Software's SDK EULA. Quake 4 game assets remain the property of id Software and ZeniMax Media.\n\n---\n\n## Disclaimer\n\nOpenQ4 is an independent project and is not affiliated with, endorsed by, or sponsored by id Software, Raven Software, Bethesda, or ZeniMax Media. Quake 4 is a trademark of ZeniMax Media Inc.\n\nThe software is provided \"as is\" without warranty of any kind. OpenQ4 is experimental software under active development and requires a legitimate Quake 4 installation.\n\n---\n\n## Links\n\n[Website](https://www.darkmatter-quake.com) | [Repository](https://github.com/themuffinator/OpenQ4) | [Game Library](https://github.com/themuffinator/OpenQ4-GameLibs) | [Issue Tracker](https://github.com/themuffinator/OpenQ4/issues) | [Releases](https://github.com/themuffinator/OpenQ4/releases)\n\n[Back to Top](#top)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemuffinator%2Fopenq4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthemuffinator%2Fopenq4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemuffinator%2Fopenq4/lists"}