ZHelper 5 User Manual v5.00.09

Table of Contents

• First Run Setup
• Updating ZHelper
• Main Menu
• Options Menu
• Hotkey & Icon Ordering Options Menu
• Using Custom Themes
• The Create New Data Screen
• Using the Tracker
• Tracker Screen's Top Section
• The Overworld Tab (OW)
• The Dungeon Tabs (D1-D9)
• The Helpful Hints Tab (HH)
• The Server Tab (SRV)
• Icon Reference
• Suggestions & Bug Reporting

When you first open ZHelper, you will be get a popup dialog informing you of a couple basic things such as how to configure tracker options, where to locate this manual, and, if you are on a desktop OS, asking whether you want to enable automatic update checking or not. If the window isn't a good size, use F7/F8 to shrink/enlarge it on non-mobile OSes. Pressing F6 will toggle between classic and HD graphics, which mostly affects fonts as well as most tracker icons. HD graphics are better for larger window scales, while classic graphics are usually better for smaller screens.

For desktop OSes, simply click yes or no to enable or disable automatic update checking. It is recommended to enable this so you always have the latest fixes and new features. For more information on the updater functionality, read the 'Updating ZHelper' section below.

For all other OSes, just click either button. They will both just close the dialog as update checking isn't available on them.

For desktop OSes, you may also get a 2nd popup asking if you want to import your existing ZHelper 4 configuration settings if they exist. Simply click yes or no to decide. You can always do this later from the Options menu if you decide not to right away.

NOTE: This section only applies to desktop OSes, as other OSes either don't support automatic updates at all (HTML5), or are handled by their respective app stores (Android/IOS).

The process to update ZHelper is very simple. It differs slightly depening on how you want to update it, and whether you have automatic updates turned on or not.

If you want to update manually, start by downloading the new version off the website.

If you have automatic updates enabled, simply click the 'Download Update' button at the bottom-right of the main menu to view the changelog, then click 'Yes' to open your default browser, which should start downloading the new version. If automatic updates are disabled, either download the new version from the website, or click the 'Check for Updates' button. If an update is available, the button will change to say 'Download Update'. Click it again to start the process.

Once the new version is downloaded, simply unzip the files, overwriting the existing files. Once you restart, everything should be good to go. You can safely skip extracting the other directories inside the zip if you don't plan on using custom graphics.

The only mandatory files are 'data.win', 'options.ini' and 'ZHelper.exe'. The 'assets-' folders contain copies of all the sprite graphics in ZHelper, which can be edited and loaded in using the expanded custom theme support in ZHelper 5. For more information, check the 'Using Custom Themes' section. The 'themes' folder contains a few custom theme files, as well as a copy of the built-in default theme.

The main menu is where you access all of the main ZHelper features from.

The options available on the main menu are:

• Create New Data: Takes you do a screen where you can configure basic tracker settings such as the save filename, preset, etc.
• Load Saved Data: Brings up a dialog letting you choose an existing save to load. Simply click on the filename in the list, or type it in the text box, then click OK. If everything goes OK, it should load directly into the tracker. If you get a warning about invalid data or a version mismatch, the data was probably created with a different version of ZHelper, and won't be able to load properly. This may change in the future.
• Connect to Server: Not yet implemented. Use ZHelper 4 if you absolutely need networking functionality. This will return in a future update.
• ZHelper Website (Help/Credits): Asks to open your default browser to the ZHelper homepage.
• Randomizer Addons: Not yet implemented. This may or may not return to ZHelper, given that existing randomizers have almost all the features this had in ZHelper 4.
• Options: Takes you to the main Options menu.
• Exit ZHelper: Immediately closes the program.

The Options menu is where you access most of ZHelper's configurable settings. They are divided into several sections. use the mouse wheel or the scrollbar to see all of the available options.

Display/Mapping:

