WTFQ3

A standalone tactical FPS built from ioquake3. Work in progress: the development build now runs a singleplayer mission prototype with botlib actors and squad control. The finished standalone game and platform packages are not yet complete. No commercial Quake III game data is included or required by the intended finished game.

Target game

• One singleplayer mission at an American freight depot: the player commands four US Marines against a fictional domestic terrorist group.
• One separate multiplayer FFA map at an industrial freight terminal.
• Squad interface: F1 opens the panel and cycles all/Marine 1–4; F2 follows; F3 holds each Marine's current position; F4 moves to the aimed reachable floor; Esc dismisses the panel. Combat continues while commanding.
• A self-contained Universal macOS app for Monterey 12+, a Windows build, and a static Linux binary. These deliverables are not yet complete.
• Original, high-quality textured models, environments, sound, and presentation.

Build the engine

CMake 3.25+, Ninja or the platform's native generator, and a C compiler are needed. SDL and most codec dependencies are included upstream on macOS and Windows.

cmake -S . -B build/macos -G Ninja -DBUILD_STANDALONE=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build/macos --parallel 8
./tools/test.sh

The engine-only macOS output is build/macos/RelWithDebInfo/WTFQ3.app. The engine is compiled for both arm64 and x86_64 with deployment target 12.0. The app reads bundled game data from Contents/Resources/wtf.

After compiling the maps, assemble a self-contained development app and ZIP:

python3 tools/package-macos.py
python3 tools/check-macos-package.py
python3 tools/check-macos-package.py --native-game

Outputs are under build/dist/macos-development. These contain current game content, portable QVMs, native Universal modules, SDL and both renderers. The startup frontend now supports briefing/deployment, FFA host/join and settings. The tactical HUD now covers campaign/squad status, FFA scores and match results. Final art/audio, full playtesting and platform release work remain unfinished. See packaging and runtime checks for usage and limitations.

Menus use F1–F4 to choose and Esc to go back. F1 on the opening screen shows the mission briefing; F1 again deploys the squad. Multiplayer supports a local host, joining by address and LAN discovery. Esc in an operation opens resume, settings, restart and leave options, with confirmation before losing progress. See frontend controls and checks.

Windows cross-compilation on macOS with Homebrew MinGW-w64:

cmake -S . -B build/windows -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/windows-mingw.cmake -DBUILD_GAME_QVMS=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build/windows --parallel 8

Portable QVMs from the native build can be packaged on any target platform. The Windows binaries have compiled but have not been tested on Windows.

Map sources are generated by python3 tools/maps.py. After setting up the pinned map tools with tools/bootstrap-map-tools.sh, run python3 tools/compile-maps.py. Compiled maps are development layouts awaiting final materials and detail.

Assets

assets/briefs contains character generation briefs. tools/meshy.py submits, polls, refines, and downloads Meshy tasks, resuming existing task IDs. It reads MESHY_API_KEY or ~/.config/wtfq3/meshy-key; never put credentials in this tree. Task provenance is in assets/source/meshy; expiring download URLs stay in the ignored build/meshy cache. Meshes still require review, rigging, animation, engine conversion, and in-game validation.

Current verification and remaining work

See docs/STATUS.md for evidence and the remaining release gates. The upstream engine documentation is retained in README-ioquake3.md. Code is GPLv2 or later; see COPYING.txt. Upstream notices are preserved. Generated asset provenance and any third-party asset licenses must accompany a release.

Campaign development checks

game/wtf/campaign.cfg starts the depot mission in team mode with sixteen client slots. The local player commands Hayes, Brooks, Reyes and Cole against eight hostiles. Casualties stay down. Clear the depot and enter its command room to win; commander death or loss of the squad ends the mission. F1 retries after an outcome. All Marines and hostiles share botlib; campaign code assigns their roles/goals.

After rebuilding the engine and maps, run:

python3 tools/package-dev.py
python3 tools/campaign-smoke.py

The smoke test runs the real client/server in a hidden SDL window, with mouse/audio disabled. It verifies roster/team assignments, actual Marine movement toward the commander, all-squad/individual orders, arrival at the aimed floor point, holding the assigned position, defeat, no automatic respawn and clean retry. Its JSON evidence and logs are written under build/. --native-game compares the native game module against the default QVM mode. tools/test.sh also covers mission victory rules, casualties, disconnects, retries and keyboard/controller logic.

The Marine integration has baked walk/run, crouch, jump/landing and three fall animations, a rifle-ready upper body and the original 4K diffuse/normal textures. The carbine now has textured first-person arms and a ready-pose glove curl. Hostiles still use the Marine fallback until their own production assets are ready. Reload is baked but not connected to gameplay. Grip refinement, final combat animation, magazine handling, final effects/audio polish, main menus, final environment art and complete platform/runtime validation remain unfinished.

To rebuild the Marine from the preserved rig and matching animation clips, run Blender in background mode:

/Applications/Blender.app/Contents/MacOS/Blender -b --python tools/export-player.py -- game/wtf/models/players/marine
/Applications/Blender.app/Contents/MacOS/Blender -b --python tools/inspect-md3.py -- game/wtf/models/players/marine build/model-inspection

The exporter preserves packed texture bytes with the correct file extensions, excludes scene helpers, matches the engine player bounds and writes source hashes/ unfinished actions to bake.json. The inspector reads the actual MD3 files and checks their limits and tag chain. python3 tools/capture-actors.py captures the models in a hidden engine window; see preview/README.md. New Blender-rendered TGA portraits can be normalized for the engine with tools/normalize-tga.py.

See player animation integration for the source clips, MD3 frame conventions and hidden engine validation.

The current carbine has a textured world model, muzzle tag and first-person positioning. Its preserved reference, Meshy task and GLB are under assets/. See the rifle integration views in preview/README.md.

Recorded carbine/foley audio and firing effects are integrated; see combat media for sources, build steps and hidden dummy-audio verification. Listening review, voices/radio, ambience and remaining media are pending.