Petari/docs/CONTRIBUTING.md

Contributing

We will be glad to answer any questions
for people who wish to contribute.

All pull requests and issues are welcome.

Before Submission

Be sure that all of your submitted code
follows the guidelines that are listed below.

When running build.py, it is REQUIRED that the output is 1:1.

After the code matches, be sure to run check.py
to check the function that you want to mark.

If it matches, it will automatically be marked as decompiled.

When each function you've matched has been marked as decompiled,
run progress.py to update the progress graph and percentages.

Questions

If you have any questions or concerns,
please join our Discord server.

---

Requirements

Tools

• A Disassembler / IDA Pro / Ghidra

  You can also use a decompiler, it can make some things easier

• CodeWarrior

  We specifically use version 3.0a3

• Python

  Version 3.7+

• Any Code IDE (Visual Studio Code recommended)

  If you are using Visual Studio Code, add this to c_cpp_properties.json:

  {
     "configurations": [
         {
             "name": "Win32",
             "includePath": [
                 "${workspaceFolder}/**",
                 "${workspaceFolder}/libs/JSystem/include",
                 "${workspaceFolder}/libs/MetroTRK/include",
                 "${workspaceFolder}/libs/MSL_C/include",
                 "${workspaceFolder}/libs/nw4r/include",
                 "${workspaceFolder}/libs/Runtime/include",
                 "${workspaceFolder}/libs/RVL_SDK/include",
                 "${workspaceFolder}/libs/RVLFaceLib/include"
             ],
             "defines": [
                 "_DEBUG",
                 "UNICODE",
                 "_UNICODE",
                 "MTX_USE_PS",
                 "GEKKO",
             ],
             "cStandard": "c99",
             "cppStandard": "c++98",
             "intelliSenseMode": "windows-msvc-x64"
         }
     ],
     "version": 4
  }
  

  This setup will help you include each library without compiler error issues from Intellisense.

Knowledge

• C / C++

  However C++ is recommended

• PowerPC Assembly

• PowerPC ➝ C / C++ reverse engineering instructions

Decompilers such as Hex-Rays (included in IDA Pro) are
useful as they can make the decompilation easier to write.

---

Guidelines

General

• Lines should not exceed 100 characters,
  these can be split into multiple lines.

• Use nullptr instead of 0 when assigning / comparing a pointer in C++ code, use NULL in C.

  Only use 0 when assigning or comparing a value.

Headers

• Use forward-declared types when possible

• At the top of every header place:

  #pragma once
  

Classes

• Follow the proper syntax for documenting a class's functions and variables:

  /* member-offset */     s32 varName;    ///< Description of varName.
  

  /// @brief Function does a thing.
  /// @param argumentName Is an argument to a function that does a thing.
  /// @return If the function did a thing.
  /// @note Might have not done a thing...
  bool func(s32 argumentName);
  

  If there is a function that does not have this implemented (ie in headers before the new documentation revamp), please take the time to help reimplement them to document this repository better! Note that the documentation website only updates every 15 minutes, so wait up to the nearest 15 minutes after your pull request has been merged. However, you can preview your changes before merging by running doxygen.

• At the top of every header place:

  #pragma once
  

Includes

• For system library includes use:

  #include <...>
  

• For game header includes use:

  #include "..."
  

  These includes must be relative to the include folder.

Names

• Names for known symbols should match exactly,
  even including typos in the symbol.

• Member variables must be prefixed with m.

• Arguments for functions must be prefixed with:

  • p for pointers

  • r for passed-by-reference

• Static variables with:

  • No known symbol must be prefixed with s

  • Global scope must be prefixed with g

• Functions with no symbols must use camelCase.

  Such as inlined functions.

Classes

• When referencing a class member, do not use
  this ->, unless it is required for compilation.

• Functions for classes must be put in the following order:

  • Constructor

  • Destructor

  • Operators

  • Virtual Functions

  • Member Functions

  If the virtual functions are not in the order that
  they are in the vtable, then the rule above can be
  ignored as these functions must be placed in order.

Nonmatching Code

If your code does NOT match, use the
NON_MATCHING macro, and explain in a
comment why it does not match.

Types

If the function arguments in the symbol use int,
do NOT use s32, you have to use int, as they
do not mangle to the same symbol.