ScummVM Configuration Profiles: Isolate Targets, Settings, and Save Paths

ScummVM’s configuration file stores both global preferences and game-specific targets. That is convenient for one collection, but it can become fragile when you maintain separate test installs, curated libraries, or a known-good profile beside an experimental one. ScummVM supports an alternate configuration file with --config; using it deliberately can keep target lists and settings separate without editing the normal profile.

An alternate configuration file is not a sandbox, a portable installation, or a save-game migration tool. It only separates the configuration state that ScummVM reads from that file. The game data, executable, plugins, supplementary resources, save files, and operating-system permissions remain separate concerns. Verify each path rather than assuming that one profile switch relocates everything.

Identify the configuration ScummVM actually uses

The default configuration location depends on the platform and package. Current upstream documentation lists %APPDATA%\\ScummVM\\scummvm.ini for Windows, ~/Library/Preferences/ScummVM Preferences for macOS, and ~/.config/scummvm/scummvm.ini by default on Linux, subject to XDG_CONFIG_HOME and package-specific behavior such as Snap. Older macOS installations may retain an earlier location. ScummVM’s Paths settings page shows the configuration path for the running build; use that value instead of copying a path from another machine or release.

The file is plain text. The [scummvm] section contains global settings, [keymapper] holds global key mappings, and each configured target has its own section. A target is the named launcher entry, not the same thing as the engine’s game ID. The configuration can hold two targets for the same title, each with its own description, data path, language, or other supported game settings.

That structure suggests a useful boundary: keep a stable collection in the normal configuration and launch a separate test collection with a different file. Do not edit the active configuration while ScummVM is open; the running application may still hold settings that it later saves. Close it cleanly, make a backup, and record the path shown in the launcher before creating the alternate profile.

`--config` and `--initial-cfg` solve different problems

The command-line option --config=FILE (short form -c) selects an alternate configuration file. It is the option for a distinct profile that should keep its own target list and settings. The file should be at a location the current user can read and update. ScummVM’s configuration documentation warns that using a writable alternate configuration requires deployment and recovery planning; do not point it at a read-only bundle and expect settings to persist.

By contrast, --initial-cfg=FILE (short form -i) supplies a default configuration when ScummVM has no saved configuration in its usual location. It is intended for first-run defaults, such as a preconfigured setup distributed with a game. It does not select an independently maintained, ongoing profile. Removing the normal configuration to make an initial file load would also remove the existing launcher state, so preserve a copy before any reset or reinstall.

Command-line options can also override applicable global or target settings for one launch. That is useful for a temporary diagnostic, such as launching a target windowed, without turning the command line into the profile’s permanent configuration. A reproducible setup should state which values live in the configuration and which are supplied by a launcher shortcut.

Build an isolated profile without overwriting the original

First quit ScummVM. Locate its current configuration using the Paths tab, then copy that file to a new, user-writable profile location. The example below is POSIX shell syntax; replace both paths with locations that exist on your system. It is illustrative and has not been run against a ScummVM installation in this environment.

mkdir -p "$HOME/Games"
profile="$HOME/Games/ScummVM-TestProfile"
if ! mkdir "$profile"; then
  printf 'Could not create a fresh profile directory; refusing to continue: %s\n' "$profile" >&2
  exit 1
fi
cp "/actual/path/to/scummvm.ini" \
   "$profile/scummvm.ini"

printf 'Using isolated profile: %s\n' "$profile"
scummvm --config="$profile/scummvm.ini" --list-targets

mkdir "$profile" deliberately fails if that fixed path already exists, so rerunning the recipe does not overwrite an earlier test profile or its edits. The same error branch stops on any other directory-creation failure instead of continuing with an uncertain path. To create another independent copy, choose a new path and keep that path with the profile manifest.

Because this recipe begins by copying the active configuration, the first target list should match the copied inventory. The command still proves that ScummVM can read the alternate file; after you add a test target there, verify that it appears only when the same --config argument is used. If the initial list differs unexpectedly, stop and verify the executable, argument spelling, and path before adding or changing anything. Some app-store, mobile, and console ports expose different command-line access or storage permissions; the desktop example is not a universal installation recipe.

For a genuinely new collection, start with a separate profile file and use the launcher under that same --config argument to add a few test targets. Verify that the file is created or updated as expected on the current build before relying on it. The documented command-line interface can also add or detect games, but detection output is not the same as a verified installation. Confirm that each entry uses the intended data directory and that the launch works before treating the profile as complete.

Separate game data, extra resources, and saves

Selecting another .ini does not move any files. In the Paths tab, ScummVM exposes global paths and per-game paths for saved games and extra files. The savepath setting identifies the directory for saved games; extrapath points to additional files such as game-specific data, SoundFonts, or MT-32 ROMs. A target can also carry a game-specific savepath, so check both the global and target sections when diagnosing where a save was written.

For two profiles that might launch the same game, give each a distinct test save directory before the first session. The following configuration fragment is a schematic excerpt of a target already added to the configuration through the ScummVM launcher or an add-target workflow. The --detect option reports detection results; it does not add a target entry. Treat gameid as generated metadata, not a field to invent or edit by hand. This is not a drop-in path for every operating system:

[scummvm]
savepath=/path/to/ScummVM-TestProfile/saves

[test_sky]
gameid=sky
path=/path/to/one/verified/sky-data-directory
savepath=/path/to/ScummVM-TestProfile/saves/test_sky

Keep the generated gameid and data path shown for the target; do not infer or edit either value from a display title. The configuration guide’s examples show that global options belong under [scummvm], while a target section can contain its own path and savepath. The same file also permits two target names to point at the same game family, which is useful for separate editions or controlled comparisons, but it does not make their assets interchangeable.

Keep shared read-only resources shared only when you intentionally want the profiles to use the same files. Keep save directories separate while testing upgrades, alternate editions, or new builds. Do not point an experimental profile at the only copy of a save set. For backup, close the application first, copy the relevant save directories, and compare a manifest or hashes before and after a test; save-file compatibility still depends on the engine and game, not merely on the profile name.

Test the boundary and document what is not isolated

Use a small acceptance matrix before trusting the profile:

Run --list-targets with the normal executable and record the baseline list.
Copy the configuration and run --list-targets with --config; verify that it initially matches the copied inventory.
Add one test target in the alternate profile, close ScummVM, and inspect which configuration file changed.
Confirm that the new target appears with --config but not in the normal profile.
Launch the test target, make a disposable in-game save, and verify the effective save directory.
Restart with the same --config and confirm that the target and test save remain visible.

If the target disappears after restart, inspect file permissions, the launcher shortcut, and the exact configuration argument. If the target appears but the game cannot start, inspect its configured data path and detector result; configuration isolation cannot repair an incomplete or mixed data directory. If a save appears in the wrong place, inspect both global and target-specific savepath values before copying files around.

Keep a short profile manifest outside the game data: ScummVM version, executable path, configuration path, target names, data directories, extra-resource locations, save directories, and the test date. Avoid storing account secrets or unrelated home-directory details in a shared manifest. Paths in a configuration are machine-specific unless deliberately made relative and validated on the destination; an alternate configuration file alone does not make an installation portable.

Finally, keep the normal profile as the recovery point. Test upgrades against a copy of both configuration and saves, preserve the original unchanged, and restore the previous executable and data set together if the trial fails. ScummVM’s profile mechanism is most useful when it makes state boundaries visible; it should not give an untested collection a misleading “portable” label.

Related:

Sources: