randovania / open-samus-returns-rando

Randomizer patcher for Metroid: Samus Returns

Randovania

Welcome to Randovania, a randomizer platform for a multitude of games.

New here or looking to install? Check our website.

Supported Games

• Another Metroid 2 Remake
• Cave Story
• Metroid Dread
• Metroid Prime
• Metroid Prime 2: Echoes
• Metroid: Samus Returns

Randovania can randomize many aspects of its supported games, all while still ensuring they're completable without using any glitches or exploits. Its features include:

• Randomizing what can be found in each item location. Weapons, keys, and more can end up in completely new places.

• Use Multiworld sessions to shuffle items between multiple separate games, alone or with friends. All Multiworld games are compatible with each other - mix and match as you like!

• Randomize how areas connect to one another, or what resources are required to travel between areas. These options are highly customizable, letting you limit or unleash the chaos.

• Randomize your starting equipment and location. Feeling brave? You can even shuffle items you normally start with.

Have fun and start randomizing!

Installation

In the releases page, we have zip files with everything ready to use. Just extract and run!

For Linux users, we recommend using our Flatpak instead.

Community

Join the Randovania Discord: https://discord.gg/M23gCxj6fw

Invite links for specific games' servers can be found in the #game-communities channel in our server.

Credits

GUI and logic written by Henrique Gemignani, with contributions by SpaghettiToastBook, gollop and many others.

BashPrime, Pwootage, and April Wade made https://randomizer.metroidprime.run/, from which the GUI was based.

Website created by Hugoshido and duncathan_salt. portfolYOU Jekyll theme by Youssef Raafat. Free for personal and commercial use under the MIT license.

Installer is powered by Advanced Installer, which has graciously provided us with an open source license.

Linux Flatpak build contributed by Ethan Lee.

Games

Metroid Prime

• Game patching via randomprime. Originally authored by April Wade, it is now maintained and developed by toasterparty with contributions from others
• Room data collected by UltiNaruto, EthanArmbrust and SolventMercury.
• Converting Metroid Prime 2 models by Migs.

Metroid Prime 2: Echoes

• Game patching written by Claris.
• Room data initially collected by Claris, revamped by Dyceron.
• Menu Mod created by Claris. For more information, see the Menu Mod README.
• Converting Metroid Prime models by Migs.

Cave Story

• Patcher and logic written by duncathan_salt.
• Based on the original randomizer by shru.
• Features contributions from many others.

Metroid Dread

• Game Patching by:

  • Henrique "Darkszero" Gemignani
  • duncathan_salt
  • ScorelessPine
  • Arcanox
  • Migs
  • hyperbola0
  • Thanatos

• Logic Database by:

  • KirbymastaH
  • Dyceron
  • XenoWars
  • Mayberry
  • Hugoshido
  • Tyranisaur

• Assets by:

  • Morph Ball and Speed Booster pickup textures created by BigSharkZ.
  • Spider Magnet pickup texture by duncathan_salt with help from BigSharkZ.
  • New map icons by SkyTheLucario.

Another Metroid 2 Remake

• Game Patching by:

  • Miepee
  • JesRight

• Logic Database by:

  • Miepee
  • DruidVorse
  • JeffGainsNGames

• Assets by:

  • Morph Ball, and the Missile Launcher sprites were made by ShirtyScarab554 licensed under CC BY-SA 4.0.
  • Power Grip and the Shiny Nothing Orb were made by ShirtyScarab554, used under CC BY-SA 4.0, modified by AbyssalCreature and licensed under CC BY-SA 4.0.
  • New door sprites and other AM2R item sprites were made by AbyssalCreature licensed under CC BY-SA 4.0.

Metroid: Samus Returns

• Game Patching by:

  • Dyceron
  • Thanatos
  • Henrique "Darkszero" Gemignani
  • duncathan_salt
  • Merikatt

• Logic Database by:

  • Dyceron
  • Miepee
  • Haxaplax

Auto Tracker

Primes

• Game theme assets were provided by MaskedTAS.
• Pixel theme assets were provided by Uncle Reggie.

AM2R

• AM2R 1.5.5 item sprites were made by Eskimode7 licensed under CC BY-SA 4.0.
• The AM2R DNA sprite was made by AbyssalCreature licensed under CC BY-SA 4.0.
• The AM2R Morph Ball and Power Grip sprites were made by ShirtyScarab554 licensed under CC BY-SA 4.0.

Metroid: Samus Returns

• Game theme assets were provided by Dyceron.

Multiworld

Server and logic written by Henrique "Darkszero" Gemignani.

Primes

