randovania / randomprime

Prime1 patcher for Randovania and a few other things.

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

1. Install a Rust compiler. It is recommended to use rustup.
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/randovania/randomprime --recursive
4. 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:

• PowerPC 750cl ISA and Appendix F
• Godbolt
• Metroid Prime Crash Parser
• Last Metaforce Commit with DATASPEC
• Unused Memory Locations

randomprime's Issues

Support building on macos-arm

GH's macos runner switched to arm by default.
x86_64 is still supported for the time being, but we should really try to figure out what stops it from compiling and fix it

Example log: https://github.com/randovania/randovania/actions/runs/8899395603/job/24438949675

Scan Visor bug when shuffling all Visors

When shuffling all visors, if Scan is the first visor received, you cannot access it until a combat capable visor is received.
To add more context:
You start with a Ghost Scan Visor
If you morph and unmorph, your ghost sscan visor becomes a ghost visor
If you receive scan visor after this fact, you can not select scan visor UNTIL a functional combat visor is received

Link to discord thread: https://discord.com/channels/914291389293027329/1171556720426876971

Shift message on title screen further to the left

It can currently clip on longer seed hashes

Have a seperate model for power beam thats distinct from the offworld item

Incorrect position for custom door locks and invisible background texture.

Position

Currently the way blast shields are placed on doors is to be placed on the exact same coordinates of the glow ring Actor, and then have a position offset based on that. This is wrong, they are supposed to have the coordinates of the door, as they were designed that way, not only it looks ugly, this implementation causes rotated doors to have the blast shields be displaced.

Ceiling/Floor doors

These doors use an ANCS different from regular doors, not only that they are slightly bigger in size, because there is no dedicated blast shield actor for them, they would not fit properly at all by just copying the door's position/rotation values, the added offset is required for them.

• Regular Door
  

• Vertical Door
  

Currently Besides having incorrect scaling values added to them, they are in the wrong position with the wrong rotation. An ideal scaling for them would be [1.1776, 1.8, 1.8] instead of [1.6, 1.6, 1.6] and rotated accordingly to the cardinal direction the door is at.

• Current
  
  

• Proper
  
  

Background texture

The hit detection trigger gets deactivated on room load via a 1 frame auto-start timer so they can't be shot, this causes the side effect of the moving cloud texture not being visible.

This can be solved in two ways:

1. Instead of the 1 frame timer sending DEACTIVATE to the damageable trigger, make it send INCREMENT instead, this will cause the dtrigger to become invulnerable, then make it receive DECREMENT when both the blast shield actor breaks or when the door gets OPENed from the other side and it will cause the dtrigger to become vulnerable again.
2. *Make the Blast Shield Actor have the IsSolid flag true, and edit the CollisionBox and CollisionOffset so they surround the damageable trigger entirely and cause it to never be able to be shot in any way. This also removes the need to use the helper damageable trigger that takes care of the actual thing to shoot at to open the door, though if the lock-on behavior is intended to be kept, it could be made so it's vulnerabilities are PassThrough so it can hit the blast shield.

Make an exception for Hall of the Elders floor door as it will cause the statue to get stuck.
6/13/24 edit: If done correctly this shouldn't happen, so the actor can stay solid here.

• Current
  

• Proper
  

Phazon Infusion Chamber Soft-Lock

...we got a seed where we could leave the Phazon Infusion Chamber from one way anywhere, but if you leave and go back in the fight apparently soft locks. That happened to me...

a) remove phazon infusion chamber as elevator destination/spawn point
b) add an entry in the readme warning to not backtrack
c) move the spawn point into the fight trigger so that there is no option to backtrack
d) fix the soft-lock, thus allowing the player to back out of the fight without ruining the game

I'm always partial to just fixing the soft lock for these kinds of things

Power Only Vertical doors don't have proper colors

The door should be fully yellow.

Relevant bug thread: https://discord.com/channels/914291389293027329/1232354188755861596

Support setting custom SCAN for objects

