GitHub - themuffinator/OpenQ4: A complete Quake 4 engine/game binary replacement for modern PCs - stock-asset compatible and QoL focused.

About

The OpenQ4 Project is a complete replacement for the Quake 4 engine and game binaries. Built on the foundation of Quake4Doom, OpenQ4 is focused on making Quake 4 feel native on modern hardware without losing stock-asset compatibility. Current work already brings in bloom, HDR tone mapping, SSAO, automatic aspect-ratio handling, multi-monitor support, and an in-progress shadow-mapping path with CSM work underway, alongside broader platform and tooling modernization. While the project aims to be as open-source as possible, the BSE library will remain closed-source for legal reasons.

Versioning

OpenQ4 uses semantic base versions from meson.build and appends an explicit build track:

• stable: release builds such as X.Y.Z
• dev: default local builds such as X.Y.Z-dev+gabcdef12
• prerelease labels like nightly, beta, or rc: for example X.Y.Z-nightly.20260307.1+gabcdef12

Meson exposes this through -Dversion_track=<label> and -Dversion_iteration=<dot-separated-iteration>. Local builds default to dev; CI nightlies set version_track=nightly.

The base semantic version stays intentionally manual and must be bumped in meson.build when OpenQ4 moves to the next release line. Track labels, iterations, git metadata, and resource build numbers are generated automatically.

What You Need

To play OpenQ4, you need:

• A legitimate copy of Quake 4 (Steam or GOG version recommended)
• The latest OpenQ4 release (from this repository)
• A modern 64-bit operating system

_{OpenQ4 running with stock Quake 4 assets.}

Features

Core Features

• Full Game Support: Complete single-player campaign and multiplayer modes in one engine stack
• Unified Game Directory: Single openq4/ directory for both SP and MP game binaries
• Stock Asset Compatibility: Built to run against official Quake 4 assets instead of shipping replacement content
• Auto-Discovery and Validation: Smart Steam/GOG detection plus official asset verification

Rendering Upgrades

• Bloom: Tunable post-process bloom for stronger highlights and a more modern presentation
• HDR Tone Mapping: Filmic-style HDR tonemapping and color controls for exposure, contrast, saturation, and vibrance
• SSAO: Screen-space ambient occlusion for added depth and contact shadowing in the final frame
• CRT Emulation: Optional CRT post-process with scanlines, mask, curvature, and chromatic offset controls
• Shadow Mapping Pipeline: Experimental shadow-map support for projected and point lights, with cascaded shadow maps (CSM) actively under development
• Resolution Scaling and Supersample Controls: Screen-fraction rendering supports lower-resolution upscale modes and menu-exposed supersample-style presets for image-quality tuning
• Modern AA and Upscaling: MSAA, SMAA, and high-quality resolution-scaling paths for cleaner output across a wide range of hardware

Display and UX Improvements

• Automatic Aspect-Ratio Management: UI, FOV, zoom behavior, and view-weapon framing adapt from live render size instead of legacy manual aspect toggles
• Multi-Monitor and Multi-Screen Support: Target specific displays, auto-detect the active monitor, and keep window/UI behavior sane across modern desktop setups
• Modern Display Modes: Fullscreen, borderless windowed, exclusive fullscreen, and desktop-native fullscreen paths
• Controller Support: Full gamepad/joystick support with hotplug and analog controls
• Responsive UI: Interface scaling and layout behavior that hold up on 4:3, widescreen, ultrawide, and multi-screen environments

Platform and Engine Modernization

• SDL3 Backend: Modern cross-platform input, windowing, and display handling
• Modern System Compatibility: 64-bit-first runtime and build targets for current Windows, Linux, and macOS environments
• Audio: Support for WAV and Ogg Vorbis formats with OpenAL Soft
• C++23: Modern C++ standards for better performance and maintainability
• Meson Build System: Fast, reliable builds with dependency management
• Crash Diagnostics: Automatic crash dumps and logs for debugging
• OpenGL Renderer Modernization: Expanded renderer paths and post-processing while preserving classic Quake 4 behavior

_{Modern renderer upgrades and modern-system support while preserving classic Quake 4 gameplay.}

Quake 4 Compatibility Status

This status focuses on compatibility with official Quake 4 assets (q4base PK4s), not proprietary game DLL compatibility.

Compatible

• ✅ Basic Set of Effects (BSE) Reconstruction: Core BSE runtime behavior has been rebuilt and integrated so stock effects execute through the OpenQ4 engine/game pipeline.
• ✅ Sound Shaders: Effect-driven sound shader paths are restored, including effect sound capability checks and runtime playback behavior.
• ✅ Screen Effects: BSE-driven screen/camera effect paths used by stock content are operational in current OpenQ4 builds.
• ✅ Material Shaders: Material handling compatibility has been restored to remove startup reliance on custom repo-side q4base material overrides.
• ✅ Modern Display Handling: Automatic aspect-ratio/FOV behavior, multi-monitor targeting, and desktop-native fullscreen paths are integrated into the compatibility baseline for current systems.
• ✅ Stock-Asset Validation Path: Repeated validation loops with stock assets have been used to keep parser/runtime compatibility regressions visible and actionable.
• ✅ Door/Trigger Script Progression Stability (OpenD3 Parity): Right-associative script compiler pointer-temp handling now guards x64 storage width mismatches (4-byte object-ref temp vs 8-byte pointer temp) by allocating pointer-sized result defs when required, preventing interpreter write corruption in affected trigger/door event chains.

