Ratchet: Deadlocked (PS2) Decompilation
A work-in-progress matching decompilation of Ratchet: Deadlocked (Ratchet: Gladiator in PAL regions; Insomniac Games, 2005) for the PlayStation 2, part of the OpenRAC initiative.
The objective is to produce C/C++ source code that, when compiled with the original toolchain, generates a byte-identical copy of the retail programs: the main program, the front end and the 47 level programs, each read straight from the disc. The primary target is the NTSC-U disc (SCUS_974.65), which the existing C was matched against; the PAL disc, Ratchet: Gladiator (SCES_532.85), is the second version, built and counted the same way, and the same C counts there wherever it builds to the PAL bytes too. Matched code is then refactored toward readable, idiomatic C++ with accurate types and naming, using matching builds as continuous regression tests.
[!NOTE]
This repository contains no game assets, retail executables, or disassembly. To build, you must provide your own legally obtained copy of the game. Please review LEGAL.md before contributing.
Progress
Progress is published on ByteMatch for both versions (US by default) and on openrac.dev.
| Version | Region | Target ID | Code Matched | Functions Matched |
|---|
| v1.00 (primary) | NTSC-U | SCUS_974.65 | | |
| PAL | Europe (Ratchet: Gladiator) | SCES_532.85 | | |
A function counts as matched on a version when its C, built with its file's own flags, gives that disc's bytes of the function with only the fields its object relocates masked (tools/match_map.py, config/<version>/map.tsv); the fuzzy figure adds what the near misses in nonmatching/ get right. There is no C in the programs' build yet: every program builds byte-identical from its assembly (docs/levels.md), and tools/audit_matches.py checks every function of src/ against the US bytes.
| Category | US | PAL | Contents |
|---|
| Main program | | | The main image: engine core, network code, resident menus, and frontbin's own code |
| Engine core | | | core.text, resident in every level (libgcc and libm apart) |
| libgcc | | | GCC's runtime, rebuilt from GCC's source (src/libgcc/) |
| libm | | | newlib's math library, rebuilt from its source (src/libm/) |
| Network | | | net.text, the same in every program |
| Resident menus | | |
NTSC-U (SCUS_974.65)
| Functions (exact) | Code (exact) | Fuzzy |
|---|
| Main program | 2,839 of 8,948 | 210,092 of 2,193,280 bytes (9.58%) | 10.08% |
| Engine core (core.text) | 765 of 1,695 | 72,908 of 298,900 bytes (24.39%) | 24.93% |
| libgcc | 2 of 2 | 16 of 16 bytes (100.00%) | 100.00% |
| Network (net.text) | 478 of 2,441 | 15,372 of 465,620 bytes (3.30%) | 4.31% |
| Resident menus (.text) | 1,591 of 4,785 | 120,992 of 1,416,576 bytes (8.54%) | 8.87% |
| frontbin's own code | 3 of 25 | 804 of 12,168 bytes (6.61%) | 6.61% |
| Shared level code | 1,560 of 5,076 | 111,664 of 1,980,204 bytes (5.64%) | 6.31% |
| Level-specific code | 1,012 of 4,061 | 86,452 of 1,608,940 bytes (5.37%) | 6.05% |
| Level 00: Multiplayer Menu | 713 of 2,798 | 61,068 of 943,140 bytes (6.47%) | 7.33% |
| Level 01: Dreadzone Station (and 21) | 80 of 356 | 5,728 of 188,848 bytes (3.03%) | 3.03% |
| Level 02: Catacrom Graveyard (and 22) | 5 of 35 | 188 of 26,596 bytes (0.71%) | 0.71% |
| Level 04: Sarathos Swamp (and 24) | 4 of 19 | 224 of 11,708 bytes (1.91%) | 1.91% |
| Level 05: Dark Cathedral (and 25) | 18 of 102 | 700 of 59,824 bytes (1.17%) | 1.33% |
Each distinct function counts once: frontbin's copy of the menus is the main image's, and a level function counts once however many of the 47 levels have it. 210,092 bytes (3.63%) are in units with nothing left to decompile.
PAL (SCES_532.85)
| Functions (exact) | Code (exact) | Fuzzy |
|---|
| Main program | 3,057 of 8,945 | 230,200 of 2,202,512 bytes (10.45%) | 10.90% |
| Engine core (core.text) | 770 of 1,699 | 73,268 of 299,052 bytes (24.50%) | 25.04% |
| libgcc | 2 of 2 | 16 of 16 bytes (100.00%) | 100.00% |
| Network (net.text) | 494 of 2,441 | 16,240 of 465,620 bytes (3.49%) | 4.50% |
| Resident menus (.text) | 1,788 of 4,786 | 140,096 of 1,422,048 bytes (9.85%) | 10.09% |
| frontbin's own code | 3 of 17 | 580 of 15,776 bytes (3.68%) | 3.68% |
| Shared level code | 1,615 of 5,088 | 121,504 of 2,008,520 bytes (6.05%) | 6.71% |
| Level-specific code | 1,084 of 4,080 | 92,444 of 1,601,892 bytes (5.77%) | 6.34% |
| Level 00: Multiplayer Menu | 757 of 2,826 | 62,972 of 943,820 bytes (6.67%) | 7.35% |
| Level 01: Dreadzone Station (and 21) | 90 of 357 | 7,196 of 189,772 bytes (3.79%) | 3.79% |
| Level 02: Catacrom Graveyard (and 22) | 5 of 29 | 188 of 21,232 bytes (0.89%) | 0.89% |
| Level 04: Sarathos Swamp (and 24) | 4 of 19 | 224 of 11,868 bytes (1.89%) | 1.89% |
| Level 05: Dark Cathedral (and 25) | 20 of 106 | 960 of 61,960 bytes (1.55%) | 1.70% |
Each distinct function counts once: frontbin's copy of the menus is the main image's, and a level function counts once however many of the 47 levels have it. 230,200 bytes (3.96%) are in units with nothing left to decompile.
Levels
Each level carries its own program: its code, data and dispatch tables, loaded over the main image's menus when the level starts. Each disc has 47 of them but only 14 distinct programs: the 12 split-screen campaign levels are byte-identical copies of their single-player levels, and all 22 multiplayer maps run one program (level 41's). Their functions are counted once each: under Shared level code when two or more distinct programs have them, else in their level's own row; a function the resident menus have too is counted there (docs/levels.md).
| Level | Name | Same program as | US | PAL |
|---|
| 00 | Multiplayer Menu | | | |
| 01 | Dreadzone Station | | | |
| 02 | Catacrom Graveyard | | | |
| 04 | Sarathos Swamp | | | |
| 05 | Dark Cathedral | | | |
| 06 | Temple Of Shaar | | | |
| 07 | Valix Lighthouse | | |
Quick Start
Prerequisites
- Linux & macOS: Docker or Podman (uses the prebuilt Wine container via GitHub Container Registry), and Python 3.10+.
- Windows: Git Bash, Python 3.10+, and community toolchain mirrors.
The compilers run natively (no Wine or container needed). The venv's interpreter is
venv/Scripts/python.exe: use it wherever these docs say venv/bin/python.
Setup & Build
-
Clone the repository:
git clone https://github.com/OpenRAC/rac-deadlocked-decomp.git
cd rac-deadlocked-decomp
-
Provide your original executable:
Copy SCUS_974.65 from your disc image into baserom/:
# Expected SHA-1: aa91b1c3b9b1a244320c47580b77342ef9856e95
cp /path/to/SCUS_974.65 baserom/SCUS_974.65
-
Generate the disassembly and fetch toolchains:
bash tools/setup_asm.sh # unpack, split, splat -> asm/
git clone https://github.com/AngheloAlf/SN-Systems-ProDG_for_PS2_3.01 toolchain/sn-prodg-3.01
git clone https://github.com/AngheloAlf/sce_ps2_sdk_24 toolchain/sn-prodg-24
-
Build and verify:
# Windows (native):
bash tools/build.sh
# Linux & macOS (via container):
bash tools/docker/run.sh bash tools/build.sh
# Then compare every function with retail:
venv/bin/python tools/audit_matches.py
# and write the progress reports (needs the dumps, see below):
python3 tools/match_map.py --write && python3 tools/progress.py --write
Both discs: the programs, their build and the count
Each disc's programs are read from your own baserom/SCUS_974.65.iso (or baserom/SCES_532.85.iso
with --version pal; the SHA-1s are in config/<version>/programs.tsv and levels.tsv), built
from their assembly, and counted (docs/levels.md):
python3 tools/levels.py dump # baserom/us/ (add --version pal for baserom/pal/)
python3 tools/build_levels.py --asm -P 16 # 49 targets, one MATCH each (ee-as/ee-ld; Linux, or the container)
JOBS=16 bash tools/docker/run.sh bash tools/build.sh # then build_libgcc.sh, build_libm.sh
python3 tools/match_map.py --write # where src/ matches (and --version pal)
python3 tools/progress.py --write # progress/report.json and its table (and --version pal)
python3 tools/check_func.py func_L01_XXXXXXXX try.c # one function against its US bytes (--version pal: PAL)
For detailed documentation:
docs/WORKFLOW.md – Setup in full, and the step-by-step function matching guidedocs/TOOLCHAIN.md – Compiler, flags, assembler passes, libraries and the containerdocs/RESEARCH.md – How the retail executable is packed and taken apartdocs/levels.md – Both discs' programs, their build, how the functions are counted, and the old against the new totalsdocs/OVERLAYS.md – The 47 US level overlays the existing C was matched against
Contributing
Contributions are warmly welcome! Whether you are interested in decompiling functions, researching engine quirks, or improving documentation:
Credits
This project builds upon years of dedicated reverse-engineering research and tooling by the community:
- rac1-decomp – Repository layout, README, progress workflow and report generator, toolchain notes, the libgcc build recipe, and
tools/ps2eeas_nops.py / tools/ps2eeas_dli.py (the nops and constant sequences of SN's assembler).
- rac3-uya-decomp-pal – The PAL treatment this repository follows: reading the levels from the disc, the function inventory (rac1-decomp's rules), the catalogue and the report (
tools/inventory.py, tools/level_catalogue.py, tools/progress.py are adapted from it).
- rac3-uya-decomp by vetusmagnus – Up Your Arsenal, the closest engine relative. Compiler research (SN ee-gcc 2.95.3 v1.36) and the
-fopt-stack, -G8 and global-declaration findings.
- OpenRAC – Status of Deadlocked, sourcing policy, and the sibling decompilations of the engine family.
- Lombyte by mateuszklysz – R&C1 NTSC decomp, checked for Deadlocked coverage (none).
- Wrench by chaoticgd – PS2 Ratchet & Clank modding tools; its documentation of the packed image (
docs/file_loading.md, "WAD Compression") and the executable's layout, and the level overlays it unpacks.
- GCC and newlib – The library sources in
src/libgcc/ and src/libm/ (see THIRD_PARTY_NOTICES.md).
- Decompilation Tooling & Ecosystem:
License
- Code written for this project is licensed under the GNU General Public License v3.0.
- Reconstructed libraries and third-party components retain their original licenses (see
THIRD_PARTY_NOTICES.md and LEGAL.md).
- Ratchet: Deadlocked is a registered trademark of Sony Interactive Entertainment. This project is not affiliated with or endorsed by Sony or Insomniac Games.
