From 628c233e6d208386325c58d1221f7442d4261f8d Mon Sep 17 00:00:00 2001 From: TakaRikka Date: Wed, 19 Feb 2025 21:33:48 -0800 Subject: [PATCH] revamp site and decomp information --- docs/contribute/contribute.mdx | 8 +- docs/contribute/guidelines.mdx | 5 +- docs/contribute/installation.mdx | 144 +++++++++---------------------- docs/contribute/workflow.mdx | 124 ++++++++++++++++++++++++++ docusaurus.config.js | 60 +++++++++---- src/pages/index.tsx | 24 +++--- src/pages/progress.tsx | 18 ++-- src/progressUtils.ts | 32 +++---- static/img/objdiff.png | Bin 0 -> 86860 bytes 9 files changed, 256 insertions(+), 159 deletions(-) create mode 100644 docs/contribute/workflow.mdx create mode 100644 static/img/objdiff.png diff --git a/docs/contribute/contribute.mdx b/docs/contribute/contribute.mdx index e71d6194..b071ae40 100644 --- a/docs/contribute/contribute.mdx +++ b/docs/contribute/contribute.mdx @@ -9,9 +9,9 @@ We gladly accept contributions! If you're interested in helping with this projec ## What is needed? -To contribute to this project, you will need: +To contribute to this project, you will (at minimum) need: - A dump of the GameCube USA version of Twilight Princess -- [Ghidra](https://github.com/NationalSecurityAgency/ghidra) +- [Ghidra](https://github.com/encounter/ghidra-ci/releases) - Basic knowledge about using Git - Basic knowledge about programming (preferrably in C++ / C) @@ -24,7 +24,3 @@ A moderately powerful computer will also be beneficial, as building the project :::caution Important note You will have to **source your own dump of the game**. We **cannot** assist you in acquiring it. ::: - -:::caution Windows users - The documentation here will assume you are using Linux (either native or through WSL). If you are on Windows, we strongly recommend setting up WSL and using it for this project. Native Windows is supported as well, but is not recommended. -::: \ No newline at end of file diff --git a/docs/contribute/guidelines.mdx b/docs/contribute/guidelines.mdx index 78f6e8c0..ba60136c 100644 --- a/docs/contribute/guidelines.mdx +++ b/docs/contribute/guidelines.mdx @@ -1,7 +1,7 @@ --- title: Coding Guidelines description: Guidelines for writing code -sidebar_position: 2 +sidebar_position: 3 --- This project aims to be as readable and easy-to-understand as is possible towards the average programmer. As such, it is important to us that the coding style is kept consistent and clean across the entire project. @@ -16,7 +16,7 @@ Clang Format will take care of most style choices, however there are other styli ## General -- Lines should not be longer than 100 characters. +- Lines should not be longer than roughly 100 characters. - Use 4 spaces to indent. - Use spaces with operators and keywords: - :heavy_check_mark: `if (x == 1 || x == 2)` @@ -28,6 +28,7 @@ Clang Format will take care of most style choices, however there are other styli - :heavy_check_mark: `if ((foo && bar) || (x && y))` - :x: `if (foo && bar || x && y)`
The parenthesis here aren't necessary, but improve readability due to operator precedence not being immediately obvious. +- Use whitespace to separate blocks of code into more readable chunks. - Declare variables close to their usage point when possible. - Do not use `this->` with member variables unless it's absolutely necessary. diff --git a/docs/contribute/installation.mdx b/docs/contribute/installation.mdx index 62e69a39..cadb15e3 100644 --- a/docs/contribute/installation.mdx +++ b/docs/contribute/installation.mdx @@ -6,131 +6,73 @@ sidebar_position: 0 Follow these steps to set up the project. -## Set Up Dependencies +## Setting up dependencies +### Windows -The following tools will be needed for the project: +- Install [Python 3.10 or newer](https://www.python.org/downloads/) and add it to `%PATH%` +- Download [ninja](https://github.com/ninja-build/ninja/releases) and add it to `%PATH%` + - Quick install via pip: `pip install ninja` -* Python 3.10 or newer -* Build-essential tools +### macOS -If you are using a distribution under Linux or WSL2, you will also need to install either **Wine** or **[WiBo](https://github.com/decompals/wibo)**. +- Install [ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages): -You can install either WiBo or Wine but you should only install one of them. We recommend to install WiBo because it is faster and more lightweight. + ```sh + brew install ninja + ``` -If you are on MacOS (only intel-based ones), only install: +- Install [wine-crossover](https://github.com/Gcenx/homebrew-wine): -* Wine (Install it with the MacOS step below) + ```sh + brew install --cask --no-quarantine gcenx/wine/wine-crossover + ``` -Linux/WSL2: -```shell -sudo apt install build-essential python3 -``` -And if you chose to install Wine instead of WiBo: -```shell -sudo dpkg --add-architecture i386 -``` -```shell -sudo apt-get update -``` -```shell -sudo apt-get install wine wine32 -``` +After OS upgrades, if macOS complains about `Wine Crossover.app` being unverified, you can unquarantine it using: -MacOS: -```shell -brew install python -``` -```shell -xcode-select --install -``` -```shell -brew cask install wine-stable +```sh +sudo xattr -rd com.apple.quarantine '/Applications/Wine Crossover.app' ``` -## Setting Up The Repository +### Linux -1. Clone the repository and switch to it by running: -```shell -git clone https://github.com/zeldaret/tp.git && cd tp -``` +- Install [ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages). +- For non-x86(_64) platforms: Install wine from your package manager. + - For x86(_64), [wibo](https://github.com/decompals/wibo), a minimal 32-bit Windows binary wrapper, will be automatically downloaded and used. -2. Place your copy of GameCube USA Twilight Princess in the root directory and call it `gz2e01.iso` - -3. Install the necessary python modules with following command: -```shell -python3 -m pip install --user -r tools/requirements.txt -``` - -4. Setup the project by executing the following command: -```shell -./tp setup -``` - -5. Create the Expected directory (for diffing asm functions via diff.py): -```shell -./tp expected -``` - -## Building -### Building a playable ROM -To build a playable game, run: -```shell -make game -``` +## Setting Up The Repository -:::caution Note -You can add the `-j#` argument where # is the amount of threads your system has in order to greatly speed up build times. -```shell -make game -j8 -``` -::: +- Clone the repository: -To make use of WiBo (if installed), append the environment variable like: -```shell -make game WINE=wibo -``` + ```sh + git clone https://github.com/zeldaret/tp.git + ``` -### Building the DOL -To build the DOL (main executable), simply run make: -```shell -make -``` +- Copy your game disc image to `orig/GZ2E01`. + - Supported formats: ISO (GCM), RVZ, WIA, WBFS, CISO, NFS, GCZ, TGC. + - After the initial build, the disc image can be deleted to save space. -### Building the RELs -To build the RELs (Relocatable code), add the `rels` parameter: -```shell -make rels -``` +- Configure: -### Extracting game assets -To extract the game assets (non-code files) from your provided ROM, add the `assets` parameter: + ```sh + python configure.py + ``` -```shell -make assets -``` + To use a version other than `GZ2E01` (USA), specify it with `--version`. +- Build: -### Cleanup -To delete only your built DOL, add the `clean` parameter: -```shell -make clean -``` + ```sh + ninja + ``` -To delete only the built RELs, add the `clean_rels` parameter: -```shell -make clean_rels -``` +## Setting up Objdiff -To delete the built playable ROM, add the `clean_game` parameter: +Objdiff is the tool we use to compare our compiled code to the expected original code. -```shell -make clean_game -``` +Download the latest release from [encounter/objdiff](https://github.com/encounter/objdiff). Under project settings, set `Project directory`. The configuration should be loaded automatically. -To delete your entire build, add the `clean_all` parameter: +Select an object from the left sidebar to begin diffing. Changes to the project will rebuild automatically: changes to source files, headers, `configure.py`, `splits.txt` or `symbols.txt`. -```shell -make clean_all -``` +![](../../static/img/objdiff.png) ## Problems? diff --git a/docs/contribute/workflow.mdx b/docs/contribute/workflow.mdx new file mode 100644 index 00000000..4a099b5d --- /dev/null +++ b/docs/contribute/workflow.mdx @@ -0,0 +1,124 @@ +--- +title: Workflow +description: General project workflow +sidebar_position: 2 +--- + +Here we'll go over the general workflow for decompiling code and how you should be using the essential tools effectively. Note that this is just a general guide, you may choose to work however works best for you. + +One extremely important point to drive home early on is that you should be **LOOKING AT THE DEBUG ROM!!!** +The debug rom (shield_chn_debug in ghidra) is special in that it was compiled without optimizations or inlining, which means it exposes much more info about how a function was originally written than the retail versions offer. + +You should always be simultaneously looking at both the retail and debug versions in ghidra to get a proper idea of what the decompiled code should look like. If you are unsure of anything, please ask in the ZeldaRET discord for advice. + +## Choosing a file +First off you'll want to pick a file (more accurately called a Translation Unit or TU) that you want to work on. + +`d_a_obj_*.cpp` TUs tend to be smaller and easier so they're good choices when starting out, however you may pick anything that interests you. + +You can check out our [GitHub Projects](https://github.com/zeldaret/tp/projects?query=is%3Aopen) to see what TUs have already been finished or are in progress to make sure you're not overlapping with anyone else + +## Setting up classes/structs +After you pick a file to work on, you'll want to setup the necessary classes/structs as best as possible before diving into decompiling code. For actor TUs, this will usually mean setting up the primary actor-specific classes/structs. + +This will generally consist of looking through all the functions that use a given class/struct within ghidra and figuring out what data types belong at which offset within the struct. Looking at class constructors (particularly within the debug rom) can give away many of the data types that belong in a class. + +Here is a guide covering the basics of using ghidra to figure out data structures. +