Launch
These commands launch games, systems, and other media.
launch
Launches media from a path or identifier.
The launch command is implied when no command prefix is used (Auto Launch mode). For example, simply writing Genesis/Sonic the Hedgehog.md will launch that game.
Syntax
**launch:<path>
Arguments
path (required)
The media to launch. Accepts multiple formats - see Path Formats below.
Advanced Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
launcher | string | - | Explicit launcher override. Wins over stored per-media overrides and system defaults. |
system | string | - | Select the system for a file path and apply its launcher defaults |
action | string | run | run to launch, details to show info (launcher support varies) |
set_name | string | - | Platform-specific launcher/core name override |
set_name_same_dir | string | - | Platform-specific flag for keeping the original game directory |
name | string | - | Custom display name for remote downloads |
pre_notice | string | - | Message to show before launching |
slot | string | primary | Media slot to play in: primary or background (audio) |
when | expression | - | Conditional execution (see Expressions) |
Examples
Launch a game using system lookup (Auto Launch mode - no **launch: prefix needed):
Genesis/Sonic the Hedgehog (USA).md
Launch from an absolute path:
**launch:/media/fat/games/Genesis/Sonic.md
Launch with a specific launcher override:
**launch:Genesis/Sonic.md?launcher=LLAPIMegaDrive
Set a launcher override for the next game scanned from a reader:
**launch?launcher=LLAPIMegaDrive
Use this on a setup token when you want the next scanned game token to use a specific launcher. The override applies once, then clears.
If a media row has a stored launcher override from media.meta.update, Core uses it automatically for title, search, path, random, and history launches. A ?launcher= argument on the token is still an explicit one-off override and takes priority.
Open a Steam game's details page instead of launching:
**launch:steam://1145360?action=details
Use a MiSTer set name for a one-off launch:
**launch:NES/Mega Man 2.nes?set_name=RA_NES&set_name_same_dir=1
Play an audio file as background music so it keeps playing while you launch games:
**launch:/media/fat/music/album/track01.flac?slot=background
Audio files (.wav, .mp3, .ogg, .flac) launch through Core's built-in audio playback. The slot argument is only used by audio playback; other launchers ignore it.
set_name and set_name_same_dir are currently used by MiSTer launchers. Unsupported platforms may ignore them. On MiSTer, set_name maps to the MGL <setname> tag. Add set_name_same_dir=1 when you want a separate core config name while still loading games from the original core folder. Without set_name_same_dir=1, MiSTer also changes the core's games folder.
Path Formats
The launch command supports several path formats, tried in this order:
- Remote URLs (http://, https://, smb://) - if
systemargument provided - Absolute paths (starting with
/) - URI schemes (steam://, etc.)
- Relative paths - searched in game folders
- Title ID -
System/Titlewithout file extension - System lookup -
System/path/to/file.ext - Search queries - if path contains
*
Title ID
The portable format for tokens that work across devices. Paths in System/Title format (no file extension) are detected as title lookups and use fuzzy matching:
Genesis/Sonic the Hedgehog
SNES/Super Mario World
N64/Legend of Zelda Ocarina of Time
The @ prefix can also be used, which explicitly invokes launch.title:
@Genesis/Sonic the Hedgehog
Both forms use fuzzy matching to find games regardless of filename differences between devices.
With tags to filter specific versions:
@SNES/Super Mario World (region:us)
@Genesis/Sonic (-unfinished:demo)
@N64/Zelda (~region:us) (~region:eu)
Tag operators:
(tag:value)or(+tag:value)- must have this tag (AND)(-tag:value)- must not have this tag (NOT)(~tag:value)- at least one of these must match (OR)
See the Tags documentation for available filters.
System Lookup
Uses the system ID as a virtual folder:
N64/1 US - A-M/Game.z64
TurboGrafx16/Game.pce
PCEngine/Game.pce
Works across different devices with the same internal folder structure. System aliases are supported.
Absolute Path
Direct path starting with /:
/media/fat/games/Genesis/Game.md
Relative Path
Path relative to game folders:
Genesis/1 US - Q-Z/Game.md
_Arcade/Game.mra
Similar to system lookup but uses the exact system games folder name.
Select a system for a file path
Add ?system=<id> when a local file's path and extension do not identify one system. This is useful for top-level relative files and formats such as .bin that several systems share:
SomeGame.bin?system=Genesis
Core uses any launcher default configured for the system. Otherwise, it uses the system and file extension to select a launcher. An explicit ?launcher= still takes priority.
Search queries
Paths containing * are automatically handled as media database search queries:
Genesis/*sonic*
SNES/*mario world*
This delegates to launch.search internally, launching the first indexed match.
Zip File Paths
On MiSTer, paths can reference files inside zip archives:
_Arcade/@Arcade - Konami.zip/Pong.mra
Genesis/@Genesis - 2022-05-18.zip/Sonic.md
URI Schemes
URIs are passed directly to the appropriate platform launcher:
steam://1145360
Remote Install
Download and install media from SMB or HTTP URLs:
smb://10.0.0.123/Games/path/to/file.bin?system=Genesis
http://10.0.0.123/path/to/file.bin?system=Genesis
The system argument is required for remote URLs. Files are cached locally after first download. Authentication can be configured in auth.toml.
launch.title
Launches media by title ID.
Syntax
**launch.title:<system>/<title>
Arguments
system (required)
The system ID (e.g., Genesis, SNES, N64).
title (required)
The game title to search for. Supports fuzzy matching.
Inline tags can be added after the title:
**launch.title:SNES/Super Mario World (region:us)
**launch.title:Genesis/Sonic (-unfinished:demo)
Advanced Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
launcher | string | - | Explicit launcher override. Wins over stored per-media overrides and system defaults. |
tags | string | - | Tag filters (alternative to inline format) |
action | string | run | run to launch, details to show info |
set_name | string | - | Platform-specific launcher/core name override |
set_name_same_dir | string | - | Platform-specific flag for keeping the original game directory |
when | expression | - | Conditional execution (see Expressions) |
Examples
Launch Sonic using title matching:
**launch.title:Genesis/Sonic the Hedgehog
Launch the US version of Super Mario World:
**launch.title:SNES/Super Mario World (region:us)
Use the tags argument instead of inline format:
**launch.title:Genesis/Sonic?tags=region:us,lang:en
The @ prefix (e.g., @Genesis/Sonic) is shorthand for **launch.title:Genesis/Sonic. Both forms are equivalent.
launch.system
Launches a system/emulator without loading specific media.
Syntax
**launch.system:<system>
Arguments
system (required)
The system ID to launch. Use menu to return to the main menu.
Advanced Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
when | expression | - | Conditional execution (see Expressions) |
Examples
Launch the Atari 2600 system:
**launch.system:Atari2600
Launch WonderSwan Color, useful for meta-systems without their own core:
**launch.system:WonderSwanColor
Return to the main menu:
**launch.system:menu
launch.random
Launches a random game from specified systems or search criteria.
Syntax
**launch.random:<query>
Arguments
query (required)
One of the following formats:
| Format | Description |
|---|---|
<system> | Random game from one system |
<system1>,<system2>,... | Random from multiple systems |
all | Random from any system |
/path/to/folder | Random file from a folder |
<system>/*pattern* | Random indexed media matching a search query |
When the selected system has fallbacks, Core tries the requested system first and only moves to the next fallback tier when no matching media exists.
Advanced Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
launcher | string | - | Explicit launcher override. Wins over stored per-media overrides and system defaults. |
tags | string | - | Tag filters to narrow results |
action | string | run | run to launch, details to show info |
set_name | string | - | Platform-specific launcher/core name override |
set_name_same_dir | string | - | Platform-specific flag for keeping the original game directory |
when | expression | - | Conditional execution (see Expressions) |
Examples
Launch a random SNES game:
**launch.random:snes
Launch a random game from SNES, NES, or Genesis:
**launch.random:snes,nes,genesis
Launch a random game from any system:
**launch.random:all
Launch a random file from a folder, useful for MGL collections:
**launch.random:/media/fat/_#Favorites
Launch a random Genesis game matching "sonic" in the media database:
**launch.random:Genesis/*sonic*
Launch a random Mario game from any system:
**launch.random:all/*mario*
When multiple systems are specified, a system is picked at random first (with equal weight per system), then a random game is selected from that system. This prevents systems with larger libraries from dominating random picks.
launch.search
Searches indexed media and launches the first result.
Syntax
**launch.search:<query>
**launch.search:<system>/<query>
Arguments
query (required)
A media database search query. * can be used for broad partial matches.
system (optional)
The system ID to search within. If omitted, searches all systems. When the selected system has fallbacks, Core searches the requested system first and only moves to the next fallback tier when no matching media exists.
Advanced Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
launcher | string | - | Explicit launcher override. Wins over stored per-media overrides and system defaults. |
tags | string | - | Tag filters to narrow results |
action | string | run | run to launch, details to show info |
set_name | string | - | Platform-specific launcher/core name override |
set_name_same_dir | string | - | Platform-specific flag for keeping the original game directory |
when | expression | - | Conditional execution (see Expressions) |
Examples
Find and launch the first indexed game matching "mario" from any system:
**launch.search:*mario*
Find and launch the first indexed SNES game matching "mario":
**launch.search:SNES/*mario*
Find a more specific match, such as a US version of a Super Mario game:
**launch.search:SNES/super mario*(*usa*
Search queries are case insensitive and use the indexed media database, not direct filesystem globbing.
launch.last
Launches a recently played game from playtime history.
Syntax
**launch.last
**launch.last:<offset>
Arguments
offset (optional)
Which recent game to launch, where 1 is the most recently played.
Defaults to 1. Duplicate plays of the same game are collapsed, so
2 is the previous different game, 3 the one before that, and so on.
Advanced Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
launcher | string | - | Explicit launcher override. Wins over stored per-media overrides and system defaults. |
action | string | run | run to launch, details to show info |
set_name | string | - | Platform-specific launcher/core name override |
set_name_same_dir | string | - | Platform-specific flag for keeping the original game directory |
when | expression | - | Conditional execution (see Expressions) |
Examples
Relaunch the most recently played game:
**launch.last
Launch the previously played game, skipping the most recent one:
**launch.last:2
Cycle back to the third most recently played unique game:
**launch.last:3
Requires playtime tracking to have recorded history. If not enough unique games are in history to satisfy the offset, the command logs a warning and does nothing.
