MuffMode Build Guide

August 3, 2026 ยท View on GitHub

README | Server Host Guide | Configuration Reference

This guide explains how to build MuffMode on Windows with Visual Studio/MSBuild.

Prerequisites

  • Windows 10 or Windows 11.
  • Visual Studio 2022 or Visual Studio 2022 Build Tools.
  • The C++ desktop workload and Windows SDK.
  • MSBuild and a configured Visual C++ environment.

The Visual Studio project uses the vcpkg manifest at vcpkg.json. Dependency policy and third-party notice obligations are recorded in Dependency Policy.

The currently supported branch/build matrix is recorded in Build Matrix.

Project Root

Run commands from the repository root:

MuffMode/

The solution file is projects/msvc/MuffMode.sln.

Open A Developer Shell

Use one of these Visual Studio shells:

  • x64 Native Tools Command Prompt for VS 2022
  • Developer PowerShell for VS 2022

This ensures msbuild, the compiler, and library paths are available.

Build Commands

Release build:

msbuild projects\msvc\MuffMode.sln /p:Configuration=Release /p:Platform=x64

Canonical CI/local release build:

./scripts/ci/build-msbuild.ps1 -Configuration Release -Platform x64

Strict warning gate:

./scripts/ci/build-msbuild.ps1 -Configuration Release -Platform x64 -TreatWarningsAsErrors

Debug build:

msbuild projects\msvc\MuffMode.sln /p:Configuration=Debug /p:Platform=x64

Analysis Commands

Generate a compile database for host-side analysis tools:

./scripts/ci/export-compile-commands.ps1

Run the currently configured analyzer entrypoints:

./scripts/ci/run-msvc-analyze.ps1
./scripts/ci/run-clang-tidy.ps1 -Files src/sgame/muffmode/mm_pconfig.cpp
./scripts/ci/run-cppcheck.ps1
./scripts/ci/run-sanitized-build.ps1 -Sanitizer Address

UndefinedBehaviorSanitizer is configured through the ClangCL MSBuild platform toolset:

./scripts/ci/run-sanitized-build.ps1 -Sanitizer Undefined

That job is experimental until the Visual Studio ClangCL build tools are installed and validated on the CI runner.

Test And Fuzz Commands

Before pushing to GitHub, run the consolidated local push verifier:

./scripts/ci/verify-github-push.ps1

Use -RemoteBranch <branch> only when the GitHub branch you intend to update differs from the local branch name or upstream.

Run the fast host-side smoke tests:

./scripts/ci/run-host-tests.ps1 -Configuration Release -Platform x64

Validate checked-in regression and fuzz corpus seeds:

./scripts/ci/check-regression-corpus.ps1

Validate dependency inventory and release notices:

./scripts/ci/check-dependency-inventory.ps1

Build and execute the first-wave libFuzzer smoke target:

./scripts/ci/build-fuzz-targets.ps1
./scripts/ci/run-fuzz-smoke.ps1 -Runs 1000

The build verifies the x64 libFuzzer/ASan runtime before compiling, stages the required runtime DLL beside the target, and then executes a bounded generated copy of the checked-in corpus. Compiler or target failures are not treated as unsupported-toolchain success.

Output

The build produces build\msbuild\x64\<Configuration>\game_x64.dll. To test locally after a release build:

  1. Back up your Quake II rerelease baseq2\game_x64.dll.
  2. Copy build\msbuild\x64\Release\game_x64.dll into the rerelease baseq2 folder.
  3. Launch Quake II and start or join a multiplayer session.

Common Issues

ProblemFix
msbuild is not recognizedOpen a Visual Studio Developer Command Prompt or Developer PowerShell, then run the command again.
Missing C++ toolchain errorsInstall the Visual Studio C++ desktop workload and Windows SDK.
Missing dependency librariesConfirm vcpkg manifest restore is enabled, then rebuild from the Visual Studio developer shell.
DLL copy or test failuresCheck your Quake II install path, file permissions, and whether the game is already running.