This page is a work in progress.
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.
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.
The main menu is where you access all of the main ZHelper features from.
The options available on the main menu are:
The Options menu is where you access most of ZHelper's configurable settings. They are divided into four sections:
NOTE: These options should NOT be enabled unless asked to for debugging purposes!
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!
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.
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.
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.
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.
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:
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:
zhtheme_version: Should always be 2 for up-to-date themes.
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.
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.
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.
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.
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.
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.