• Show mouseover outlines on maps: Shows or hides the white outlines around the currently-selected map cell. May make things less usable, but is included as some users requested it.
• Show coordinates on OW map: Toggles whether the Overworld map should be split into 8 rows with coordinates for each screen displayed above them, or compacted into a single grid with no coordinate display directly on the map.
• Use hexadecimal map coordinates: If this is enabled, coordinate displays will use hexadecimal numbers rather than the more common A1-H16 screen designations.
• Dungeon crosshatch overlays: When this is enabled, dungeons that are marked as a specific level will have a purple overlay over screens that are not part of the dungeon, to make the layout more obvious.
• Enable dungeon sub-icons: Toggles visibility of extra icons for marking certain problematic dungeon room enemies and item drops. They are displayed at the top-left and bottom-right of each dungeon room.
• Colorize dgn. rooms & doors: When this is turned on, the entire dungeon map will be displayed with the selected dungeon color, just as ZHelper 4 displayed it. When off, the map itself will always be gray, and only the item boxes and guide images will change color.
• Auto-highlight item boxes: If enabled, standard item boxes will automatically be highlighted when an item is selected in that box. Clearing the icon will also remove the highlight automatically.
• Show overlays on hover: If enabled, you can hover over the various overlay buttons above the Overworld map to temporarily show the respective overlays.
• Write timer stats files: Another feature from Bogie's ZHelper 4 edit with extra improvements. If enabled, a file with your run times on the Overworld and in each dungeon will be written to '%LocalAppData%\ZHelper\times\times.txt' (home/<username>/.config/ZHelper/times/times.txt on Ubuntu/Linux) when the run timer is stopped. A backup copy will also be saved in '%LocalAppData%\ZHelper\times\[Data Filename]-times.txt' (home/<username>/.config/ZHelper/times/[Data Filename]-times.txt on Ubuntu/Linux), where [Data Filename] is the full save filename you chose on the Create New Data screen. Now also writes additional files containing the location and acquisition time for various items. Can be used as part of a stream overlay if configured correctly in your broadcasting software. Item locations are blank for no location, ? for unknown levels, 1-9 for L1-L9, W for white sword cave, A for under the armos item and C for coast heart item. The current order of the item stats files is as follows, one per line: Book, boomerang, bow, bracelet, ladder, magic boomerang, magic key, raft, recorder, red candle, red ring, magic shield, silver arrows, wand, white sword, wooden sword, magic sword, blue candle, wooden arrows, blue ring, boomstick book, bomb upgrade rooms 1 & 2, Overworld take-any-one hearts 1-4, triforce pieces 1-8, Ganon defeated, Zelda saved, Bomb upgrade item drops 1 & 2 and finally, dungeon heart containers 1-9 (includes coast heart).
• + individual timer stats files: If enabled, individual files will also be written for each level, named 'level#.txt', where # 0 is the Overworld and 1-9 are for dungeons, as well as a file for the total time named 'total.txt'. Now also writes individual files for various item locations and their acquisition time. Item files are named [Item Name]_location.txt and [Item Name]_time.txt. Used for more advanced control over placement on stream overlays.
• Timer stats zero padding: If enabled, timer stats files will be padded with zeroes to make everything a fixed width.
• RMB on lvl. # sets itembox flags: When enabled, you can right-click the L1-L9 buttons in the top navigation bar in the tracker to highlight all item boxes for that level to mark them as obtained. This WILL break the timeline function! Do not report that as a bug as the highlights are intended to be 'item obtained' flags, not 'dungeon found' flags.
• Show fixed item boxes: On by default, this option toggles visibility of the six fixed item boxes in the top section of the tracker (wooden sword, magic sword, blue candle, arrows, blue ring and book).
• Dim inaccessible OW spots: Enabling this will dim Overworld screens that you don't have the proper items to access. Works with the bracelet, raft and recorder. Recorder screens will still have a blue tint, but it will be darker.
• Race mode: On by default, this disables any features that could potentially be considered as giving an unfair advantage during races. Currently only fully disables the dungeon finder function when active.
• Show zoomed OW map preview: When enabled, a zoomed-in version of the Overworld map will be drawn in the top-right corner of the window if the mouse is over an Overworld screen.
• Timer write interval: Controls how often the timer stats files will be written regardless of changes. This is in frames, so 60 is one second. 7200 (2 minutes) is the default. This can be set between 64 (1 second) and 216000 (1 hour). Very low values may cause performance issues due to the large amount of very small files being written repeatedly!
• OW tint: Allows you to select the desired invalid/whistle screen overlay colors on the Overworld map. Black is similar to the look of Z-Tracker, while red is closer to older versions of ZHelper. You can also disable the tint overlay entirely. Can be overridden using the buttons on the tracker screen.
• OW info: Changes the default info page shown below the OW map in the Classic UI. Choose between timeline, OW icon counters or notepad. Only OW icon counters are currently implemented! See the Overworld Tab (OW) section for more info on what each page does.
• OW icon translucency: Changes the translucency level for icons on the Overworld map. Can be overridden using the buttons on the tracker screen.
• Dgn. BG translucency: Changes the translucency level for unmarked areas on dungeon maps. Can be overridden using the buttons on the tracker screen.

Controls/Icon Ordering:

• Use hotkeys: If enabled, allows the use of 0-9 and A-Z keys to quickly set most map icons. Modifiers (Ctrl, Alt, Shift) can also be used.
• Hotkeys are global: Allows the use of map hotkeys while ZHelper isn't the active window. Use with caution!
• Configure hotkeys and icon order: Brings up the hotkey and icon order configuration screen. See the Hotkey & Icon Ordering Options Menu for more information on how to configure these.
• Arrow keys move cursor: A feature from Bogie's ZHelper 4 edit, this will enable the use of the arrow keys on the Overworld and dungeon maps while the mouse cursor is already over the map or a dungeon room. Pressing an arrow key will move the cursor one map cell in that direction, and will wrap around the edges to the opposite side as necessary. This only works while ZHelper is the active window due to GameMaker limitations.

Graphics:

• HD UI skin: Switches between the classic and HD UI skins. Mostly affects fonts as well as most tracker icons. Can also be toggled at any time by pressing F6. Classic graphics are easier to see in smaller windows, while HD graphics are better for larger windows. If you are using the default theme, this will also toggle the theme between its built-in classic and HD modes.
• Window scale: Click the + or - buttons to change the window scale. You can also use F7 and F8 at any time to change this.
• NES palette: Switches between using the FCEUX and Nestopia YUV NES palettes for dungeon color selection.
• Anim. Spd.: Changes the speed of pulsing animations such as mixed quest overlays and icon glow effects. This value is in frames.
• UI type: Changes between various UI layouts. Only Classic (the default) and Compact are currently implemented. Compact is simply a less-tall version of the Classic mode that is closer to the size of the ZHelper 4 window. You lose access to a few things on certain tabs and others are slightly modified to fit better. Overworld info tabs and shop tracking requires 'Show coordinates on OW map' to be disabled. Holding Shift and clicking the button will set the Debug mode. This makes the screen huge, but has room for lots of future debug info to be shown on screen and isn't meant to be used outside of development and testing.
• Load custom theme/Set default theme: Click the load button to choose a custom theme file to change the look and feel of most of the program. Explained in detail in the 'Using Custom Themes' section. Clicking the set default button will ask if you want to revert to the default theme. Note that you will have to restart ZHelper afterwards to revert any changed sprite graphics back to the defaults. This is due to GameMaker limitations.
• Theme editor (NYI!): Opens the built-in theme editor. Can be used to easily make custom themes. Not yet implemented, but you can still open it. Nothing is functional yet.

Performance:

• Auto-save delay: Controls the delay before data is automatically saved after updating an icon. This value is also in frames, and higher values reduce disk activity while saving less often, while lower values increase disk activity but save changes faster.

Network:

• Check for updates: Enables automatic update checking on desktop OSses. See the 'Updating ZHelper' section above for more information. Note: you can still check for updates manually by clicking the 'Check for Updates' button on the main menu.
• Include beta builds: When enabled, you will be informed of new beta and preview updates. This setting is ignored and always enabled if you are already running a beta or preview build.
• Set player name: Click to set your player name for use in co-op networking mode. Names can be up to 16 characters long.
• Set player color: Click to set your player color for co-op mode. Uses NES palette indexes. Simply click the color you want in the popup and click OK.
• Require server password: Requires anyone connecting to your session to enter the set password to be able to connect.
• Set server password: Click to set the server password. Max 48 characters. Text in this dialog is ALWAYS masked and will NOT have an option to unmask it for obvious reasons!

REMINDER: IT SHOULD BE OBVIOUS, BUT DO NOT USE PASSWORDS YOU USE ANYWHERE ELSE!