Dolphin and Nintendont integrations written by Henrique "Darkszero" Gemignani. These were based on Dolphin Memory Engine and Pwootage's Nintendont fork, respectively. In-game message alert initially written by encounter.

Cave Story

Cave Story Doukutsu and CSE2 Tweaked integations written by duncathan_salt, periwinkle and ikuyo.

Metroid Dread

Integration written by Thanatos and Henrique "Darkszero" Gemignani. The "unplug" icon is by tezar tantular from Noun Project (licensed under CC BY 3.0).

Another Metroid 2 Remake

Integration written by Miepee. Offworld sprites are licensed under CC BY-SA 4.0 and are made by AbyssalCreature, ShirtyScarab554 and many others.

Metroid: Samus Returns

Integration written by Thanatos.

Developer Help

Dependencies

• Python 3.12 64-bit
• Git

Setup

Getting started:

1. Clone this repository. (downloading the zip is not supported and will not work)
2. Open a terminal in the repository root
3. Run the following file:
   1. Windows: tools/prepare_virtual_env.bat
   2. Linux/macOS: tools/prepare_virtual_env.sh
4. You should see "Setup finished successfully." visible when the command finishes.
5. For certain use cases, such as exporting games or running tests, additional setup is needed.

In order to start Randovania, open:

1. Windows: tools/start_client.bat
2. Linux/macOS: tools/start_client.sh

In order to update your repository:

1. Update the git repository. (With git pull or anything else)
2. Make sure that Randovania is closed.
3. Re-run the steps from "Getting Started", starting at step 2.
   1. In case of unexpected errors, delete the venv in the root of the repository and start again.
4. Open Randovania normally.

In order to be able to export games:

1. Run both "Getting started" and "Start Randovania" steps.
2. Activate the virtual env. Check start_client.bat/sh for details.
3. Run python -m pip install -r requirements.txt.

In order to run the tests:

1. Run both "Getting started" and "Start Randovania" steps.
2. Activate the virtual env. Check start_client.bat/sh for details.
3. Run python -m pip install -r requirements.txt.
4. Run python -m pytest test.

In order to run the server:

1. Run both "Getting started" and "Start Randovania" steps.
2. Activate the virtual env. Check start_client.bat/sh for details.
3. Run python -m pip install -r requirements.txt.
4. Run python tools/prepare_dev_server_config.py once.
5. If you wish to use any Discord functionality, you'll need to create an app in Discord and fill both ids in tools/dev-server-configuration.json.
6. Run the server and client. You can this on
   1. Windows with tools/start_dev_server.bat for the server and tools/start_debug_client.bat for the client
   2. Linux/macOS with tools/start_dev_server.sh for the server and tools_start_debug_client.sh for client

This repository uses pre-commit. The hook is automatically configured with the prepare_virtual_env scripts.

Suggested IDE: PyCharm Community

Visual Studio Code

Clone this repository and open the folder in Visual Studio Code. It suggests several useful plugins for developing which you should download and install.

If your Python is setup properly, you can use the Create venv with all exporters task by pressing CTRL+SHIFT+P, type in Task, select Tasks: Run task and then select the task. It will create the venv with all the dependencies installed for you.

There is also a task defined to run all tests. To run individual tests you can utilise the Testing section of Visual Studio Code. You can simply run or debug a test there.

To start Randovania you can press CTRL+F5. If you only press F5, Randovania will start with a debugger. Be aware that starting with a debugger makes the application much slower.

Documentation

• Unfamiliar with a term? Check the glossary.
• Adding a new game? Check the dedicated guide.
• Changing a data format? Check the migrations documentation.
• Working with the logic database?
  • Read how the database is organized.
  • Read the unfinished script for a video on how to use the data editor.

open-samus-returns-rando's Issues

Keep Fleech Swarms active even after collecting Gravity Suit

After collecting Gravity Suit, if a scenario has Fleech Swarm, they get disabled. If you collect Gravity in the same scenario that has Fleech Swarm, they remain active, but when in contact, they latch onto Samus dealing no damage, and then the Hive deactivates

Disable Chozo Seal cutscene when collecting first DNA in Surface

Also activate the Chozo Seal automatically outside of the cutscene

Pre-Chozo Seal activation collision_cameras activate when returning all DNA for an area

I haven't tested every area, but this does happen in Surface, so I suspect that the collision_cameras weren't disabled properly.

Force Multi-Room Gammas to spawn/remain in same room

Makes maintaining the database easier and also saves headaches.

Increase tile range of Scan Pulse

CTunableMinimapScenario: iScanningPulseRadiusInTiles

Could be an alternative to #36

