Toolchain per OS

Windows. Install Visual Studio 2022 Community with the Desktop development with C++ workload; it is the supported way to get the Windows SDKs. Get the rest through Scoop:

scoop install git llvm nasm python task ninja cmake

Linux (Ubuntu 20.04).

sudo apt install gcc make cmake ninja-build build-essential g++ nasm clang-format libxrandr-dev libxinerama-dev libxcursor-dev libpulse-dev libxi-dev python libgl1-mesa-dev libssl-dev
sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

clang and lld compile and link faster than gcc on this codebase and are what the clang preset (below) uses.

Linux (Arch).

sudo pacman -S cmake ninja libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi
yay -S go-task

Every task command in this page is go-task on Arch.

Linux (Fedora).

sudo dnf install cmake ninja-build python lld clang nasm libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel pulseaudio-libs-devel mesa-libGL-devel
sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

macOS. Not a platform this fork builds or tests yet; it is on the Roadmap. The steps the tree inherited from upstream are kept in docs/setup/system/macos.md for whoever takes that up.

Selecting the game and the region

task set-game-jakx            # or jak1, jak2, jak3
task set-decomp-ntscv1        # aka black label; also ntscv2 (red label), pal, ntscjp, ntscko

task settings prints what is currently persisted. Use task --list-all, not task --list: the game and region setters declare no desc:, so the short form hides them entirely.

Building, extracting, the REPL and (mi)

Command	What it does
task gen-cmake-release	Configures CMake into out/build/<preset>
task build-release	Builds gk, goalc, the decompiler and the rest of the tools into out/build/<preset> (with a bin/ subdirectory on Windows)
task extract	Runs the decompiler over iso_data/<game> with the region config you selected, writing into decompiler_out/
task repl	Starts goalc's REPL against the selected game
task run-game	Starts gk; with no -boot argument, the game only actually boots once the attached REPL drives it there

Inside the REPL, evaluate (mi) to compile the game's GOAL source under goal_src/<game> into out/<game>/obj and out/<game>/iso, which gk reads. This is a separate half of the build from task build-release: rebuilding gk.exe does nothing to GOAL code, and after editing any .gc file you need to run (mi) again, or the boot runs the previous GOAL build while looking current.

For a direct boot instead of a REPL-driven one, task boot-game runs gk with -boot -fakeiso -debug and writes its output to its own timestamped log under out/runs/, which is useful when you want a record of exactly what a boot did.

Tree layout

• decompiler/: the decompiler and the extractor, driven by the per-game config under decompiler/config/<game>/.
• goal_src/: the game source in GOAL and GOOS, one directory per game plus the project file each game's build reads.
• compiler/: goalc, the GOAL compiler and REPL.
• runtime/: gk, the C++ runtime, including the renderer with its OpenGL and Vulkan device backends.
• assets/: data the compiled programs read by path at run time: fonts, the FMV upscaler's weights, the controller database and the per-game text projects.
• docs/: setup guides, this fork's own recipes and design notes, and the third-party notices a release carries.
• landing/: the tooling that assembles a reviewed branch into a train and lands it.
• gates/: the checker battery that CI's lint job and the landing pipeline both run.

What actually builds where

Windows is the platform the port is built and played on daily. A Linux build compiles and boots in continuous integration on every landing; building it by hand uses the same task commands above once the clang preset is configured, or directly:

cmake --preset=Release-linux-clang -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"
cmake --build out/build/Release -j 8

Its unit tests, goalc-test, are what CI's Linux job runs:

./out/build/Release/goalc-test --gtest_color=yes --gtest_filter="-*MANUAL_TEST*"

macOS and the Steam Deck are on the Roadmap rather than platforms this fork builds or tests today.

Phaethon is a hard fork of OpenGOAL's jak-project. Naughty Dog made the games; you need your own copy of each. built from the wiki · 27 Sep 2026