Pokémon HGSS Setup Guide

Required Software

• Archipelago
• A US Pokémon HeartGold or SoulSilver ROM. The Archipelago community cannot provide this. Other regions and other revisions will be rejected when you patch your game -- the client will tell you if your ROM doesn't match.
• BizHawk version 2.10 or later

That's it -- the ROM read/write library this world needs (apnds, MIT) is bundled directly inside poke_hgss.apworld, so there's no separate install step, even on the official portable Windows release.

Configuring BizHawk

Once you have installed BizHawk, open EmuHawk.exe and change the following settings:

• Go to Config > Customize. On the Advanced tab, disable (if it is not already) Auto Save Ram. Having this option enabled may not allow BizHawk to properly save for NDS games.
• Under Config > Customize, check the "Run in background" option to prevent disconnecting from the client while you're tabbed out of EmuHawk.
• Open an .nds file in EmuHawk and go to Config > Controllers… to configure your inputs. If you can't click Controllers…, load any .nds 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.

Generating and Patching a Game

1. Add poke_hgss.apworld to your custom_worlds folder in your Archipelago install. It should not be in lib/worlds.
2. Create your options file (YAML). You can make one by choosing Generate Templates from the Archipelago Launcher. From there, you can edit the .yaml in any text editor. If you'd rather not generate one yourself, a ready-to-edit default is provided at docs/Poke_HGSS.yaml in this repository.
3. Follow the general Archipelago instructions for generating a game on your local installation. This will generate an output file for you. Your patch file will have the .appokehgss file extension and will be inside the output file.
4. Open ArchipelagoLauncher.exe
5. Select "Open Patch" on the left side and select your patch file.
6. If this is your first time patching, you will be prompted to locate your vanilla ROM.
7. A patched .nds file will be created in the same place as the patch file.
8. 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. Pokémon HeartGold 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.
6. The emulator and client will eventually connect to each other. The BizHawk Client window should indicate that it connected and recognized Pokémon HeartGold.
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 don't need to type your slot name: the client reads it from your patched ROM. Check that the client shows "(your name) playing Pokemon HGSS Singe has joined".

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.

Client commands

• /pending: lists the items the server sent you that are not in your game yet. Compare with /received (the full list from the server). An item stays pending while its Bag pocket is full; the client also says so in its log.
• /resend <item>: gives you one more copy of an item the server already sent you, for example /resend Expert Belt. Use it for an item that never reached your Bag with an older client (game closed or reloaded right after it arrived). Key items and HMs come back on their own. It never gives more copies than the server sent you. Save in-game afterwards.
• /restore_power: repairs the Kanto Power Plant in your save, so the Magnet Train runs as soon as you hold the Pass. With magnet_train on this already happens automatically; use it only if you are stuck with the option off. Save in-game afterwards. With magnet_train off, the Power Plant manager's TM57 check is sent at the same time and its item arrives through the server.

Tracking

PopTracker

A PopTracker pack is attached to each release (poke_hgss_poptracker.zip). Put the zip in PopTracker's packs folder, open it, choose "English" or "Français", then connect to your room with the AP button (server address, slot name). Received HMs, badges and key items light up on their own, a gym leader lights up once its badge check is done, checked locations are cleared, and each pin shows what you can currently reach with your items. The seed's goal and options (Johto only, Magnet Train, Trainersanity, Dexsanity...) are read from the server. Dexsanity checks are listed in the "Pokedex" tab without logic. PopTracker 0.26.2 or later is needed.

Every check has a "?" icon. Click it to see what is there (and whose item it is), click again to hide it. The tracker asks the server without creating hints, so nobody else is told anything.

Web tracker

poke_hgss_tracker.html, also attached to each release, is the same tracker as a single web page: open it in your browser (double-click), enter the server address and your slot name, and click Connect. It works offline too (click tiles and checks to mark them by hand). The Map tab colours every town, route and cave by what you can reach; click one to see its checks. Places fold out region by region (Johto, Kanto), then towns, caves and towers, and routes, down to each check and its "?". French and English, switched with the FR/EN button.

Maintainers: python tracker_gen.py builds the pack and the web page (needs an Archipelago checkout; the web map also needs HEARTGOLD_ROM_PATH and the map sources in ressources/).

Universal Tracker

Pokémon HeartGold supports the Universal Tracker (tracker.apworld, dropped into your custom_worlds folder next to this world). Connect it to your slot as usual: it works out what you can currently reach on its own, and does not need the slot's YAML.

Common Issues

1. Problem: "No handler was found for this game." in the client. Solution: Update to at least BizHawk version 2.10.
2. Problem: The BizHawk Client never recognizes the game. Solution: load the .nds produced by opening your .appokehgss file with this version. The client ignores unpatched ROMs, and ROMs patched by another HGSS world or by an older version of this one (anything before v0.2.5).
3. Problem: "File hash does not match" (or the client says my ROM doesn't match) when applying the patch. Solution: you need a US Pokémon HeartGold (game code IPKE) or SoulSilver (IPGE) ROM, not another region; the error says which ROM it found. Archipelago keeps a copy of the first ROM you gave it, in your Archipelago folder as Pokemon - HeartGold Version (USA).nds / Pokemon - SoulSilver Version (USA).nds (or at the path set in host.yaml under pokemon_heartgold_settings): delete that file, then open the patch again to pick the right ROM. Reinstalling the APWorld does not change it. Trimmed US ROMs are accepted.
4. Problem: Pokémon HGSS never shows up in Generate Template Options / Option Creator, even after installing the .apworld. Solution: check your logs/Launcher_*.txt for a traceback naming this world -- it'll say exactly what failed to import. If you replaced an existing poke_hgss.apworld, make sure the old copy was actually removed from custom_worlds first; the Launcher's "Install APWorld" refuses to overwrite an existing file with the same name.
5. Problem: a fix says "needs the ROM re-patched" (DeathLink, trainer moves, the lighthouse). Solution: install the new .apworld, then open the same .appokehgss again: it builds a new .nds for the same seed. It has the same file name, so BizHawk loads your existing save. No new generation is needed while the APWorld version stays the same.