Fullscreen and Cabinet Startup

For a cabinet or living-room PC, use fullscreen presentation with controller navigation. Choose desktop startup first, then a dedicated graphical session after your games and hardware work.

Choose a startup mode

Mode	What starts	Best fit
Desktop fullscreen	Your normal desktop, then a fullscreen app	Initial setup and everyday desktop use
Time-based startup	HyperHQ or HyperSpin after desktop login and a configured delay	Cabinets needing normal desktop services
Full screen startup	A dedicated graphical login session with your chosen app	A cabinet opening directly into HyperHQ or HyperSpin
Steam Gaming Mode	Steam's gaming session, then your Non-Steam shortcut	Optional handheld or TV testing
Headless	A process without a local display	Service hosting and automated tests, rather than a local arcade frontend

Dedicated fullscreen startup is also called kiosk-style startup. A compositor still renders the app, games, and overlays. The normal desktop shell and Steam home do not run in this session. This is different from hiding a desktop panel or opening Steam Big Picture.

Start after desktop login

1. Open HyperHQ, then Settings → Startup → Apps.
2. Choose Time-based for HyperSpin, HyperHQ, or both.
3. Set Launch delay from 0 to 600 seconds. Allow time for controllers, audio, network storage, and external drives.
4. Save, log out, and sign back in. Confirm each selected app starts once.
5. Test one game and return to HyperSpin.

Linux uses XDG desktop autostart. Your desktop must log in before these entries run. Automatic desktop login is a separate OS setting. Steam Gaming Mode does not run these desktop entries.

Prepare a dedicated session

• Install HyperHQ and HyperSpin. Development Electron binaries are unsuitable as boot applications.
• Finish sign-in, plugins, library paths, emulator setup, and controller mappings on the desktop.
• Configure all displays, resolution, scaling, rotation, and sound output.
• Select your main and marquee displays in HyperHQ.
• Confirm external storage mounts before launch.
• Keep a database backup and a keyboard available for setup and recovery.

The installed build checks for KWin with dbus-run-session, or Gamescope, plus Python 3, a graphical polkit authentication agent, and an active supported login manager. Supported managers are SDDM, Plasma Login Manager, and GDM. GDM also needs busctl and AccountsService. Review the availability message in Startup Apps.

Desktop or distribution	Dedicated session difference
Bazzite KDE	KWin provides the multi-display path. Use your configured desktop layout.
SteamOS	Check the installed build's availability result. Dedicated startup changes the login session rather than adding a Steam shortcut.
Ubuntu GNOME	GDM support alone does not provide KWin. Gamescope is a single-display fallback where installed.
Other Linux desktops	Normal XDG startup works independently. Dedicated startup needs the listed compositor and login-manager requirements.

Enable Full screen startup

1. Open Settings → Startup → Apps in HyperHQ.
2. Choose Full screen startup for HyperSpin to open directly into your wheel, or HyperHQ to open into library management.
3. Select one primary fullscreen app. Set the other app to Time-based if required, with a delay.
4. Review the availability result and save.
5. Authenticate through the administrator prompt. Setup registers the dedicated session and changes the login manager's automatic login selection.
6. Save your work, then restart. Setup does not restart the login manager or log you out.
7. Confirm display placement, controls, audio, game launch, pause, exit, and desktop return.

Standard desktop installation does not request administrator access. Dedicated session setup does, since the login configuration belongs to the OS. Setup uses writable system locations without disabling Bazzite or SteamOS read-only protection.

The primary app starts fullscreen for this session. Your normal desktop window preferences stay saved. Selecting a different primary app moves the previous owner to Time-based startup.

Fresh login, reboot, physical displays, and desktop handoff still need device testing with your release. Start with desktop login when evaluating the alpha.

Main display and marquee

KWin exposes connected displays and uses a private copy of your desktop layout. HyperSpin uses your saved main display. HyperMarquee uses your saved marquee display and its normal plugin startup flow.

Gamescope supplies one virtual display. Use KWin for a separate physical marquee. Configure the desktop layout and both app display selections before enabling dedicated startup. Test again after changing cables, docks, scaling, or monitors.

Return to the desktop

Use Exit to Desktop from the primary app. The dedicated compositor closes and the recorded desktop starts in the same authenticated login. App reopening depends on your installed build and startup settings. Review Reopen HyperHQ after Exit to Desktop where offered.

Exit to Desktop leaves fullscreen startup selected for the next login. To restore your previous login setup:

1. Open HyperHQ on the desktop.
2. Open Settings → Startup → Apps.
3. Change Full screen startup to Time-based or Off.
4. Save and authenticate.
5. Restart and check your original login flow.

The Linux uninstaller also restores the previous login configuration. If another tool has changed the managed configuration, restoration reports a conflict and retains the backup. Resolve the reported conflict before deleting recovery files.

Recover a failed session

If startup returns to the login screen, choose your normal desktop session from the session selector and sign in. Open HyperHQ and disable Full screen startup.

If the desktop is unavailable, switch to a text console with Ctrl+Alt+F3 where supported, sign in as the setup user, and run the generated restoration script:

sudo /bin/sh "$HOME/.local/share/hyperhq/fullscreen/restore.sh"

Restoration requires administrator authentication. Read the result before restarting. Keep the backup if restoration reports a conflict.

For support, include your app version, distribution, login manager, compositor, GPU, connected displays, and error text. Startup recovery data lives under ~/.local/share/hyperhq/fullscreen/; display diagnostics use display-startup.json where available. Remove account secrets before sharing logs.