Sly Cooper and the Thievius Raccoonus

This is a work-in-progress decompilation of Sly Cooper and the Thievius Raccoonus for the PlayStation 2. It builds the NTSC-U version of the game, SCUS_971.98 (SHA1: 57dc305d).

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.

Setup

Clone the repo

First clone the repository to your local machine:

git clone https://github.com/TheOnlyZac/sly1
cd sly1

Install Python packages

Splat is used for binary splitting, and Ninja is used for building the project. You will need Python 3. Install dependencies with pip:

pip install -U -r requirements.txt

Setup build environment

The scripts directory contains scripts for setting up the build environment on Windows and Linux, which automatically download and install the required runtime libraries. Follow the instruction for your platform below.

Linux/WSL

Prerequisites: git, make, wine-stable, p7zip-full, binutils-mips-linux-gnu

cd scripts
./setup-progd-linux.sh

Windows

Prerequisites: git, make, 7zip

Note: Building Windows is untested with the new build system. If you encounter issues, you can still build on Windows using WSL.

cd scripts
.\setup-progd-windows.bat

Setup binary splitting

To build the ELF , you will need to extract the original ELF file from your own legally obtained copy of the game. Mount the disk on your PC and copy the file SCUS_971.98 from the root directory of the disc to the disc directory of this project.

Building

The project can be compiled on Windows (using WSL) or Linux. It builds the executable SCUS_971.98.

First configure the project:

python configure.py

Then build with Ninja:

ninja

Running

Running the executable requires PCSX2 1.7. 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.

Once you have those and you have built the executable, you can run it in one of these three ways:

1. Autorun script

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.

2. Run from command line

To boot the elf in PCSX2 from the command line, use the following command:

pcsx2-1.7.exe -elf ".../sly1/bin/debug/SCUS_971.98" "/path/to/game/backup.iso"

Replace pcsx2-1.7.exe with the path to your PCSX2 v1.7 executable (for Linux it will be an .appimage file).

• The -elf parameter specifies the path to the SCUS_971.98 you built from this project. Replace ... with the path to this repository. The emulator will use this ELF to boot the game.
• The last argument is the path to your game ISO. Replace /path/to/game/backup.iso with the path to a backup of your own game disc. This is where the game will load the assets from.

3. Run from PCSX2 GUI

Copy SCUS_971.98 from the out dir to your PCSX2 Games folder and rename it to SCUS_971.98.elf. Right click on the game in PCSX2 and click "Properties...". Go to "Disc Path", click "Browse", and select the ISO of your game backup. Then click "Close" and start the game as normal.

Project Structure

The project is divided into the following directories:

• include - Header files for the game engine.
• src - The decompiled source code.
  • All of the code for the game engine is in src/P2.
  • Code for the game's scripting engine is in src/P2/splice.
• config - Config files for Splat (binary splitting tool).
• scripts - Utility scripts for setting up the build environment.
• docs - Documentation and instructions for contributing.
• tools - Utilities for function matching.
• reference - Reference files for functions and data structures.

When you build the executable, the following directories will be created:

• asm - Disassembled assembly code from the elf.
• assets- Binary data extracted from the elf.
• obj - Compiled object files.
• out - Compiled executables.

FAQ

What is a decompilation?

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.

How does it work?

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.

Has this ever been done before?

This is one the first ever PS2 decompilations. We draw 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++.

Is this a matching decomp?

This was the first PS2 decompilation project that aimed to target the PS2 and utilize function matching. The ultimate goal is to match as many functions as possible.

How can I help?

If you want to contribute, read through CONTRIBUTING.md and feel free to join our discord server if you have any questions!

Star History