Ratchet & Clank 3 (PS2) Decompilation

A work-in-progress matching decompilation of Ratchet & Clank 3 (Insomniac Games, 2004) for the PlayStation 2, part of the OpenRAC initiative. One repository covers two versions (docs/versions.md): PAL (SCES-524.56), the primary target, and NTSC-U (Ratchet & Clank: Up Your Arsenal, SCUS-973.53). A function whose code is the same on both discs is one C source, checked against both.

The PAL disc's three core programs and its 49 level programs are rebuilt from C and assembly until every byte equals retail:

Program	What it is	Size	SHA-1 of the retail file
frontbin	the front end (menus)	2,219,756	5a7ff1fe9c73a63c6ce6fe7b5f80cd7cab3aa553
boot_elf	the main executable: the engine core plus a second copy of the front end	3,534,436	e0a4e82e9a363a64db5a555db8c8f927ef58c3d8
i5bootn	a loader: decompresses and starts another program	810,640	c1166658edad1b6b04b7671af77fff53f2560e71

The objective is to produce C source code that, when compiled with the original toolchain, generates a byte-identical copy of the retail programs. 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 bytematch.dev/OpenRAC/rac3-decomp.

Version	Region	Target ID	Code Matched	Functions Matched
v1.00	PAL (En, Fr, De, Es, It)	SCES-524.56
v1.00	NTSC-U	SCUS-973.53

Program	Functions	Final source	in C	ASM_FUNC	LINKER_REMNANT	INCLUDE_ASM
frontbin	1667	1393 (83.6%)	1034	138	221	274
boot_elf	1043	852 (81.7%)	575	204	73	191
i5bootn	194	193 (99.5%)	41	147	5	1
Shared level code	7747	2758 (35.6%)	2259	0	499	4989
Level-specific code	5513	611 (11.1%)	449	0	162	4902

	Functions (exact)	Code (exact)	Fuzzy
Core programs	2,438 of 2,904	380,896 of 639,780 bytes (59.54%)	59.54%
Shared level code	2,758 of 7,747	251,444 of 3,914,160 bytes (6.42%)	6.42%
Level-specific code	611 of 5,513	25,440 of 2,993,008 bytes (0.85%)	0.85%
Total	5,807 of 16,164	657,780 of 7,546,948 bytes (8.72%)	8.72%

Each distinct function counts once: boot_elf's copy of the front end is frontbin's, and a level function counts once however many of the 49 levels have it. 204,304 bytes (2.71%) are in source files with nothing left to decompile.

NTSC-U (SCUS-973.53: 3 core programs and 51 levels, built byte-identical from assembly; docs/versions.md):

NTSC-U program	Functions	Final source	in C	ASM_FUNC	LINKER_REMNANT	INCLUDE_ASM
frontbin	1660	1370 (82.5%)	1012	138	220	290
boot_elf	1042	810 (77.7%)	539	204	67	232
i5bootn	191	183 (95.8%)	35	145	3	8
Shared level code	7728	2715 (35.1%)	2209	0	506	5013
Level-specific code	5601	593 (10.6%)	431	0	162	5008

	Functions (exact)	Code (exact)	Fuzzy
Core programs	2,363 of 2,893	353,304 of 639,076 bytes (55.28%)	61.22%
Shared level code	2,715 of 7,728	249,772 of 3,883,768 bytes (6.43%)	6.46%
Level-specific code	593 of 5,601	23,928 of 2,986,136 bytes (0.80%)	0.85%
Total	5,671 of 16,222	627,004 of 7,508,980 bytes (8.35%)	8.89%

Counted from the NTSC-U disc's own function tables; a function is final when PAL's source for the function with its code checks MATCH there (config/us/map.tsv, tools/version_map.py), and the fuzzy figure adds what the near misses and the C that does not check yet reach there (docs/versions.md). 51 levels; each distinct function counts once.

