Skip to main content

Getting Started with HyperOverlay

HyperOverlay is a companion app for HyperSpin that displays a transparent game information overlay when you launch a game. It shows the game name, system, and other details as an elegant overlay that fades out automatically so you can get to playing.

What HyperOverlay Does​

When HyperSpin launches a game, HyperOverlay:

  • Displays a transparent overlay with game information
  • Follows HyperSpin's display position automatically (even if HyperSpin moves to a different monitor)
  • Fades out after a configurable timeout so it doesn't block gameplay
  • Shows a loading/extraction screen while content is being prepared
  • Works alongside your emulator without interfering with it

Platform Support​

HyperOverlay runs on Windows, Linux, and macOS.

PlatformStatus
Windows✅ Fully supported
Linux✅ Supported (X11 and Wayland)
macOS✅ Supported

Linux Notes​

On Linux, HyperOverlay supports both X11 and Wayland display servers:

  • X11: Full support via xdotool for keystrokes and window focus
  • Wayland: Supported via ydotool, wtype, or wlrctl — install at least one of these for full functionality

For transparent windows on Wayland, a compositor with transparency support is required (most modern ones like KWin, Mutter, and wlroots-based compositors work fine).

For display capture on Wayland, PipeWire with xdg-desktop-portal is required.

Linux Dependencies

Install SDL2 for input handling:

# Ubuntu/Debian
sudo apt install libsdl2-2.0-0

# Fedora
sudo dnf install SDL2

# Arch
sudo pacman -S sdl2

macOS Notes​

On macOS, HyperOverlay uses native system APIs (osascript) for keystrokes and window focus. Transparent windows work natively. Note that per-app audio capture has limitations on macOS due to OS restrictions.

Installation​

HyperOverlay is managed by HyperHQ and does not need to be installed separately. HyperHQ handles launching and communicating with HyperOverlay automatically.

If you need to install or update HyperOverlay manually, download it from HyperSpin-fe.com and place it in your HyperSpin directory.

Configuration​

HyperOverlay settings are configured from within HyperHQ:

  1. Open HyperHQ
  2. Go to Settings > HyperOverlay
  3. Configure fade timeout and other options
  4. Settings can be set globally, per system, or per game

See Settings for the full configuration reference.

The Debug Status Window​

HyperOverlay includes a built-in Debug Status Window for real-time monitoring during setup and troubleshooting.

What it shows:

  • Current connection status to HyperSpin
  • Events being received (game launch, display updates, etc.)
  • Display position and bounds
  • Active overlay state

How to open it: The debug window can be toggled from HyperOverlay's system tray icon. It's intended for setup and troubleshooting—you don't need it during normal use.

For Cabinet Builders

Use the debug window when positioning HyperOverlay on a new setup. You can see in real time that HyperOverlay is receiving display updates from HyperSpin and rendering on the correct screen.

Display Tracking​

HyperOverlay automatically follows HyperSpin's display position at runtime. If HyperSpin moves to a different monitor (or you change your display configuration), HyperOverlay updates its position to match without requiring a restart.

This is handled by the Display:update event—HyperSpin sends its current display bounds to HyperOverlay whenever its position changes.

Extraction Screen​

When HyperSpin is preparing to launch a game (extracting archives, loading content), HyperOverlay can show an extraction screen—a progress indicator that lets users know something is happening rather than seeing a blank screen.

The extraction screen appears automatically when HyperSpin signals that content is being prepared, and dismisses itself when the game is ready to launch.

Fallback Images​

If a game or system doesn't have artwork configured for the overlay, HyperOverlay displays a fallback image instead of showing a blank overlay. This ensures the overlay always looks polished even with incomplete media collections.

Keyboard Shortcuts​

HyperOverlay supports multi-key combinations for triggering overlay actions. Key combinations are configured in HyperHQ and passed through to HyperOverlay at runtime.

Troubleshooting​

Overlay doesn't appear?

  • Make sure HyperHQ has HyperOverlay enabled (Settings > HyperOverlay)
  • Check that HyperSpin and HyperHQ are both running
  • On Linux/macOS, verify the required platform dependencies are installed
  • Check HyperHQ logs for connection errors

Overlay appears on the wrong screen?

  • HyperOverlay follows HyperSpin's display automatically
  • Make sure HyperSpin is configured to run on the correct monitor
  • Use the Debug Status Window to verify display bounds are being received correctly

Transparent window not working on Linux?

  • Ensure your compositor supports transparency
  • On Wayland, try adding --enable-transparent-visuals (handled automatically by HyperOverlay)
  • Some minimal window managers may not support transparency

Wayland capture not working?

  • Install PipeWire and xdg-desktop-portal
  • Grant screen capture permissions when prompted
  • Falls back gracefully with an error message if capture is unavailable

Got more questions? Visit the HyperSpin community or check the Troubleshooting guide.