diff --git a/README.md b/README.md index d6948ec..bceb1b5 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,12 @@ An Archipelago implementation of Metroid Prime multiworld randomizer using [rand To get started or for troubleshooting, see [the Setup Guide](./docs/setup_en.md). -## What does randomization do to this game? +## Info +### What does randomization do to this game? In Metroid Prime, all suit upgrade and expansion items are shuffled into the multiworld, giving the game a greater variety in routing to complete the end goal. -## What is the goal of Metroid Prime when randomized? +### What is the goal of Metroid Prime when randomized? The end goal of the randomizer game can consist of: @@ -20,11 +21,11 @@ The end goal of the randomizer game can consist of: If randomized, the end goal can be scanned in the Temple Security station. -## Which items can be in another player's world? +### Which items can be in another player's world? All suit upgrades and expansion items can be shuffled in other players' worlds, excluding Power Suit and Combat Visor. -## What does another world's item look like in Metroid Prime? +### What does another world's item look like in Metroid Prime? Multiworld items appear as one of the following: @@ -32,20 +33,15 @@ Multiworld items appear as one of the following: - Useful Item: Metroid Model with a random texture - Filler Item: Zoomer Model with a random texture -## What versions of the Metroid Prime are supported? +### What versions of the Metroid Prime are supported? -Only the GameCube versions of the game are supported. +Only the GameCube versions of the game are supported. +The Wii and Switch version of the game are _not_ supported. -- `DOL-GM8E-0-00 USA` version recommended - Other GameCube regions/versions will also work! - The Wii and Switch version of the game are _not_ supported. - -## When the player receives an item, what happens? +### When the player receives an item, what happens? The player will immediately have their suit inventory updated and receive a notification in the Client and a HUD message in-game. -## FAQs - ### Can I teleport to the starting room? To warp to the starting location, @@ -54,17 +50,17 @@ To warp to the starting location, 2. When prompted to Save, choose No 3. While choosing No, simultaenously hold down the L and R buttons. -### When fighting Ridley my screen keeps changing width, what's going on? - -This is an issue with having aspect ration set to `auto`. Forcing it to `4:3` should resolve the issue. +### What happens to my own collected items at Game Over or if the game is reset without saving? +As long as the game is connected to the Client and the Client is connected to the server, items you collected before the Game Over or reset will be kept and returned to you when you re-enter the game, even if you did not save. +(The item dot indicators on the map will still show the item location as not collected, even if the Client gives the items back to you.) ### What Metroid Prime mods/tools does this work with? It is recommended to use a vanilla ISO with the latest release of [Dolphin](https://dolphin-emu.org/download/#). -- Not thoroughly tested; but some users report that these work +- Not thoroughly tested; but some users report that these tools and mods work - [PrimeHack](https://forums.dolphin-emu.org/Thread-fork-primehack-fps-controls-and-more-for-metroid-prime) - - [Widescreen HUD Mod]() (0-00 USA only) + - [Widescreen HUD Mod]() (Revision 0 "0-00" only) - [MPItemTracker](https://github.com/UltiNaruto/MPItemTracker) - Not compatible - Practice Mod (The AP client is unable to connect to the game with this mod present.) @@ -86,5 +82,4 @@ Some of the changes include: In Main Quarry, the barrier is automatically disabled when entering from Mine Security Station. - In Elite Research, Phazon Mines, the fight with Phazon Elite can now be started without needing to collect the item in Central Dynamo. - QOL Changes: - - When Morph Ball Bomb is acquired, Spring Ball can be used. - To use Spring Ball, tilt the C-Stick Up. + - Spring Ball has been implemented! When Morph Ball Bomb is acquired, Spring Ball can be used. To use Spring Ball, tilt the C-Stick Up. diff --git a/docs/setup_en.md b/docs/setup_en.md index 55dcb44..b38f112 100644 --- a/docs/setup_en.md +++ b/docs/setup_en.md @@ -1,150 +1,141 @@ # Setup Guide for Metroid Prime Archipelago -This guide is meant to help you get up and running with Metroid Prime in your Archipelago run. - -Windows is the only OS this has been tested on, but feel free to let us know if you get the chance to try it on Linux or MacOS +This guide is meant to help you get up and running with Metroid Prime APWorld with Archipelago. +This has only been tested on Windows, but feel free to let us know if you get the chance to try it on other OS platforms! ## Requirements -The following are required in order to play Metroid Prime in Archipelago - -- Installed [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases) v0.4.5 or higher.\ - **Make sure to install the Generator if you intend to generate multiworlds.** -- The latest version of the [Metroid Prime apworld](https://github.com/Electro1512/MetroidAPrime/releases/latest). - - If you are on version `5.1` or later of Archipelago, make sure to download the apworld ending with `3.12.zip` instead. -- [Dolphin Emulator](https://dolphin-emu.org/download/). We recommend the latest beta version. -- A Metroid Prime US ISO (`DOL-GM8E-0-00 USA`) +The following are required in order to play _Metroid Prime_ in Archipelago: -## AP World Installation +- [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases) + For Archipelago 5.0/5.1, see the Note about Python versions in [APWorld Installation](#apworld-installation) +- [Dolphin Emulator](https://dolphin-emu.org/download/). We recommend the latest Release version. +- A _Metroid Prime_ (GameCube version) ISO file + - Any official release copy of the GameCube version will work. (All region versions are compatible, including all three versions of NTSC-USA) + - The Wii and Switch version of the game are _not_ supported. -1. Unzip the downloaded Metroid Prime apworld zip file -2. Double click the `metroidprime.apworld` to install it to your local Archipelago instance. +## APWorld Installation - - If you have used a version that required copying folders into the `/lib` folder, go to your `Archipelago/lib` folder and delete the following directories. These are now included in the `.apworld` +1. Download the latest version of the [Metroid Prime AP](https://github.com/Electro1512/MetroidAPrime/releases/latest) +2. Unzip the downloaded Metroid Prime APWorld zip file and extract its files. +3. In the Archipelago Launcher, select `Install APWorld`, and then select `metroidprime.apworld` file from the previous step. - - `ppc_asm` - - `dolphin_memory_engine` - - `py_randomprime` +>[!NOTE] +> Because Archipelago 5.1 on Windows transitioned to using Python 3.12, [Metroid Prime AP version 0.4.8](https://github.com/Electro1512/MetroidAPrime/releases/tag/v0.4.8) has two versions: +> | Archipelago Version (Windows) | | +> |------------------------------|----------------------------------------------| +> | Archipelago 5.0 or earlier | Download APWorld file ending with `3.11.zip`.| +> | Archipelago 5.1 or later | Download APWorld file ending with `3.12.zip`.| +> +> Future versions after Metroid Prime AP 0.4.8 will likely target only Python 3.12 and will only work on Archipelago 5.1. - - If you are currently on Archipelago version < `0.5.0` Place the `metroidprime.apworld` file in your Archipelago installation's `lib/worlds` folder (Default location for Windows: `%programdata%/Archipelago`). Overwrite any existing `metroidprime.apworld` file +>[!IMPORTANT] +> If you have used a previous version of Metroid Prime AP that required copying folders into the `/lib` folder, go to your `Archipelago/lib` folder and delete the following directories: +> - `dolphin_memory_engine` (This may be kept if another APWorld depends on this folder, but may cause issues if versions are mismatched.) +> - `ppc_asm` +> - `py_randomprime` +> +> These are now included in the APWorld file. -## Setting Up a YAML +## Setting Up Player Options YAML File -All players playing Metroid Prime must provide the room host with a YAML file containing the settings for their world. -A sample YAML file for Metroid Prime is supplied in the Metroid Prime apworld download. Refer to the comments in that file for details about what each setting does. +All players playing _Metroid Prime_ must provide the room host with a YAML file containing the player options for their world. +A sample YAML file for _Metroid Prime_ is supplied in the Metroid Prime APWorld download. Refer to the comments in that file for details about what each setting does. -Once complete, provide the room host with your YAML file. +Once complete, provide the person generating with your YAML file. ## Generating a Multiworld - -If you're generating a multiworld game that includes Metroid Prime, you'll need to run it locally since the online -generator does not yet support it. Follow these steps to generate a multiworld: - -1. Gather all player's YAMLs. Place these YAMLs into the `Players` folder of your Archipelago installation. If the - folder does not exist, then it must be created manually. The files here should not be compressed. - -2. Modify any local host settings for generation, as desired. - -3. Run `ArchipelagoGenerate.exe` (without `.exe` on Linux) or click `Generate` in the launcher. The generation output - is placed in the `output` folder (usually named something like `AP_XXXXX.zip`). \* Please note that if any player in the game you want to generate plays a game that needs a ROM file to generate, - you will need the corresponding ROM files. - -4. Unzip the `AP_XXXXX.zip` file. It should include a zip file for each player in the room playing Metroid Prime. Distribute each file to the appropriate player. - -5. **Delete the distributed zip files and re-zip the remaining files**. In the next section, use this archive file to - host a room or provide it to the room host. \* If you plan to host the room on a local machine, skip this step and use the original zip file (`AP_XXXX.zip`) instead. +As usual, randomized Archipelago games with custom worlds must be generated locally - see [Archipelago Setup Guide: Generating a game - On your local installation](https://archipelago.gg/tutorial/Archipelago/setup/en#on-your-local-installation) ## Hosting a Room If you're generating the multiworld, follow the instructions in the previous section. -Once you have the zip file corresponding to your multiworld, follow [these steps](https://archipelago.gg/tutorial/Archipelago/setup/en#hosting-an-archipelago-server) to host a room. -Follow the instructions for hosting on the website from a locally generated game or on a local machine. +Once you have the zip file corresponding to your multiworld, follow [Archipelago Setup Guide: Hosting an Archipelago Server](https://archipelago.gg/tutorial/Archipelago/setup/en#hosting-an-archipelago-server) to host a room. + +> [!NOTE] +> When hosting with the Archipelago website, the website will *not* host patch files from imported custom worlds, such as Metroid Prime AP. +> The person generating must manually distribute the `.apmp1` patch files to the corresponding players. ## Starting the Game and Connecting to a Room -You should have the `apmp1` file provided to you by the multiworld generator. You should also have the room's server +You should have the `.apmp1` patch file provided to you by the multiworld generator. You should also have the room's server name and port number from the room's host. Once you do, follow these steps to connect to the room: -0. (Optional): If you want the `apmp1` file to automatically open your game for you, navigate to your `Archipelago` installation and edit the `host.yaml` file. - - Scroll down to `metroidprime_options` and either set `rom_start` to `true` if ISO files are already associated with Dolphin, or set it to the path to your `Dolphin.exe`. - - If `metroidprime_options` isn't in the `host.yaml` yet, click your `apmp1` file and then reopen the `host.yaml` and it should now be there. -1. Double click the `apmp1` file. If you have not done so before, it will ask you what program you want to open it with. - Click "Choose another program" and browser to your Archipelago directory. Select `ArchipelagoLauncher.exe`. -2. Be patient, after clicking the `apmp1` file, it can take a minute to have the client and patched iso showup -3. If this is your first time, it will prompt you for an input iso. Select your Metroid Prime DOL-GM8E-0-00 USA iso -4. Once the output iso file appears in the same directory as your `apmp1` file (it should have a name `AP_XXXX.iso`), open it with Dolphin (or if you associated the file type with Dolphin, sit back and enjoy watching the computer do this menial task for you) +1. In the Archipelago Launcher, click `Open Patch File`. Then select the `.apmp1` patch file. + If you have not done so before, it will ask you what program you want to open it with. +2. If this is your first time, it will prompt you for an input iso. Select your _Metroid Prime_ GameCube ISO file. +3. The patch will take some time to complete in the background. (Be patient! The game is 1.46 GB!) +4. Once the output iso file appears in the same directory as your `.apmp1` file (it should be named `AP_XXXX.iso`), open it with Dolphin. 5. After the game is running, connect the Metroid Prime Client to the room by entering the server name and port number at the top and pressing `Connect`. For rooms hosted on the website, this will be `archipelago.gg:`, where `` is the port number. If a game is hosted from the `ArchipelagoServer.exe` (without `.exe` on Linux), this will default to `38281` but may be changed in the `host.yaml`. -## Troubleshooting - -- If you launch the client and the game but are still getting an error saying it is waiting for the game to start, verify you are running version `0-00`. To check this: - - - Add your original ISO to the list of games in Dolphin - - Right click on it, select properties - - Browse to the info tab (you will need to click the arrow to view more tabs to the right) - - Verify under name it says `Metroid Prime (Revision 0)` - -- If the client is running, connected to the Archipelago server but it appears to not be able to connect to dolphin, verify you only have one instance of Dolphin opened up. If there are other windows (even if they aren't running anything) it will cause problems with the client. +>[!TIP] +> **Optional** +> If you want double-clicking `.apmp1` patch file to automatically open your game for you, +> - Navigate to your `Archipelago` installation and edit the `host.yaml` file. +> - Scroll down to `metroidprime_options` and either set `rom_start` to `true` if ISO files are already associated with Dolphin or set it to the path to your `Dolphin.exe`. +> - If `metroidprime_options` isn't in the `host.yaml` yet, click your `.apmp1` patch file and then reopen the `host.yaml` and it should now be there. +> +> Now when double-clicking the `.apmp1` patch file, it should open the client, patch, and launch Dolphin all at once! -- If you do not see the client in the launcher, ensure you have your `metroidprime.apworld` in the correct folder (either the `custom_worlds` folder or the - `lib/worlds` folder of your Archipelago installation). - -- If you receive this error in a dialog box after opening the AP_XXXXX_PX.apmp1 file: - > Count Mount File - > The disc image is corrupted. - > This is not an error related to the patcher - this Windows File Explorer attempting to mount the GameCube ISO as a removable drive. It's likely that the patcher did sucessfully patch the game. - > See if the patched ISO exists (often named AP_XXXXX_PX.iso), - > If it does, you can load it manually in Dolphin. - -## Connection Troubleshooting +## Troubleshooting +### General Troubleshooting Tips - Use the latest Metroid Prime Archipelago release - - Metroid Prime Archipelago: [Releases · Electro1512_MetroidAPrime](https://github.com/Electro1512/MetroidAPrime/releases) -- Use the latest Dolphin - - - Dolphin Beta (**Recommended**): [Dolphin Emulator - Download](https://dolphin-emu.org/download/#download-beta) - - PrimeHack (Not thorougly tested with Metroid Prime AP): [Releases · shiiion_dolphin.htm](https://github.com/shiiion/dolphin/releases) - -- Use the Correct Version of the Game +- Use the latest Dolphin Emulator + - Dolphin Emulator Release (**Recommended**): [Dolphin Emulator - Download](https://dolphin-emu.org/download/) + - PrimeHack: [Releases · shiiion/dolphin](https://github.com/shiiion/dolphin/releases) + - While the dependencies that Metroid Prime AP uses does not target PrimeHack, many users report that PrimeHack can work. + However, any issues found while using PrimeHack should be reproduced with the official Dolphin Emulator before reporting. - - Ensure your ISO of Metroid Prime is the supported version: - - Platform: `GameCube` (None of the Wii versions are supported.) - - Game ID: `GM8E01` - - Version Number: `DOL-GM8E-0-00 USA` ("0-00") - - SHA-1: `ac20c744db18fdf0339f37945e880708fd317231` - - For information on determining the disc's version number, see [metroid2002.com metroid prime version differences version number](https://www.metroid2002.com/version_differences_version_number.php). +### Generating and Patching Troubleshooting -- Ensure Only One Instance of Dolphin is Running +- If you do not see the client in the Archipelago Launcher + - Ensure you have your `metroidprime.apworld` in the correct folder (The `custom_worlds` folder). + - Check if you have residual files from previous versions in the lib/worlds folder - see the [APWorld Installation section](#apworld-installation) + - Go to `%TEMP%` (C:\Users\\AppData\Local\Temp) and delete the folder `ap_metroidprime_temp_lib_vX.Y.Z`. Then restart the Archipelago Launcher. - - Check Task Manager to see if there's multiple emulator instances running. - - You can also just restart your computer to be sure. - -- Disable Emulated Memory Size Override - - In Dolphin, - Config -> Advanced tab, - **Uncheck** Enable Emulated Memory Size Override -- Start the Metroid Prime Client and Dolphin in a Specific Order - - - For some users, connecting to the AP server before letting the Metroid Prime client causes connection issues - Try starting the game in this order: - 1 . Start the Metroid Prime client - 2 . Start Dolphin and start the game (if it launches automatically, that's fine) - 3 . Select or create a save file and enter the game - 4 . Enter the AP server address into the Metroid Prime Client - -- Avoid using Dolphin FlatPak - - - FlatPak may block the Metroid Prime client's ability to connect to Dolphin - You may need to build and run the Dolphin binaries directly - see [Building for Linux · dolphin-emu_dolphin Wiki.htm](https://github.com/dolphin-emu/dolphin/wiki/Building-for-Linux) - -- Make Sure the ISO is Randomized - - On the Main Menu, "Archipelago Metroid Prime" text should appear. ([image example](https://i.imgur.com/W6172zf.png)) +- If you receive this error in a dialog box after opening the AP_XXXXX_PX.apmp1 file: + > Count Mount File + > The disc image is corrupted. + + This is not an error related to the patcher - this is Windows File Explorer attempting to mount the GameCube ISO as a removable drive. It's likely that the patcher did sucessfully patch the game. + See if the patched ISO exists (often named AP_XXXXX_PX.iso). If it does, you can load it manually in Dolphin. + +### Connection Troubleshooting +- I have the randomized game open in Dolphin, but the Metroid Prime client says it can't connect to it! + - Make Sure the ISO is Randomized + - On the Main Menu, "Archipelago Metroid Prime" text should appear. ([image example](https://i.imgur.com/W6172zf.png)) + - Ensure Only One Instance of Dolphin is Running + - Check Task Manager to see if there's multiple emulator instances running. + - You can also just restart your computer to be sure. + + - Disable Emulated Memory Size Override + - In Dolphin, + Config -> Advanced tab, + **Uncheck** Enable Emulated Memory Size Override + - Start the Metroid Prime Client and Dolphin in a Specific Order + + - For some users, connecting to the AP server before letting the Metroid Prime client causes connection issues. + Try starting the game in this order: + 1.) Start the Metroid Prime client + 2.) Start Dolphin and start the game (if it launches automatically, that's fine) + 3.) Select or create a save file and enter the game + 4.) Enter the AP server address into the Metroid Prime Client + + - For Linux, use Dolphin FlatPak + - Install Dolphin Emulator from [Flathub](https://flathub.org/apps/org.DolphinEmu.dolphin-emu) + - Dolphin Memory Engine, as part of the Prime AP Client, can not access regular Dolphin's process but can access Flatpak's containerized Dolphin's process + +### In-Game Troubleshooting +- In Dolphin, when fighting Ridley my screen keeps changing width + - This is an issue with Dolphin's widescreen detection heuristic. + - In Dolphin, go to Graphics > General tab, and then set Aspect Ratio to `Force 4:3` ## Feedback