Support shuffling items onto Metroids

Implement Boss/DNA Door Locks

For whenever Door Lock rando is relevant in the far future

Reloading from checkpoint/save respawns randomized items

Seems to only apply to Major Items. Tanks do not respawn. This is likely due to checkpoint shenanigans.

Item Balancing

Certain items could be balanced to create a more enjoyable randomizer experience.

Power Bombs

• Can open all beam doors (Charge, Wave, Spazer, Plasma)
• Can destroy Blob Throwers and Steel Orbs

Solution: Remove PB vulnerability from these actors to give their respective items more use

Screw Attack

• Requires two hits to kill late game enemies since it's a mid game item
• This can be annoying since Screw Attack should be really powerful

Solution: Greatly increase the damage output of Screw Attack

Plasma Beam

• Heavily nerfed compared to Spazer and Wave during the Ridley fight

Solution: Buff Plasma or nerf the other beams to match Plasma against Ridley

Add the devs to the credits

Unlock Hard and Fusion Mode from the start

Item from Arachnus faces the wrong way

If the item that Arachnus drops is a tank, it will face to the right. This does not affect Major Items because they rotate and are viewable from all angles.

Progressive Beam uses the Itemsphere model

Make all heated rooms real

Improve traversal between areas

Area 1

The Crumble blocks leaving the area forces having Spider or Clipping to leave.

Solution: Remove these blocks so only Morph Ball is required.

Charge Doors

These are at the entrance/exit of every except Area 8 and Surface West. It pretty much forces needing Charge or PBs or Beam Burst early to just travel into areas.

Solution: Change these doors into Power Doors

Grapple Blocks

Leaving Areas 5-7 requires moving a Grapple block to access the next area. This is especially bad for random start/elevators, since backwards traversal in these areas is impossible unless you enable tricks, which is not a good thing IMO.

Solution: Set the blocks to post-state (pulled or broken)

---

Should these be toggleable? Does it enhance the rando to keep/remove them? Having a mostly open path to get around the map could improve the experience a lot.

Possible option to implement a remote connector

Some notes for future which maybe makes it doable:

• Use Magikoopa https://github.com/RicBent/Magikoopa for injecting / hooking code
• Magikoopa patches the binary and the exheader. See https://citra-emu.org/help/feature/game-modding/ for reference where to place the files
• find luaRegisterGlobals and lua_pcall in SR binary
• we need the socket service https://www.3dbrew.org/wiki/Socket_Services https://libctru.devkitpro.org/index.html
• ...which should be available in citra's HLE: https://github.com/citra-emu/citra/blob/cab0ad50f00837014cd910f7406eed9e6281360f/src/core/hle/service/service.cpp#L96C9-L96C9 and https://github.com/citra-emu/citra/tree/master/src/core/hle/service/soc
• Easy part is probably the lua itself: This could be copied up to 99 % from dread

If the whole stuff really works: Find a way to make it usable for non-devs.

Collecting a suit while morphed only updates the morph model

Starting at a teleporter softlocks the game

Likely because the teleporter isn't active yet, so the game doesn't know what to do. Might need to activate the teleporter in the blackboard first.

https://youtu.be/tOysFdwkXoU?t=16

Suit model override

Collecting Varia Suit after having Gravity Suit changes the model to be Varia. Reloading the file/reloading checkpoint reverts the suit model back to Gravity.

Suits, Aeion Abilities, and the Baby require a reload to be visible/use

White Flash when collecting a suit

Even after removing the suit cutscenes, the screen flashes white. This should be removed.

SJ in 2c

Looks like it is missing a dependency. See: #89 (comment)

Prevent going to the item status screen after getting a major

Big QoL that improves flow of the game

See https://github.com/dyceron/MSRScripts/blob/main/MSRScripts/romfs/gui/scripts/guicallbacks.lua

Items do not display properly in certain areas

When items are placed in different areas, how they appear varies even though their dependencies are set. These issues need to be fixed:

• Textures do not load
• Models do not animate
• Aeion Ability FX does not display properly

"damage_alarm.wav" no longer plays while inside damageplants

Enable amiibo reserves without needing amiibo

Possibly find a way to shuffle them into the item pool as well

Add guaranteed Ice Beam hint

If Chozo Seals will be used for hints, possibly make a copy of one and put it in the room before the first Larva Metroid in Area 8. No DNA requirement necessary.

Most items remove the block that hides them

Certain items in the game are locked inside breakable blocks and aren't accessible until after the block is broken. When certain items are placed in these locations, they remove the block that is hiding them, thus removing requirements. The items that do work properly are as follows:

