Super Metroid Map Rando

This is the repository for the Super Metroid Map Rando project, which randomly rearranges how the Super Metroid rooms connect to each other, creating fresh randomized worlds for players to explore.

Development

If you are interested in contributing, feel free to reach out on the Discord. There are a few ways to run the randomizer for development, described in detail below.

Run the web service using Docker
Run the web service using Cargo
Run the CLI using Cargo

Using Windows

If you are running on Windows, be sure to enable symlinks in Git before cloning the repository:

git config --global core.symlinks true

You likely also need to enable "Developer Mode" in Windows settings in order for Git to have permissions to create symlinks.

Clone the repository

Clone the repository:

git clone --recurse-submodules https://github.com/blkerby/MapRandomizer
cd MapRandomizer

Run the web service using Docker

Install Docker if it is not already installed on your system.

Docker Compose build and run

docker-compose up --build

Manual Docker build and run

Build the Docker image:

docker build . -t map-rando

Run the web service:

docker run -p 0.0.0.0:8080:8080 map-rando /rust/maprando-web --seed-repository-url mem

Open a browser and navigate to localhost:8080 and you should see your locally running copy of the Map Rando website.

With the option "--seed-repository-url mem", any randomized seeds that you generate are stored in memory. You can also use "--seed-repository-url file:my-seeds" to store the seed data as local files under "my-seeds", where you could inspect the data.

Run the web service using Cargo

Building and running locally using Cargo is generally faster than using Docker, as you can take advantage of incremental compilation.

Install the stable Rust toolchain (e.g. using rustup).

After cloning the GitHub repository, download and extract the randomized map pools:

mkdir maps && cd maps
wget https://storage.googleapis.com/super-metroid-map-rando/maps/session-2023-06-08T14:55:16.779895.pkl-small-71-subarea-balance-2.tgz
mv session-2023-06-08T14:55:16.779895.pkl-small-71-subarea-balance-2.tgz tame-maps.tar.gz && tar xfz tame-maps.tar.gz
wget https://storage.googleapis.com/super-metroid-map-rando/maps/session-2023-06-08T14:55:16.779895.pkl-small-64-subarea-balance-2.tgz
mv session-2023-06-08T14:55:16.779895.pkl-small-64-subarea-balance-2.tgz wild-maps.tar.gz && tar xfz wild-maps.tar.gz
cd ..

Run the web service:

cd rust
cargo run --bin maprando-web -- --seed-repository-url mem

Run the CLI using Cargo

As an alternative to using the web service, a CLI tool can also be used to generate a seed, to get results with fewer steps. At the moment, the CLI tool has many randomization options hard-coded into it and is intended for development rather than general use.

After cloning the GitHub repository and downloading/extracting the maps (as above), run the CLI tool like this:

cd rust
cargo run --bin maprando-cli -- --map ../maps/session-2023-06-08T14:55:16.779895.pkl-small-64-subarea-balance-2/10005.json --item-placement-seed 1 --input-rom YOUR-PATH-TO-VANILLA-ROM --output-rom OUTPUT-ROM-FILENAME