mirror of
https://github.com/pmret/papermario.git
synced 2024-11-18 08:52:40 +01:00
121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# Paper Mario
|
|
|
|
This is a WIP decompilation of Paper Mario (USA). It builds the following ROM:
|
|
|
|
* papermario.z64 `md5: a722f8161ff489943191330bf8416496`
|
|
|
|
Discord: [Paper Mario Modding](https://discord.gg/urUm3VG)
|
|
|
|
## Setup
|
|
|
|
You'll need Linux, a Linux VM, or Windows 10 (WSL) to work on this project.
|
|
|
|
#### Clone the repository
|
|
|
|
```sh
|
|
$ git clone https://github.com/ethteck/papermario.git
|
|
$ cd papermario
|
|
```
|
|
|
|
#### Install build dependencies
|
|
|
|
```sh
|
|
$ ./install.sh
|
|
```
|
|
|
|
Our install script does not yet support distros other than Ubuntu, Arch, and their derivatives. Please consider contributing to the script if you use another distro!
|
|
|
|
#### Base ROM
|
|
|
|
You'll need a Paper Mario (USA) ROM to work on this project. Copy it into the root directory of the repository with the name `baserom.z64`.
|
|
|
|
#### Install tools and extract ROM
|
|
|
|
```sh
|
|
$ make setup
|
|
```
|
|
|
|
### Compile the game
|
|
|
|
```sh
|
|
$ make
|
|
```
|
|
|
|
If you get `OK`, you're all set! Otherwise, please feel free to reach out to us in [our Discord channel](https://discord.gg/urUm3VG).
|
|
|
|
## Contributing
|
|
|
|
### Dependencies
|
|
|
|
There are a few additional dependencies needed when contributing to this project. You can install them with `./install.sh --extra`.
|
|
|
|
### Rebuilding
|
|
|
|
Setting the `PM_HEADER_REBUILD` environment variable will cause `make` to rebuild all `.c` files whenever a `.h` file is modified.
|
|
|
|
```sh
|
|
$ PM_HEADER_REBUILD=1 make
|
|
```
|
|
|
|
If you use Visual Studio Code, you can use _Run Build Task_ (Ctrl+Shift+B) to run `make`. Any errors or warnings generated by the compiler will show up in the _Problems_ tab.
|
|
|
|
### Matching a function
|
|
|
|
#### Setup
|
|
|
|
Once you've created a successful (`OK`) build, copy `build/` to `expected/build/`:
|
|
|
|
```sh
|
|
$ mkdir -p expected
|
|
$ cp -r build expected
|
|
```
|
|
|
|
#### Roughly converting assembly to C
|
|
|
|
Decide on a function to match. These can be found in the subdirectories of `asm/nonmatchings/`. Currently, functions which use float constants, data sections, or jump tables are unmatchable.
|
|
|
|
Take the relevant `.s` file and pass it to [mips_to_c](https://github.com/matt-kempster/mips_to_c) ([web version](https://simonsoftware.se/other/mips_to_c.py)).
|
|
|
|
If mips_to_c gives you an error about branch-likely instructions, edit the `.s` file and rename any branch-likely instructions to their unlikely equivalent (i.e. remove the `l` suffix). Add a `nop` after the branches and move the instruction that was originally in the delay slot (directly after the branch instruction) to the start of the target label. Don't commit the edited assembly.
|
|
|
|
Open up the relevant `.c` file and replace the function's `INCLUDE_ASM` macro with the output from mips_to_c. Run the following command to attempt to compile, replacing `function_name` with the name of the function you're working with:
|
|
|
|
```sh
|
|
./diff.py -mwo function_name
|
|
```
|
|
|
|
Fix any errors and rerun `diff.py`. This will involve typing the function signature correctly, which you will probably find in [Star Rod's library database](https://github.com/nanaian/star-rod/blob/master/database/common_func_library.lib). See also [common_structs.h](include/common_structs.h).
|
|
|
|
Once a successful build is made, `diff.py` will show you the difference between the original game's assembly (on the left) and what your C code generated (on the right).
|
|
|
|
#### Matching the function
|
|
|
|
You're on your own now. Get your C code compiling to match the original assembly! `diff.py`, when running, will automatically recompile your code whenever you save the `.c` file.
|
|
|
|
If you use Visual Studio Code, you can use _Run Test Task_ to run `diff.py` and show you errors and warnings from the compiler inline. You might want to attach _Run Test Task_ to a keybinding, as you'll be using it often.
|
|
|
|
#### Formatting and linting
|
|
|
|
Once your function is matching, you'll want to make a pull request. Before you do that, run the following script to reformat your code. (You can also format specific files with `./format.sh path/to/file.c`.)
|
|
|
|
```sh
|
|
$ ./format.sh
|
|
```
|
|
|
|
If `format.sh` displays any errors, go and fix them. If you can't fix them without breaking the function from matching, append `// NOLINT` to the offending line.
|
|
|
|
## FAQ
|
|
|
|
* If you received the following error when running `make`:
|
|
```
|
|
sha1sum -c checksum.sha1
|
|
sha1sum: 'papermario.z64'$'\r': No such file or directory
|
|
: FAILED open or read
|
|
sha1sum: WARNING: 1 listed file could not be read
|
|
Makefile:118: recipe for target 'verify' failed
|
|
make: *** [verify] Error 1
|
|
```
|
|
> 💡 Solution
|
|
>
|
|
> This is a Windows line ending issue run `git checkout checksum.sha1` to fix it.
|