ZHelper 4 User Manual v4.44
Table of Contents
- First Run
- Main Menu
- Options Menu
- Using the Tracker
- Icon Reference
- Using Hotkeys
- Automapping
- Randomizer Addons
- Server Operation
- Update Procedure
- Custom Graphics
- Reporting Bugs
First Run
The first time you run ZHelper, it will bring up a screen prompting for a player name and color, which is used for player markers in network mode. Simply click the Set Name button and enter a name, and then click a color to choose a player color. Next, just click on Continue and you'll be taken to the main menu. If you need to, you can change the name/color later in the Options menu.
Main Menu
The main menu is where you access all of the main ZHelper features from. Note that you may receive an update notification immediately upon accessing the main menu if an important update is available. See the Update Procedure section for details on how to update ZHelper properly.
The options available on the main menu are:
- SRL Mode: Click this button to toggle SRL compliance mode on/off. Various features such as automapping, the dungeon finder, and network mode are unavailable when SRL mode is on
- Create New Data: Takes you to the tracker with everything blank
- Load Existing Data: Loads the existing saved data and takes you to the tracker
- Options: Lets you change various options
- Help/Credits: Opens the ZHelper website
- Randomizer Addons: Takes you to a screen where you can patch a ROM with various additional randomizations
- Start Server: Starts the ZHelper server for collaborative network tracking (may require port forwarding for others to connect)
- Exit ZHelper: Closes ZHelper
- Arrow at bottom right: Click this to start the update process or to check for updates. See the Update Procedure section for details.
Options Menu
The options menu is where you access various configurable features of ZHelper. You can also change your player name and color here if you wish.
The options available are:
- Show Mouseover Outlines: When active, a bright outline is shown around the currently selected grid cell in the tracker
- Show Coords/Player Indicators: When active, coordinates and player markers are shown on the map
- Coords Button: Switches the coordinate display on the overworld map between hexadecimal and A1-H16 style
- Window Scale: Lets you change the size of the ZHelper window
- Icon/Hotkey Settings: See the Using Hotkeys section for details on this feature
- Set Name: Click to change your player name
- Player Color: Click a colored box to change your player color
- Dgn.Find Delay: Click to set the amount of time between dungeon finder updates (you usually don't need to change this!)
- Dgn. Trans. Lvl: Click to set how translucent unmarked dungeon rooms and doors are when hiding them.
- Dungeon Item Style: Toggles the boxes below the triforce icons on the tracker between hearts and regular item boxes. Use item boxes for seeds where boss hearts are shuffled. Please note that there is no syncing between the hearts and item boxes yet!
- Reload Custom GFX: Reloads the custom graphics stored in "%LocalAppData%\ZHelper\assets\"
- Back: Go back to the main menu
Using the Tracker
The tracker screen may look overwhelming at first with the amount of buttons and stuff, but don't worry, its very easy to use once you get used to it. I'll go over things screen by screen. You will start off on the overworld screen when you first open the tracker. You can look at the "OW" button directly below the level 1 heart on the left edge of the screen to see what tracker screen you are currently on.
Common Features (found on every screen)
- Quick Screen Switcher (green bar on top): Left click a button to quick switch to the corresponding tracker screen
- Triforce Buttons (near top left): Left click to toggle on/off
- Hearts (near top right): Left click toggles on/off, right click marks as skipped (for when you get candle instead of heart in a cave), middle click marks as a double heart for the dungeon that has 2 heart containers
- Item Boxes (blank boxes at top left and middle): From left to right the boxes correspond to dungeon boss items (heart is an option as well), level 1-9 item, then ladder, armos, white sword cave. L/R Click or mousewheel to select an item, middle click to toggle your personal marker on/off to mark whether you have the item or not. Hold shift and middle click to change the box to an X icon if you want to mark it as not needed. This icon cannot be accessed in any other way.
- Bomb Upgrades (blue circle buttons with B in middle): Left click to toggle on/off
- OW Button: L/R Click or mousewheel to cycle between the different tracker screens
- 1st/2nd Button: Click to switch the overworld map between 1st & 2nd quest layouts
- Mix Button: Click to toggle mixed quest mode on/off. This shows secret locations for both quests as well as pulsating indicators for secrets in the opposite quest of the one you have selected. You can also right-click this button to mirror the overworld map horizontally for mirrored runs
- Area Button: Click to toggle the hint area overlay on/off. Useful for figuring out where the old man is telling you to go for something
- TR Button: When on OW map, Left click to toggle visibility of the overworld marker icons, and Right click to toggle mapping mode (useful for automapping mode). When on D1-D9 dungeon maps,left click to make unmarked rooms and doors translucent.
- Auto Button: Shift-left click to toggle automapping and player position tracking on/off. See the Automapping section for details on how to use this feature. This feature is disabled in SRL mode
- Net Button: Shift-left click to toggle network mode on/off. You will be asked for the server IP and a port number when connecting. When connected to a ZHelper server, all connected players share the same overworld, dungeon and item box markers. You will also see the location of connected players who are using the automapping feature. See the Server Operation section for details on how to set up and run the server. This feature is disabled in SRL mode
- Location Bar (just below the previously listed buttons): This bar shows helpful tooltips when you mouseover various things, such as overworld screen descriptions when mousing over an overworld screen
- Player List (bottom of the screen): This list shows all connected players as well as their positions if available
- Item Button (top right of the screen): This button toggles the boxes below the triforce icons between hearts and regular item boxes. It overrides the default setting in the Options menu, and is saved with the rest of the tracker data so it will persist on a reload
Overworld Map (OW screen)
The overworld screen is very simple to read and use. The background shows all the locations of various secrets using different colored dots. Screens with a red tint have no secret, while blue screens have a recorder secret. If you have coords/indicators turned on you will see a space in between each row of screens with the screen number as well as markers for each player so you know if you have visited a given screen or not.
To mark a screen, use L/R click or the mousewheel. There are various icons for different things. They should be self-explanatory. Shift-left click a screen to mark it as the overworld start screen. If you set up hotkeys, you can just hover over a square with ZHelper focused and press the key to set the icon. Middle clicking toggles your player indicator on/off for that screen to mark if you've gotten that screen cleared or not. If you or other connected players have automapping on, you'll see pulsing outlines around screens where players are located.
Dungeon Maps (D1-D9 screens)
The dungeon maps are easy to understand as well. The grid squares as well as door markers in between rooms work exactly the same as the overworld grid does, with the exception that the door markers have no middle-click function. Below the map is a cross-section of the upper-left dungeon wall so you can tell which column you are in when automapping isn't on.
On the right, you will see two rows of 1-9 buttons. These will turn red/gray depending on what screens you have marked on the map. Gray squares mean the dungeon you are in may be that dungeon. Once only one gray button remains, you'll know exactly which dungeon you are in, assuming you aren't using random shapes. Clicking a button will show a "shadow" map of that dungeon layout. While the "shadow" maps are available in SRL mode, the narrowing feature is disabled.
Below these buttons are a bunch of colored palette selectors. Click one to set the dungeon's color palette. You can click the clear button to completely clear the current dungeon map as long as network mode isn't active.
Finally, there are a set of arrow buttons for shifting the map. Clicking an arrow will move the entire map one screen in that direction. It is smart enough to not allow accidental wrapping around the edges of the map. The buttons will be grayed out if any potential issues are detected, or if network mode is active, as this feature is incompatible with the auto-sync between D maps and the classic C maps. It will also throw an error if auto-mapping is active, as shifting the map would cause serious issues. The buttons update on the same timer as the dungeon narrowing does in the Options menu, as the checking can get very CPU-intensive if it is run every frame.
Classic (ZHelper 3) Dungeon Maps (C1-C4 screens)
The classic dungeon maps are a feature from ZHelper 3 that was left in by user request. They work exactly the same as the overworld map, and if you are in network mode, they do have limited syncing capabilities with the new dungeon maps. It isn't 100% accurate though, so don't rely on it. These maps may be removed in the near future, as they are made obsolete by various other features of both ZHelper and Zelda Randomizer 3.0+.
Helpful Hints (HH screen)
This screen is for keeping track of the various hints the old man gives about dungeon locations. L/R click or mousewheel over an icon to cycle through the available options.
Icon Reference
This section contains information on what each icon for the maps is meant to be used for.
Overworld Icons

- These are the level markers. The one with a ? is used for unknown levels.

- These icons are used to mark the destinations for the "Take any Road" caves.

- These icons are used for marking that a shop has a particular item. The gray one with 2 potions is a potion shop.

- These are for rupee secrets. The minus is door repair, ? is unknown rupee secret, and the others are 10 (green), 30 (blue), 100 (red).

- From left to right: letter cave (the one with the letter in it), armos item, sword (magic), sword (white), sword (wooden), pay for info cave, money-making game, heart/potion (take any one) cave, nothing/junk room.
Dungeon Icons

- These icons mark rooms with stairs in dungeons. the 1-9 are used to mark sets of passageway stairs. The ? is an unknown passageway stair, and the I with green square is for a secret item room.

- These icons mark item blocks preventing you from completing a room. From left to right: ladder, recorder, bow/arrow, sword/wand.

- From left to right: Gannon room, Gannon roar, boss roar, Zelda's room.

- From left to right: Key, Triforce, heart container, map, compass, bombs, 5 rupees, special item.

- These mark special "Guy" rooms in dungeons. They are for bomb upgrade, leave money or life, 10-rupee room (technically a guy/boss room in the code), grumble grumble room.

- These icons are used for generic dungeon room marking. X means the room is cleared and has nothing important, while ? is a room not cleared yet.
Dungeon Door Icons
A wall that has no passage. Usually marked if a wall is bombed and doesn't have a bomb wall so you know what you're already bombed.
An open passageway.
Shutter doors. First two are one-way, while the third is a two-way.
Walkthrough walls. First two are one-way, while the third is a two-way. The 4th and 5th are for vertical & horizontal walls which are not walk-through, but have not had bombs checked yet.
Locked door that requires a key to open.
A known bombable wall.
Using Hotkeys
ZHelper comes with a built-in hotkey system that you can use to quickly set various icons. To begin, go to the Options menu and click on the Icon/Hotkey Settings button. Once there, click on the checkbox next to Enable Hotkeys to turn hotkeys on. Below are a couple notes on hotkey usage:
- Hotkeys only work if ZHelper is the focused window, so make sure you have background input on in your emulator, and keep ZHelper focused
- Hotkeys are currently limited to the numbers 0-9 (no numpad) and letter keys. Better hotkey and control systems are in the works
To set a hotkey, L/R click on an icon. You can also toggle icons on/off altogether by middle clicking them. This means you will not be able to select that icon in the tracker by the normal means. If you are connected to a server, you will still see the disabled icons if others set them.
Using the hotkeys once they are set is easy. Just hover over an overworld/dungeon/door icon while ZHelper is focused and push the key you set. That's it.
Automapping
ZHelper comes with a built-in automapper function that can read the pixel data off the emulator screen and react accordingly. Currently it is limited to providing player position tracking and automapping the visited overworld screens (useful if you're using ZHelper's overworld randomizer addon). Automapping is disabled in SRL mode. Some notes on automapping:
- Automapping currently REQUIRES FCEUX 2.2.2 to work. Proper Nestopia support as well as arbitrary palette support is in the works
- You MUST use the default FCEUX palette without any screen filtering, aspect correction, non-integer scaling, or NTSC emulation
To activate automapping, Shift-left click the Auto button on the tracker window. A dialog will pop up with some information and a confirmation prompt. Once automapping is activated, go to the name select, save, or title screen in-game. Next, while ZHelper is focused, hover your mouse over the emulator window and press F4. If all goes well the Auto button should have turned green. If not something went wrong. Once the button is green, hop in-game and you should start to see your player position on the ZHelper screen.
Right now, you still need to mark screens manually, with the exception of dungeon entrances if the level number can be read off the screen by the tracker. Dungeon maps and palettes will be assigned automatically, but the dungeon finder feature will be unavailable. This will be fixed once I find a way to make it work better. Changing window scale or even minimizing ZHelper might erase the automapped screenshots. The screenshots are also not currently saved in the save data. Most of these issues are due to DirectX/OpenGL/Etc. quirks that will require me to write some checks and a workaround for them. This will come in the future. After each run is over, backing out to the main menu and starting fresh is advised. Be sure to re-enable automapping if you want to use it again.
Randomizer Addons
ZHelper comes with a few additional randomization options, as well as a couple fun cosmetic ones. To access them, click the Randomizer Addons button on the main menu. If you plan on also using Fred's randomizer, patch your ROM with it before using ZHelper's addons. Once ready, click the Pick ROM button and browse to the ROM you want to patch. Next, use the buttons on the top-left to select or enter a seed. After you have picked a seed, simply check the options you want on the rest of the screen, then press the Generate button. Please note that a few of the options are currently incompatible with each other, as the Randomizer Addons feature is a work-in-progress. ZHelper will open a "Save As" prompt so you can choose the output location and filename. If all goes well, you should get a success message and the patched ROM should appear where you selected.
If you want more palettes added, just send me the NES color values either on the ZeldaOne Discord server or in a Twitch message and I'll add them if they make sense.
Server Operation
ZHelper has the ability for users to run collaborative tracking servers that up to 8 players can connect to and share the same maps. This feature is incredibly useful when doing team or co-op runs. It is disabled if SRL mode is active. To start the server, click the Start Server button on the main menu. You'll be prompted to enter a port for the server to listen on. If you're planning on having users connect over the Internet, you may have to forward this port depending on your networking setup. Google is your best friend for this if you do need to forward ports. If everything goes well, you should see the server screen.
Once the server is started and your network is properly configured, other players should be able to connecting using the Net button on the tracker window. They'll need to enter the correct IP and port to connect. If you need to know your correct external IP for others to connect over the Internet, just do a Google search for "my ip address" and it should be right in a neat box at the top of the page. As players connect, you will see their names and colors pop up in the player list, and the server will being syncing data with them. If you also want to connect, you will need to run a second instance of ZHelper and just connect to your own PC (use "localhost" if the server is on the same PC, or your LAN IP found by doing "/ipconfig" at the Command Prompt otherwise).
As players start to mark things, you will see the info pop up in the log area. It'll also be logged to a file in ZHelper's AppData folder so it can be used for debugging in the case that something goes horribly wrong. If an error occurs, the log window will change to a red background, and a warning prompt and sound will play to let the server host know. The audio alerts can be turned off using the checkbox on the server window.
If you need to resync a player, just click the Sync button next to their name. To kick a player if they're no longer going to connect, click the X and they'll get kicked and the player slot will be freed. In the event of a connection loss, or if the client disconnects on their own, the player slot will remain used so they can reconnect with the same player ID as before if needed. Just press the kick buttons to clear unneeded players as necessary. To completely reset every connected player's tracker as well as the server data, click the Reset All Data button. To shut down the server, click the Shutdown button.
Update Procedure
ZHelper has an automatic update checker built in so you'll always know when new features or fixes are released. The program will automatically check for updates when you enter the main menu. In the event an important update is released, you will get a dialog box informing you of the update each time you enter the main menu. It is advised to keep the program up to date if you rely on features that have been fixed, or if you plan on using the network mode or randomizer addons, as the network protocol may change, or seeds might output different results after an "important" update. The update process is as follows:
- First, go to the main menu and click the update button at the bottom right corner (the up arrow button). If an update is available you'll get a dialog box with the changelog
- Click Yes on the update dialog after going over the changes, and choose a location to save the update file
- The update will download in the background. Just stay on the main menu until you get a popup saying that its done. If it fails, you can always download the update file from the ZHelper website
- Once the update zip is downloaded, locate and open it in your favorite archiving program
- Close all open ZHelper instances, and extract, at the very least, the "Zhelper.exe" file to whereever you want, usually just overwriting the existing "ZHelper.exe". If you want the source GM Studio project as well, extract the "ZHelper.gmx" folder and other files
- Once you've extracted the new executable, open it and you should be good to go
Custom Graphics
ZHelper has built-in support for loading custom graphics to replace the defaults. To use custom graphics, you need to create an assets folder inside "%LocalAppData%\ZHelper\" (press Windows+R and paste that in, without the quotes) and put the edited files inside the correct subfolder. Those subfolders are:
- firstrun
- fonts
- mainmenu
- options
- rando
- server
- tracker
- warning
For convenience, a copy of all the default assets with the correct folder structure is provided in the ZIP file with the program. The best way to get started is to copy the whole assets folder into "%LocalAppData%\ZHelper\" and edit away.
Files must be kept the same size as the originals, and must not be renamed. You can change transparency and it should work correctly, though some things might look funny if you do. A few things have hardcoded alpha settings and cannot be made fully opaque without editing the source.
Please note that using this feature may have a noticeable performance impact on slower systems, as it negates the texture page optimizations that GM does internally, leading to far more draw calls and texture batch changes than normal. On faster systems it shouldn't affect performance at all.
Custom graphics can be reloaded while the program is still running by using the reload button in the Options menu. Additional support for recoloring certain UI elements might come in the future.
Reporting Bugs
If something doesn't quite work the way you'd expect with the tracker, or if it crashes, won't start, etc., there are a couple places you can send bug reports:
- (Recommended)The zhelper-bug-reports channel on the Zelda 1 Randomizer Discord server. You can join by using this link: https://discord.gg/sSbA7Y. Feel free to throw in @Questwizard if its really urgent and I'll get to it as soon as I can.
- Sending me a PM on Twitch. My username there is Questwizard. I'd recommend using Discord instead. Twitch's notifications for messages pretty much don't exist/work, so I may not see it unless I happen to look.
When sending a bug report, try to be as detailed as possible. Try to give steps to recreate the issue if you can. If you get a GM error dialog (the one with the Abort button), copy and paste the text of that error into your report is possible. That info is very useful for tracking down where or what might have caused the crash.
