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 (SCUS_974.65, NTSC-U v1.00), 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 executable. 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

Decompilation progress is tracked live on openrac.dev and decomp.dev/OpenRAC/rac-deadlocked-decomp.

Version	Region	Target ID	Code Matched	Functions Matched
v1.00	NTSC-U	SCUS_974.65

Only NTSC-U is targeted; PAL (Ratchet: Gladiator) may follow as a second version if someone with a PAL disc joins. There is no linked image yet: a function counts as matched when its compiled code equals retail with only the fields it relocates masked (tools/audit_matches.py), so a function that calls or reads the wrong symbol can still count.

Category	Progress	Contents
Game		All game code
Core		Engine and SDK code that stays resident (core.text)
Network		Network code (net.text)
Resident level code		The level text kept in the executable (.text); the menus' code
libgcc		GCC runtime library rebuilt from GCC's own source (src/libgcc/)
libm		Math library rebuilt from newlib's source (src/libm/)
Level overlays		All level overlay code (docs/OVERLAYS.md)
Common		Overlay code shared by two or more levels
Level-specific		Overlay code found in one level only (the multiplayer menu)

Level overlays

Each level carries its own build of the level code, loaded over the resident image when the level starts (docs/OVERLAYS.md). There are 47 overlays (24 campaign and 23 multiplayer levels) that share 85 to 97 percent of their code at different addresses. Their functions are split and counted once each: code shared by two or more levels under Common (4,714 functions), code found in one level only under Level-specific (2,315 functions, all of them the multiplayer menu's), and in the row of every level that contains it. As in rac1-decomp, their sources live in src/overlays/shared/ and src/overlays/lNN_<level>/. Functions identical to one in the resident level text are counted there, not twice. The overlays come from your own disc: unpack it with the wrench build tool and run tools/split_overlays.py (see docs/OVERLAYS.md).

Per level

Each row counts the overlay code of that level, including the common code it contains (code identical to the resident level text is counted under Resident level code instead).

Level	Name	Kind	Code	Functions
00	Multiplayer Menu	multiplayer
01	Dreadzone Station	campaign
02	Catacrom Graveyard	campaign
04	Sarathos Swamp	campaign
05	Dark Cathedral	campaign
06	Temple Of Shaar	campaign
07	Valix Lighthouse	campaign
08	Mining Facility	campaign
10	Torval Ruins	campaign
11	Tempus Station	campaign
13	Maraxus Prison	campaign
14	Ghost Station	campaign
15	Control Level	campaign
21	Dreadzone Station Splitscreen	campaign
22	Catacrom Graveyard Splitscreen	campaign
24	Sarathos Swamp Splitscreen	campaign
25	Dark Cathedral Splitscreen	campaign
26	Temple Of Shaar Splitscreen	campaign
27	Valix Lighthouse Splitscreen	campaign
28	Mining Facility Splitscreen	campaign
30	Torval Ruins Splitscreen	campaign
31	Tempus Station Splitscreen	campaign
33	Maraxus Prison Splitscreen	campaign
34	Ghost Station Splitscreen	campaign
35	Control Level Splitscreen	campaign
41	Battledome Tower	multiplayer
42	Catacrom Graveyard	multiplayer
44	Sarathos Swamp	multiplayer
45	Dark Cathedral	multiplayer
46	Temple Of Shaar	multiplayer
47	Valix Lighthouse	multiplayer
48	Mining Facility	multiplayer
50	Torval Ruins	multiplayer
51	Tempus Station	multiplayer
53	Maraxus Prison	multiplayer
54	Ghost Station	multiplayer
61	Battledome Tower Splitscreen	multiplayer
62	Catacrom Graveyard Splitscreen	multiplayer
64	Sarathos Swamp Splitscreen	multiplayer
65	Dark Cathedral Splitscreen	multiplayer
66	Temple Of Shaar Splitscreen	multiplayer
67	Valix Lighthouse Splitscreen	multiplayer
68	Mining Facility Splitscreen	multiplayer
70	Torval Ruins Splitscreen	multiplayer
71	Tempus Station Splitscreen	multiplayer
73	Maraxus Prison Splitscreen	multiplayer
74	Ghost Station Splitscreen	multiplayer

---

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

1. Clone the repository:

   git clone https://github.com/OpenRAC/rac-deadlocked-decomp.git
   cd rac-deadlocked-decomp

2. 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

3. 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

4. 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 and write the progress report:
   venv/bin/python tools/audit_matches.py
   python3 tools/gen_progress_report.py

For detailed documentation:

• docs/WORKFLOW.md – Setup in full, and the step-by-step function matching guide
• docs/TOOLCHAIN.md – Compiler, flags, assembler passes, libraries and the container
• docs/RESEARCH.md – How the retail executable is packed and taken apart
• docs/OVERLAYS.md – The 47 level overlays and how they are split and counted

---

Contributing

Contributions are warmly welcome! Whether you are interested in decompiling functions, researching engine quirks, or improving documentation:

• See CONTRIBUTING.md for contribution guidelines and rules.
• See docs/WORKFLOW.md for the step-by-step function matching guide.
• Join our Discord Community to discuss progress, ask questions, and collaborate!

---

Credits

This project builds upon years of dedicated reverse-engineering research and tooling by the community:

• GFI (Game Fuckery Inc.) – Special thanks to the GFI Discord community for years of reverse engineering, game research, and technical insights that made this decompilation possible.
• 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 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:
  • splat & spimdisasm – Binary splitting and MIPS disassembly.
  • m2c & asm-differ – Assembly-to-C translation and diffing.
  • objdiff – Object diffing tool.
  • decomp.dev & decomp.wiki – Progress tracking and decompilation knowledge base.
  • AngheloAlf – PS2 toolchain mirrors.

---

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.