mirror of
https://github.com/encounter/tp.git
synced 2026-07-11 06:18:46 -07:00
Update README and Contributing
This commit is contained in:
Pheenoh
@@ -2,46 +2,140 @@
|
|||||||
|
|
||||||
This repo contains a WIP decompilation of The Legend of Zelda: Twilight Princess (GCN USA).
|
This repo contains a WIP decompilation of The Legend of Zelda: Twilight Princess (GCN USA).
|
||||||
|
|
||||||
It builds the following DOL:
|
<!--ts-->
|
||||||
|
* [Project Setup](#project-setup)
|
||||||
|
* [Building The Game](#build-game)
|
||||||
|
* [Extract Game Assets](#extract-game-assets)
|
||||||
|
* [Create Expected Directory](#create-expected-directory)
|
||||||
|
* [Clean Directories](#clean-directories)
|
||||||
|
* [Project Overview](#project-overview)
|
||||||
|
* [Contributing](./docs/Contributing.md)
|
||||||
|
* [FAQ](https://zelda64.dev/games/tp)
|
||||||
|
|
||||||
main.dol - `sha1: 4997D93B9692620C40E90374A0F1DBF0E4889395`
|
<!--te-->
|
||||||
|
|
||||||
And will eventually build all the [RELs](./docs/rels_sha1.md).
|
Project Setup
|
||||||
|
=================
|
||||||
|
|
||||||
## Windows Prerequisites
|
1. Clone down project
|
||||||
|
|
||||||
1. Download and run the latest release of the [Windows devkitpro installer](https://github.com/devkitPro/installer/releases)
|
|
||||||
2. Run the executable located at `devkitPro\msys2\msys2.exe`
|
|
||||||
3. Update pacman by running the following command: `pacman -Syu`
|
|
||||||
4. Install the necessary dependencies by running the following command: `pacman -S python3-pip base-devel gcc vim cmake`
|
|
||||||
5. Change to the directory of where you cloned this repository
|
|
||||||
6. Install the required python dependencies with `python3 -mpip install -r tools/requirements.txt`
|
|
||||||
|
|
||||||
## Build Instructions
|
|
||||||
|
|
||||||
1. Obtain a clean DOL of TP (GCN USA) and place it at the root of the repo and name it `baserom.dol`.
|
|
||||||
2. Obtain a copy of the MWCC PowerPC compiler (version 2.7 to be exact). See below for a link to our Discord server which has the CodeWarrior compilers pinned in the #tp-decomp channel.
|
|
||||||
3. Replace `tools/mwcc_compiler/2.7/mwcceppc.exe` with the custom one also pinned in the #tp-decomp channel.
|
|
||||||
4. Run `make` at the root of the repo.
|
|
||||||
|
|
||||||
## Dump Assets
|
|
||||||
|
|
||||||
1. Place a vanilla copy of the NTSC-U version at the root of the folder and call it `gz2e01.iso`.
|
|
||||||
2. Make the game directory.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mkdir game
|
$ git clone https://github.com/zeldaret/tp
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Run make assets.
|
2. Setup compiler directory
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make assets
|
$ mkdir -p tools/mwcc_compiler/
|
||||||
````
|
```
|
||||||
|
|
||||||
|
3. Download `GC_COMPILERS.zip` from the [Discord](https://discord.gg/Nshw5pHS4h) server. See the pins in the `#tp-decomp` channel under the Twilight Princess group.
|
||||||
|
|
||||||
|
4. Extract `GC_COMPILERS.zip` into the previously created `mwcc_compiler` directory
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ unzip GC_COMPILERS.zip -d tools/mwcc_compiler/
|
||||||
|
```
|
||||||
|
|
||||||
|
5. Place a copy of NTSC-U GCN Twilight Princess in the root directory and call it `gz2e01.iso` (find this on your own)
|
||||||
|
|
||||||
|
6. Setup the project
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./tp setup
|
||||||
|
```
|
||||||
|
|
||||||
|
Building The Game
|
||||||
|
-----
|
||||||
|
|
||||||
|
1. To build a playable game, complete the [Project Setup](#project-setup) steps, then run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make game
|
||||||
|
```
|
||||||
|
|
||||||
|
The completed build is under `build/dolzel2/game/sys/main.dol`
|
||||||
|
|
||||||
|
Build DOL
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make
|
||||||
|
```
|
||||||
|
|
||||||
|
Build RELs
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make rels
|
||||||
|
```
|
||||||
|
|
||||||
|
The completed RELs will be under `build/dolzel2/rel`
|
||||||
|
|
||||||
|
Extract Game Assets
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make assets
|
||||||
|
```
|
||||||
|
|
||||||
|
Create Expected Directory
|
||||||
|
|
||||||
|
1. [Build the DOL](#build-dol)
|
||||||
|
2. Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./tp expected
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
## Contributions
|
Clean Directories
|
||||||
|
-----
|
||||||
|
|
||||||
All contributions are welcome. This is a group effort, and even small contributions can make a difference. Some tasks also don't require much knowledge to get started.
|
Clean RELs
|
||||||
|
|
||||||
Most discussions happen on our [Discord Server](https://discord.zelda64.dev/), where you are welcome to ask if you need help getting started, or if you have any questions regarding this project and other decompilation projects.
|
```bash
|
||||||
|
$ make clean_rels
|
||||||
|
```
|
||||||
|
|
||||||
|
Clean Game Directory
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make clean_game
|
||||||
|
```
|
||||||
|
|
||||||
|
Clean Build Directory
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make clean_all
|
||||||
|
```
|
||||||
|
|
||||||
|
Clean everything
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ make clean
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
Project Overview
|
||||||
|
=================
|
||||||
|
```
|
||||||
|
tp/
|
||||||
|
├── .github # Github actions for this project.
|
||||||
|
├── asm # The assembly for unmatched functions.
|
||||||
|
├── defs # Python modules used by dol2asm.
|
||||||
|
├── docs # Notes and documentation about this project.
|
||||||
|
├── include # Header files used by this project.
|
||||||
|
├── libs # Source code for the libraries based on the symbol map.
|
||||||
|
├── rel # Source code for the game RELs.
|
||||||
|
├── src # Source code for the main game.
|
||||||
|
├── tools # Various tools to support the project.
|
||||||
|
├── .clang-format # Clang format file.
|
||||||
|
├── .gitignore # Files/folders to ignore changes to when making commits.
|
||||||
|
├── Doxyfile # Doxygen configuration file.
|
||||||
|
├── Makefile # Makefile for the project containing various targets.
|
||||||
|
├── README.md # The file you're currently reading.
|
||||||
|
├── diff.py # Python script to diff two functions.
|
||||||
|
├── diff_settings.py # Settings for the diff.py script.
|
||||||
|
├── dolzel2.sha1 # SHA1 of the dol.
|
||||||
|
├── include_link.mk # Makefiles to include in the main Makefile.
|
||||||
|
├── obj_files.mk # Object files to include in the main Makefile.
|
||||||
|
└── tp # Bash script used to call the main tp python script in tools directory.
|
||||||
|
```
|
||||||
@@ -0,0 +1,57 @@
|
|||||||
|
Contributing
|
||||||
|
=================
|
||||||
|
Ghidra Setup
|
||||||
|
-----
|
||||||
|
1. Install [Java 11 64-bit Runtime and Development Kit](https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html).
|
||||||
|
2. Download Ghidra from [here](https://github.com/NationalSecurityAgency/ghidra/releases).
|
||||||
|
3. Request an account from Pheenoh#0001 on Discord (either ping him in one of the [Discord](https://discord.gg/Nshw5pHS4h) channeld or DM directly).
|
||||||
|
4. Login using the following server info:
|
||||||
|
|
||||||
|
```
|
||||||
|
Server: ghidra.tpgz.io
|
||||||
|
Port: 13100
|
||||||
|
Username: <your_username>
|
||||||
|
Password: <your_password>
|
||||||
|
```
|
||||||
|
|
||||||
|
After logging in you will see a list of all the Twilight Princess DOLs for each version.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Getting Started
|
||||||
|
-----
|
||||||
|
To begin, select a file to begin work on. You can check what files are available on [Trello](https://trello.com/b/Y04SAxbw/twilight-princess-decompilation).
|
||||||
|
|
||||||
|
This project has been automatically generated using `dol2asm`. This process generates blank headers for every source file, default includes, necessary types to be used within the file, forward references, and external references of data / functions used within the file's functions. Additionally, all data and functions have been split and generated with default types.
|
||||||
|
|
||||||
|
When decompiling a file, you will need to manually fix structs/classes, function return types, data types, and data definitions. Parameters are already setup for any function with a mangled name. Some functions / data may need to be changed to be auto-generated by the compiler, such as by inlining functions or making data in-function static.
|
||||||
|
|
||||||
|
The TP Nvidia Shield Debug Rom contains extra useful info, as it was compiled with less aggressive function inlining, and also contains debug tools / debug strings. While the primary focus currently is on the NTSC-U GameCube version, it is highly recommended to reference the Debug rom for help / documentation.
|
||||||
|
|
||||||
|
### diff.py
|
||||||
|
`diff.py` is the tool we use to fix matching errors. You can invoke `diff.py` from command line like:
|
||||||
|
`python diff.py -mwo mangled_symbol_name`
|
||||||
|
- `-m` will run make before opening diff.
|
||||||
|
- `-w` will automatically update the diff when you save your changes.
|
||||||
|
- `-o` will diff only the necessary `.o` file, which is recommended for this project.
|
||||||
|
- You can find the mangled symbol name in the function info comment. (Ex. `onEventBit__11dSv_event_cFUs`)
|
||||||
|
|
||||||
|
NOTE: You must run `./tp expected` with an OK build before diffing to have a correct binary to compare to.
|
||||||
|
|
||||||
|
You can install the requirements for `diff.py` by running `pip install -r tools/requirements.txt`.
|
||||||
|
|
||||||
|
### tp.py
|
||||||
|
`tp.py` is a multi-purpose tool that can be used for things such as checking SHA1 checksums, current decompilation progress, and removing unused assembly files.
|
||||||
|
You can invoke `tp.py` from command line either directly in the `tools/` folder, or by running the `tp` bash script.
|
||||||
|
Useful commands:
|
||||||
|
- `check` - Compares the SHA1 checksums of your current build to the ones of the expected build. Add `--rels` to check rel checksums.
|
||||||
|
- `expected` - Copies your current build folder to the expected build folder.
|
||||||
|
- `progress` - Calculates and displays the decompilation progress of the main dol. Add `--rels` to calculate rel progress.
|
||||||
|
- `remove-unused-asm` - Finds and removes all assembly files that are no longer being used.
|
||||||
|
- `pull-request` - Verifies that everything is OK before you set up a pull request.
|
||||||
|
|
||||||
|
### decomp.me
|
||||||
|
[decomp.me](https://decomp.me/) is a very useful website for sharing individual functions with other contributers.
|
||||||
|
To use decomp.me with TP, select the `GameCube / Wii` platform and `Twilight Princess` compiler preset. Enter your function's mangled name under `Function name`, and copy / paste the function assembly from the project into the `Target assembly` box. Provide any necessary context within the provided box, then create your scratch.
|
||||||
|
|
||||||
|
From here you can use the built-in editor to write your function code. Make sure to save the scratch when you are done, then you can copy and share the URL to receive help matching the function.
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Reference in New Issue
Block a user