Short sessions on a handheld are great until you get stuck. A boss you cannot beat, a puzzle you have forgotten the answer to, an item you are sure you missed three dungeons ago. Out comes the phone, you find the guide, lose your place in it, and by the time you are back the mood is gone.
I wanted the guide on the Miyoo itself. So I built Guide Watch for OnionOS: it tells you when a guide exists for your game, opens it on a button combo, and puts you back exactly where you paused.
What it does
- A rumble tells you a guide exists. Start a game that has a guide and the Miyoo gives one short buzz. No buzz, no guide, no menu to check.
- L2 + R2, then Down, opens it. Hold L2 and R2, press Down. The game saves, there is a short black screen, and the guide opens full screen.
- MENU brings you back. Press MENU and the game relaunches and loads the save state. You are where you left off. A buzz tells you the combo is armed again.
- It remembers your place in the guide. Reopen the same guide later and it is on the page you left. That part is done by the Ebook Reader itself.
- A downloader on the device. Guide Downloader fetches the guides over wifi, so you never need a computer. It scans your
Romsfolders, tells you how many guides are missing and roughly how long it will take, and lets you fetch for all consoles or just one. Guides land next to each ROM asGame Name.txt, which is where Guide Watch looks. ROMs that already have a guide are never touched, so re-runs only fetch what is new.
Install
You need a Miyoo Mini Plus running OnionOS 4.2 or later (the plain Mini runs the same OnionOS, but I have only tested on the Plus), plus the Ebook Reader app, which you install from Onion's own Package Manager. Guide Watch shows guides through it. Onion's Auto save setting must be on, which is the default.
- Download
GuideWatch-OnionOS.zipfrom the latest release and unzip it. - Copy three items onto the SD card, merging with what is already there:
App/GuideWatch/,App/GuideDownload/and.tmp_update/startup/guidewatch.sh. - Reboot.
Nothing is patched or overwritten. To uninstall, delete the folders. Two new entries appear in the Apps menu: Guide Watch (a manual stop/start for the background part, not needed normally) and Guide Downloader.
On Windows the .tmp_update folder is hidden by default. Turn on hidden files, or drag App/ first and copy the startup script separately.
Where the guides come from
The walkthroughs are plain-text FAQs from the GameFAQs archive on archive.org. Many were written by fans decades ago and are still the best guides for those games.
I don't host any of them, and neither does the GitHub repository or the index the downloader uses. Each guide is pulled straight from archive.org onto your card. The downloader matches your ROM names against that index, and a handful of awkwardly named games may not match. For those, the browser tool at guides.retromodlab.com writes the same Game Name.txt files to the same places, from a computer.
The hard problems
The Miyoo taught me three things the hard way. I wrote them down for anyone porting this to another handheld.
You cannot draw over a paused RetroArch. My first version paused the game and ran the reader on top. It ran, invisibly, because the frozen game frame stays composited over everything. So Guide Watch does it the long way: it saves and quits the game, shows the guide, then relaunches with the save state. It uses the same quick-switch mechanism Onion's own Game List Options uses for "restart game". That is why opening and closing take a few seconds each.
Onion deletes the launch file. After every program exits, Onion's runtime deletes cmd_to_run.sh, unless /tmp/quick_switch exists. Without that flag, the handoff to the reader lands you on the main menu instead of the guide.
Busybox awk fails silently. The awk on this device returns an empty string on bracket-expression regexes, with no error. I only found out because guides stubbornly refused to match. String work in the scripts now uses shell built-ins.
Known limits
I would rather you know these up front:
- RetroArch games only. Standalone emulators such as DraStic are not supported.
- It is a real save, quit and relaunch. Opening and closing the guide each take a few seconds.
- Big guides open slowly the first time. Guides of 500 KB or more take extra time on first open, because the reader lays out the whole file. Reopening is faster.
- The Down press reaches the game for one frame before the save happens.
- If you reboot with a guide open, the next boot lands on the main menu, not the game.
- Downloads take a while. Expect roughly one guide per second, so a full card on the first run is a wait.
Credits and links
This is built on other people's work. Thanks to OnionUI for the firmware and a source tree clear enough to learn from, and to ealang for pixel-reader, the Ebook Reader that displays the guides. The idea itself is from the Real Time Game Guide feature in cbepx-me's StockOS mod for Anbernic handhelds, so credit where it is due.
Guide Watch is free and open source (MIT) on GitHub. If it saves you a trip to your phone mid-boss-fight, you can buy me a coffee.
Update, October 2026: Guide Watch has since come to other consoles. There is a Switch overlay (read the post), a 3DS plugin (read the post), and a DS version for the DSpico flashcart (read the post).