8e47263c3f
* rm debug.i * match phys_update_action_state * world/action/idle.c * ~update_npcs * document npc_iter_nop * fix diff.py expected/ location * struct/naming updates * update Npc struct via clover * coverage * ~world_action_idle_update * walk, run actions * jump * land * name temp anim * size for struct * yucky * talk * stuff * all the action segments * ~func_802B61E4_E23444 * ~func_802B6000_E287F0 * cleanup * remove step_entity_updatecmd comment Co-authored-by: Ethan Roseman <ethteck@gmail.com>
3.5 KiB
Contributing
Thank you for your interest in contributing to this project!
Dependencies
There are a few additional dependencies needed when contributing to this project. You can install them with ./install.sh --extra.
Build System
You will need to re-run ./configure.py whenever splat.yaml or the number of source files changes (e.g. a function is matched and its .s file is removed). If you git pull and ninja breaks, you probably need to re-run ./configure.py.
If you use Visual Studio Code, you can use Run Build Task (Ctrl+Shift+B) to run ninja. Any errors or warnings generated by the compiler will show up in the Problems tab.
Tutorial: Matching a function
Setup
Once you've created a successful (OK) build, copy ver/us/build/ to ver/us/expected/build/:
./make_expected.sh
(If you're working with other versions of the game, replace us in the file paths.)
Roughly converting assembly to C
Decide on a function to match. These can be found in the subdirectories of ver/us/asm/nonmatchings/.
Take the relevant .s file and pass it to mips_to_c (online version).
Open up the .c file that uses your function and replace the function's INCLUDE_ASM macro with the output from mips_to_c. For example, for a function asm/nonmatchings/FOO/func_DEADBEEF:
// src/FOO.c
- INCLUDE_ASM("FOO", func_DEADBEEF);
+ s32 func_DEADBEEF() {
+ // ...
+ }
Compile the ROM:
ninja
This will probably end up either FAILing (the resulting ROM does not match the baserom), or the compilation of the C file you just modified did not succeed. mips_to_c loves to use void pointers and weird syntax that won't compile properly. Fixing this will involve typing the function signature correctly, which you may find in Star Rod's library database. For structs, see common_structs.h.
Once the C file compiles, you can compare the assembly generated by your code versus the original assembly with the following command, replacing function_name with the name of the function you're working on:
./diff.py -mwo function_name
(Sometimes, -mwo doesn't work. We don't know why yet; use -mw if you encounter issues.)
diff.py displays 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 with -m, 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.)
If you have any questions or encounter any issues, we suggest:
- Reaching out on Discord
- Using decomp permuter if your code is logically equivalent
- Wrapping what you have in
#ifdef NON_MATCHING(see other examples of this in the codebase) and trying a smaller function
After matching
Once you've matched a function, run the following:
./coverage.py --delete-matched
Then, go ahead and create a pull request!