Providing a way to set the Scan File used for entities would be nice.
something akin to

"12456789": {
  "scanEntry": {
    "strg": [
        "This is Bob",
        "Names",
        "Bob likes to hydrate regularly. Be like Bob."
    ],
    "scanSpeed": 10,
    "logbookCategory": 0,
    "critical": true,
    "images": [
      {
        "textureID": 987654321,
        "appearancePercentage": 0.01,
        "imagePosition": 1,
        "width": 0,
        "height": 0,
        "interval": 0.0,
        "fadeDuration": 0.0
      },
      // repeat for all 4 images
    ]
  }
}

Feature: Missile/Power Bomb launchers / Required Mains

Apparently no one made an issue for this yet here.

Prime 1: seeds are indistinguishable in game folders

Also, the title doesn't show any sort of identifying change - it's still just "Metroid Prime", with very little way to determine which seed it is. I currently have two seeds in my game folder.
Prime 2 seeds follow "Metroid Prime 2: Randomizer - " naming scheme, maybe Prime 1 generation should be updated to mirror this

From randovania/randovania#2168

FEATURE: Scan visor doors

IIRC THose were on the list:tm: to add.

PAL Export error: Attempt to subtract with overflow

If generating a PAL Prime iso with qolCosmetic turned off, this error shows up.

When using API which is hinting at adding room properties, have a field on whether it should throw when editing existing IDs

