2023-11-12 13:39:34 -08:00
|
|
|
# Pokémon Emerald Setup Guide
|
|
|
|
|
|
|
|
|
|
## Required Software
|
|
|
|
|
|
|
|
|
|
- [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases)
|
|
|
|
|
- An English Pokémon Emerald ROM. The Archipelago community cannot provide this.
|
|
|
|
|
- [BizHawk](https://tasvideos.org/BizHawk/ReleaseHistory) 2.7 or later
|
|
|
|
|
|
|
|
|
|
### Configuring BizHawk
|
|
|
|
|
|
|
|
|
|
Once you have installed BizHawk, open `EmuHawk.exe` and change the following settings:
|
|
|
|
|
|
|
|
|
|
- If you're using BizHawk 2.7 or 2.8, go to `Config > Customize`. On the Advanced tab, switch the Lua Core from
|
|
|
|
|
`NLua+KopiLua` to `Lua+LuaInterface`, then restart EmuHawk. (If you're using BizHawk 2.9, you can skip this step.)
|
|
|
|
|
- Under `Config > Customize`, check the "Run in background" option to prevent disconnecting from the client while you're
|
|
|
|
|
tabbed out of EmuHawk.
|
|
|
|
|
- Open a `.gba` file in EmuHawk and go to `Config > Controllers…` to configure your inputs. If you can't click
|
|
|
|
|
`Controllers…`, load any `.gba` ROM first.
|
|
|
|
|
- Consider clearing keybinds in `Config > Hotkeys…` if you don't intend to use them. Select the keybind and press Esc to
|
|
|
|
|
clear it.
|
|
|
|
|
|
|
|
|
|
## Optional Software
|
|
|
|
|
|
2024-05-02 11:56:35 +02:00
|
|
|
- [Pokémon Emerald AP Tracker](https://github.com/seto10987/Archipelago-Emerald-AP-Tracker/releases/latest), for use with
|
2023-11-12 13:39:34 -08:00
|
|
|
[PopTracker](https://github.com/black-sliver/PopTracker/releases)
|
|
|
|
|
|
|
|
|
|
## Generating and Patching a Game
|
|
|
|
|
|
2023-12-28 04:33:30 -08:00
|
|
|
1. Create your options file (YAML). You can make one on the
|
|
|
|
|
[Pokémon Emerald options page](../../../games/Pokemon%20Emerald/player-options).
|
2023-11-12 13:39:34 -08:00
|
|
|
2. Follow the general Archipelago instructions for [generating a game](../../Archipelago/setup/en#generating-a-game).
|
|
|
|
|
This will generate an output file for you. Your patch file will have the `.apemerald` file extension.
|
|
|
|
|
3. Open `ArchipelagoLauncher.exe`
|
|
|
|
|
4. Select "Open Patch" on the left side and select your patch file.
|
|
|
|
|
5. If this is your first time patching, you will be prompted to locate your vanilla ROM.
|
|
|
|
|
6. A patched `.gba` file will be created in the same place as the patch file.
|
|
|
|
|
7. On your first time opening a patch with BizHawk Client, you will also be asked to locate `EmuHawk.exe` in your
|
|
|
|
|
BizHawk install.
|
|
|
|
|
|
|
|
|
|
If you're playing a single-player seed and you don't care about autotracking or hints, you can stop here, close the
|
|
|
|
|
client, and load the patched ROM in any emulator. However, for multiworlds and other Archipelago features, continue
|
|
|
|
|
below using BizHawk as your emulator.
|
|
|
|
|
|
|
|
|
|
## Connecting to a Server
|
|
|
|
|
|
|
|
|
|
By default, opening a patch file will do steps 1-5 below for you automatically. Even so, keep them in your memory just
|
|
|
|
|
in case you have to close and reopen a window mid-game for some reason.
|
|
|
|
|
|
|
|
|
|
1. Pokemon Emerald uses Archipelago's BizHawk Client. If the client isn't still open from when you patched your game,
|
|
|
|
|
you can re-open it from the launcher.
|
|
|
|
|
2. Ensure EmuHawk is running the patched ROM.
|
|
|
|
|
3. In EmuHawk, go to `Tools > Lua Console`. This window must stay open while playing.
|
|
|
|
|
4. In the Lua Console window, go to `Script > Open Script…`.
|
|
|
|
|
5. Navigate to your Archipelago install folder and open `data/lua/connector_bizhawk_generic.lua`.
|
BizHawkClient: Add support for multiple concurrent instances (#2475)
This allows multiple client/connector pairs to run at the same time. It also includes a few other miscellaneous small changes that accumulated as I went. They can be split if desired
- Whatever the `client_socket:send` line (~440) was doing with that missing operator, it's no longer doing. Don't ask me how it was working before. Lua is witchcraft.
- Removed the `settimeout(2)` which causes the infamous emulator freeze (and replaced it with a `settimeout(0)` when the server socket is created). It appears to be unnecessary to set a timeout for discovering a client. Maybe at some point in time it was useful to keep the success rate for connecting high, but it seems to not be a problem if the timeout is 0 instead.
- Also updated the Emerald setup to remove mention of the freezing.
- Connector script now picks the first port that's not in use in a range of 5 ports.
- To summarize why I was previously under the impression that multiple running scripts would not detect when a port was in use:
1. Calling `socket.bind` in the existing script will first create an ipv6 socket.
2. A second concurrent script trying to bind to the same port would I think fail to create an ipv6 socket but then succeed in creating an ipv4 socket on the same port.
3. That second socket could never communicate with a client; extra clients would just bounce off the first script.
4. The third concurrent script will then fail on both and actually give an `address already in use` error.
- I'm not _really_ sure what's going on there. But forcing one or the other by calling `socket.tcp4()` or `socket.tcp6()` means that only one script will believe it has the port while any others will give `address already in use` as you'd expect.
- As a side note, our `socket.lua` is much wonkier than I had previously thought. I understand some parts were added for LADX and when BizHawk 2.9 came out, but as far back as the file's history in this repo, it has provided a strange, modified interface as compared to the file it was originally derived from, to no benefit as far as I can tell.
- The connector script closes `server` once it finds a client and opens a new one if the connection drops. I'm not sure this ultimately has an effect, but it seems more proper.
- If the connector script's main function returns because of some error or refusal to proceed, the script no longer tries to resume the coroutine it was part of, which would flood the log with irrelevant errors.
- Creating `SyncError`s in `guarded_read` and `guarded_write` would raise its own error because the wrong variable was being used in its message.
- A call to `_bizhawk.connect` can take a while as the client tries the possible ports. There's a modification that will wait on either the `connect` or the exit event. And if the exit event fires while still looking for a connector script, this cancels the `connect` so the window can close.
- Related: It takes 2-3 seconds for a call to `asyncio.open_connection` to come back with any sort of response on my machine, which can be significant now that we're trying multiple ports in sequence. I guess it could fire off 5 tasks at once. Might cause some weirdness if there exist multiple scripts and multiple clients looking for each other at the same time.
- Also related: The first time a client attempts to connect to a script, they accept each other and start communicating as expected. The second client to try that port seems to believe it connects and will then time out on the first message. And then all subsequent attempts to connect to that port by any client will be refused (as expected) until the script shuts down or restarts. I haven't been able to explain this behavior. It adds more time to a client's search for a script, but doesn't ultimately cause problems.
2023-11-23 06:00:46 -08:00
|
|
|
6. The emulator and client will eventually connect to each other. The BizHawk Client window should indicate that it
|
|
|
|
|
connected and recognized Pokemon Emerald.
|
2023-11-12 13:39:34 -08:00
|
|
|
7. To connect the client to the server, enter your room's address and port (e.g. `archipelago.gg:38281`) into the
|
|
|
|
|
top text field of the client and click Connect.
|
|
|
|
|
|
|
|
|
|
You should now be able to receive and send items. You'll need to do these steps every time you want to reconnect. It is
|
|
|
|
|
perfectly safe to make progress offline; everything will re-sync when you reconnect.
|
|
|
|
|
|
|
|
|
|
## Auto-Tracking
|
|
|
|
|
|
|
|
|
|
Pokémon Emerald has a fully functional map tracker that supports auto-tracking.
|
|
|
|
|
|
2024-05-02 11:56:35 +02:00
|
|
|
1. Download [Pokémon Emerald AP Tracker](https://github.com/seto10987/Archipelago-Emerald-AP-Tracker/releases/latest) and
|
2023-11-12 13:39:34 -08:00
|
|
|
[PopTracker](https://github.com/black-sliver/PopTracker/releases).
|
|
|
|
|
2. Put the tracker pack into packs/ in your PopTracker install.
|
|
|
|
|
3. Open PopTracker, and load the Pokémon Emerald pack.
|
|
|
|
|
4. For autotracking, click on the "AP" symbol at the top.
|
|
|
|
|
5. Enter the Archipelago server address (the one you connected your client to), slot name, and password.
|