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			The main image's resident .text (the menus); frontbin links it a second time and is counted with it
frontbin			The functions only frontbin has
Level code			Every level program's code, each distinct function once
Shared level code			In two or more distinct level programs
Level-specific code			In one level program only

<details> <summary>The counts</summary>

NTSC-U (SCUS_974.65)

<!-- progress:begin SCUS_974.65 (tools/progress.py --write) -->

	Functions (exact)	Code (exact)	Fuzzy
Main program	2,863 of 8,948	216,224 of 2,193,280 bytes (9.86%)	10.36%
Engine core (core.text)	765 of 1,664	72,908 of 288,080 bytes (25.31%)	25.87%
libgcc	26 of 33	6,148 of 10,836 bytes (56.74%)	56.74%
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.30%
Level-specific code	1,012 of 4,061	86,452 of 1,608,940 bytes (5.37%)	5.89%
Level 00: Multiplayer Menu	713 of 2,798	61,068 of 943,140 bytes (6.47%)	7.07%
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%
Level 06: Temple Of Shaar (and 26)	6 of 31	376 of 9,360 bytes (4.02%)	4.02%
Level 07: Valix Lighthouse (and 27)	4 of 46	464 of 28,304 bytes (1.64%)	1.64%
Level 08: Mining Facility (and 28)	7 of 48	1,188 of 24,400 bytes (4.87%)	4.87%
Level 10: Torval Ruins (and 30)	5 of 37	284 of 20,140 bytes (1.41%)	1.41%
Level 11: Tempus Station (and 31)	3 of 17	212 of 8,804 bytes (2.41%)	2.41%
Level 13: Maraxus Prison (and 33)	9 of 34	524 of 16,916 bytes (3.10%)	3.10%
Level 14: Ghost Station (and 34)	6 of 29	444 of 14,548 bytes (3.05%)	3.05%
Level 15: Control Level (and 35)	17 of 135	1,188 of 116,368 bytes (1.02%)	1.02%
Level 41: Battledome Tower (all 22 multiplayer maps)	135 of 374	13,864 of 139,984 bytes (9.90%)	11.77%
Total	5,435 of 18,085	414,340 of 5,782,424 bytes (7.17%)	7.73%

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. 216,224 bytes (3.74%) are in units with nothing left to decompile.

<!-- progress:end -->

PAL (SCES_532.85)

<!-- progress:begin SCES_532.85 (tools/progress.py --write) -->

	Functions (exact)	Code (exact)	Fuzzy
Main program	3,295 of 8,945	274,528 of 2,202,512 bytes (12.46%)	12.87%
Engine core (core.text)	772 of 1,668	73,404 of 288,232 bytes (25.47%)	26.03%
libgcc	26 of 33	6,148 of 10,836 bytes (56.74%)	56.74%
Network (net.text)	494 of 2,441	16,240 of 465,620 bytes (3.49%)	4.50%
Resident menus (.text)	2,000 of 4,786	178,156 of 1,422,048 bytes (12.53%)	12.71%
frontbin's own code	3 of 17	580 of 15,776 bytes (3.68%)	3.68%
Shared level code	1,643 of 5,088	127,280 of 2,008,520 bytes (6.34%)	6.99%
Level-specific code	1,094 of 4,080	95,808 of 1,601,892 bytes (5.98%)	6.39%
Level 00: Multiplayer Menu	759 of 2,826	63,712 of 943,820 bytes (6.75%)	7.16%
Level 01: Dreadzone Station (and 21)	92 of 357	7,936 of 189,772 bytes (4.18%)	4.18%
Level 02: Catacrom Graveyard (and 22)	5 of 29	188 of 21,232 bytes (0.89%)	0.89%
Level 04: Sarathos Swamp (and 24)	5 of 19	600 of 11,868 bytes (5.06%)	5.06%
Level 05: Dark Cathedral (and 25)	21 of 106	1,280 of 61,960 bytes (2.07%)	2.22%
Level 06: Temple Of Shaar (and 26)	7 of 31	460 of 9,440 bytes (4.87%)	4.87%
Level 07: Valix Lighthouse (and 27)	4 of 44	464 of 27,640 bytes (1.68%)	1.68%
Level 08: Mining Facility (and 28)	9 of 48	1,492 of 24,900 bytes (5.99%)	5.99%
Level 10: Torval Ruins (and 30)	6 of 38	424 of 20,392 bytes (2.08%)	2.08%
Level 11: Tempus Station (and 31)	4 of 17	500 of 9,024 bytes (5.54%)	5.54%
Level 13: Maraxus Prison (and 33)	12 of 34	1,200 of 15,996 bytes (7.50%)	7.50%
Level 14: Ghost Station (and 34)	6 of 23	444 of 8,884 bytes (5.00%)	5.00%
Level 15: Control Level (and 35)	23 of 134	2,540 of 116,624 bytes (2.18%)	2.18%
Level 41: Battledome Tower (all 22 multiplayer maps)	141 of 374	14,568 of 140,340 bytes (10.38%)	12.24%
Total	6,032 of 18,113	497,616 of 5,812,924 bytes (8.56%)	9.05%

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. 274,528 bytes (4.72%) are in units with nothing left to decompile.