"Final source" is C, hand-written assembly (ASM_FUNC) and linker remnants (LINKER_REMNANT); INCLUDE_ASM is what is left to decompile. Flags are per source file, never per function (docs/BUILD_FIDELITY.md).

Every function links at its original retail address. Functions not yet decompiled are built from disassembly, so a program always links and matches retail byte-for-byte outside in-progress functions. For the level overlays and the breakdown details, see ByteMatch and docs/levels.md.

The disc is SCES-524.56 (Europe and Australia; English, French, German, Spanish, Italian), kept locally as baserom/SCES_524.56.iso (SHA-1 5593eab45eac8814ce4b95fa1c23510fc0a21ebf). docs/targets.md says where each core program comes from on the disc and how its layout compares with the US version's; docs/BETA.md what the July 2004 beta disc (baserom/TCES_524.56.iso, a reference only) offers.

---

Quick Start

Prerequisites

• Linux & macOS: Python 3, wibo to run the Windows compilers, and Wrench to unpack the disc.
• Windows: SN's make.exe, Python 3.9+, and the toolchain mirrors.

Toolchain

You need the SN Systems ee-gcc 2.95.3 v1.36 package (the compiler and the assemblers retail was built with) and Sony's ee-gcc 2.9-ee-991111 (for the Sony library files), plus Python 3.9 or newer. The SN package is preserved in AngheloAlf/SN-Systems-ProDG_for_PS2_3.01.

Setup & Build

1. Clone the repository:

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

