Building

Building

The full game build requires a local NTSC-U (SLUS_212.07) disc dump. Without one, you can build the launcher stub and authored test suites. Extracted game files and generated C++ are local build inputs, not distributable project source.

The most recent gameplay validation is on Apple Silicon macOS. Linux build support exists; Windows and cross-platform gameplay parity need validation. A successful CI stub build does not establish game compatibility.

The launcher

To play rather than develop, the launcher in tools/launcher does all of this page by itself. Drop your disc image on its window: it checks the image against the known-good dump, extracts it, builds the recompiler, translates and compiles the game, and starts it. Its download on the Releases page carries every tool the build needs except a C++ compiler, which the launcher installs through your system. From a checkout, it builds that checkout with the tools described below:

cmake -S tools/launcher -B build/launcher -G Ninja
cmake --build build/launcher

Then open build/launcher/DQ8Recomp Launcher.app on macOS, or run build/launcher/dq8-launcher on Linux and Windows. dq8-launcher --build --disc <image.iso> runs the same build without the window.

Dependencies

• Git, CMake 3.24 or newer, Ninja, and Python 3.10 or newer.
• A C++20 compiler. Clang is the default when available.
• SDL3 3.2 or newer for the SDL GPU renderer, and a compatible GPU/driver.
• pkg-config and FFmpeg development libraries for movie decoding: libavcodec, libavformat, libavutil, libswresample, and libswscale.
• On Linux, raylib's X11/OpenGL and audio development dependencies.
• On macOS, Xcode command-line tools. LLVM's llvm-ar is optional: CMake looks for it in the usual Homebrew LLVM locations and archives the generated corpus in one piece with it, or in parts of 1,500 files with Apple's ar. Leave Homebrew's LLVM out of PATH: configure takes the first clang++ it finds, and LLVM 23's libc++ cannot build the tree yet (missing standard includes).
• Optional: ccache, which CMake detects automatically.

CMake fetches several pinned dependencies, so the first configure needs network access. It can build glslang and SPIRV-Cross when suitable shader tools are not installed. Keep the license files supplied with these dependencies.

On an Apple Silicon machine using Homebrew, the host packages can be installed with:

xcode-select --install
brew install cmake ninja pkgconf sdl3 ffmpeg llvm

Clone and check the toolchain

git clone --recurse-submodules https://github.com/Sinan-Karakaya/DQ8-Recompiled.git
cd DQ8-Recompiled
cmake -S . -B build/stub -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build/stub --parallel 2
./build/stub/src/runtime/dq8

This checks the launcher build. It does not contain the game. For an existing checkout, run git submodule update --init --recursive after pulling changes that update submodule revisions.

Prepare the disc

Keep the disc image and extracted ISO filesystem outside the checkout. The examples use this layout; the filenames are not required:

workspace/
  DQ8-Recompiled/
  DQ8_USA.iso
  Extracted_Usa/
    SLUS_212.07
    SYSTEM.CNF
    BIN/
    MOVIE/
    ...

Extract the complete ISO filesystem with an ISO9660-capable archive tool. The setup script does not perform ISO filesystem extraction. Verify the inputs:

python3 setup.py verify --version SLUS_212.07 \
  --iso ../DQ8_USA.iso --extracted ../Extracted_Usa

Add --all to check every extracted file recorded in the hash database. A mismatch means the input is not the configured revision; do not bypass it by changing expected hashes. PAL configuration files do not make PAL gameplay supported.

setup.py extract is an optional archive/movie inspection workflow. It is not required for the normal game build, which reads archive sectors from the ISO. Offline movie conversion requires an explicitly supplied key; none is bundled.

Build the recompiler

cmake -S thirdparty/PS2Recomp -B build/ps2recomp-standalone -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DPS2X_BUILD_RUNTIME=OFF -DPS2X_BUILD_STUDIO=OFF -DPS2X_BUILD_TEST=OFF
cmake --build build/ps2recomp-standalone --target ps2_recomp --parallel 2

Generate game code

python3 setup.py recompile --version SLUS_212.07 \
  --extracted ../Extracted_Usa \
  --recompiler build/ps2recomp-standalone/ps2xRecomp/ps2_recomp

This generates the resident executable, six MWo3 overlays, and the overlay dispatch table under build/. It also rebuilds the VU1 microprograms listed in config/SLUS_212.07/vu1-programs.txt from your ELF, into build/generated/SLUS_212.07-vu1, for the runtime to compile. The configurations and function maps in config/ are the inputs; do not maintain fixes only in generated C++.

Compile and run

cmake -S . -B build/game -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DDQ8_LINK_GENERATED=ON -DDQ8_LINK_OVERLAYS=ON \
  -DDQ8_GFX_ENABLE_SDLGPU=ON
cmake --build build/game --target dq8 --parallel 2
./build/game/src/runtime/dq8 ../Extracted_Usa/SLUS_212.07 \
  --iso=../DQ8_USA.iso --gs=sdlgpu

Check that configure reports the SDL3 GPU backend as enabled. SDL3 absence is not fatal: the project can build without the hardware renderer. FFmpeg absence also permits a build, but movies will be skipped.

The generated corpus has about 14,000 translation units: about an hour of compiling in all, so about 7 minutes at 10 jobs on an M1 Pro. No translated function is over 0.8 MB of C++, and most compile in a fraction of a second; the slowest steps are the VU1 program shards and SPIRV-Cross, at 15 to 18 s each. Clang peaks at 0.5 GB on the heaviest file, so one job per GB of RAM, up to the number of cores, is safe. Keep the generated-code aliasing and wrapping flags; they preserve guest semantics.

On macOS, the full build also creates build/game/DQ8Recomp.app. Its launcher uses DQ8_MACOS_ELF and DQ8_MACOS_ISO CMake paths. Override them at configure time when using another directory layout, and reconfigure after moving files.

VU compilation and iteration

Configuring the game after setup.py recompile compiles the VU1 programs it rebuilt, so VU1 runs compiled from the first boot, with nothing to record. If build/generated/SLUS_212.07-vu1 is missing, configure says so and VU1 runs in the interpreter; run setup.py recompile, then configure again.

The list covers the programs seen in play so far, from the boot to Farebury, and the other microcode the ELF uploads at the same addresses. A scene that uses something else runs those programs in the interpreter. Recording it (PS2_VU_PROGRAM_PROFILE while playing, then PS2X_VU_PROGRAM_PROFILES at configure time) covers it locally, and the recording can extend the list in config/; see Vector Units. Recordings themselves are game code and are not distributed. Block-level VU compilation still works from local recordings only, so do not expect a build without them to reproduce every performance figure.

Pulling the change that added sound also changed the stub list in config/SLUS_212.07/dq8.toml, so generate the game code again before building. The same goes for the changes that fixed the characters' bodies and that brought the VU1 program list: rebuild ps2_recomp and run setup.py recompile again.

Renderer work can use the standalone harness without rebuilding the game. Changes to broadly included PS2 runtime headers may rebuild most generated files. See Testing for focused targets and Running for controls.