Game-Decompilation/dinosaur-planet
1
0
Fork 0
mirror of https://github.com/zestydevy/dinosaur-planet.git synced 2025-02-17 03:18:13 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
dinosaur-planet/CONTRIBUTING.md
zestydevy ab4b2add2f
workflow test
2024-05-15 13:36:41 -05:00

6.5 KiB
Raw Permalink Blame History

Contributing to the Dinosaur Planet Decompilation

Welcome to the Dinosaur Planet Decompilation and thanks for taking the time to contribute!

Please read on to learn about what the decompilation involves and how you can help.

Discord

https://discord.gg/H6WGkznZBc

If you're interested in contributing, please consider joining us on Discord over at the Dinosaur Planet Community server in the #decompilation channel! The Discord server is the best place to get your questions answered and is where a lot of the project's discussions take place.

Table of Contents

How does decompilation work

The goal behind the decompilation is to extract and convert the game's code from MIPS machine code to human readable MIPS assembly and ideally C code. Once this code has been converted, the game can then be recompiled using the same compiler as the original game to produce an identical ROM. A identical recompiled ROM is important because it verifies that the converted code is, at least, functionally 100% the same as the original ROM.

At a high level, the process goes like this:

  1. Disassemble the ROM's executable machine code into MIPS assembly code.
  2. Import assembly code in C source files on a function-by-function basis using #pragma GLOBAL_ASM(...).
  3. Replace each #pragma GLOBAL_ASM(...) by decompiling the included assembly code into a C function.
  4. Recompile the ROM. If the recompiled ROM matches the original ROM, the function decompiled in step 3 is correct!

Things to know before contributing

Before working on the decompilation, you should (ideally):

  • Have a decent understanding of the C89 programming language.
  • Be at least a little familiar with the MIPS instruction set and/or assembly programming in general.
  • Understand the basics of compilers and assemblers.
  • Have some familiarity with compiler optimizations.

It is perfectly okay if you don't know all of this right away! Decomp can be fairly involved and it's normal to need to learn things as you go.

How can I contribute?

The most important work that needs to be done currently is decompiling and understanding functions and data structures.

Style guide

The Dinosaur Planet Decompilation follows the same style guide as the SM64 Decompilation.

In addition:

  • Use Unix line endings (\n).
  • Ensure files end with a newline.
  • Strip trailing whitespace.

Opening a pull request

Before opening a pull request, you should make sure that:

  1. Any code additions/changes follow the project's style guide.
  2. The ROM builds and matches the original ROM (only for non-draft pull requests).
    • If you have a decompiled function that doesn't match but is worth committing, make sure to use an #if macro to let the compiler ignore the decompiled implementation and include the original assembly instead.

Resources

The following is a list of external resources that may be helpful: