Pokémon Puzzle League

Matching decomp of Pokémon Puzzle League

Progress graph :chart_with_upwards_trend:

Dependencies

System packages

The build process has the following package requirements:

• make
• git
• build-essential
• wget
• clang
• binutils-mips-linux-gnu
• gcc-mips-linux-gnu
• Rust

Under Debian / Ubuntu (which we recommend using), you can install most of them with the following commands:

sudo apt update
sudo apt install make git build-essential wget clang binutils-mips-linux-gnu gcc-mips-linux-gnu

uv

We use uv to manage Python and its dependencies.

See the official uv docs to install it: https://docs.astral.sh/uv/getting-started/installation/

Then run uv sync to install and update Python and any dependency needed.

If you need to run any Python script directly you can use either uv run ./script.py or enable the venv in your shell.

Rust dependencies

To install Rust, run the following command and follow the on-screen instructions (same as official docs from https://rustup.rs/):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Building

Copy your big-endian Pokémon Puzzle League ROM into the repository's config/usa directory and rename it to baserom.usa.z64. Then run the following commands to download the appropriate compiler versions, extract ROM data using splat, and build the files back into a rom.

You can pass -j N, where N is the number of cores your processor has (you can know this value by using the nproc command), to speedup the build by parallelizing.

make setup
make extract
make

If successful, the last line of output should say:

build/usa/puzzleleague64.usa.z64: OK

Other versions

By default this repository builds the USA version of this game, but it can also build the eur, fra and ger versions.

To build other versions, place your ROM in the config/VER/ directory (where VER corresponds to the specific version of your ROM) of the repo and rename it to baserom.VER.z64. Then run all the above make comands, but passing the VERSION=VER flag to them to build each version respectively.

DWARF

This repository uses the DWARF debugging information contained in the PANEPON.plf binary from the "Nintendo Puzzle Collection" Gamecube game as a reference for naming symbols and structs.

Even if at a first glance Panel de Pon and Puzzle League may seem like different games, they share big chunks of the same codebase.

You can access the DWARF dump in this repository: https://github.com/AngheloAlf/puzzle_collection_dwarf

Contributing

Check the CONTRIBUTING.md file.

Small efforts are appreciated. Just open a PR and try to address any review comments left by other contributors c:

Important note

This matching decomp effort is being done leak-free. If you have looked/worked with leaked materials (i.e. gigaleak) then it's a shame but you can't contribute to this project.

LLM policy

This project does not welcome LLM-based contributions.

The biggest reason for this is using an LLM to code sucks all the fun out from programming. This repo is one of my hobby projects, I work on it because I think it is fun what this project conveils, I don't aim for a finished project, I want to live the travel that leads to that finished project.

Each function is a puzzle on its own that I want to solve by myself, like a sudoku. Is there any fun on just seeing the solution to a sudoku instead of solving it yourself? Human-based contributions do not suffer from this problem, since you can interact with the community, pass knowledge along and see them get the same feeling of accomplishment.

If anybody wants to interact with this repository, I expect a human on the other side, not an LLM or a meat-proxy. I expect a person wanting to learn about the process, not a robocall.

Other reasons for not welcoming LLM-based contributions:

• Uncertainty of the legality of the training material for the LLM.
  • Unless you have training the LLM you are using by yourself from scratch, ther's no way to know what was used to train it, meaning it could have used copyrighted materials on its training. This is a big no for a reverse engineering project that aims to be as clean as possible and avoid any kind of legal issues.
• Enviromental concerns.
  • All the recent infrastructure development has led to a negative enviromental impact and has accelerated the climate change. I want to avoid encouraging the detrimental acts towards the world.
• Putting a price tag on a free hobby.
  • Any half decent LLM agent will require a subscription for its use. I feel this is against the spirit of OSS. Anybody should be able to work on projects like this one, not only the people able to pay that subscription.

Finally, I wish for this project to be opt-out from any usage on training LLMs.

License

The repo is licensed under the MIT license, except for files that may have its own license stated either in the top of the file or are in a folder which has its own LICENSE file.

One notable exception is the src/ folder, which is licensed under the CC0 license.

N.B.

The intention of this project is to understand the inner workings of this game better, make it easier to modify its behaviour, and have fun while working on the project itself.

As such, over and above the actual licensing of the repo, the decomp team requests that this codebase not be used to build binaries targeting non-MIPS machines ("porting").