mirror of
https://github.com/TheOnlyZac/sly1.git
synced 2024-11-23 05:39:54 +00:00
Update documentation
This commit is contained in:
Zac
GitHub
parent
de8a744dd8
commit
0178646ade
122
CONTRIBUTING.md
122
CONTRIBUTING.md
@ -1,122 +0,0 @@
|
||||
# Contributing
|
||||
|
||||
Welcome to the Sly Cooper Decompilation Project! This guide will help you get started with contributing to the project.
|
||||
|
||||
# Contents
|
||||
|
||||
1. [Beginner's Guide](#beginners-guide)
|
||||
2. [Writing Tests](#writing-tests)
|
||||
3. [Code Review Process](#code-review-process)
|
||||
|
||||
|
||||
## Beginner's Guide
|
||||
|
||||
If you are new to using Git, follow these steps to get started. If you already familiar with Git, skip to the next section.
|
||||
|
||||
### 1. Fork the repository on GitHub
|
||||
|
||||
Click the "Fork" button in the top-right corner of the [GitHub repository](https://github.com/theonlyzac/sly1). This will create a copy of the repository on your own GitHub account.
|
||||
|
||||
### 2. Clone the forked repository to your machine
|
||||
|
||||
Use a terminal or GitHub GUI to clone the forked repo to your machine.
|
||||
|
||||
### 3. Create a new branch for your changes
|
||||
|
||||
Navigate to the `sly1` directory and run the following command:
|
||||
|
||||
`git checkout -b branch-name`
|
||||
|
||||
Replace `branch-name` with whatever you want to call your working branch. This will automatically create a new branch and switch to it.
|
||||
|
||||
### 4. Write your code
|
||||
|
||||
Write your code in the `src/P2` directory. You can use any text editor you like, but we recommend [Visual Studio](https://visualstudio.microsoft.com/downloads/).
|
||||
|
||||
#### 4b. Write test cases
|
||||
|
||||
If you are adding new code, it is strongly reocmmended that you also write unit tests for it. See the [unit tests section](#writing-tests) for more information.
|
||||
|
||||
<!-- #### 4b. Match your code
|
||||
|
||||
You can follow the [Code Matching Guide](/tools/README.md) to match your code against the Sly 1 May 2002 Prototype. This will tell you if your code is exactly the same as the original code.
|
||||
|
||||
Most of the code in the repository is not yet matching, but we are working on it and in the future we may require that your code matches before it can be merged to the main branch. -->
|
||||
|
||||
### 4. Commit the changes to your branch
|
||||
|
||||
Whenever you feel you have reached a stop where you would like to save your progress you should commit your changes the working branch. First use `git add <files>` to add files to the commit, then `git commit -m "commit message"` to commit your changes with a message saying what you did.
|
||||
|
||||
Use `git status` to see which files you have changed. If a filename is red, it means that the file has been modified, but not added to the commit. If a filename is green, it means that the file has been added to the commit.
|
||||
|
||||
### 6. Push the commits to your fork
|
||||
|
||||
When you are done committing your changes, you can push your branch to your forked repo. Use `git push origin branch-name` to push your branch to your forked repository.
|
||||
|
||||
### 7. Create a pull request on GitHub
|
||||
|
||||
When you are have pushed all commits to your fork and are ready to submit your code, create a pull request on GitHub. Go to your forked repository on GitHub and click the "Pull requests" tab. Then click the "New pull request" button. Select your branch from the "compare" dropdown menu and click "Create pull request".
|
||||
|
||||
|
||||
## Writing Tests
|
||||
|
||||
Since the process for function matching is not fully set up yet, it is strongly recommended that you write tests for any new code you add to ensure it behaves the same way as the original code. Each test is a program with a main function; the test passes if the program exits with a return code of 0.
|
||||
|
||||
To write a new test, create a new source file in the `test` directory under a subdirectory for the system you are testing. For example, if you are testing the `clock` system, create a new source file in `test/clock`. The name of the source file should be the same as the name of the test, e.g. `test/clock/set_clock_rate.cpp`.
|
||||
|
||||
You can use the `JtAssert(condition)` macro (from `test/test.h`) to assert that a condition is true. If the condition is false, the test will fail and the test runner will print the file and line number where the assertion failed.
|
||||
|
||||
```cpp
|
||||
JtAssert(1 == 1); // Passes
|
||||
JtAssert(1 == 2); // Fails
|
||||
```
|
||||
|
||||
<!-- TODO: Add a way to run the tests -->
|
||||
|
||||
### Example Test
|
||||
|
||||
**test/clock/set_clock_rate.cpp**
|
||||
```
|
||||
#include <clock.h>
|
||||
#include <test/test.h>
|
||||
|
||||
int main()
|
||||
{
|
||||
SetClockRate(1.0);
|
||||
JtAssert(g_rtClock == 1.0f);
|
||||
JtAssert(g_clock.fEnabled);
|
||||
|
||||
SetClockRate(0.5);
|
||||
JtAssert(g_rtClock == 0.5f);
|
||||
JtAssert(g_clock.fEnabled);
|
||||
|
||||
SetClockRate(0);
|
||||
JtAssert(g_rtClock == 0.f);
|
||||
JtAssert(!g_clock.fEnabled);
|
||||
|
||||
SetClockRate(-1);
|
||||
JtAssert(g_rtClock == -1.f);
|
||||
JtAssert(!g_clock.fEnabled);
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## Code Review Process
|
||||
|
||||
After you create a pull request, a code reviewer will review it before it can be merged into the main branch. We are a volunteer-driven project, so please be patient while we review your code. These are the main things we will look for in your code:
|
||||
|
||||
* It compiles and runs without any errors
|
||||
* It follows the [style guide](/STYLEGUIDE.md), or is at least clean and readible
|
||||
* Nothing is copy/pasted directly from Ghidra
|
||||
|
||||
If everything looks good, we will merge your pull request as soon as possible. If anything needs to be fixed, we will let you know.
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
Thank you for reading, and we appreciate any contributions you make to the project!
|
||||
|
||||
When in doubt, just try and follow the style of the existing code, and do your best to make your code clean and readable. The project is 100% volunteern-driven, so perfection is not required.
|
||||
|
||||
If you have any questions or concerns, feel free to ask in the [Discord server](https://discord.gg/2Y8b8Z2) or [open an issue](https://github.com/TheOnlyZac/sly1/issues/new).
|
||||
12
README.md
12
README.md
@ -35,12 +35,12 @@ The goal of this project is to better understand the game engine. This repo does
|
||||
|
||||
Documentation of the code can be found at [theonlyzac.github.io/sly1](https://theonlyzac.github.io/sly1). For further reading on the game's internal structures and mechanics, visit the [SlyMods Wiki][wiki-url].
|
||||
|
||||
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](/CONTRIBUTING.MD) and feel free to [join our Discord server][discord-url] for guidance.
|
||||
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](/docs/CONTRIBUTING.md) and feel free to [join our Discord server][discord-url] for guidance.
|
||||
|
||||
|
||||
## Building
|
||||
|
||||
The project can be built on Windows or Linux using `make`. It will build the executable `SCUS_971.98`.
|
||||
The project can be compiled on Windows or Linux using `make`. It builds 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.
|
||||
|
||||
@ -73,11 +73,13 @@ make
|
||||
|
||||
Running the executable requires the [PCSX2 emulator](https://pcsx2.net/). 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 three ways.
|
||||
|
||||
### Automatic (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.
|
||||
|
||||
### Command line
|
||||
### Manual (command line)
|
||||
|
||||
To boot the elf in PCSX2 from the command line, use one of the following commands:
|
||||
|
||||
@ -93,7 +95,7 @@ Replace `pcsx2-1.6` or `pcsx2-1.7` with the path to your PCSX2 executable.
|
||||
* The `elf` flag is required and specifies the path to the elf file.
|
||||
* The last argument is the path to your game ISO.
|
||||
|
||||
### PCSX2 GUI
|
||||
### Manual (PCSX2 GUI)
|
||||
|
||||
* For PCSX2 1.6, click `System > Run ELF...`, change the file type to "All Files", and browse for `SCUS_971.98` in the `bin` dir of the project.
|
||||
* For PCSX2 1.7, add the `bin` dir 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 `.elf` for it to automatically detect it.
|
||||
@ -136,7 +138,7 @@ This is the first PS2 decompilation project to target the PS2 and utilize functi
|
||||
|
||||
#### How can I help?
|
||||
|
||||
If you want to contribute, read through [CONTRIBUTING.md](/CONTRIBUTING.md) and feel free to [join our discord server](https://discord.gg/gh5xwfj) if you have any questions!
|
||||
If you want to contribute, read through [CONTRIBUTING.md](/docs/CONTRIBUTING.md) and feel free to [join our discord server](https://discord.gg/gh5xwfj) if you have any questions!
|
||||
|
||||
|
||||
## Star History
|
||||
|
||||
53
docs/BEGINNERSGUIDE.md
Normal file
53
docs/BEGINNERSGUIDE.md
Normal file
@ -0,0 +1,53 @@
|
||||
# Beginner's Guide
|
||||
|
||||
If you are new to using Git, follow these steps to get started. If you already familiar with Git, go ahead and read the [contributing guide](/docs/CONTRIBUTING.md) instead.
|
||||
|
||||
**1. Fork the repository on GitHub**
|
||||
|
||||
Click the "Fork" button in the top-right corner of the [GitHub repository](https://github.com/theonlyzac/sly1). This will create a copy of the repository on your own GitHub account.
|
||||
|
||||
**2. Clone the forked repository to your machine**
|
||||
|
||||
Use a terminal or GitHub GUI to clone the forked repo to your machine.
|
||||
|
||||
**3. Create a new branch for your changes**
|
||||
|
||||
Navigate to the `sly1` directory and run the following command:
|
||||
|
||||
```sh
|
||||
git checkout -b branch-name
|
||||
```
|
||||
|
||||
Replace `branch-name` with whatever you want to call your working branch. This will automatically create a new branch and switch to it.
|
||||
|
||||
**4. Write your code**
|
||||
|
||||
Write your code in the `src/P2` directory. You can use any text editor you like, but we recommend [Visual Studio](https://visualstudio.microsoft.com/downloads/).
|
||||
|
||||
**4b. Write test cases**
|
||||
|
||||
If you are adding new code, it is strongly recommended that you also write unit tests for it. See the [contributing guide](/docs/CONTRIBUTING.md#writing-tests) for more information.
|
||||
|
||||
**4c. Match your code**
|
||||
|
||||
You can follow the [Code Matching Guide](/tools/codematcher/README.md) to match your code against the Sly 1 May 2002 Prototype. This will tell you if your code is exactly the same as the original code. This is not perfect because the prototype is not the same as the final release, but it is still a good way to make sure your code is correct.
|
||||
|
||||
**5. Commit the changes to your branch**
|
||||
|
||||
Whenever you feel you have reached a point where you would like to save your progress, you should *commit* your changes the working branch with the following command.
|
||||
|
||||
```sh
|
||||
git commit -am "What you did"
|
||||
```
|
||||
|
||||
If you only want to commit certain files, first add the them to the commit with `git add <files>`, then commit with `git commit -m "What you did"`.
|
||||
|
||||
Use `git status` to see which files you've changed. If a file is red, it means that the file has been modified, but not added to the commit. If a filename is green, it means that the file has been added to the commit.
|
||||
|
||||
**6. Push the commits to your fork**
|
||||
|
||||
When you are done making commits, push your branch to your forked repo. Use `git push origin branch-name` to push your branch to your forked repository.
|
||||
|
||||
**7. Create a pull request on GitHub**
|
||||
|
||||
When you are have pushed all commits to your fork and are ready to submit your code, create a pull request on GitHub. Go to your forked repository on GitHub and click the "Pull requests" tab. Then click the "New pull request" button. Select your branch from the "compare" dropdown menu and click "Create pull request".
|
||||
94
docs/CONTRIBUTING.md
Normal file
94
docs/CONTRIBUTING.md
Normal file
@ -0,0 +1,94 @@
|
||||
# Contributing
|
||||
|
||||
Welcome to the **Sly Cooper Decompilation Project**! This guide will help you start contributing to the project. We are a volunteer-driven project, so we appreciate any contributions you make.
|
||||
|
||||
# Contents
|
||||
|
||||
1. [Getting Started](#getting-started)
|
||||
2. [Function Matching](#function-matching)
|
||||
3. [Writing Tests](#writing-tests)
|
||||
4. [Code Review Process](#code-review-process)
|
||||
5. [Conclusion](#conclusion)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
If you have never used Git before, follow the steps in the [Beginner's Guide](/docs/BEGINNERSGUIDE.md) to learn how to fork the repo, make changes, and submit a pull request. If you are already familiar with Git, go ahead and read the rest of this guide instead.
|
||||
|
||||
For instructions on how to build and run the project, see the [README](/README.md).
|
||||
|
||||
|
||||
## Function Matching
|
||||
|
||||
The goal of this project is to match the original code as closely as possible. This means writing code that compiles to the same assembly as the original code, or at least has identical behavior at runtime.
|
||||
|
||||
We use [CodeMatcher](https://github.com/felinis/CodeMatcher) to match our code against the original code. CodeMatcher can compile and match the entire source tree or just one file at a time. Matching against the release elf is not fully set up yet, so for now we are matching against the [May 19 2002 prototype](https://hiddenpalace.org/Sly_Cooper_and_the_Thievius_Raccoonus_(May_19,_2002_prototype)). For instructions on using CodeMatcher, see the [Code Matching Guide](/tools/codematcher/README.md).
|
||||
|
||||
If you are adding new code, it is strongly recommended that you run CodeMatcher before submitting a pull request. We will accept pull requests that don't match as long as the code is clean and readable, but in the future we may require that your code matches before merging it into the main branch.
|
||||
|
||||
|
||||
## Writing Tests
|
||||
|
||||
Since the process for matching against the release elf is not fully set up yet, we recommended that you write tests for any new code you add to ensure it behaves the same way as the original code. Each test is a program with a main function; The test passes if the program runs successfuly without any errors.
|
||||
|
||||
To write a new test, create a new source file in the `test` directory under a subdirectory for the system you are testing. For example, if you are testing the `clock` system, create a new source file in `test/clock`. The name of the source file should be the same as the name of the test, e.g. `test/clock/set_clock_rate.cpp`.
|
||||
|
||||
You can use the `JtAssert(condition)` macro (from `test/test.h`) to assert that a condition is true. If the condition is false, the test will fail and the test runner will print the file and line number where the assertion failed.
|
||||
|
||||
```cpp
|
||||
JtAssert(1 == 1); // Passes
|
||||
JtAssert(1 == 2); // Fails
|
||||
```
|
||||
|
||||
<!-- ### Running tests
|
||||
|
||||
TODO: Add a way to compile and run the tests -->
|
||||
|
||||
### Example Test
|
||||
|
||||
**test/clock/set_clock_rate.cpp**
|
||||
```
|
||||
#include <clock.h>
|
||||
#include <test/test.h>
|
||||
|
||||
int main()
|
||||
{
|
||||
SetClockRate(1.0);
|
||||
JtAssert(g_rtClock == 1.0f);
|
||||
JtAssert(g_clock.fEnabled);
|
||||
|
||||
SetClockRate(0.5);
|
||||
JtAssert(g_rtClock == 0.5f);
|
||||
JtAssert(g_clock.fEnabled);
|
||||
|
||||
SetClockRate(0);
|
||||
JtAssert(g_rtClock == 0.f);
|
||||
JtAssert(!g_clock.fEnabled);
|
||||
|
||||
SetClockRate(-1);
|
||||
JtAssert(g_rtClock == -1.f);
|
||||
JtAssert(!g_clock.fEnabled);
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Code Review Process
|
||||
|
||||
Once you create a pull request, a code reviewer will need to approve it before it can be merged into the main branch. We are a volunteer-driven project, so please be patient while we review your code. These are the main things we will look for in your code:
|
||||
|
||||
* It compiles and runs without any errors.
|
||||
* It follows the [style guide](/docs/STYLEGUIDE.md), or is at least clean and readible.
|
||||
* Nothing is copy/pasted directly from Ghidra.
|
||||
|
||||
If everything looks good, we will merge your pull request as soon as possible. If anything needs to be fixed, we will let you know.
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
Thank you for reading, and we appreciate any contributions you make to the project!
|
||||
|
||||
When in doubt, just try and follow the style of the existing code, and do your best to write clean and readable code. The project is 100% volunteern-driven, so perfection is not required. The most important thing is to have fun and learn something new about the game!
|
||||
|
||||
If you have any questions or concerns, feel free to ask in the [Discord server](https://discord.gg/2Y8b8Z2) or [open an issue](https://github.com/TheOnlyZac/sly1/issues/new) on GitHub.
|
||||
@ -16,12 +16,13 @@ Please try and follow these general rules when writing your code:
|
||||
* Put opening curly braces on a new line.
|
||||
* Don't leave trailing whitespace at the end of lines.
|
||||
* End every file with a single blank line.
|
||||
* Keep lines between 80-100 character long at most.
|
||||
|
||||
## Symbol Names
|
||||
|
||||
For variables/symbols, use the official name from the [Sly 1 May 2002 demo](https://hiddenpalace.org/Sly_Cooper_and_the_Thievius_Raccoonus_(May_19,_2002_prototype)) if it is known. If it is not known, use a clear and descriptive name.
|
||||
For new symbols (i.e. classes, variables, and functions), use the official name from the [May 19 2002 demo](https://hiddenpalace.org/Sly_Cooper_and_the_Thievius_Raccoonus_(May_19,_2002_prototype)) if it is known. If it is not known, use a clear and descriptive name.
|
||||
|
||||
When naming symbols, mimic the style of the official symbol names, Official names use a loose version of [Hungarian Notation](https://en.wikipedia.org/wiki/Hungarian_notation). The most important part is the prefixes used to denote the **type** and **scope** of a symbol, as shown below.
|
||||
When making up symbol names, mimic the style of the official symbol names, Official names use a variation of [Hungarian Notation](https://en.wikipedia.org/wiki/Hungarian_notation). The most important part is the prefixes used to denote the **type** and **scope** of a symbol, as shown below.
|
||||
|
||||
These prefixes denote the **type** of a symbol:
|
||||
|
||||
@ -66,7 +67,7 @@ Use `lowerCamelCase` for local variables, function parameters, and class members
|
||||
|
||||
## Documentation
|
||||
|
||||
Comment your code with [Doxygen-style comments](http://micro-os-plus.github.io/develop/doxygen-style-guide/). They will be used to automatically generate [documentation](https://theonlyzac.github.io/sly1). You don't need to read the whole Doxygen style guide, just follow these rules.
|
||||
Comment your code with [Doxygen-style comments](http://micro-os-plus.github.io/develop/doxygen-style-guide/). They will be used to automatically generate a [documentation website](https://theonlyzac.github.io/sly1). You don't need to read the whole Doxygen style guide, just follow these rules.
|
||||
|
||||
### File Comments
|
||||
|
||||
@ -76,7 +77,7 @@ Put file comments at the top of each file, before any includes.
|
||||
* @file filename.xyz
|
||||
* @brief A brief description of the file.
|
||||
*
|
||||
* A longer description of the file that goes into more detail
|
||||
* @details A longer description of the file that goes into more detail
|
||||
* if you feel it is necessary.
|
||||
*/
|
||||
```
|
||||
@ -88,7 +89,7 @@ Put function comments before the declaration of each function in the header file
|
||||
/**
|
||||
* @brief A brief summary of the function.
|
||||
*
|
||||
* A longer summary of the function that goes into more detail
|
||||
* @details A longer summary of the function that goes into more detail
|
||||
* if you feel it is necessary.
|
||||
*
|
||||
* @param param1 Description of the first parameter
|
||||
@ -109,7 +110,7 @@ Put class (and struct) comments before the class declaration in the header file.
|
||||
/**
|
||||
* @brief Full name of the struct/class.
|
||||
*
|
||||
* A longer summary of the struct/class that goes into more detail
|
||||
* @details A longer summary of the struct/class that goes into more detail
|
||||
* if you feel it is necessary.
|
||||
*/
|
||||
```
|
||||
@ -126,7 +127,7 @@ Use `@todo` to mark something that needs to be done in the future.
|
||||
```
|
||||
|
||||
Use `@note` to add a note which will be differentiated form the rest of the comment.
|
||||
```
|
||||
```c
|
||||
/**
|
||||
* ...
|
||||
* @note The name of this struct is not official.
|
||||
@ -144,15 +145,15 @@ This code is clear and conforms to the style guide:
|
||||
/**
|
||||
* @brief Activates a cheat code.
|
||||
*
|
||||
* Sets the given flag on the global fcht variable. Also reloads the level if
|
||||
* is is a reload code.
|
||||
* @details Sets the given flag on the global fcht variable. Also reloads the
|
||||
* level if it is a reload code.
|
||||
*
|
||||
* @param nparam Cheat code to check
|
||||
*/
|
||||
void AddFcht(int nParam);
|
||||
|
||||
|
||||
//joy.cpp
|
||||
// joy.cpp
|
||||
|
||||
void AddFcht(int nParam)
|
||||
{
|
||||
@ -170,7 +171,7 @@ This code does **not** conform to the style guide and should be rewritten:
|
||||
```cpp
|
||||
// vec.h
|
||||
|
||||
// Sets the vector cylinderically
|
||||
// Sets the vector cylinder
|
||||
void SetVectorCylind(float x, float y, float z, VECTOR* pvec);
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user