2. Provide your original disc: Put your own copy of the disc image in baserom/ as SCES_524.56.iso (the folder is gitignored), unpack it with Wrench and copy the three programs out of it:

   # wrenchbuild unpack baserom/SCES_524.56.iso -o out
   cp out/uya_sces_524_56/boot_elf.elf baserom/
   cp out/uya_sces_524_56/globals/misc/frontbin.elf baserom/
   cp out/uya_sces_524_56/files/i5bootn.elf baserom/
   shasum baserom/*.elf   # must print the SHA-1s of the table above

   On a Mac, run Wrench's Linux build in an amd64 container.

3. Install the dependencies:

   python3 -m venv venv && venv/bin/pip install -r tools/requirements.txt

4. Generate the disassembly:

   python3 tools/setup_asm.py --target all

   It writes asm/ from your programs (gitignored, so a fresh clone has none; without it the build stops with "No rule to make target asm/..."). It takes a few minutes and is safe to repeat.

5. Build and verify:

   python3 tools/build.py --target all -j 8 \
       --toolchain <SN ee-gcc dir> --runner <wibo> --ee29 <2.9-ee dir>

   It ends with one MATCH line per program:

   MATCH: build/frontbin.bin sha1 5a7ff1fe9c73a63c6ce6fe7b5f80cd7cab3aa553
   MATCH: build/boot_elf/boot_elf.bin sha1 e0a4e82e9a363a64db5a555db8c8f927ef58c3d8
   MATCH: build/i5bootn/i5bootn.bin sha1 c1166658edad1b6b04b7671af77fff53f2560e71
   

6. The levels:

   python3 tools/levels.py dump
   python3 tools/build_levels.py --setup -P 8 -j 4 \
       --toolchain <SN ee-gcc dir> --runner <wibo> --ee29 <2.9-ee dir>

   It ends with one MATCH line per level.

On Windows, the Makefile does step 5 with SN's make.exe. python3 tools/check.py FILE.c compiles one function with its file's flags and diffs it against retail.

For detailed documentation:

• docs/wiki/Setup.md – the toolchain, your own copy of the game, the first build
• docs/BUILD_FIDELITY.md – what the build reproduces of retail's toolchain, what it models, and the rules that keep it honest
• docs/levels.md – the 49 level programs, how they are built and how their functions are counted
• docs/targets.md – the three core programs, their layout and their tables

---

Contributing

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

• Read AGENTS.md and CONTRIBUTING.md first; they hold the rules.
• The wiki sources are in docs/wiki/: Setup, Workflow, Matching patterns, Pull requests, Credits.
• The matching techniques of the US project apply here unchanged (Matching patterns); its research notes, with US addresses, are in docs/us/.
• python3 tools/todo.py sorts the functions still to match into buckets; many have a US draft in nonmatching/ to start from.
• Join our Discord Community to discuss progress, ask questions, and collaborate! info@openrac.dev reaches the maintainers privately.

---

Tools

Tool	Purpose
tools/setup_asm.py	Generates asm/ from your programs (splat plus the fix-ups the build needs)
tools/build.py	The full build for Linux and macOS: one MATCH per program
tools/build_levels.py	Builds the levels, several at a time; one MATCH per level
tools/build_text.py	Builds a program's code, one object per source file, with that file's flags
tools/check.py	Compiles a snippet with its file's flags and diffs it against retail
tools/todo.py	Sorts the functions still to match into buckets
tools/progress.py	The counts, the README table and progress/report.json
tools/levels.py	The levels: from the disc, their configuration, the catalogue, their build trees
tools/inventory.py	Every function of the core programs, found from the binaries (config/inventory.tsv)
tools/level_catalogue.py	Every distinct level function once, and boot_elf's front-end pairs
tools/resolve_symbols.py	Writes config/<program>/symbol_addrs_resolved.txt
tools/port_from_us.py	Made this tree from the US decompilation (kept as the record)
tools/port_verify.py	Checks every function of a build against retail, for the port
tools/pr_check.py	One program's source checks, plus compiling every file
tools/try_in_context.py	Compiles a draft in place, in the file's real build context
tools/flags_probe.py	Finds the mode and assembler a near miss wants, for the file's text_parts.txt line
tools/permuter_setup.py	Sets up a decomp-permuter run for one function (docs/permuter.md)
tests/check_repository.py	The pre-commit check: sources, tables, progress, no game data (CI runs it)

---

Credits

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

• rac3-uya-decomp by vetusmagnus – Matching decompilation of the NTSC-U release of Ratchet & Clank: Up Your Arsenal. This repository was made from it: its tools, its layout and the C of every function whose PAL bytes are the US ones come from there (docs/porting.md, CREDITS.md).
• rac1-decomp and rac2-decomp – the OpenRAC decompilations of the first two games: their way of finding functions in the binaries, of telling linker remnants and joined pieces apart, and their level catalogue and report categories came over as tools/inventory.py, tools/level_catalogue.py and tools/progress.py.
• Lombyte by mateuszklysz – Matching decompilation of the NTSC build of Ratchet & Clank. A reference for function pairing and symbol names.
• ReRAC by the ReRAC team – Native PC port of the US release. Documentation of formats and overlay mechanics.
• Wrench by chaoticgd – Ratchet & Clank PS2 modding tools and asset format specifications; it unpacks the disc.
• wibo by decompals – Runs the Windows toolchain on Linux and macOS.
• Decompilation Tooling & Ecosystem:
  • splat & spimdisasm – Binary splitting and MIPS disassembly.
  • m2c & asm-differ – Assembly-to-C translation and diffing.
  • decomp-permuter – Finds the C rewrites behind register and scheduling near misses.
  • objdiff – Object diffing tool.
  • ByteMatch & decomp.wiki – Progress tracking and decompilation knowledge base.
  • AngheloAlf – PS2 toolchain mirrors.

rac3-decomp is led by Veradictus, both the PAL and the NTSC versions; CREDITS.md and docs/wiki/Credits.md name everyone else.

---

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).
• The decompiled game code in src/ is a derivative of the original game (copyright Sony Interactive Entertainment LLC): no copyright is claimed over it and it is not licensed.
• Ratchet & Clank is a registered trademark of Sony Interactive Entertainment. This project is not affiliated with or endorsed by Sony or Insomniac Games.