# ZHelper 5
---
## About ZHelper
Zhelper is a digital "tracker" program designed to assist you in keeping track of various things like map layouts, collected items, hints and more during NES Zelda 1 Randomizer runs. It was designed mainly for use with [Fred Coughlin's Zelda Randomizer](https://sites.google.com/site/zeldarandomizer/), but it can be used for other randomizers, vanilla Z1, romhacks and even some ZC/ZQC quests if they are similar enough to vanilla Z1. Additional support for other randomizers and ZC/ZQC may or may not happen in the future.

ZHelper was built entirely using GameMaker and can run on any OS that it supports exporting to, though a proper touch-based interface doesn't exist yet, so usability on things like phones and tablets may be limited. Certain features may only work on certain OSes due to GameMaker limitations. This mainly applies to global hotkeys, which only work on Windows unfortunately.

For Linux AppImage builds, you may need to perform additional setup like setting execute permissions on the file and/or installing some additional packages in order to get them working. It will depend heavily on what Linux distro you use. For example, I had to both set execute permission on the file manually and install two extra packages to get AppImages working on my end.

I have switched completely to using an Arch-based Linux distro as my main OS, so the Windows builds are going to be less tested than the Linux ones from now on.

## Features
- A detailed, markable overworld map showing where default secrets are, with support for all randomizer modes and even custom map images!
- A dungeon map system designed to be able to mark even very complicated random dungeon layouts in detail
- Automatic narrowing-down of which dungeons a given dungeon map can be as you mark dungeon screens (only if race mode is OFF)
- Markers for things like triforce pieces, heart containers, dungeon blockers, shop items and prices and all dungeon/overworld items
- A screen to mark helpful hints given by the old man
- A built-in timer that keeps track of how long you spent on each level as well as the overworld complete with an export function for showing the data on stream
- Advanced hotkeys including modifiers (shift, alt, ctrl)
- The ability to reorder and toggle on/off most types of icons to suit your preferences
- Tracker preset support
- Redesigned UI with higher-resolution icons and custom theme support that is easy to customize using a simple config file. A bunch of themes in both dark and light mode UI are included by default
- Greatly improved performance and compatibility from moving to modern GameMaker. No more sluggish 45fps scrolling!

## Planned Features
These may or may not make it in depending on how difficult they are to implement!

- (In progress) Networking support like v4 had, but no longer requiring two instances of ZHelper to be running (WebSocket-based server)
- (In progress) Touch-compatible UI layout
- Dashboard-style UI for showing almost all info at once on a full monitor
- Run Summary screen built into the tracker itself with data on level clear times, item acquisition, etc.
- Broadcast view for easily showing only the most relevant data on stream
- (In progress) Built-in theme editor

## Manual
Can't figure out how something works? A complete manual is available at [https://questwizard.net/zhelper/help-v5.html](https://questwizard.net/zhelper/help-v5.html).

### A couple notes on various features:
- 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 Linux.
- Custom themes should be in ztheme format (see the included files in the themes folder for examples), and need to be placed in "%LocalAppData%\ZHelper\themes\" on Windows or "/home/<username>/.config/ZHelper/themes/" on Linux. The built-in themes are included in the themes folder for reference. For Linux builds, these are inside the AppImage bundle, in "/usr/bin/assets/themes/".
- Custom sprite graphics are also supported. See the file HOW TO USE-READ THIS PLEASE!.txt in the assets-default folder for details.
- If you turn on the option to write timer stats to file, they are written to "%LocalAppData%\ZHelper\times\" on Windows or "/home/<username>/.config/ZHelper/times/" on Linux. Two copies are written, one with the data filename you choose on the create new data screen, and another that is always named times.txt. Times.txt is good for loading into an OBS scene for example, as a sort of recap scene of how long you spent in each dungeon and on the overworld. There is also an option for outputting individual level and total time files that are useful for more advanced stream layouts.

## License
ZHelper is open-source and all assets and code are free to use for anything you'd like, including your own projects. Feel free to make your own modifications as long as you aren't doing anything illegal with it.

## Credits
- Nintendo for making Zelda 1.
- Fred Coughlin for making the Zelda Randomizer.
- Thank you to everyone who has helped with their suggestions, testing, and feedback over the course of ZHelper's development! This thing wouldn't be in its current state without your help!
---

-Questwizard