• Set max clients: Click to set the maximum number of clients the server will allow to be connected at once. The maximum is 8 and the minimum is 2.
• Set server port: Click to set the port number the server will listen for connections on. Text in this dialog is ALWAYS masked and will NOT have an option to unmask it for obvious reasons!

Debug:

NOTE: These options should NOT be enabled unless asked to for debugging purposes! They are not saved to the config file and must be re-enabled every time you start the program.

• GameMaker debug overlay: Toggles GameMaker's internal debug overlay showing various stats as well as the real FPS.
• Uncapped FPS: Removes the FPS cap. Only for performance overhead testing. Don't use this for normal use, as it may break things. The program is designed around running at 60fps, and while running faster might help very slightly with responsiveness, its usually not worth the CPU/GPU usage.
• Size/aspect ratio overlay: Mainly used for mobile debugging, as ZHelper needs to be scaled to fit all different sizes of screens, and this helps with that.
• Mouse position overlay: Shows the detected mouse position within the ZHelper window. Used for debugging scaling issues mainly with HTML5.
• Data integrity debugging: For debugging data corruption issues. Shows two numbers over anything that can have hotkeys and ordering changed. The various modes toggle between showing certain data since there isn't enough screen space to fit all of it at once. The yellow value is the original value in code, while the cyan one is the value after icon reordering is taken into account. Modes: 1 = Dungeon rooms, 2 = Horizontal dungeon doors, 3 = Dungeon sub-icons, 4 = Vertical dungeon doors. Things not on dungeons screens are always shown in any mode other than OFF.
• JSON packet debugging (F3): When enabled, you can press F3 while the mouse is over most things to see it's internal data as JSON. Mostly used for networking debugging.

---

Hotkey & Icon Reordering Options Menu

The Hotkey & Icon Reordering Options menu is where you configure map hotkeys and reorder/toggle icons to suit your preferences. Each section is for a different type of map icon. Use the Next/Prev. Page buttons to move between pages.

To set a key, left click an icon, and type the key you want to use into the dialog that pops up, then click OK. You can use modifier keys (Ctrl, Alt, Shift) by adding any combo of C, A or S before the hotkey you want to assign. For example, if you wanted to use Ctrl + Alt + R, type "car" in the box. Leaving the box blank will un-set that hotkey. Currently, only the letters A-Z and numbers 0-9 are supported as base hotkeys.

Right-clicking a box will toggle an icon on or off from the normal icon rotation when clicking or using the mouse wheel. You can still set a disabled icon by using its assigned hotkey, however.

Using Shift + Left-click lets you set special glow effects that pulse around certain icons. These use NES palette colors. Simply choose the color you want in the popup. Choose the bottom-right black color for a black glow or any black color with an X to clear the glow. Glow only works on Overworld and dungeon room icons currently.

To reorder icons, hover your mouse over the icon you want to move and press either Left Arrow or A to swap it with the previous icon in the list or Right Arrow or D to swap it with the next icon in the list. This affects the order icons will cycle in when clicking boxes or using the mouse wheel to scroll through them in the tracker.

To use hotkeys, simply put your mouse cursor over the icon you want to change and press the icon's assigned hotkey and modifier keys (if applicable). If global hotkeys are enabled, this also works while ZHelper is not the active window. Use global hotkeys with caution, as you might inadvertently change things when you didn't mean to without even realizing it!

---

Using Custom Themes

Introduction

ZHelper 5 has the ability to import custom sprite graphics to replace the defaults just as ZHelper 4 did. However, it also builds on this functionality by allowing near-complete customization of the color scheme of various items. Things like text-based buttons, dialogs, etc. are no longer individual sprites, but are now drawn on-the-fly using scripting. There is a new addition of .zhtheme files to support this. They are simple ini files that tell ZHelper the theme's color palette as well as which colors to use where. Loading of custom sprite graphics is now tied to these custom theme files, although there is still a way to load custom graphics using the default theme just in case.

To get started, you'll want to copy an existing theme you want to edit or the 'Template (Built-in).zhtheme' file (good for starting from scratch) from the included 'themes' folder to '%LocalAppData%\ZHelper\themes\' for Windows or '/home/<username>/.config/ZHelper/themes/' on Ubuntu/Linux. For the Ubuntu/Linux versions, the built-in themes are in the AppImage bundle in the '/usr/bin/assets/themes/' folder. A copy of the default sprite graphics is also included in the 'assets-default' folder. Do NOT copy the entire assets-default folder into the themes folder as-is unless you plan on changing everything, as unnecessary loading of custom graphics can have an impact on performance, especially on very slow systems. This is due to how GameMaker handles sprites from external files, and I have no control over how it does so. A copy of the default theme variants are included in the 'Default-Classic (Built-in).zhtheme' (Classic UI skin) and 'Default-HD (Built-in).zhtheme' (HD UI skin) files. These themes are a perfect match to the internal defaults as a reference.

Loading a Custom Theme

To load a custom theme, click the 'Load Custom Theme' button on the Options menu, then select the desired .zhtheme file. If a theme includes custom sprite graphics, see the next section on where to put them so they will be loaded along with the theme itself. To reset to the default theme, click the Set Default Theme button, then confirm by clicking OK on the popup dialog. Note: You will have to restart ZHelper to revert any loaded custom sprite graphics back to the internal defaults. This is just how GameMaker works unfortunately.

If you get a version mismatch popup, the loaded theme was designed for a different version of ZHelper. The program will try to account for this as best as possible to make older themes work correctly, but compatibility isn't guaranteed. If everything works as expected, you can probably just update the 'zhtheme_version' value in the file to the current version displayed in the mismatch dialog to stop the popup from appearing again. If things are broken, the theme will have to be updated manually in order to work.

Loading Custom Sprite Graphics

To load custom sprite graphics, you first need to create a folder inside '%LocalAppData%\ZHelper\themes\' on Windows or '/home/<username>/.config/ZHelper/themes/' on Ubuntu/Linux named 'assets-[Theme Name]', where [Theme Name] is replaced by the filename of the .zhtheme file you want the sprites to load with, including the extension. For example, if you had a theme file named 'custom.zhtheme', you would create a folder named 'assets-custom.zhtheme'. For the default theme, name the folder 'assets-default', with no .zhtheme on the end. This is because the default theme is stored internally, and not loaded from a .zhtheme file.

