This is a work-in-progress decompilation of Sly Cooper and the Thievius Raccoonus for the PlayStation 2. It is based on the NTSC-U version of the game (SCUS-971.98).
The goal of this project is to better understand the game engine. This repo does not contain any game assets or code from the game's executable, and it requires your own copy of the game to run.
Documentation of the code can be found at theonlyzac.github.io/sly1. For further reading on the game's internal structures and mechanics, visit the SlyMods Wiki.
New contributors are welcome and encouraged to make a pull request! If you would like to help but aren't sure where to start, check out CONTRIBUTING.md and feel free to join our Discord server for guidance.
The project can be built on Windows or Linux using make. It will build the executable SCUS_971.98.
The scripts directory contains scripts for setting up the build environment on each platform, which involves downloading and installing the required runtime libraries.
Prerequisites: git, make, wine-stable, p7zip-full
git clone https://github.com/TheOnlyZac/sly1
cd sly1/scripts
./setup-progd-linux.sh
cd ..
makePrerequisites: git, make, 7zip
git clone https://github.com/TheOnlyZac/sly1
cd sly1\scripts
.\setup-progd-windows.bat
cd ..
makeRunning the executable requires the PCSX2 emulator. You must have your own copy of the original game and the BIOS from your own PS2. They are not included in this repo and we cannot provide them for you.
The run.sh script in the scripts dir will automatically rebuild the executable and run it in the PCSX2 emulator. To use it, you must first edit the script to set the PCSX2_PATH and ISO_PATH variables to the correct paths on your system.
To boot the elf in PCSX2 from the command line, use one of the following commands:
pcsx2-1.6 --console --elf="/path/to/SCUS_971.98" "/path/to/game/backup.iso"pcsx2-1.7 -elf "/path/to/SCUS_971.98" "/path/to/game/backup.iso"Replace pcsx2-1.6 or pcsx2-1.7 with the path to your PCSX2 executable.
- The
elfflag is required and specifies the path to the elf file. - The last argument is the path to your game ISO.
- For PCSX2 1.6, click
System > Run ELF..., change the file type to "All Files", and browse forSCUS_971.98in thebindir of the project. - For PCSX2 1.7, add the
bindir to your Games folders and the ELF will show up as a game in your library. When it asks you to search recursively, say yes. You may have to rename the elf to end in.elffor it to automatically detect it.
The project is split into the following directories.
src- Contains the decompiled source code.- All of the code for the game engine is in
src/P2. - Code for the game's scripting engine, Splice, is in
src/P2/splice.
- All of the code for the game engine is in
test- Contains subdirectories for each game system. Each subdirectory contains unit tests for that system.build- Makefiles used to build the executable.scripts- Utility scripts for setting up the build environment.tools- Utilities for function matching.
Additionally, when you build the executable, the following directories will be created.
obj- Compiled object files.bin- Compiled executables.
When the developers created the game, they wrote programming code that we call the source code, and compiled that into an exectuable which can run on the PS2. Our job is to reverse-engineer the compiled code and produce new, original code that behaves the same way. This process leaves us with code that is very similar (but not identical) to the source code and helps us understand what the programmers were thinking when they made the game.
We use a tool called Ghidra which was created by the NSA for reverse-engineering software. Ghidra analyzes the game binary to identity functions, variables, data types and structures. We then reimplement each individual function by writing C++ code that produces the same output. We do not copy/paste any code or include any original assembly code from the game binary in the decompilation.
This is one of the first major PS2 decompilations. We take inspiration from other decomp projects such as the Super Mario 64 decomp for the N64 and the Breath of the Wild decomp for the Wii U (the latter being more similar in scope to this project). There is a Jak & Daxter decomp/PC port called OpenGOAL, though that game is written in 98% GOAL language rather than C/C++.
This is the first PS2 decompilation project to target the PS2 and utilize function matching. Most of the decompiled code is not yet matching, and we do not currently require it, but the ultimate goal is to match as many functions as possible.
If you want to contribute, read through CONTRIBUTING.md and feel free to join our discord server if you have any questions!