Unresolved

• ❌ Ongoing Compatibility Sweep: Additional map-by-map gameplay validation remains in progress to catch residual non-script regressions.

Current known compatibility regressions and follow-up work are tracked in TODO.md and docs-dev/release-completion.md.

Quick Start

Prerequisites

• Quake 4 installed (Steam or GOG)
• Windows: Visual Studio 2026+ (or MSVC 19.46+)
• Linux: GCC 13+ or Clang 17+
• macOS: Xcode 16+ (Clang 17+)
• Build Tools: Meson and Ninja

Installation

1. Clone the repository

   git clone https://github.com/themuffinator/OpenQ4.git
   cd OpenQ4

2. Build the engine

   Windows (PowerShell)

   # Setup the build
   powershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 setup --wipe builddir . --backend ninja --buildtype=debug --wrap-mode=forcefallback
   
   # Compile
   powershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 compile -C builddir
   
   # Install (optional - creates distributable package)
   powershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 install -C builddir --no-rebuild --skip-subprojects

   Linux / macOS (Terminal)

   # Setup the build
   bash tools/build/meson_setup.sh setup --wipe builddir . --backend ninja --buildtype=debug --wrap-mode=forcefallback
   
   # Compile
   bash tools/build/meson_setup.sh compile -C builddir
   
   # Install (optional - creates distributable package)
   bash tools/build/meson_setup.sh install -C builddir --no-rebuild --skip-subprojects

3. Run the game

   Windows

   builddir/OpenQ4-client_x64.exe

   Linux / macOS

   builddir/OpenQ4-client_x64

The engine will automatically find your Quake 4 installation and validate the game files.

Building from Source

-Dbuild_engine=true|false     # Build OpenQ4-client_<arch> and OpenQ4-ded_<arch> executables
-Dbuild_games=true|false      # Build game modules
-Dbuild_game_sp=true|false    # Build single-player module
-Dbuild_game_mp=true|false    # Build multiplayer module
-Denforce_msvc_2026=true      # Enforce MSVC 2026+ requirement (Windows only, optional)

# Configure
powershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 setup builddir . --backend ninja --buildtype=release

# Build
powershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 compile -C builddir

# Create distributable package
powershell -ExecutionPolicy Bypass -File tools/build/meson_setup.ps1 install -C builddir --no-rebuild --skip-subprojects

meson setup builddir . --backend ninja --buildtype=release
meson compile -C builddir

# Configure
bash tools/build/meson_setup.sh setup builddir . --backend ninja --buildtype=release

# Build
bash tools/build/meson_setup.sh compile -C builddir

# Create distributable package
bash tools/build/meson_setup.sh install -C builddir --no-rebuild --skip-subprojects

Game Directory Structure

OpenQ4 uses a unified game directory approach:

OpenQ4/
├── OpenQ4-client_x64      # Main executable (.exe on Windows)
├── OpenQ4-ded_x64         # Dedicated server (.exe on Windows)
├── OpenQ4-BSE_x64         # BSE runtime module (.dll / .so / .dylib)
└── openq4/                # Unified game directory
    ├── game-sp_x64        # Single-player module (.dll / .so / .dylib)
    └── game-mp_x64        # Multiplayer module (.dll / .so / .dylib)

The engine automatically selects the correct module based on game mode:

• Single-player: Loads game-sp_<arch> (for example game-sp_x64)
• Multiplayer: Loads game-mp_<arch> (for example game-mp_x64)
• BSE runtime: Loads OpenQ4-BSE_<arch> from the executable directory when available
• Windows BSE compatibility: OpenQ4-BSE_<arch> must be built with the same MSVC CRT flavor as the engine build (/MDd debug, /MD non-debug)

No need for separate mod folders or manual switching!

SDK and Game Library

The game code in OpenQ4 is derived from the Quake 4 SDK, which is distributed under id Software's End User License Agreement. The SDK source code is maintained in the companion OpenQ4-GameLibs repository.

SDK EULA Summary

The Quake 4 SDK is provided under id Software's EULA, which permits:

• Modification of the SDK code for use with Quake 4
• Creation of custom game modifications
• Non-commercial distribution of modifications

Important Restrictions:

• SDK code cannot be used for commercial purposes without id Software permission
• SDK code cannot be used to create standalone games
• Modified code must be used only with a legitimate copy of Quake 4
• Original id Software and Raven Software copyrights must be preserved

For complete terms, refer to the EULA.

Game Library Repository

The OpenQ4-GameLibs repository contains:

• SDK-derived game code for single-player and multiplayer
• Synchronized automatically during OpenQ4 builds
• Maintained separately to clearly identify SDK-licensed components

Project Goals

Primary Objectives