From here, you need to place any edited graphics in the exact same folder/file structure as the included assets-default folder. If they aren't named correctly, or aren't in the correct folder, they will not be loaded along with the theme.

Remember to only include the edited sprite files, as loading custom graphics will have a performance impact if you load too many on slower systems. Faster systems shouldn't have a problem with this, although its still wasting performance for no benefit. This is because GameMaker normally optimizes sprites to be on as few texture pages as possible, which allows for much more efficient rendering with fewer batches and draw calls. However, every single custom sprite is stored on its own unique texture page when it is loaded, which defeats the entire purpose of these optimizations, causing more batch breaks and draw calls to be necessary. There is literally nothing I can do about this other than convert the entire sprite set to my own custom texture page and use that everywhere, which would be both a pain for me as well as you to make custom themes with. If you want to see this in action, turn on the GameMaker debug overlay in the Options menu, copy the whole 'assets-default' folder over, set the default theme, and watch the batch and draw call counts on that overlay skyrocket, while the FPS takes a nosedive.

.zhtheme File Format (Theme version 2)

A .zhtheme file is a standard .ini format configuration file, just with a different extension. Sections are defined using a name inside square brackets '[ ]', while individual keys and values in those sections are stored one per line with the format 'key = value'. I'd recommend using the included file named 'Template (Built-in).zhtheme' as a starting point for making a fully-custom theme, as it only relies on a few grayscale colors, leaving most color slots available. Loading .zhtheme files themselves have no additional performance cost unlike custom sprites.

A Quick Note on Button Skins

If you see a key listed below with the format 'keyname_*' it is usually a button skin, which typically (but not always) have six key/value pairs, where the * is replaced with the following:

• lt: Light color, used as the color for the top and left two rows and columns of pixels in the button.
• ml: Medium light color, used as the color for the next two rows and columns of pixels from the top and left.
• bg: Background color for the middle of the button.
• txt: Text color.
• md: Medium dark color, used as the 3rd and 4th row and column of pixels from the bottom and right corner.
• dk: Dark color, used as the two rows and columns of pixels at the bottom and right corner.

Any additional pairs will be explained below as necessary. With creative use of different colors, you can create several different styles of buttons, both flat and 3d-looking.

A ZHelper theme file contains the following sections and keys:

[version]

zhtheme_version: Should always be 2 for up-to-date themes.

[colors]

Up to 48 sets of RGB key/value pairs named 'col_#_r', 'col_#_g' and 'col_#_b', where # is replaced with the number from 0-47. Any colors not included will just use the internal defaults. I'd recommend keeping color 0 as black in all cases, although its not strictly necessary. Values are from 0-255. All other values below are references to one of these 48 colors unless specified, and should have the values 0-47.

[theme_generic]

gen_txt: Generic white text color used in the menus.

gray_txt: Generic gray text color used in the menus.

title_txt: Generic text color used for the title text in various menus.

red_txt: Generic red text color used in the menus.

green_txt: Generic green text color used in the menus.

btn_gen_*: Default button skin used in the menus.

btn_gen_dis_*: Default disabled button skin used in the menus.

btn_gen_ok_*: Default OK button skin used in the menus.

btn_gen_ok_dis_*: Default disabled OK button skin used in the menus.

btn_gen_can_*: Default Cancel button skin used in the menus.

btn_gen_can_dis_*: Default disabled Cancel button skin used in the menus.

[theme_mainmenu]

mm_room_bg: Main menu background color.

opt_room_bg: Options menu background color. Applies to all menus other than the main menu.

btn_mm_*: Main menu button skin.

btn_mm_dis_*: Disabled main menu button skin.

[theme_panels]

pnl_title: Color used for the title text above panels in the menus.

pnl_*: Rest of the panel colors. Works just like a button skin even though it isn't one internally.

btn_pnl_*: Default panel button skin.

btn_pnl_dis_*: Default disabled panel button skin.

btn_pnl_inv_*: Default inverted panel button skin. Used for checkboxes.

btn_pnl_inv_dis_*: Default inverted disabled panel button skin. Used for checkboxes.

[theme_dialogs]

dlg_mask: A translucent background color that gets drawn over the entire window when a dialog is active.

dlg_mask_alpha: The alpha value for the dialog mask background. Needs to be a value from 0-1.

dlg_title_l & dlg_title_r: Two key/value pairs used to determine the color of dialog titlebars. Drawn as a smooth gradient from the l color to the r color.

dlg_title_txt: Dialog titlebar text color.

dlg_*: Main dialog box colors. Works just like a button skin, but isn't internally.

btn_dlg_*: Default dialog button colors. Used by scrollbars.

btn_dlg_dis_*: Default disabled dialog button colors.

btn_dlg_ok_*: Dialog OK button colors.

btn_dlg_ok_dis_*: Disabled dialog OK button colors.

btn_dlg_can_*: Dialog Cancel button colors.

btn_dlg_can_dis_*: Disabled dialog Cancel button colors.

dlg_txtbox_*: Dialog text box colors. Usually similar to inverted panel colors to make them recessed in 3D. These three sets are not button skins internally, but work like them.

dlg_txtbox_dis_*: Disabled dialog text box colors. Usually similar to inverted panel colors to make them recessed in 3D.

dlg_file_*: Same as text box colors, but for file selection boxes. Has a couple additional colors listed below.

dlg_file_sel_bg: Background color for the currently selected file in the list.

dlg_file_sel_txt: Text color for the currently selected file in the list.

dlg_scb_area_bg: Scrollbar area background color.

[theme_tracker]

trk_room_bg: Tracker screen background color.

trk_gen_txt: Generic white text color used in tracker screens.

trk_gray_txt: Generic gray text color used in tracker screens.

trk_triforce_txt: Text color used for the number on obtained triforce icons.

trk_triforce_dis_txt: Text color used for the number on un-obtained triforce icons.

trk_bomb_txt: Text color used for the number on obtained bomb upgrade icons.

trk_bomb_dis_txt: Text color used for the number on un-obtained bomb upgrade icons.

btn_trk_gen_*: Default button skin used by many tracker buttons.

btn_trk_gen_dis_*: Default disabled button skin used by many tracker buttons.

trk_top_bg_l & trk_top_bg_r: Two key/value pairs used to determine the color of the top bar on the tracker screen. Drawn as a smooth gradient from the l color to the r color.