Stuff like room.distanceFog will either add distanceFog objects or edit distanceFog objects depending on if the ID already exists or not.
However, from a user PoV, it is hard to know whether one accidentally used an id that already exists.
Thus, some field (that doesn't break backwards compatibility with older jsons) would be nice to have added where it then fails when you're editing a property when you meant to add a new one. Suggestion would be to name it throwOnEdit.

Same goes for relays, triggers, hudMemos, etc.

Option to replace power bomb drop obtain SFX to the one from Echoes

Prime 1: Add support for required mains

Patcher needs to support require mains on for Missiles and Power Bombs

Control Tower Sometimes Flys off into the distance

I've seen about 3-4 bug reports on this, and unfortunately dismissed most of them to "Because PrimeHack"

This seems to affect players who don't do the fight skip, one reporter describes their exact steps:

0. Play on Nintendont with starter preset (Competitive by default)
1. Trigger fight from Observatory side
2. ignore all pirates
3. shoot tower by SJ-ing from boxes

i've played like 100 randos on dolphin and nintendont and never had this bug happen

New practice mod and rando do not stack

Legacy practice mod works fine, but new practice mod renames the dol and does a couple other things that are incompatible.

Apply Color Rotations to Fusion Suit

Scale "etank regen rate" when switching between samus and morph based on energy per etank

Just something I noticed in a multi with someone who set their energy per tank to 1000. it can take multiple rooms to refill the energy bar to the correct value at high values.

Probably need to find which function increases the displayed number each frame, and scale that factor by ETANK_CAPACITY / 100.

Plateed Beetle having no aggro if its cutscene is skipped in ruined shrine

https://clips.twitch.tv/CrypticAbstruseTray4Head-6pp8mf1Dzlmz3CGY, skippable competitive

link to discord thread: https://discord.com/channels/914291389293027329/1169793744376172695 , includes a video of what should happen.

Suggestion: Custom Scan Text for Community-Named Enemies

If someone writes up the room/community name for all joke names of enemies, I will put in a setting to replace their scans to read their name. This actual has some non-meme usage, as knowing which pirate is "Edward" helps you have more clear/meaningful conversations about various parts of the game.

Expose option of enforcing whether an item gets to play a major/artifact fanfare when collected

FR: Hard require thermal for thermal things

At the very least thermal conduits, maybe other things like thardus too.

Unbreakable Totems during Ridley fight

Shale — Today at 6:33 AM
When there are extra artifacts in the Prime item pool, any artifacts not collected at time of the Ridley fight will mean their corresponding pillars are unbreakable. Having unbreakable pillars in the fight genuinely makes it harder, both because it makes getting out of the way of attacks harder & because each one is one less health/ammo drop. If there's a way to set all pillars to their "artifact collected" state at the start of the fight, that would be much appreciated

Relevant bug reports thread: https://discord.com/channels/914291389293027329/1221865313310736464

The following scenario should also hopefully not break: have 1 out of 6 artifacts, you collect 1, go fight ridley, the statues break because of the fight, then collect the other 5 and bring them back to artifact temple

Central Dynamo locking door to Quarantine Access A in PAL when item is not collected

This forces you to collect the item, which doesn't happen in NTSC.
Link to discord thread: https://discord.com/channels/914291389293027329/1182037047372955688

2nd digit of the current PB capacity gets truncated away on morph ball HUD

Edit the FRME to make space for it

Metroid Prime 1 - Door Lock Rando Fails to Apply Proper Blast Shield in Research Core Following Power Outage

Game: Metroid Prime 1 (NTSC 0-00)
Emulator: Dolphin 5.0-21174 (Windows)
Randovania: 7.4.2 (Windows)

Permalink: DerUcq0uTokZ4BssjW3HVGhc8rTsTBI-lNjCAyI7HM7jqOd8vdz0yDKU9sCwJN5LuoTokXqDr-4AAN3f

In Metroid Prime 1 with door lock randomization enabled, some vanilla Wave Beam doors may be randomized as blast shield doors. This is the case in the included demonstration permalink, wherein the Wave Beam door in Phendrana Drifts - Research Core leading to Research Core Access has been shuffled to a Super Missile blast shield. However, when the item in Research Core is collected, leading to the power outage event, the blast shield fails to appear properly over the door. The blast shield is physically present and deflects all other weapons fire, but it cannot be scanned or visualized in any visor. The blast shield is invisible and can only be opened by knowing there "ought to be" a blast shield present, and firing a Super Missile accordingly.

Steps to reproduce:

1. Import the included demonstration permalink, or create a randomized Prime 1 world which randomizes Wave Beam doors to Super Missile blast shield doors.
2. Enter Research Core in Phendrana Drifts and collect the item therein.
3. The power will go out. Energize the energy conduit at the top of the room.
4. Attempt to open the door to Research Core Access. Though it appears to be a blue door, an invisible Super Missile blast shield is present which will deflect all other weapons fire.

Expected behavior: Any blast shield applied to the door leading from Research Core to Research Core Access should be visible, or failing that, disabled to prevent player confusion.

Cross-game models don't have the post obtain particle.

0deb9456.PART.mp4

Prime: Geothermal Core Platform Visibility

The collision in front of the door to Plasma Processing is invisible. Future versions have changed it to be visible. It would be a nice QOL improvement to have this for rando.

Add option to reduce volume of acid damage

from dan:

Reduce the volume [...] to like 75% its current volume. It's uncomfortably loud compared to other SFX.

Softlock if you don't skip the Omega Pirate's death cutscene

If you don't skip the Omega Pirate's death cutscene:

• Letterboxing and Samus' cutscene model won't go away.
• The doors and the elevator will stay locked, which essentially softlocks you in Elite Quarters.

This wasn't a thing on the patcher's versions 1.22.1 and below (the only issue in these versions is that the music doesn't start playing, just like in the vanilla 0-00).

Prime 1: Map QOL improvements

• Rooms are in "used map station" state by default (aka blue rooms)
• Optionally select to show room names for blue rooms.
• Configurable which rooms aren't visible by default, as to hide elevator rooms

Improve UX with less artifacts required than shuffled

Currently, its not quite clear in-game that this setting is enabled / how many are actually required.
If you go to artifact temple, the layers/scan totems for all shuffled are active. But if you have somehow forgotten about your preset (or mixed it up with a different one, or has been given an rdvgame by someone else) there's no indication in-game on how many artifacts are required

Ideas:

• have a scan point somewhere near the middle totem detailing how many are required to (still?) collect
• have a message pop up when you collect all required ones.

Crash - Specific rooms can have "too many" blast shields

The following rooms have caused an "alloc-failed" crash due to this:

Biohazard Containment <--> Biotech Research Area 1

• Might need unlocked read speed for this crash
• IIRC the load triggers are not ideal here

Central Dynamo

• We already remove all the debris in this room and adjacent. Will be tricky to find more to remove

Option to change completion% calculation from inventory to # of locations collected

I'm thinking:

• dol patch to increment power suit capacity every time a non-refill pickup is acquired
• dol patch to use power suit capacity for inventory calculation
• optional config to specify denominator of completion calculation (default=100)

15th E-Tank and above are invisible on HUD

Prime1: General Colorblind Support for Prime1

Some features of prime 1 can cause issues for colorblind players.

Such as:
Colors for Metroid Prime Boss
Colors for Impact Crater Metroids
Colors for Beam Specific Pirates

Any other examples that can be found can also be included in this feature.

As of now the best implementation I can think up would involve the user specifying the color they prefer for these elements within randovania in a similar way to how custom suit colors work, though I'm definitely open to other suggestions.

Fix blast shield position on hive totem door(s)

                    ], /* This, but it needs to be done in code.
                    "editObjs": {
                        // Missile Lock
                        "2359799": {
                            "position": [
                                94.620384,
                                335.728577,
                                -6.138761
                            ]
                        },
                        // Door
                        "2359859": {
                            "position": [
                                94.620384,
                                335.97287,
                                -6.138761
                            ],
                            "rotation": [
                                0.019047,
                                0.480051,
                                90.001442
                            ]
                        },
                        // Actor_DoorShield
                        "2359862": {
                            "position": [
                                94.626328,
                                335.605164,
                                -4.333776
                            ],
                            "rotation": [
                                0.019047,
                                0.480051,
                                90.001442
                            ]
                        },
                        // Actor_DoorShield_Key
                        "2359855": {
                            "position": [
                                94.626328,
                                335.605164,
                                -4.333776
                            ],
                            "rotation": [
                                0.019047,
                                0.480051,
                                90.001442
                            ]
                        },
                        // Trigger_DoorUnlock
                        "2359860": {
                            "position": [
                                94.410385,
                                335.469147,
                                -4.128055
                            ]
                        },
                        // Trigger_DoorKey
                        "2359854": {
                            "position": [
                                94.410385,
                                335.469147,
                                -4.128055
                            ]
                        }
                    },*/

Screen continues to shake for a bit when landing cutscene is not skipped immediately

The screen shake is only for a second or so, but still shouldn't happen.

Killing all 5 pirates in research entrance before the fight will trap the player inside

This involves backwards labs and killing the pirates in their hidey-hole through the doors which isn't easy.

Major Cutscene Skip Export Error

Could not find object 0x180016 in room 0x8316EDF5

Furnace Entrance Spider Track is missing standable in PAL

Link to discord bug: https://discord.com/channels/914291389293027329/1179195299483353201
includes a video

Tower of Light scandash not possible on PAL

IDK what it is there, IIRC ulti once mentioned that the geometry has been made sloped there. I cannot get any scandash possible on PAL, but can do it on NTSC

Main Plaza ledge door can't be randomized.

Non-NTSC Prime has Rubble in Crashed Frigate Preventing UBJ SW

Revert this change like how we do all other non-NTSC changes

Option to remove chozo ghost music for optional ghost fights in chozo ruins

it's uncomfortable to get interrupted by screaming ghost music for the 30 seconds it takes you to pass the one room :(

(PAL) Attempt to subtract with overflow

qolCosmetic: false

Unskippable cutscene in Landing Site

If you choose to save at the ship, you cannot skip the cutscene afterwards. Refusing to save has no such issue.

According to the changelog, it was fixed in 1.24.0 version of the patcher, but the issue just came back at some point and 1.25.0 still has it.

1.25.0_unskippable.mp4

Warp to start text not present in other langauges / PAL

Saving at a save station still prints the vanilla text

Option to specify rotation option for `blocks`