• Energy Tank
• Missile Tank
• Super Missile Tank
• Power Bomb Tank
• Aeion Tank
• Spider Ball
• Space Jump

Example of Plasma Beam being placed and not having a bomb block covering it

Support Warp to Start

Remove intro storyboard cutscene

Implement random elevators

Change beam door covers to be properly double sided

Non-Beam Covers (Missile, Super, Power Bomb) can be opened on either side of the door, even on the side you aren't supposed to access. They have the proper collision, but do not visually appear on the wrong side.

Beam Door Covers on the other hand can be opened from the backside, but the collision/actor does not transfer over. In order to open them from the wrong side, you have to place Samus up against the door and shoot backwards through the door at certain angles to open the lock. There are situations where opening from the back might be impossible, so it might be best to change every beam door cover to be easily accessible from both sides and have the proper visuals.

Changing all door covers to be easily accessible from both sides would be a good QoL.

Some items are invisible

Some items do not spawn

I'm not sure why they aren't spawning. They exist in the json but just do not spawn. Might be overloading?

This location is supposed to be Phase Drift but I did not collect it nor does it appear.

Add custom texture/model for Baby Metroid pickup

Either use itemsphere or make a custom texture for the baby

Reload required when activating multiple teleporters in the same scenario

If you activate a teleporter in a scenario that has multiple teleporters, and it's the first one activated in the game, the first one will not activate even after a second one is activated until a reload happens.

Use Chozo Seals for hints

Either for Major Items or DNA in the area

Make them require x amount of DNA to use, using a global DNA amount

QoL: Disable locking Metroid doors during fights

• Locked doors might cause issues with Door Lock Rando
• Reduces need for reloading save/checkpoint if the player lacks Ice/enough Missiles to beat the Metroid variants that don't give drops
• No real reason to keep the player locked inside, since there is no acid to be lowered anymore and DNA will eventually be shuffled
• It allows the player to refill or bypass the fights without hindering potential paths

Add Music Shuffle

Ideally have two options:

• Shuffle all music together
• Shuffle areas and metroid/bosses separately

Update Map Icons

This is what item icons look like on the vanilla map

• Tanks are open circles when the tile is not visited, and then change to the correct icon after being visited/exposed.
• Powerups always use the itemsphere orbs regardless of being visited or not.
• Statues are always just visible.

Ideally, we should change the powerup tiles to also use the open circle when not visited, because Scan Pulse would reveal majors when it shoudn't. The statues can stay just because they show the location of the item, though maybe we could do away with this too.

Map with majors changed

Map with majors and statues changed

Allow for the Baby Metroid to be shuffled

Properly support exporting games

Citra/3DS might be different as well, so we'd have to account for that

Progressive Models do not animate

2023-08-30_19-32-56-1.mp4

Prevent access to "fake" West Surface from East Surface until Ridley condition is met

Warp player to other Surface scenario on both sides until enough DNA requirement is met. Also solves issue of duplicate items off of the Landing Site

Prevents this https://youtu.be/gOaW8hpZhUc

Restore SpecialEnergyOrb to Major Pickup locations

Prevent Chozo Seals from decreasing DNA amount

Since DNA will be the end game requirement and Chozo Seals are eventually planned to be used for hints, changing this behavior is mandatory.

Remove checkpoints from Major Items

Reveal map from the start

Might be found in minimap.lua

Fix starting inventory

Our current schema requires to have ITEM_MAX_LIFE in the patcher file.
e.g.

        "starting_items": {
          "ITEM_MAX_LIFE": 99,
          ....
        },

The inventory is recalculated in the patcher to pop the energy tanks and add them to ITEM_MAX_LIFE

    final_inventory = {
        "ITEM_MAX_LIFE": max_life,
        "ITEM_MAX_SPECIAL_ENERGY": max_aeion,
        "ITEM_METROID_COUNT": 0,
        "ITEM_METROID_TOTAL_COUNT": 40,
        "ITEM_WEAPON_MISSILE_MAX": 0,
        "ITEM_WEAPON_SUPER_MISSILE_MAX": 0,
        "ITEM_WEAPON_POWER_BOMB_MAX": 0,
    }
    final_inventory.update(inventory)

The last line updates the values from final_inventory with the ones in inventory, so ITEM_MAX_LIFE it is set back to "ITEM_MAX_LIFE": 99, from patcher file.

Collecting Gravity Suit Underwater/Underlava does not remove liquid effect

This is a major bug because reloading to save directly causes the effect to be permanent until you restart the game.

A temporary solution until #13 is fixed is to reload from checkpoint first which does remove the effect, but this is not ideal.