trk_top_txt: Text color for the timer and FPS counter on the top bar of the tracker screen.

btn_trk_top_*: Default button skin for the top bar on the tracker screen.

btn_trk_top_dis_*: Default disabled button skin for the top bar on the tracker screen.

btn_trk_top_timer_*: Button skin for the timer button on the tracker screen.

btn_trk_top_timer_dis_*: Disabled button skin for the timer button on the tracker screen.

btn_trk_top_help_*: Button skin for the help button on the top-right corner of the tracker screen.

btn_trk_top_help_dis_*: Disabled button skin for the help button on the top-right corner of the tracker screen.

btn_trk_top_reset_*: Button skin for the reset button on the top-right corner of the tracker screen.

btn_trk_top_exit_*: Button skin for the exit button on the top-right corner of the tracker screen.

trk_info_bg_l & trk_info_bg_r: Two key/value pairs used to determine the color of the middle info bar above the map on the tracker screen. Drawn as a smooth gradient from the l color to the r color.

trk_info_txt: Text color for the middle info bar above the map on the tracker screen.

btn_trk_df_y_*: Button skin for selected valid dungeon number buttons on the dungeon map screens.

btn_trk_df_y_dis_*: Button skin for valid dungeon number buttons on the dungeon map screens.

btn_trk_df_n_*: Button skin for selected invalid dungeon number buttons on the dungeon map screens.

btn_trk_df_n_dis_*: Button skin for invalid dungeon number buttons on the dungeon map screens.

trk_btm_*: Has the same values as a button skin, but is nothing like one. These colors control the text, border, and background of various parts of the info text and shop area at the bottom of the tracker. Also has an extra values below.

trk_btm_sel_bg: Background color for selected items on the shop tracker.

trk_save_bg_l & trk_save_bg_r: Two key/value pairs used to determine the color of the autosave text area drawn on the right side of the info bar above the map on the tracker screen. Drawn as a smooth gradient from the l color to the r color.

trk_save_txt: Text color for the autosave text area drawn on the right side of the info bar above the map on the tracker screen.

btn_trk_area_*: Button skin used to draw the area names on the Overworld area overlay.

btn_trk_dgn_clear_*: Button skin used by the clear button at the bottom of dungeon maps. Also used by the 'I Derped' button on the Overworld map.

btn_trk_map_current_*: Button skin used by the current map button at the left side of the middle info bar on the tracker screen.

btn_trk_hint_y_*: Button skin used by hint buttons in the true state.

btn_trk_hint_n_*: Button skin used by hint buttons in the deceptive state.

---

The Create New Data Screen

This screen is where you set up various options for a new tracking session.

Data filename:

Choose: Click this button to select a filename to save the new tracking session to. Using an existing filename will overwrite the existing data if a save is triggered.

Auto-append date and time to filename: If checked, will add the current date and time to the end of the chosen filename automatically. Use short filenames or this may overflow the maximum filename length the dialog box can support and cause issues.

Preset selection:

Default: Nothing marked. A completely blank slate.

1st/2nd quest default caves: Fills in the icons on the Overworld map with the respective quest's vanilla cave types. Also fills in the shop section at the bottom of the tracker screen with the vanilla data.

Custom: Click the choose button to choose a saved tracker session to use as a preset. The selected saved data will not be overwritten unless you choose the same filename as the data filename.

Internal Server Settings (Not yet implemented!)

Allow clients to connect: This toggles the ability for other users to connect to your tracker session. Can also be changed on the SRV tab during a session.

Require server password: Requires anyone connecting to your session to enter the set password to be able to connect.

Set server password: Click to set the server password. Max 48 characters. Text in this dialog is ALWAYS masked and will NOT have an option to unmask it for obvious reasons!

REMINDER: IT SHOULD BE OBVIOUS, BUT DO NOT USE PASSWORDS YOU USE ANYWHERE ELSE!

Set max clients: Click to set the maximum number of clients the server will allow to be connected at once. The maximum is 8 and the minimum is 2.

Set server port: Click to set the port number the server will listen for connections on. Text in this dialog is ALWAYS masked and will NOT have an option to unmask it for obvious reasons!

---

Using the Tracker

The following sections all cover how to use the tracker itself. Once you have gone through the Create New Data screen, you will go to the main tracker screen. It is broken into several sections.

NOTE: Depending on your UI type, the following things may be in different spots or missing altogether (this is intentional for the Compact UI, for example). The positions mentioned in this documentation all assume you are on the default 'Classic' UI type.

To use hotkeys for items that have them set, simply hover the mouse over the icon you want to set and press the hotkey (plus any modifier keys) you assigned in the Options menu. If global hotkeys are on, this will also work if ZHelper is not the focused window, but increases the chances of accidentally marking something you didn't mean to.

At the very top is the navigation bar, which has buttons for each individual tracker tab, the timer and help, reset and exit buttons.

Below that is the 'Top' section that contains boxes for what items you have found and where, dungeon blockers and various buttons to toggle things like overlays and maps

Right below that is the info bar, which shows you info on what the mouse is over.

Next is the map section which contains the main map you are working on.

Finally, at the bottom is the info panels, shop info and status bar.

---

Tracker Screen's Top Section

Navigation Bar

The navigation bar is at the very top of the screen and goes all the way across it. It contains buttons for switching tabs, the timer and help, reset and exit buttons.

Your current tab is the highlighted button. Each tab is explained in detail further down.

To the right of the tab buttons is the timer. Left-clicking the button or pressing the F11 key will start and stop the timer. Right-click the timer button to reset it. This will also stop the timer. When the timer is stopped, info files containing the time spent on each map will be generated if the respective options are on in the Options menu.

Next is the FPS counter. This should always be 60 if the program is running properly.

The three buttons at the far right have their own functions. The first is the help button, which will change the info bar from showing detailed descriptions of Overworld screens to showing control help instead.

The 2nd button is the reset button. Left-click or press F1 to reset the tracker to the selected preset. Shift + Left-click or Shift + F1 to soft-reset, which only clears triforces and 'obtained' flags on everything, but leaves the general maps intact. You will get a confirmation dialog before anything gets cleared.

The final button is the exit button. Left-click or press F9 to save and exit to the main menu. Shift + Left-click or Shift + F9 will exit without saving. This will also pop up a dialog for confirmation before exiting.

