A work-in-progress matching decompilation of the Gran Turismo 4 engine (PS2, CORE.GT4, NTSC-U SCUS-97328 v1.01): C++ source that compiles, with the original compiler, to the exact same instructions as the game. The long-term goal is a native port.

Most of GT4's game logic lives in Adhoc scripts, which OpenAdhoc already re-creates; this project covers the executable that runs them. Format documentation comes from the Gran Turismo Modding Hub.

Sister project: the Tourist Trophy decompilation, built on GT4's code base with the same tools; functions identical in both games are matched once and copied to the other (tools/crossgame.py).

This repository contains no game data. You need your own copy of the game.

• The executable is understood: retail CORE.GT4 is raw deflate (no encryption), loading at 0x00100000 with entry 0x00100008; 15,068 functions are reached by calls.
• The compiler is identified: Sony's ee-gcc 2.96 build 001003-1, -O2 -G0; game code is C++.
• A first pilot matched 13 of 20 randomly picked functions by hand; see PILOT.md.
• 14% of the functions are exact copies of another; one match settles a whole group.

• Progress (October 2026, commit 72c766491255): 30,157 of 30,875 functions match (97.7%), 89.0% of the code bytes; 87.3% of the sources are clean. Clean source: 87.3% of the 30,158 function sources are free of m2c macros, raw offset casts, temp_/var_ names and pasted headers (tools/clean_report.py). The live numbers are on the progress branch (objdiff report format); this paragraph is written by tools/update_readme.py from progress/report.json, never by hand.
• The full build reproduces the original executable (both loaded segments, SHA-1 checked): 30,128 functions, 88.9% of the code bytes, are linked from C/C++ source at their original addresses, and the rest is assembled from splat's disassembly of your own executable. 68,346 of 2,664,152 data bytes (2.57%; .data plus .bss) are the constants of 1,549 functions, placed from source at their original addresses. 289 functions that were hand-written assembly in the original are listed in config/asm_functions.txt and not counted.

• Matched functions are in src/, one file per function, organised as src/<subsystem>/<unit or class>/ and named after the script-engine or RTTI name when one is known (func_ADDR otherwise; config/symbol_addrs.txt and config/adhoc_methods.txt map names to addresses). Most were produced by AI agents (Claude) driving the tools in tools/, each one verified by the compiler and the judge, never by eye.

What the game code does, as far as the project has established it (each page marks what is inferred or unknown):

• knowledge/architecture.md: the engine's subsystems (start-up, Adhoc script VM, game data, UI, race and physics, sound, file system, network, libraries), address ranges, match status and how they connect.
• knowledge/classes.md: the 509 RTTI classes grouped by subsystem, with parents, instance sizes, vtable sizes and script natives.
• knowledge/script-engine.md: how C++ classes are registered with the Adhoc VM and how scripts call into them, mapped to the community's documentation.
• knowledge/runtime-types.md: the ref-counted string, handles, allocator, STL containers and object layout seen in the matched code.
• knowledge/coverage-map.md: what is matched and what is missing, by subsystem; knowledge/gt4.md and knowledge/ee-gcc-2.96.md cover the compiler side.

• GT4 Native is the separate, experimental source-level PC port built from this matching decompilation. It is not playable; matching PS2 code does not automatically run on a modern PC. GT4 Native maintains an automated, pinned-source import and host-compatibility triage pipeline, but imported or link-tested files are not automatically integrated into the runtime.
• GT3 decompilation reconstructs the preceding Gran Turismo engine generation.

Started and maintained by Gustavo Canepa (@gustavocanepa), with AI agents (Anthropic's Claude) doing the bulk of the matching. Thanks to Nenkai and the Gran Turismo modding community, whose research made the file formats and scripts understandable.

If you use these tools or this work elsewhere, please credit this project (MIT, see LICENSE).

This license covers the tools, documentation and the source code written for this project. Gran Turismo 4 is a trademark of Sony Interactive Entertainment; this project is not affiliated with or endorsed by Sony Interactive Entertainment or Polyphony Digital. It contains no game data, and you need your own copy of the game to use it.

GitHub Sponsors is active. Contributions and sponsorship are voluntary; sponsorship does not provide copyrighted game files or guarantee a release.

Help is welcome: matching functions, naming them, reconstructing structs and classes, or improving the tools. Start with CONTRIBUTING.md.

Requirements: Python 3.11+ with rabbitizer (pip install rabbitizer), and Linux or WSL (Ubuntu). To run the unit tests with the right Python (it falls back to the project virtual environment when the default python3 has no rabbitizer): bash tools/run_tests.sh.

1. Dump your disc and place the image as described in orig/README.md, then extract and convert the executable (commands there).
2. Set up the Linux side once: bash tools/setup_linux.sh (compiler, MIPS binutils, permuter).
3. Split the executable with splat (assembly for every function, under build/splat/): bash tools/splat.sh (in WSL/Linux).
4. Build the function list, which the build reads: python tools/find_functions.py orig/SCUS-97328/files/CORE.GT4 build/functions.csv.
5. Check that the full build reproduces your executable: python tools/build.py.
6. Build the duplicate groups: python tools/dedup.py scan.

SETUP.md walks through these steps on a fresh machine, with the places a first build gets stuck (the permuter's Python modules, the other compilers that sources ask for).

The automated loop (tools/autoloop.py) and how to reuse these tools for another game are described in TOOLS.md.

python tools/match.py asm 3951d0                    # show the original
python tools/match.py check 3951d0 src/func_003951D0.c   # compile and compare

A function is done when check prints MATCH and python tools/build.py still reproduces the original (it links every function at its real address and compares SHA-1). Notes on idioms found so far are in NOTES.md and PILOT.md.