---

Work In Progress

This page is a work in progress.

Table of Contents

• First Run Setup
• Updating ZHelper
• Main Menu
• Options Menu
• Hotkey Options Menu
• Using Custom Themes

---

First Run Setup

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.

---

Updating ZHelper

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 or themes.

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.

---

Main Menu

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 an older version of ZHelper, and won't be able to load properly. This may change in the future once a stable release happens.
• 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.

---

Options Menu

The Options menu is where you access most of ZHelper's configurable settings. They are divided into four sections:

Tracker Options:

• 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.
• Show crosshatch overlay on non-dungeon screens: 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.
• 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.
• Write timer stats file: Another feature from Bogie's ZHelper 4 edit. If enabled, a file with your run times on the Overworld and in each dungeon will be written to '%LocalAppData%\ZHelper\times\times.txt' when the run timer is stopped. A backup copy will also be saved in '%LocalAppData%\ZHelper\times\[Data Filename]-times.txt', where [Data Filename] is the full save filename you chose on the Create New Data screen. Can be used as part of a stream overlay if configured correctly in your broadcasting software.
• Also write individual stats files: In 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'. Used for more advanced control over placement on stream overlays.
• Dungeon Finder Delay: Controls the time in between runs of the dungeon finder logic when the feature is enabled on the dungeon maps. The value is in frames, and lower values will reduce the update delay at a heavy performance cost, while higher values will reduce CPU usage but increase delay.
• 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.
• Use hotkeys: If enabled, allows the use of 0-9 and A-Z keys to quickly set most map icons.
• Global keys: Allows the use of map hotkeys while ZHelper isn't the active window. Use with caution!
• Configure: Brings up the hotkey configuration screen.
• OW Tint Type: 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.

Graphics Options:

• 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.
• NES Palette: Switches between using the FCEUX and Nestopia YUV NES palettes for dungeon color selection.
• 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.
• Window Scale: Click the + or - buttons to change the window scale. You can also use F7 and F8 at any time to change this.

Network Options:

• 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 & preview 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.

Debug Options:

NOTE: These options should NOT be enabled unless asked to for debugging purposes!

• Enable GameMaker's built-in debug overlay: Toggles GameMaker's internal debug overlay showing draw call/batch counts 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 will break the timer functionality. 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.
• Show display 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.

---

Hotkey Options Menu

The Hotkey Options menu is where you configure map hotkeys. Each section is for a different type of map icon. 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. Leaving the box blank will un-set that hotkey. Currently, only the letters A-Z and numbers 0-9 are supported. Better hotkey support will come in the future. Right-clicking a box will disable that icon from showing up in the normal icon rotation when clicking or using the mouse wheel. You can still set a disabled icon by using its assigned hotkey, however.

To use hotkeys, simply put your mouse cursor over the cell you want to change on the map, and press the icon's assigned hotkey. 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 almost 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 the contents of the included 'themes' folder to '%LocalAppData%\ZHelper\themes\'. A copy of the default sprite graphics is included in the 'assets-default' folder. Do NOT copy the entire assets-default folder into the themes folder as-is, as unnecessary loading of custom graphics can have a HUGE impact on performance, especially on slower 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 is included in the 'beta-default-hd.zhtheme' file. This theme is a perfect match to the internal defaults.

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\' 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 HUGE 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. It should be 4/4 in the menus, 4/6 in the tracker, and 4/7 with a custom Overworld map loaded into the tracker.

.zhtheme File Format (Note: Theme v2 is still WIP and the following may change at any time!)

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 'beta-default-hd.zhtheme' as a starting point, as it is an exact copy of the internal default theme. 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_lt_*: 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_lt_*: 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.

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.

---

    -Questwizard