Item Buttons

Below the navigation bar, the left 2/3 of the top section is mostly made up of various types of item buttons, with some tracker control buttons below. Those will be explained later. This section only goes over the item buttons.

At the far left are four heart icons in a vertical column. These are for the Overworld 'Take One' cave hearts. Left-click/Right-Click or use the mouse wheel to cycle through the different options. A dark gray heart means not obtained, while the bright red one means you have that heart container. A heart within a heart is part of the hidden dungeon mode and can not be set for these four boxes. Finally, the X means you won't get that heart or took something else.

Along the top row is a miniature version of the hints tab where you keep track of the location hints from info shops and the old man. Hints are sorted by level, plus WS and MS for the white sword and magic sword. Use Left-click/Right-click/mouse wheel on the ? icon to cycle through locations for each hint. Hold Shift to cycle through truth states instead. White text is unknown, green is true and red is deceptive. Extra icons for whether the raft and bracelet are not required are also provided.

Below that are 9 triforce buttons and a fire icon to the right of those. Left-click toggles the icon on or off, Right-click marks as not needed and the mouse wheel changes the triforce level number if hidden dungeons mode is active. The 9th icon is for marking Ganon's defeat. Right-click is also supported for that icon. The fire icon is for marking when you save Zelda. This will automatically stop the timer if it is active as well. Marking a dungeon on the Overworld map will light up the text on the respective triforce icon. If you also have a non-deceptive hint set on the hints tab, hovering over a triforce icon will show all of the possible screens that level might be found on.

Below the triforce icons are the main dungeon item boxes. The top row will be mostly replaced by heart icons if heart shuffle mode is off. These heart icons work the same way as the previous set do and will sync up with the item boxes used when heart shuffle is on, but only if said heart icons are marked in the top row as well. There may be more or less boxes in the bottom row depending on whether hidden dungeon numbers is turned on. The 1Q L1 and 2Q L4 boxes are toggled by changing the dungeon quest using the '1-6' quest button on any dungeon tab. For item boxes, Left-click/Right-click/mouse wheel cycles through the different icons available. Middle-click or Shift + Left-click highlights the border around the box indicating you have obtained that item. Setting the 'X' icon or pressing Shift+Middle-click or Shift + Right-click will mark the item as 'Don't want' which both puts an X on the item icon and tints the box red. If you set dungeon colors on the dungeon maps, the boxes themselves will be tinted that same color with the exception of 'X' icons which remain red.

To the right of the item boxes are 9 more item boxes plus two bomb upgrade icons. The leftmost column of boxes work the exact same as the dungeon item boxes, but are for marking the white sword cave, under the armos and ladder heart items. The other six boxes are for marking the wooden and magic swords, candle, arrows, blue ring and book. These icons are only visible if the 'Show fixed item boxes' option is enabled in the Options menu. These boxes can only be highlighted by Left-clicking them. They are fixed to their specific items unlike the other item boxes. For bomb upgrades, Left-click/Right-click/mouse wheel cycles through which level the upgrade is located in, while Shift + Left-click or Middle-click highlights the box as obtained.

Blockers

The numbered rows of item boxes on the far right are for dungeon blockers, meaning things like ladder block, meat block, recorder block, etc.. A gray background means it is a known blocker, while the orange background icons are for marking possible blockers that are not known for sure. These boxes use the same control scheme as the dungeon item boxes.

Tracker Control Buttons

The row of buttons below the item boxes are for controlling various settings such as the Overworld quest, map overlays and hidden dungeon items modes. For overlay buttons, if the 'Show overlays on hover' option is on, you can hover over the various overlay buttons with the mouse to see the overlays and or hide icons temporarily. They are as follows:

• OW: #: This button changes the selected Overworld quest which will change the Overworld map and its overlays to match the selected quest. It cycles through 1st, 2nd, mixed 1st, mixed 2nd and custom quests. Custom quest is a special mode for playing with non-standard Overworld maps. You can also use this mode for tracking romhacks, Infinite Hyrule maps or NES-like Zelda Classic/ZQuest Classic quests. The map background will become gray when custom quest mode is on, but you can load a custom background by using the 'Load Custom Map' button located below the map on the Overworld tab. See the Overworld tab section for more info on this function.
• MIR: Mirrors the Overworld map horizontally. Will automatically ensure overlays are also mirrored, but will not mirror icons you have already marked, so make sure this is on before you start marking anything!
• AREA: Toggles an overlay that shows the names and screens that are part of various areas of the vanilla Overworld maps. These can be used to narrow down what screens something can be on based on hints you have found. This function is not supported in custom quest mode.
• OPEN: This button toggles yellow ? icons on screens that are open caves which require no item to enter. If an icon is already marked on a screen, it will show instead. F10 also toggles this at any time. This function is not supported in custom quest mode.
• HDN: Toggles hidden dungeon items mode. This adds extra item boxes in the third row and allows you to change the dungeon numbers by using the mouse wheel on a triforce icon.
• OV#: Toggles tinted overlays on the map showing which screens have an entrance and which are recorder screens. The default type of overlay changes based on the 'OW Tint' option in the Options menu, but can be overridden here if needed.
• TR: #: Sets the icon translucency level on the Overworld map as well as the translucency level of unexplored dungeon areas. Which value is changed depends on your current tab. The default values change based on the translucency options in the Options menu, but can be overridden here if needed.
• HS: Toggles heart shuffle mode. Replaces the top row of dungeon item boxes with heart icons. This function is there for those who prefer these icons. They will sync with the dungeon item boxes as long as they are set to hearts in the same position as the heart icon itself.
• ZM: Toggles showing a zoomed-in view of the Overworld map in the top-right corner of the tracker window while the mouse is over the Overworld map.

Info Bar

The info bar is located right between the top section and the current map.

At the far left is a button that shows the currently-selected tab. Left-Click/Right-click/mouse wheel can be used to quickly change tabs. Page Up and Page Down also work at any time to quickly switch tabs without using the mouse.

The text shown will depend on what the mouse is over currently as well as whether the help button is toggled on or off.

During an auto-save, a small 'Saving...' message will pop up at the far-right side briefly, letting you know a save has occured.

Shop Info

At the bottom right of the screen, you will see a shops section for tracking shop items and prices. This is visible on all tabs. SH1-SH4 corresponds to the matching SH1-SH4 Overworld icons.

