randomprime

This repository implements a "patcher" for the subset of Metroid Prime versions released for the Nintendo Gamecube. In the simplest sense, it takes a game ISO as input, makes modifications defined by a JSON layout description, and then outputs a new ISO. The output ISO is officially compatible with Dolphin, Nintendont and GC Loader.

This repository contains no intellectual property for Metroid Prime. The only game-specific data present is information regarding the offsets/names of data known to exist on an unmodified copy of the game and custom-made assets. As such, users are required to provide their own legally obtained copy of Metroid Prime to use this patcher.

Features

To give you a taste of what's implemented, here are some highlighted features which are available via this program:

Relocate upgrades (a.k.a randomizer, the namesake of this repository)
Quality of life changes such as softlock fixes, crash fixes, hud changes, etc...
Modify scripting objects and scripting connections
Modify door colors, blast shields, room connections etc...
Place simple objects such as blocks, platforms, triggers, timers etc...

Usage

The application which best makes use of this program is randovania. It's a full-GUI application centered around randomizing the game with various settings, even supporting co-operative multiworld. It's implemented via the py-randomprime wrapper (described below)
Some "fanhacks" have been made utilizing the features exposed by this program more directly. They can be found in the metroid-prime-fanhacks repository. Be sure to check out the Creator's Guide for an in-depth dive into the patcher API and how to use it.
py-randomprime implements Python bindings for this project's feature set making it much more portable. The py-randomprime repository also builds standalone windows executable files (.exe) and attaches them to each release.

Documentation

The API is documented thoroughly at randovania.org/randomprime. Though a bit dated, some auxillary documents which may be useful can be found in the /doc/ folder.

Changelog

Updates to this program are documented as part of the py-randomprime Release Process. The versioning for py-randomprime follows Semantic Versioning. The version number exposed in the standalone application can be ignored.

Compiling

Install a Rust compiler. It is recommended to use rustup.
Add powerpc-unknown-linux-gnu as a target, like so: rustup target add --toolchain stable powerpc-unknown-linux-gnu
Clone the repo and all its submodules: git clone https://github.com/randovania/randomprime --recursive
Run cargo build

That should create a standalone executable in ./randomprime/target/debug/randomprime_patcher.exe.

Occasionally run rustup update to keep your toolchain version up-to-date.

Contributing

In order to pass this project's Pull Request requirements, your proposed change must pass the following checks:

cargo fmt --check
cargo clippy -- -D warnings

You can use these commands to fix most issues automatically:

cargo fmt
cargo clippy --fix --allow-dirty

Resources

Some helpful resources for those starting out with modding Metroid Prime can be found in the Metroid Prime Fanhacks repository. Furthermore there's:

randovania / randomprime

readme