Game-Decompilation/sly1
1
0
Fork 0
mirror of https://github.com/TheOnlyZac/sly1.git synced 2024-11-30 09:00:36 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update readme

Browse Source
This commit is contained in:
Zac 2023-11-26 20:23:14 -05:00 committed by GitHub
parent 02430b8b64
commit 2d7b74f9a6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 33 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
README.md
View File

@ -1,64 +1,63 @@
# Sly Cooper and the Thievius Raccoonus
<!-- Readme badges -->
[![Build status][build-badge]][build-url] [![AppVeyor tests][tests-badge]][tests-url] [![Discord Channel][discord-badge]][discord-url] [![Wiki][wiki-badge]][wiki-url]
<!-- shields.io badges -->
[![Build status][build-badge]][build-url] <!--[![AppVeyor tests][tests-badge]][tests-url]--> [![Discord Channel][discord-badge]][discord-url] [![Wiki][wiki-badge]][wiki-url] [![Contributors][contributors-badge]][contributors-url]
<!-- Build status links -->
<!-- Build status badge -->
[build-url]: https://ci.appveyor.com/project/TheOnlyZac/sly1/branch/main
[build-badge]: https://ci.appveyor.com/api/projects/status/800esepa77ctpv5p/branch/main?svg=true
<!-- Test status links -->
<!-- Test status badge -->
[tests-url]: https://ci.appveyor.com/project/TheOnlyZac/sly1/branch/main/tests
[tests-badge]: https://img.shields.io/appveyor/tests/theonlyzac/sly1/main
<!-- Contributors badge links -->
<!-- Contributors badge -->
[contributors-url]: https://github.com/theonlyzac/sly1/graphs/contributors
[contributors-badge]: https://img.shields.io/github/contributors/theonlyzac/sly1?color=%23006ED1
<!-- Discord badge links -->
<!-- Discord badge -->
[discord-url]: https://discord.gg/2GSXcEzPJA
[discord-badge]: https://img.shields.io/discord/439454661100175380?color=%23006ED1&logo=discord&logoColor=%23FFFFFF
<!-- Wiki badge links -->
<!-- Wiki badge -->
[wiki-url]: https://slymods.info
[wiki-badge]: https://img.shields.io/badge/wiki-slymods.info-006ED1
This is a work-in-progress, experimental 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`).
This is a work-in-progress decompilation of [*Sly Cooper and the Thievius Raccoonus*](https://en.wikipedia.org/wiki/Sly_Cooper_and_the_Thievius_Raccoonus) for the PlayStation 2. It is based on the NTSC-U version of the game (`SCUS-971.98`). Documentation of the game's internal structures and mechanics can be found on the [SlyMods Wiki][wiki-url].
The goal of this project is to better understand how the game works. **This repo does not contain any game assets or original code from the game's executable.**
The goal of this project is to better understand how the game works. **This repo does not contain any game assets or code from the game's executable.**
New contributors are welcome and encouraged to make a pull request! If you would like to help but aren't sure where to begin, you can [join our Discord server][discord-url] and/or read [CONTRIBUTING.md](/CONTRIBUTING.MD) for info on how to get started.
New contributors are welcome and encouraged to make a pull request! If you would like to help but aren't sure where to start, you can [join our discord server][discord-url] and checkout [CONTRIBUTING.md](/CONTRIBUTING.MD) for info on how to get started.
## Frequently Asked Questions
#### What is a decompilation?
When the developers created the game they wrote programming code that we call the source code. Then, they compiled the source code into machine code that 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.
When the developers created the game they wrote programming code that we call the source code. Then they compiled the source code into machine code that 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](https://ghidra-sre.org/) which was created by the [NSA](https://www.nsa.gov/) 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 of the first-ever large scale PS2 decompilation projects. Our inspiration comes from other decomp projects such as the [Super Mario 64 decomp](https://github.com/n64decomp/sm64) for the N64 and the [Breath of the Wild decomp](https://github.com/zeldaret/botw) for the Wii U (the latter is more similar in scope to what we are trying to do). There is also a Jak & Daxter decomp/PC port called [OpenGOAL](https://github.com/open-goal/jak-project), though that game is written in 98% GOAL language, not native PS2 code.
This is one of the first large-scale PS2 decompilation projects. We take inspiration from other projects like the [Super Mario 64 decomp](https://github.com/n64decomp/sm64) for the N64 and the [Breath of the Wild decomp](https://github.com/zeldaret/botw) for the Wii U (the latter being more similar in scope to this project). There is also a Jak & Daxter decomp/PC port called [OpenGOAL](https://github.com/open-goal/jak-project), though that game is written in 98% GOAL language rather than C/C++.
#### Is this a matching decomp?
Due to the lack of resources on PS2 reverse-engineering, the currently decompiled code is not matching. However, we are actively researching the PS2 compiler and working to come up with with a process for function matching.
Most of the decompiled code is not yet matching. We are actively researching the PS2 compiler and working to come up with with a process for function matching.
#### How can I help?
If you would like to contribute but have no idea where to start, you can [join our discord server](https://discord.gg/gh5xwfj) and/or check out [CONTRIBUTING.md](/CONTRIBUTING.MD) for some resources and advice to get started!
If you would like to contribute but have no idea where to start, you can [join our discord server](https://discord.gg/gh5xwfj) and/or read [CONTRIBUTING.md](/CONTRIBUTING.MD) for some resources and advice to get started!
## Getting Started
### Windows - Visual Studio
### Windows/Linux - CLI
*Prerequisites: C++ CMake tools for Windows*
Clone the repo and open Visual Studio. Click `File > Open > CMake...` and open the file `CMakeLists.txt` in the main project folder. To build and run the main test program, set your startup item to `main.exe`.
For unit testing, build the target "Check" and the tests should appear in the Test Explorer window. It will run the tests, and the results will show in the Test Explorer as well as the Output window.
### Windows/Unix - MSYS2 MINGW64/UCRT64 - GNU/Linux
*Prerequisites: gcc (optionally clang), cmake, ninja, git, and base-devel*
**Prerequisites**: gcc, cmake, ninja
```bash
git clone https://github.com/TheOnlyZac/sly1
@ -66,7 +65,15 @@ cd sly1
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j8
cmake --build .
```
For testing, cd into the build directory and run `cmake --build . --target check` or `make check` to build the tests. Then run the tests with `ctest -C Debug`.
To build unit tests, `cd` into the build directory and run `cmake --build . --target check` or `make check`. Run them with `ctest -C Debug`.
### Windows - Visual Studio
**Prerequisites**: C++ CMake tools for Windows
Clone the repo and open Visual Studio. Click `File > Open > CMake...` and open the file `CMakeLists.txt` in the main project folder. Set the startup item to `SCUS_971.98`.
For unit testing, build the target "Check" and the tests should appear in the Test Explorer window. It will run the tests, and the results will show in the Test Explorer as well as the Output window.