# Melee decomp resources

**Decompiling functions with the live compilation on decomp.me**
You can find the functions that still have to be decompiled in the project's `asm/` folder. You can also use the dolphin debugger to find functions you're interested in (see below).

Then navigate to decomp.me/new, select GameCube/Wii and in the compiler preset select 'Melee'. Now copy the assembly code of the function from the project's `asm/` folder here and fill in a function name. All occurences of `-_SDA2_BASE_` in the code must be replaced with `@sda21`. Click on create scratch and you are ready to go.

Since we have the same compiler that was used for the original Melee project, the goal is to write C code that matches the assembly 100%. Global variables, functions and constants can not be matched on decomp.me, this has to be done when adding the function to https://github.com/doldecomp/melee. When doing so, variables must be declared in the order that they are defined in the assembly's data sections (someone correct me if I'm wrong, I haven't done that part yet).

**Automated decompilers**
They are not perfect, but can be a good start:
https://simonsoftware.se/other/ppc2cpp.py (github repo at https://github.com/matt-kempster/mips_to_c/tree/ppc2cpp)
ghidra (TODO: setup instructions)
IDA https://hex-rays.com/ida-free/ (TODO: setup instructions)

**Using the Dolphin debugger**
In Dolphin go to Settings > Interface > select 'Show Debugging UI'. Now you can inspect registers, Memory, the call stack, set break points and set memory watches.

Dolphin also allows you to assign names to functions and save them as so called MAP files. The dolphin debugger then shows you useful function names instead of cryptic function addresses. You can get such a map file here: https://github.com/UnclePunch/Training-Mode/blob/master/GTME01.map
By compiling the project with `make GENERATE_MAP=1`, you can also generate a map file of all assembly and all decompiled functions.

**Understanding the assembly**
The most common registers are R0-R31 for integers or bit fields, and f0-f31 for floating point values.
- R1 is used as the stack pointer.
- R2 points to a read only data section called SDA2 (small data area), also referred to as the table of contents pointer or RTOC.
- R13 points to another data section, but this data can change.
- PC is the instruction pointer
- CR is the condition register, used for conditional jumps (For example an integer subtraction sets CR as a side effect, then a conditional jump can be used when the result was less than, greater than, or equal to zero.)

R2 and R13 stay constant and have values `R2=0x804df9e0`, `R13=0x804db6a0`. When a value relative to R2 or R13 is dereferenced, you can find those values with the Dolphin debugger.

PPC instruction set documentation: http://math-atlas.sourceforge.net/devel/assembly/ppc_isa.pdf
ABI documentation (haven't read this, don't know how good it is): https://www.nxp.com/docs/en/application-note/PPCEABI.pdf
Compiler Writer's Guide (useful for recognizing assembly instruction patterns used for flow control, conversions, calling conventions, ...): https://cr.yp.to/2005-590/powerpc-cwg.pdf
Calling conventions (short, probably incomplete): http://wiki.tockdom.com/wiki/Compiler
The last site also contains a lot of other useful information for decompiling.

**Other Melee reverse engineering resources**
Community spreadsheet, documentation of data structures: https://docs.google.com/spreadsheets/d/1JX2w-r2fuvWuNgGb6D3Cs4wHQKLFegZe2jhbBuIhCG8/edit#gid=5

m-ex: Has C files with many struct definitions. But we don't copy-paste them blindly to this project until we can verify everything by decompilation.
https://github.com/akaneia/m-ex/blob/master/MexTK/include/

**Compiling the repo locally**
Clone the repo https://github.com/doldecomp/melee to your PC and follow the build instructions in the Readme.md. Due to a bug we need an older version of devkitPPC which you can get here: https://wii.leseratte10.de/devkitPro/devkitPPC/r39%20(2021-05-25)/

TODO: This info should really go into the Readme.md instead

**Contributing code**
Ideally you have decompiled a whole assembly file, because then the file can be replaced by a single C file. Replacing only individual functions with C versions is tricky. Talk to the devs how to procede when the assembly file is too large for you to decompile alone.

TODO: How to contribute individual functions (put them in a temporary file that doesn't get compiled?)