• Complete code replacement for Quake 4 (engine + game code)
• Support genuine Quake 4 assets without redistribution
• Feature parity for single-player and multiplayer
• Modernize rendering, audio, and platform support
• Full support for Windows, Linux, and macOS (x64 baseline)

Non-Goals

• Binary compatibility with proprietary Quake 4 DLLs
• Support for third-party mods built against original SDK

OpenQ4 maintains complete freedom to evolve independently while preserving compatibility with official Quake 4 content.

Documentation

• Platform Support - Cross-platform roadmap and status
• SDL3 Linux/macOS Migration - Staged backend convergence plan for non-Windows platforms
• Display Settings - Multi-monitor and display configuration
• Multiplayer Networking - MP lag compensation and prediction cvars
• Input Key Matrix - Keyboard and controller input reference
• Release Completion - Release checklist and changelog
• Project TODO - Known issues and upcoming features

Asset Validation

OpenQ4 automatically validates your Quake 4 installation to ensure you have legitimate, unmodified game files. This protects the multiplayer experience and ensures compatibility.

How it works:

1. Engine validates official q4base PK4 checksums at startup
2. Refuses to run if required assets are missing or modified
3. Auto-discovers your Quake 4 installation (checks Steam, GOG, or current directory)
4. Uses proper paths for configuration and save files

Configuration:

• fs_validateOfficialPaks 1 (default) - Enable asset validation
• See official-pk4-checksums.md for checksum reference

Advanced Configuration

_{Built for modern displays, modern GPUs, and modern systems without changing the original game feel.}

Dependencies

OpenQ4 manages dependencies through Meson subprojects:

All dependencies are automatically handled during the build process - no manual setup required!

Debugging and Development

Crash Diagnostics

Debug builds (buildtype=debug) include automatic crash handling:

• Crash logs saved to crashes/*.log
• Memory dumps saved to crashes/*.dmp
• Timestamps included for easy identification

Companion Repository

The game library source code is maintained separately in OpenQ4-GameLibs:

• Expected location: ../OpenQ4-GameLibs
• OpenQ4 consumes this source directly at configure/build time (no in-repo src/game mirror)
• Optional game library builds with OPENQ4_BUILD_GAMELIBS=1

Build Automation

• Missing or stale build directories are auto-regenerated (Windows wrapper)
• Visual Studio environment auto-detected and loaded (Windows only)
• On Linux/macOS, use meson commands directly (no wrapper required)
• Use OPENQ4_GAMELIBS_REPO=<path> to override repository location

Levelshot Capture

• Use levelshot [size] in-game to capture a loading-screen tile set.
• Each tile is captured from a raw 4:3 source view, then resampled to square output so the loading GUI's 4:3 stretch remains tile-accurate.
• The command writes the current map's loadscreen plus _left, _right, _top, and _bottom variants as both .tga and .dds, without the view weapon.
• OpenQ4 always uses the current map name under gfx/guis/loadscreens/; size defaults to 512.
• Set com_showLevelshotBounds 1 to draw a live centered 4:3 framing guide while composing shots; the guide is not included in levelshot output.

Contributing

OpenQ4 is an open-source project and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Development Guidelines

• Maintain compatibility with official Quake 4 assets
• Follow existing code style and conventions
• Document significant changes
• Test on multiple platforms when possible
• Keep performance in mind for older hardware

License

OpenQ4 is licensed under the GNU General Public License v3.0 (GPLv3).

This means you are free to:

• Use the software for any purpose
• Modify the source code
• Distribute copies
• Distribute modified versions

See the LICENSE file for full details.

Note: The GPLv3 license applies to OpenQ4's engine code only. The game library code in OpenQ4-GameLibs is derived from the Quake 4 SDK and subject to id Software's EULA. Quake 4 game assets remain the property of id Software and ZeniMax Media.

Credits

OpenQ4 builds upon the work of many talented developers and projects:

Core Contributors

• themuffinator - OpenQ4 development and maintenance
• Justin Marshall - Quake4Doom, BSE reverse engineering
• Robert Backebans - RBDOOM3 modernization work

Original Developers

• id Software - idTech 4 engine and Quake 4
• Raven Software - Quake 4 game development

Third-Party Libraries

• Sean Barrett - stb_vorbis audio codec
• GLEW Team - Nigel Stewart, Milan Ikits, Marcelo E. Magallon, Lev Povalahev
• OpenAL Soft Contributors - 3D audio implementation
• SDL Team - Cross-platform framework

Special Thanks

• The Quake and id Tech community for continued support and enthusiasm
• All contributors who have submitted bug reports, patches, and improvements

Links

• Website
• Repository
• Game Library
• Issue Tracker
• Quake 4 on Steam
• Quake 4 on GOG

Disclaimer

OpenQ4 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.

You must own a legitimate copy of Quake 4 to use this software. OpenQ4 does not include any copyrighted game assets.

Use At Your Own Risk

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. OpenQ4 is experimental software under active development. Use at your own risk. The developers and contributors are not responsible for any damage, data loss, or issues that may arise from using this software.

Copyright © 2026 The OpenQ4 Project
All rights reserved. Licensed under GPLv3.

Back to Top