Skip to content

Command line arguments

Jump to bottom
Claudio Filipe edited this page Oct 8, 2026 · 1 revision

Command-line arguments

Odyssey Launcher starts fine with no arguments. These are for shortcuts, scripts and troubleshooting: starting full screen, launching one game straight away, trying a theme, or keeping a test setup apart from your real one.

Examples use PowerShell, from the folder OdysseyLauncher.exe is in. In a Windows shortcut, put the arguments after the path in Target.

Two kinds of argument

The launcher is built on the Godot engine, so its command line has two parts:

  • Engine arguments (window and renderer) go first, with no separator: --fullscreen, --resolution 1280x800.
  • Launcher arguments (--launch, --user-dir, --theme, ...) go after a separator, -- or ++, and use --name=value, with no space around the =.
.\OdysseyLauncher.exe --fullscreen -- --theme=console "--launch=megadrive/Sonic the Hedgehog (USA, Europe).md"

Use ++ in PowerShell. Windows PowerShell can swallow a bare --; ++ means the same and always gets through. Quote a value that contains spaces or brackets, as above (quote the whole "--launch=...").

Window

These are Godot's own. When you give one, it decides the window for that run, and Settings, Graphics, Screen mode isn't applied at start-up. (Changing it in the settings afterwards still works.) With none of them, the screen mode and window size from the settings apply.

Argument What it does
--fullscreen, -f Starts full screen.
--windowed, -w Starts in a window.
--maximized, -m Starts in a maximised window.
--resolution <width>x<height> The window's size, e.g. --resolution 1280x800.
--position <x>,<y> The window's position on the desktop, e.g. --position 100,50.
--screen <n> Starts on that monitor. The first is 0.

Renderer

The launcher draws with Direct3D 12 by default. Settings, Graphics can switch it to Vulkan, and the choice is kept. To try the other one for a single run without changing it, use the engine's arguments:

Argument What it does
--rendering-driver <name> d3d12 or vulkan.
--rendering-method <name> Give mobile along with a driver. It is the launcher's renderer, and without it the engine picks a heavier one. 
.\OdysseyLauncher.exe --rendering-driver vulkan --rendering-method mobile

When the command line names the driver, the launcher leaves the saved choice alone.

Launcher arguments

Put these after -- or ++. An absolute path is needed wherever a path is.

Argument What it does
--launch=<system>/<path> Starts a game as soon as the launcher is ready.
--quit-after-launch With --launch: quits when the game ends.
--theme=<id> Uses that theme for this run only.
--user-dir=<folder> Keeps all settings, databases and media in that folder.
--save-responses Saves what each scraper downloads, for troubleshooting.

--launch=<system>/<path>

Starts one game without browsing to it, for a desktop shortcut or a front end that calls the launcher.

  • <system> is the system's id, its ROM folder name (see ROM folder names): megadrive, psx, ps2.
  • <path> is the game's file, relative to the system's ROM folder, subfolders included. Use / or \.
.\OdysseyLauncher.exe ++ "--launch=megadrive/Sonic the Hedgehog (USA, Europe).md"
.\OdysseyLauncher.exe ++ "--launch=psx/Final Fantasy VII/Final Fantasy VII (Disc 1).cue"

If the game isn't in the library yet, the launcher scans that system first and then starts it. The game starts as it would from the games grid, with the same emulator and options and the same "Running <title>" screen. When it ends, the launcher is back in front and carries on as normal.

If the system or file can't be found, or the emulator can't start, the launcher stays open and shows a message at the top of the window; the reason is in the log.

--quit-after-launch

Needs --launch. When the game ends the launcher exits, instead of returning to the systems grid. Use it to make the launcher invisible between games. The exit code is 0 if the game ran and 1 if the launch failed, so a script can check $LASTEXITCODE.

.\OdysseyLauncher.exe --fullscreen ++ "--launch=snes/Super Metroid (USA).sfc" --quit-after-launch

--theme=<id>

Uses a theme for this run instead of the one in the settings, without changing the setting. The id is the name of the theme's folder: a built-in theme (slab, console), or one in the themes folder of your user folder. An id that isn't installed is logged as a warning, and the launcher uses the default theme.

--theme=memory-card runs the base theme on its own. The settings can't choose it, because every other theme builds on it.

--user-dir=<folder>

Keeps config, data and cache in one folder you name, as portable mode does, instead of your AppData folders. Your real library and settings aren't touched. It is for trying a different set of settings, for a test library, or for two separate setups on one PC. A new, empty folder starts from the built-in defaults, and holds its own settings.toml, systems.toml, databases and themes folder from then on.

.\OdysseyLauncher.exe ++ --user-dir=D:\OdysseyKids

The folder must be a full path, such as D:\OdysseyKids, and not .\kids.

--save-responses

For one run, saves what each scraping provider sent back (with your passwords and keys removed) in the scraped\responses folder of the data folder. Turn it on when a scrape gives the wrong game or no art, and send the files with your report. Leave it off the rest of the time, because they add up.

Portable mode

Not an argument: an empty file named portable.txt beside OdysseyLauncher.exe keeps settings, databases, media and caches in a userdata folder next to it, so the whole launcher can live on a USB drive. --user-dir does the same job for one run, for any folder.

If an argument is wrong

A mistake in one of the launcher's arguments (a missing value, a relative path, a malformed id, the same argument twice) stops it from starting: it prints Debug arguments: ... with the reason to the log and exits with code 2. If the window never appears, check the spelling and the quotes first.

  • Unknown arguments are skipped without an error, so a typo in an argument's name isn't reported.
  • --quit-after-launch and --save-responses take no value; the others need one after =.
  • A well-formed --theme id that no theme has isn't an error: the launcher logs a warning and uses the default theme.
  • The log is %APPDATA%\Godot\app_userdata\Odyssey Launcher\logs\godot.log, rewritten each time the launcher starts.
Select-String -Path "$env:APPDATA\Godot\app_userdata\Odyssey Launcher\logs\godot.log" -Pattern '^Launch|Debug arguments|warning|error'

Clone this wiki locally