Launchers
A launcher tells Zaparoo Core how to open a game, video, app, or other media file. Each platform has its own launchers for matching a system and file to the right program.
Loading games
Core first adds installed games and media files to its media database. It then uses the matching platform launcher when you scan a token or select a search result. If a game is missing from search, update the media database. If the game appears but does not open, check its platform launcher guide for required software and setup.
Platform launcher guides
Use your platform guide for exact setup, supported systems, and launcher limitations. Built-in integrations include:
| Platform | Launcher integrations |
|---|---|
| MiSTer FPGA | MiSTer cores, AO486, ScummVM, video, and scripts |
| Windows | Steam, LaunchBox/Big Box, RetroBat, Flashpoint, Kodi, executables, and scripts |
| Linux | Steam, Lutris, Heroic, RetroArch, standalone emulators, EmuDeck, RetroDECK, Bottles, Faugus, Moonlight, Kodi, browser URLs, and scripts |
| SteamOS | Steam, native emulators, RetroArch, EmuDeck, RetroDECK, Bottles, Faugus, Moonlight, Kodi, and scripts |
| Bazzite | Steam, Lutris, Heroic, standalone emulators, EmuDeck, RetroDECK, Bottles, Faugus, Moonlight, Kodi, browser URLs, and scripts |
| ChimeraOS | Steam, ChimeraGOG, standalone emulators, EmuDeck, RetroDECK, Bottles, Faugus, Moonlight, Kodi, and scripts |
| Batocera | EmulationStation, Kodi, and scripts |
For an emulator or media app without a built-in integration, write a custom launcher.
Launchables
Some things can be launched but don't map cleanly to a file on disk or a normal system, like a ROM-less FPGA core. Launchables are how Core handles these. Core defines them in code and exposes them as virtual versions of the things you already use: a virtual system or a virtual media entry, whichever fits.
You don't deal with launchables as a separate concept. They show up in the Zaparoo App as ordinary systems or media that you can browse, pick, and write to a token like anything else. The only difference is that there is no real file or system behind them.
MiSTer's ROM-less Other cores, like Chess or Flappy Bird, are the first example. They have no game file and no system of their own, so Core exposes each one as a virtual system and indexes the ones you have installed.
The one place this shows through is the token value. A launchable is identified by a compact zaparoo:// URI instead of a file path, so a token that launches one holds a value like zaparoo://gezdgnbvgy3tqojqgezdgnbvgy rather than a normal path. You don't write this by hand; the App fills it in when you save a launchable.
A custom launcher can expose a command as a virtual system on any Core platform; see command launchables. For MiSTer cores that launch without media, use the mister_core backend.
Launcher controls
Launcher controls send actions to the launcher handling the currently active media. Use them for actions like pause, stop, save state, load state, fast forward, rewind, or next and previous track.
Control support depends on the active launcher. If no media is active, or the launcher does not support the requested action, the command returns an error.
Each launcher supports its own set of actions. Check the active media response to see which controls are available.
How control actions work
Zaparoo Core asks the active launcher to run a named control action. Official launchers can implement controls directly. Custom launchers can define controls as ZapScript snippets in their launcher configuration.
When Core can tell that media is still starting, the control command waits before sending the action.
Built-in action names include:
| Action | Typical use |
|---|---|
toggle_pause | Pause or unpause active media |
pause | Pause active media |
resume | Resume active media |
save_state | Save emulator state |
load_state | Load emulator state |
save_ram | Save RAM data |
toggle_menu | Open or close an in-game menu |
reset | Reset active media |
stop | Stop active media |
fast_forward | Fast forward |
rewind | Rewind |
next | Move to the next item, such as the next track or disc |
previous | Move to the previous item |
toggle_tray | Open or close the emulated disc tray |
Not every launcher supports every action. Use the media or media.active API response to check the launcherControls available for the current media.
Current support
Built-in launcher support currently includes:
| Launcher | Supported actions |
|---|---|
Kodi launchers: KodiLocalVideo, KodiMovie, KodiTVEpisode, KodiLocalAudio, KodiAlbum, KodiArtist, KodiTVShow, KodiSong | toggle_pause, stop, fast_forward, rewind, next, previous |
| Built-in RetroArch launchers on Linux and SteamOS, including EmuDeck | save_state, load_state, toggle_menu, toggle_pause, reset, fast_forward, rewind, stop, plus toggle_tray, next, and previous for swapping discs in a loaded multi-disc game |
Native audio launcher (Audio system, see Audio Playback) | toggle_pause, pause, resume, stop, fast_forward, rewind |
| Custom launchers | Whatever is defined in the launcher's controls table |
EmuDeck standalone emulator launchers and RetroDECK launchers do not currently define built-in launcher controls.
To control background audio instead of the active game, add ?slot=background to the control action.
ZapScript control
Use the control command to send a control action from a token:
**control:toggle_pause
Save state for the active media, if the launcher supports it:
**control:save_state
See the ZapScript utility command reference for exact syntax and examples.
API control
Apps and integrations can use the media.control API method to send launcher control actions. The active media response includes launcherControls when controls are available.
Launcher availability
Core checks whether each launcher's runtime dependencies are present. Unavailable launchers are excluded from automatic selection, but remain in the launchers API response with available: false and an availabilityReason explaining what is missing. On Linux desktop platforms, standalone emulator launchers are only registered for emulators Core finds installed, so a missing emulator is not listed at all.
After installing a missing dependency, restart Core or use Settings > Advanced > Reload Core in the terminal UI. You can also run -reload. Reloading asks supported platforms to rediscover launcher data such as MiSTer RBF files and Batocera's EmulationStation system configuration.
Default launchers
Core resolves launcher choices in this order:
- Explicit ZapScript
?launcher=argument - Saved per-media launcher override
- Explicit
[[systems.default]]launcher - First available
launchers.preferenceentry - Normal platform launcher detection
Use a system default when every game in one system should use the same launcher. Core applies it to title/search launches and direct path launches when it can infer the system from the path. System defaults remain authoritative even when their selected launcher is unavailable, so Core reports the missing dependency instead of choosing another launcher.
API clients can save a per-media launcher override through media.meta.update. Use this when one game should always use a different launcher from the rest of its system. A one-shot **launch?launcher= override from a setup token lasts five minutes and is rejected immediately when the launcher ID does not exist, so a typo shows up on the setup token rather than on the next game.
Per-media overrides are stored alongside favorites in Core's user database, separate from the rebuildable media database, so they are kept even if Core has to rebuild the media database after corruption. This user data is included in Core's device backups.
Use launchers.preference when you want an ordered fallback across launcher groups or IDs. Unavailable preference entries are skipped. SteamOS, Linux, Bazzite, and ChimeraOS support the Native, EmuDeck, and RetroDECK groups, for example:
[launchers]
preference = ["Native", "EmuDeck", "RetroDECK"]
MiSTer groups its alternate cores the same way: RetroAchievements, DB9, LLAPI, DualRAM, Sinden, PWM, and Unstable. See MiSTer launcher groups.
Use [[launchers.default]] to set launcher-specific defaults such as action, load_path, render_scale, or render_resolution.
Problems with a custom launcher not loading or a command not running are covered under custom launcher troubleshooting.