[!IMPORTANT]
This repository does not contain any game files (ISO, executable, IRX modules, saves) nor the C++ code generated
from them. You need your own legal copy of God of War for the PS2.

Contents

• What is this?
• Current status
• Repository layout
• Requirements
• Building and running
• How it works
• Documentation
• Credits and license

What is this?

Instead of emulating the PlayStation 2, this project translates the game's executable (SCUS_973.99) into C++
with PS2Recomp and compiles it into a Windows program. On top of that, every
piece of PS2 hardware the game used is being replaced, layer by layer, by native code that produces the same result
from the game's own data:

The end goal: after the PC port is complete, the same native port running on the Nintendo Switch.

Current status

Per-component breakdown: docs/status-map/detail.md. Regenerated from
docs/status-map/data.toml by tools/status_map.py (and automatically on push to main).

Native Windows build, 1920x1080 window, captured by the automatic zone test (tools/zones.py).

Latest zone check (4 save slots, ~2 minutes each): all zones reach gameplay with no runtime errors, fps
60 / 60 / 60 / 60, save test passes. Details and the ordered next steps: docs/status.md and
docs/native-port.md.

Repository layout

The project lives in two branches of this repository:

• main (this branch): documentation, tools, game overrides, recompiler configuration.
• runtime: the runtime (fork of PS2Recomp): native GS renderer, VU1 and IOP code generators, sound engine,
  native services. It goes into ext/PS2Recomp-kl/ of a main checkout.

.
├── docs/                    # Documentation (single source of truth, start with docs/README.md)
│   └── captures/            # Screenshots for this page
├── port/
│   ├── functions.csv        # Function map
│   ├── gow.toml, gow-kl.toml  # PS2Recomp configurations
│   └── overrides-usa/       # Hand-written game overrides (gow_overrides.cpp)
├── tools/
│   ├── zones.py             # Zone regression test: load every save slot, walk, capture, judge fps
│   ├── savetest.py          # Memory card save test
│   ├── movies.py            # Movie test: play every movie of the disc, judge picture and sound
│   ├── vu1/ iop/            # Ahead-of-time code generators (VU1 microcode, IOP modules)
│   ├── dis.py, irxdis.py    # Disassemblers for the game ELF and IRX modules
│   └── switch/              # Switch smoke-link helpers
├── gemini-work/             # Requests/results of the read-only helper agent
├── play.cmd                 # Launcher (release settings)
├── disc-usa/, iso-usa/      # YOUR game files go here (ignored by git)
└── ext/PS2Recomp-kl/        # The `runtime` branch (ignored by git on main)

Requirements

• Windows 10/11 x64, a GPU with OpenGL 4.3.
• Visual Studio Build Tools (MSVC, x64) with its bundled CMake; Python 3.11 with capstone and Pillow.
• Your own copy of God of War (USA): the ISO and SCUS_973.99.

Building and running

The pipeline is still manual; the exact steps and their build cost are in
docs/build-and-run.md and the top of docs/status.md. In short:

1. Check out runtime into ext/PS2Recomp-kl/, configure with CMake (out/build-kl), build ps2_recomp.
2. Recompile SCUS_973.99 with ps2_recomp and copy the generated code plus port/overrides-usa/gow_overrides.cpp
   into ps2xRuntime/src/runner/.
3. Generate the native IOP and VU1 code (tools/iop/iopn_gen.py, tools/vu1/; see docs/native-port.md).
4. Build ps2EntryRunner (Release) and run it with play.cmd.

Test runs: python tools/zones.py --slots 1,2,3,4 (sound on, --silent mutes) and python tools/savetest.py; every movie of the disc: python tools/movies.py (muted, sound recorded and checked).

How it works

• EE: PS2Recomp turns every MIPS R5900 function into a C++ function; the runtime provides the kernel (threads,
  syscalls, interrupts) as native code.
• VU1: the vector-unit microprograms are compiled ahead of time to C++ per instruction pair, verified against an
  interpreter A/B.
• GS: a render-target renderer: real GPU render targets and textures, paletted textures as index + palette
  textures, the game's framebuffer tricks (channel shuffles, aliased Z, CRTC merge) reproduced natively.
• IOP: the game's IRX modules are compiled ahead of time to C++; the hardware behind them (SPU2, SIO2, DMA) is
  replaced by native services.

Documentation

Everything is in docs/: status, build and run, diagnostics, native-port inventory, performance,
sound, memory card, game internals, Switch notes.

Credits and license

• PS2Recomp by ran-j and contributors: the recompiler and runtime this port is
  built on (GPL-3.0; the runtime branch keeps that license).
• KIexster/god-of-war-recomp: a parallel God of War recompilation;
  its patch stack and function map were the starting point of the USA build, and its game-speed meter was ported.
• PCSX2: used as the reference for verification.
• Developed by Waffle565 with Claude (Anthropic) as co-author.

God of War is a trademark of Sony Interactive Entertainment. This project is not affiliated with or endorsed by Sony.