Cabinet Mode: how it works under the hood

Cabinet Mode is the feature that makes Velocity different from "just an emulator launcher." The idea is straightforward: a Mac mini hidden inside a cabinet should behave like an arcade machine, not a personal computer. Getting there required solving a few non-obvious problems.

Taking over the display

macOS doesn't expose a "kiosk mode" API — there's no single call that hides everything and gives you a full-screen canvas. We achieve it through a combination of NSApplication's activation policy, a custom NSWindow with NSWindowStyleMask set to .borderless, and setLevel(.screenSaver + 1) to float above the Dock. The menu bar is suppressed with NSMenu.setMenuBarVisible(false). On wake from sleep, a distributed notification triggers a re-assertion of all three.

Boot-to-game with a Login Item

When you enable Cabinet Mode, Velocity registers itself as a Login Item via SMAppService.mainApp. On next login, macOS launches Velocity before Finder. Velocity checks for a pinned game in its preferences and launches it immediately. The user never sees the desktop.

A complication: macOS 14+ asks the user to confirm Login Items via System Settings. Velocity walks you through this confirmation the first time you enable Cabinet Mode — we can't suppress the prompt, but we can make the path obvious.

Controller input routing

Velocity uses the GameController framework (GCController) for all controller input. In Cabinet Mode, we additionally call IOHIDManager to consume HID events at the kernel level before they reach the system. This means pressing a button on a connected gamepad doesn't accidentally trigger a macOS shortcut — the input is captured entirely by the emulator.

The exit mechanism

Because Cabinet Mode suppresses all normal OS access points, we needed a reliable escape hatch. The exit shortcut is Cmd+Shift+Q, held for 2 seconds. The hold duration is intentional — it prevents accidental exits during gameplay. On exit, Velocity restores the menu bar, releases the display override, and returns to normal app behavior without a restart.

Display output and HDMI

Cabinet Mode works with any display connected to the Mac mini's HDMI or Thunderbolt port. For typical arcade monitor resolutions (1024×768, 1280×1024), we apply a custom display scaling profile via CoreGraphics. This is particularly relevant for CRT-connected builds — see the arcade cabinet build guide for details on HDMI-to-VGA adapters and resolution targeting.

What's next

The next Cabinet Mode update adds per-game startup sounds (the attract-mode loop), configurable attract-mode screensaver cycling between game title screens, and a hardware watchdog that auto-restarts the last game if Velocity crashes. That last one is the most asked-for feature from early cabinet builders — it's coming in v1.2.