Games, Controls, and Displays on Linux

Emulators and game stores

The platform catalog must offer downloads for your operating system and architecture. Use Manual setup when no matching automatic install is available. A Windows catalog entry does not establish Linux compatibility.

Platform	Linux setup
MAME	HyperHQ's Linux provider selects the reviewed Flathub package on Flatpak-capable systems or detects supported native installations. Windows executables and MAME machine-list XML archives are not Linux emulators.
RetroArch	Install the Linux executable and matching Linux cores. Replace Windows core DLL paths. Check core, BIOS, save, and shader directories.
Standalone emulators	Select a Linux build for your architecture. Check executable permission and launch the emulator directly before linking ROMs.
Native Steam	Confirm Steam starts and the game runs from its own library before importing into HyperHQ.
Flatpak Steam	Keep the Flatpak launcher and sandbox paths. Do not replace the launcher with a Windows steam.exe path.
Proton or Wine	Configure the intended runtime, prefix, and game launcher. Test game startup, process tracking, pause, and exit separately.
Other stores and Windows tools	Check the plugin's platform declaration. Use a tested Linux integration or manual launch flow. Store support on Windows does not establish Linux support.

For pinball and arcade packages, check the entire chain: emulator, table scripts, helper apps, backglass, feedback, and cabinet hardware. A working base emulator does not establish compatibility for its Windows add-ons.

LEDBlinky and eXoDOS Windows batch wrappers are Windows-specific integrations. Do not use their Windows instructions for native Linux setup.

Controllers and keyboard

1. Connect USB controls or pair Bluetooth controls in your Linux desktop settings.
2. Confirm Linux recognizes the device.
3. Open Settings, Controllers in HyperHQ and map navigation and game actions.
4. Test navigation in HyperSpin, then test the same controls inside a game.
5. Disconnect and reconnect the device. Confirm player assignment and mappings.

Windows driver tools such as DS4Windows do not apply to native Linux setup. Device access depends on Linux drivers, session permissions, and any sandbox around the emulator. Use device-specific udev rules supplied by the hardware project when required.

Steam Input and emulator mappings require separate checks. Resolve duplicate input before saving your cabinet configuration. Test lightguns, spinners, trackballs, rumble, and multiple identical controllers individually.

X11, Wayland, and Gaming Mode

Feature	Linux difference
Global keyboard shortcuts	Wayland depends on desktop portal support and the packaged Electron version. Check shortcut registration and desktop permission prompts.
Window focus	KDE KWin provides a native Wayland provider path. Other compositors impose different focus rules.
X11 window tools	wmctrl and xdotool apply to X11/XWayland paths. They do not establish control over native Wayland windows.
AutoHotkey automation	The Essentials ahk_x11 runtime requires X11. Windows scripts need compatibility review. Native Wayland automation is not covered by AHK_X11.
Gaming Mode	Outside the current Desktop Mode alpha scope. Test gamescope, Steam Input, overlay placement, exit, and suspend/resume separately.

Electron documents the Wayland global shortcut portal. Validate behavior against the Electron version shipped with your release.

HyperOverlay and game lifecycle

Enable Loading Screen and Pause Menu in Settings, HyperOverlay. Launch a game from HyperSpin.

Verify loading progress, pause, resume, restart, game exit, and return to HyperSpin. Open a manual and test save or disc actions where supported by the emulator.

Linux process suspension and audio controls use different providers from Windows. Confirm the game resumes and audio returns after closing the pause menu, exiting HyperOverlay, or recovering from a crash. Steam, Proton helpers, and unrelated apps must stay running.

The shared Linux providers include per-process audio operations. The Utils pause guardian documents Linux suspend/resume support and rejects per-process mute without exact restoration support. Do not assume every pause route has the same audio capability.

If the overlay opens behind a game, test windowed or borderless mode, record your compositor, and check the supported focus path. Do not treat an X11 result as native Wayland acceptance.

HyperMarquee and displays

Dedicated full screen startup needs KWin for separate main and marquee displays. Its Gamescope fallback exposes one display. Configure and test desktop placement first.

1. Open your Linux desktop's display settings.
2. Extend the desktop across the main and marquee displays.
3. Set display positions, resolution, rotation, and scaling.
4. Select separate HyperSpin and HyperMarquee displays in HyperHQ.
5. Test artwork, video, game launch, and return from the game.
6. Reconnect the marquee and reselect the display if its identity changed.

Linux panels belong to the desktop environment. The Windows taskbar setting does not control them. Configure panel placement or auto-hide through your desktop.

Test mixed scaling, portrait displays, refresh rates, and reconnect behavior with your actual cabinet screens.

Media and HyperTheme

Use the same theme workflow in your Linux browser. Verify uploads, drag and drop, fonts, PSD import, keyboard shortcuts, audio, preview, export, and publishing. Browser shortcuts or desktop shortcuts sometimes take priority over editor bindings; remap conflicts through the relevant settings.

Test the published theme in packaged HyperSpin. Browser preview alone does not establish frontend playback. Check transparency, fonts, shaders, video, sound, aspect ratio, and frame pacing.

Linux thumbnail extraction uses ffmpeg from PATH. Install your distribution's FFmpeg package if thumbnail generation reports a missing executable. Missing thumbnails and failed video playback require separate diagnosis.

Cabinet lighting

LEDBlinky setup applies to Windows. For HyperLED or another Linux-capable plugin, check release availability and support for your exact device. Test USB access, network endpoints, profile changes, reconnect, and shutdown behavior. Record hardware model and firmware in a support report.

Troubleshooting checklist

Symptom	First check
App does not start	CPU architecture, executable permission, mount options, and terminal error
AppImage reports FUSE failure	Use the archive or extract-and-run option
ROM or BIOS is missing	Exact filename case, mount location, and Flatpak folder access
Game runs directly but fails from HyperHQ	Saved executable, runtime arguments, working directory, and plugin platform
Pause shortcut fails	Mapping, conflicting binding, portal availability, desktop permissions, and session type
Game stays suspended or muted	Logs from HyperHQ, HyperOverlay, and the active helper; report the affected process and versions
Marquee opens on the wrong screen	Desktop layout, scaling, and saved display selection
Sign-in does not return to the app	Browser callback handling, desktop URL registration, connectivity, and system clock

Include distribution/version, architecture, kernel, desktop/version, X11 or Wayland, GPU/driver, package format, app/plugin versions, and reproduction steps. Include Gaming Mode status where relevant. Remove tokens and account secrets from logs before sharing.