The top row (potions) have the item icon locked, while all the others (defaults to a ?) can be changed by using Left-click/Right-click/mouse wheel.

To the right is the price of the item. To set a price, either use the mouse wheel over individual numbers to increase or decrease the price by 1/10/100 or Left-click to bring up a dialog where you can type in the correct price.

Pressing Delete over either the icon or the price will clear both the item icon and the price.

Status Bar

At the very bottom of the screen is the status bar. Various messages will pop up here when certain things happen. The status bar is only visible in the Classic UI.

---

The Overworld Tab (OW)

The Overworld map is very easy to read and use. It may look different depending on what options and overlays are in use. The background shows the current quest's Overworld map (or a custom map if selected). Yellow dots are bomb spots, lime green are candle burn spots, pink spots are either caves under armos statues or pushable rocks and black are open caves.

If tint overlays are on, darkened or red-tinted screens do not have any entrances and don't usually get marked. Blue-tinted screens are screens where the recorder may open up an entrance.

If coordinates are on, the map will be separated and the coordinates of each screen will be shown above the screen in the grid. If the number is lit up, the screen flag is on, meaning you have been there. The screen flag can be toggled manually by using Middle-click or Shift + Right-click. NOTE: Screen flags are not visible if the 'Show coordinates on OW map' options is off in the Options menu.

To set an icon on the selected screen, use Left-click/Right-click/mouse wheel.

To set the Overworld start screen, use Shift + Left-click. This will overlay a bright green box on that screen. Shift + Left-click again will clear the flag. Only one screen can be set as the start screen at a time.

To set danger flags, use Ctrl + Left-click. This overlays a red box on that screen with an !. This is used for marking screens with potentially dangerous enemy combinations to assist in routing around them.

Pressing Delete will clear the current screen's icon and flags.

There is a timer below the Overworld map showing how long you have been on the Overworld while the timer is active. This goes purely off how long you have been on that tab in the tracker, not by game time.

The 'Load Custom Map' button below the Overworld map can be used to load in a custom map background when custom quest mode is active. Custom map images should be in png format, and need to be placed in '%LocalAppData%\ZHelper\maps\' on Windows or '/home/<username>/.config/ZHelper/maps/' on Ubuntu/Linux. The map image will be stretched to fit the whole background. Leave the filename blank in the popup dialog to clear the map back to a blank gray one and use the Cancel button to keep the current map.

The 'I Derped' button (yep this is a thing lol) lets you clear all X icons off the Overworld map in case you find out you mis-marked one somewhere and can't figure out which one it is. This pops up a confirmation dialog before clearing anything.

The rest of the bottom area will depend on which info page is currently selected. Left-click the 'T/O/N' button just to the left of the shop info area to change between pages.There are three different pages to select from: Timeline, OW icon counters and notepad.

The timeline page will show a graph of when you obtained various items throughout the run as well as a line graph of your current Overworld progress. The timer must be active or the timeline will not properly update with new things you have marked.

If the 'OW icon counters' page is selected and you are not in custom quest mode, there will be a bunch of text info below the map. This shows how many of each type of icon you have marked, which levels and warps are marked, etc.. Gray text means you don't have the item marked, green means you have the correct amount marked and red means you have too many of that icon for the current quest marked. The numbers in parenthesis show the current total marked vs how many there should be on the map.

The notepad page will allow you to type a few lines worth of custom text to keep whatever notes you need. This is not implemented yet and will be blank.

---

The Dungeon Tabs (D1-D9)

The dungeon tabs house everything you need to map out even complex randomized dungeons. it contains icons for rooms themselves, doors and (if enabled) sub-icons for marking additional enemy and item types per room.

Dungeon Map

All dungeon map icon boxes use the exact same control scheme. Left-click/Right-click/mouse wheel cycles through icon types. Delete will clear the icon. In addition, the room icon boxes have danger flags just like the Overworld ones. Use Ctrl + Left-click on a room icon to toggle the danger flag.

Each room is made up of a central room icon for marking the bulk of room types possible, up to four (depending on position) door icons for marking door types and (if enabled in the Options menu), sub-icons for enemies (just outside the top-left of the room icon) and items (just outside the bottom-right of the room icon).

On the right and bottom sides of the map, there are guides showing what icons and parts of the dungeon wall graphics on screen line up with the game's built-in minimap. You can edit the 'LEVEL-?' by clicking the '^Edit' button below the guide images.

There is also a timer showing how long you have been on that particular dungeon map while the timer is active.

Clicking the red 'Clear' button will clear the entire dungeon map, all flags on it and also reset both the dungeon overlay setting and dungeon color.

Dungeon Overlay

The dungeon overlay section is located to the right of the map and lets you choose a vanilla dungeon layout for the current map. Left-click a number to choose the dungeon you want. The '1>' row is 1st quest and the '2>' row is 2nd quest. If the 'Dungeon crosshatch overlays' option in the Options menu is enabled, a purple crosshatch overlay will be put on top of room icons that are not part of the chosen dungeon. The proper rooms will also have their background lit up slightly. These icons will stay lit up regardless of what the dungeon translucency setting is changed to.

Using the 'Set All' button will set all overlays in one click based on the selected dungeon quest settings.

The 'Finder' button will activate special dungeon finder logic that can automatically narrow down possible dungeons based on which rooms you have marked. This function is disabled in race mode. The dungeon finder will change the dungeon overlay buttons to red or green depending on whether they are a valid dungeon or not. You can still choose an invalid map if needed to check layouts manually.

Quest

The quest section sets which vanilla quest levels 1-6 and 7-9 use. This will also change which extra item box is visible in the 3rd row of the top section while hidden dungeon numbers mode is off. Left-click to change the quest. Right-clicking the button will set all of the item boxes for those dungeons to their vanilla items for easy reference. This will popup a confirmation dialog as it cannot be undone without manually unsetting each box.

Dungeon Color

The dungeon color setting lets you set a color tint for all the dungeon room backgrounds as well as the item boxes for that dungeon in the top section of the tracker. Left-click a color to set it.

Drop Rooms

These graphics show the drop rooms for the current dungeon based on vanilla dungeon numbers and the selected quest.

Map Shift Controls

