From 92e457e60c20c0bfebbeb0e23dd6201f64b53c63 Mon Sep 17 00:00:00 2001 From: toasterparty Date: Tue, 23 Jan 2024 14:08:43 -0800 Subject: [PATCH] readme --- README.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6a8923da..1fdbeaa1 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,48 @@ # randomprime -the patcher for metroid prime 1 in randovania +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. -`master` - dirty fork of `aprilwade/randomprime` +*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.* -`randovania` - based off master, developed into the version used by [randovania](https://github.com/randovania/randovania) via [py-randomprime](https://github.com/randovania/py-randomprime) +## Features -# Compiling +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](https://github.com/randovania/randovania). It's a full-GUI application centered around randomizing the game with various settings, even supporting co-operative multiworld. +- Some "fanhacks" have been made utilizing the features exposed by this program more directly. They can be found in the [metroid-prime-fanhacks](https://github.com/toasterparty/metroid-prime-fanhacks) repository. Be sure to check out the [Creator's Guide](https://github.com/toasterparty/metroid-prime-fanhacks/blob/main/doc/readme.md) for an in-depth dive into the patcher API and how to use it. +- [py-randomprime](https://github.com/randovania/py-randomprime) implements Python bindings for this project's feature set making it much more portable. + +## Documentation + +The API is documented thoroughly at [randovania.github.io/randomprime](https://randovania.github.io/randomprime). Though a bit dated, some auxillary documents which may be useful can be found in the [/doc/](./doc/) folder. + +## Changelog + +Updates to this program are documented as part of the [py-randomprime Release Process](https://github.com/randovania/py-randomprime/releases). The versioning for py-randomprime follows [Semantic Versioning](https://semver.org/). The version number exposed in the standalone application can be ignored. + +## Compiling 1. Install a Rust compiler. It is recommended to use [rustup](https://www.rust-lang.org/tools/install). 2. Add `powerpc-unknown-linux-gnu` as a target, like so: `rustup target add --toolchain stable powerpc-unknown-linux-gnu` -3. Clone the repo and all its submodules: `git clone https://github.com/toasterparty/randomprime --recursive` +3. Clone the repo and all its submodules: `git clone https://github.com/randovania/randomprime --recursive` 4. Run `cargo build` That should create a standalone executable in `./randomprime/target/debug/randomprime_patcher.exe`. +## Resources + +Some helpful resources for those starting out with modding Metroid Prime can be found in the [Metroid Prime Fanhacks](https://github.com/toasterparty/metroid-prime-fanhacks/tree/main/doc#resources) repository. Furthermore there's: + +- [PowerPC 750cl ISA](https://fail0verflow.com/media/files/ppc_750cl.pdf) and [Appendix F](https://www.nxp.com/docs/en/user-guide/MPCFPE_AD_R1.pdf) +- [Godbolt](https://godbolt.org/) +- [Metroid Prime Crash Parser](https://metroidprimemodding.github.io/prime-crash-parser/crash.html) +- [Last Metaforce Commit with DATASPEC](https://github.com/AxioDL/metaforce/tree/1655d229cfdfbd5f792a7c3e84adc862653f70a7) +- [Unused Memory Locations](https://github.com/MetroidPrimeModding/prime-practice-native/blob/main/unused_memory.txt)