Skip to main content

Emulator Auto-Download

When you add a system in HyperHQ, the wizard automatically filters the emulator list to show only emulators it can download for you. If a download link is available, HyperHQ can install the emulator in the background — no manual downloading required.

How It Works​

When you select a system in the Add System wizard, HyperHQ:

  1. Fetches the list of supported emulators for that system from the HyperHQ API
  2. Checks each emulator for a available download URL (matched to your OS)
  3. Filters out any emulators that don't have a download available
  4. Shows only downloadable emulators as selectable options in the wizard
  5. Falls back to manual mode if no downloadable emulators are found

This means the wizard never shows you an emulator you can't actually get — every option in the list can be installed automatically.

RetroArch is always included

RetroArch is exempt from the download availability filter and always appears in the emulator list. It's the universal fallback for systems where no other downloadable emulator is available.

Download Availability Check​

The availability check queries the HyperHQ API with your OS (Windows, macOS, or Linux). Results are cached locally for 15 days so the check is fast on subsequent visits.

The cache lives at:

[HyperHQ install folder]/data/emulator-download-availability.json

If you need fresh data (for example, after a new emulator version adds download support), you can clear this cache from Settings → Advanced or simply wait for it to expire.

During System Setup​

When a Downloadable Emulator is Available​

  1. The wizard shows matching emulators as selectable cards
  2. RetroArch always appears first if it supports your selected system
  3. The recommended emulator is pre-selected (marked with a badge)
  4. Select your preferred emulator and continue

HyperHQ queues the emulator download to happen after your system is saved. You don't wait for the download to complete before finishing setup — the download runs in the background.

When No Downloadable Emulator is Available​

If no emulators with download links are found for a system:

  • The wizard switches to Manual Emulator mode automatically
  • You'll see a prompt to locate the emulator executable yourself
  • Browse to the .exe (or equivalent) of your already-installed emulator
  • Setup continues normally — the only difference is you provide the path manually

This is common for emulators with complex licensing (like BIOS-dependent systems) or emulators that don't offer direct downloads.

After Setup: Download Progress​

Once you save the system, emulator download happens via a background event (DownloadEmulator). Progress appears as a notification or status indicator in HyperHQ. You can continue using HyperHQ while the download completes.

The download process typically:

  1. Downloads the emulator archive (.zip or installer)
  2. Extracts it to the HyperHQ emulators folder
  3. Registers the emulator path in your local database
  4. Links the emulator to the new system

Custom Category: No Auto-Download​

Systems added under the Custom category skip the auto-download flow entirely. Custom systems use Manual Emulator mode by default — you supply the emulator path yourself.

Manual Emulator Setup (Fallback)​

If you need to set up an emulator manually at any point:

  1. In the Add System wizard, select Manual Emulator from the emulator options
  2. Browse to the emulator executable using the file picker
  3. HyperHQ stores the path and associates it with your system

You can also add, update, or replace emulators after setup via Settings → Emulators.

Troubleshooting​

My emulator isn't showing up in the wizard​

  • The emulator may not have a download link available for your OS. This is common for emulators distributed as installers without direct .zip download links.
  • Try the Manual Emulator option and point to your existing installation.

The wizard shows "No Matching Emulator"​

  • No downloadable emulators were found for the selected system.
  • The wizard switches to Manual mode automatically — browse to your emulator and continue.
  • If you believe an emulator should be available, check your internet connection and try again (the availability cache may be stale).

Emulator download stalled or failed​

  • Check the notification area in HyperHQ for error details.
  • You can retry by going to Settings → Emulators, finding the emulator, and triggering a re-download.
  • As a fallback, download the emulator manually from its official website and point HyperHQ to it.

Availability cache is showing outdated results​

  • The cache expires after 15 days automatically.
  • To force a refresh immediately: delete emulator-download-availability.json from the HyperHQ data folder and reopen the Add System wizard.