ZHelper 4

Home ZHelper Home v5 Manual v4 Manual HTML5 Version Version History Privacy

ZHelper 4 User Manual v4.44

Table of Contents

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:

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:

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)

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

Level Icons Warp Icons Shop Icons Rupee Secret Icons Misc. OW Icons

Dungeon Icons

Stair Icons Blocker Icons Boss Icons Drop Icons Guy Room Icons Misc. Dungeon Icons

Dungeon Door Icons

Wall Icon Open Door Icon Shutter Icons Walk-through Wall Icons Locked Door Icon Bombable Wall Icon

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:

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:

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:

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:

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:

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.