<!-- progress:end --> </details>

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

<details> <summary>Per level</summary>

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
08	Mining Facility
10	Torval Ruins
11	Tempus Station
13	Maraxus Prison
14	Ghost Station
15	Control Level
21	Dreadzone Station (split screen)	01	(level 01's)	(level 01's)
22	Catacrom Graveyard (split screen)	02	(level 02's)	(level 02's)
24	Sarathos Swamp (split screen)	04	(level 04's)	(level 04's)
25	Dark Cathedral (split screen)	05	(level 05's)	(level 05's)
26	Temple Of Shaar (split screen)	06	(level 06's)	(level 06's)
27	Valix Lighthouse (split screen)	07	(level 07's)	(level 07's)
28	Mining Facility (split screen)	08	(level 08's)	(level 08's)
30	Torval Ruins (split screen)	10	(level 10's)	(level 10's)
31	Tempus Station (split screen)	11	(level 11's)	(level 11's)
33	Maraxus Prison (split screen)	13	(level 13's)	(level 13's)
34	Ghost Station (split screen)	14	(level 14's)	(level 14's)
35	Control Level (split screen)	15	(level 15's)	(level 15's)
41	Battledome Tower
42	Catacrom Graveyard (multiplayer)	41	(level 41's)	(level 41's)
44	Sarathos Swamp (multiplayer)	41	(level 41's)	(level 41's)
45	Dark Cathedral (multiplayer)	41	(level 41's)	(level 41's)
46	Temple Of Shaar (multiplayer)	41	(level 41's)	(level 41's)
47	Valix Lighthouse (multiplayer)	41	(level 41's)	(level 41's)
48	Mining Facility (multiplayer)	41	(level 41's)	(level 41's)
50	Torval Ruins (multiplayer)	41	(level 41's)	(level 41's)
51	Tempus Station (multiplayer)	41	(level 41's)	(level 41's)
53	Maraxus Prison (multiplayer)	41	(level 41's)	(level 41's)
54	Ghost Station (multiplayer)	41	(level 41's)	(level 41's)
61	Battledome Tower (multiplayer, split screen)	41	(level 41's)	(level 41's)
62	Catacrom Graveyard (multiplayer, split screen)	41	(level 41's)	(level 41's)
64	Sarathos Swamp (multiplayer, split screen)	41	(level 41's)	(level 41's)
65	Dark Cathedral (multiplayer, split screen)	41	(level 41's)	(level 41's)
66	Temple Of Shaar (multiplayer, split screen)	41	(level 41's)	(level 41's)
67	Valix Lighthouse (multiplayer, split screen)	41	(level 41's)	(level 41's)
68	Mining Facility (multiplayer, split screen)	41	(level 41's)	(level 41's)
70	Torval Ruins (multiplayer, split screen)	41	(level 41's)	(level 41's)
71	Tempus Station (multiplayer, split screen)	41	(level 41's)	(level 41's)
73	Maraxus Prison (multiplayer, split screen)	41	(level 41's)	(level 41's)
74	Ghost Station (multiplayer, split screen)	41	(level 41's)	(level 41's)

</details>

---

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:
   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 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/levels.md – Both discs' programs, their build, how the functions are counted, and the old against the new totals
• docs/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:

• 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:

• 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:
  • splat & spimdisasm – Binary splitting and MIPS disassembly.
  • m2c & asm-differ – Assembly-to-C translation and diffing.
  • objdiff – Object diffing tool.
  • ByteMatch, 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.