Left-click these buttons to move the entire map around if you accidentally mis-aligned it at some point. It will not wrap around the edges of the map and will just throw an error in the status bar in that case.

---

The Helpful Hints Tab (HH)

The hints tab is where you keep track of the location hints from info shops and the old man. Hints are sorted by level, plus WS and MS for the white sword and magic sword.

The first column, Hint Location, has buttons used to select the location of that specific level or item. Use Left-click/Right-click/mouse wheel to cycle through locations.

The second column is used to mark the hint as truthful or deceptive, as both can exist in the randomizer. Use Left-click/Right-click/mouse wheel to cycle through truth states.

To the right of the truth buttons is the text the message will say when referring to that specifc level or item.

Below the main hint buttons are checkboxes for the 'No feat of strength...' and 'Sail not...' hints. If you see either of these, check the matching box here to automatically dim the associated Overworld screens.

Clicking the 'Extra Hint Info' button will bring up a dialog with some extra messages you may see and what they actualy refer to.

Clicking the 'Triforce Layouts' button will bring up a dialog with the 1st/mixed and 2nd quest subscreen triforce layouts.

---

The Server Tab (SRV)

Coming Soon!

Networking isn't currently implemented in ZHelper 5. Use ZHelper 4.45 if you absolutely need networking support. Networking will be in v5 soon.

---

Icon Reference

This section is a reference of what all of the different types of icons in the tracker are in case you are not sure what some of them refer to. Icons are shown with both the Classic and HD UI versions. Classic UI will be the top half of each image, while the HD UI will be the bottom half.

Heart Icons


• From left to right: Blank, obtained, will not obtain, double heart for dungeons.

Triforce Icons


• From left to right: Blank, obtained, not needed, Ganon not defeated, Ganon defeated, Zelda not saved, Zelda saved. The number is the dungeon number for that piece. A white (rather than gray) number on an unmarked icon means that dungeon has been found.

Blank Item Box Icons


• From left to right: Blank, obtained item. Same in both Classic and HD UI. This same style applies to all item and blocker boxes.

Dungeon Item Box Icons


• From left to right: Book, boomerang, bow, bracelet, ladder, magic boomerang, magic key, raft, recorder.

• From left to right: Red candle, red ring, shield, silver arrow, wand, white sword, will not obtain, heart container.

Overworld Item Box Label Icons


• From left to right: White sword cave, under the armos item, ladder heart item.

General Item Box Icons


• From left to right: Wooden sword, magic sword, blue candle, arrows, blue ring, boomstick book (usually marked in atlas and/or boomstick mode).

Dungeon Blocker Box Icons


• Known blockers from left to right: Bow & arrow, recorder, ladder, key, red bubbles, meat, rupees, bombs, sword power.

• Potential blockers from left to right: Bow & arrow, recorder, ladder, key, red bubbles, meat, rupees, bombs, sword power.

Overworld Icons


• Overlays from left to right: Danger flag (coordinates on), Danger flag (coordinates off), Overworld start screen overlay, open cave overlay icon. All icons except the open cave overlay are the same in both Classic and HD UI.

• From left to right: Unknown level, levels 1-9.

• From left to right: Warp caves 1-4.

• From left to right: Take any one cave, letter cave, under the armos item screen, magic sword cave, white sword cave, wooden sword cave, pay for info shop, cleared/not important screen.

• From left to right: Arrow shop, bomb shop, book shop, candle shop, heart shop, key shop, meat shop, blue ring shop, shield shop.

• From left to right: Potion shop, tracked shops 1-4 (corresponds to the tracker's shop section).

• From left to right: Money-making game, Door repair charge, unknown rupee secret, large rupee secret (~100), medium rupee secret (~30), small rupee secret (~10).

Dungeon Room Icons


• Overlays from left to right: Danger flag (Same in both Classic and HD UI), dungeon layout crosshatch overlay.

• From left to right: Cleared/not important room, Unknown room, not a room.

• From left to right: Key drop, triforce, heart container, map, compass, special item (stairs), special item (floor drop), bomb drop, blue rupee drop.

• From left to right: Bomb upgrade, leave money or life, meat block (grumble, grumble room), old man, Zelda.

• NOTE: This item is NOT up-to-date! It will be updated soon!
• From left to right: 10-rupee boss, Ganon, Ganon roar, boss roar, red bubbles, blue bubbles, both bubbles.

• Dungeon start rooms from left to right: Left entrance, right entrance, top entrance, bottom entrance.

• Dungeon stair rooms from left to right: Unknown stairs, passageways 1-9 (mark both the entrance and exit screens as the same number).

• From left to right: Recorder block, bow & arrow block, sword/wand block, vertical chute room, horizontal chute room, possible push block room, turnstile room.

• Ladder block rooms from left to right: Generic ladder block, top block, horizontal chute, right block, middle block, 'chevy' room, upside-down U block, 'r' block.

Dungeon Door Icons


• Horizontal dungeon doors from left to right: Solid wall (already bombed), open door, two-way shutter, walk-through wall (right), walk-through wall (left), walk-through wall (left + right), unknown wall, one-way shutter (right), one-way shutter (left), locked door, bombable wall.

• Vertical dungeon doors from left to right: Solid wall (already bombed), open door, two-way shutter, walk-through wall (down), walk-through wall (up), walk-through wall (up + down), unknown wall, one-way shutter (down), one-way shutter (up), locked door, bombable wall.

Dungeon Enemy Sub-Icons


• From left to right: Gleeok, Gohma, Digdogger, Dodongo, Patra, Wizzrobes, Darknuts, Manhandla, other enemies, blue bubbles, red bubbles.

Dungeon Item Sub-Icons


• From left to right: Triforce, heart container, other item, bomb drop, key drop, blue rupee drop, map, compass.

---

Suggestions & Bug Reporting

For reporting bugs or suggesting new features, you can do so in a couple different ways:

• (Recommended)The ZHelper channels on the Zelda 1 Randomizer Discord server. You can join by using this link: https://discord.gg/BEwVJUxxrW. Feel free to throw in @Questwizard if its really urgent and I'll get to it as soon as I can. If the invite link stops working, let me know however you can and I'll see if they can get a new link. I don't have invite permission anymore so I can't do it myself.
• 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 GameMaker error dialog (the one with the Abort button), copy and paste the text of that error into your report if possible. That info is very useful for tracking down what might have caused the crash.