MAME Configuration Precedence: Tracing INI, UI, and Command-Line Values

When a MAME setting appears to ignore an edit, the usual cause is not that the emulator randomly forgot the value. MAME can read multiple configuration files, keep machine-specific UI state separately, and accept command-line overrides. A vertical-game rotation in vertical.ini, a driver-family value in source/cps2.ini, a clone-specific option in ssf2t.ini, and an explicit command-line flag can all be relevant to one launch. The answer is to trace the configuration path for the exact system and option, not to keep editing whichever mame.ini is easiest to find.

This article focuses on MAME’s INI configuration resolution and the boundary with per-machine UI configuration. It is not a guide to RetroArch’s override hierarchy: those are different file formats and scopes.

The precedence model

MAME’s documented configuration loader processes the command line first, then the global mame.ini (or a platform-specific INI such as mess.ini), followed by applicable specialized INI files. Later INI files normally override earlier INI values for the same option. The command line remains higher priority than INI files. This explains an important debugging trap: an option shown in the global INI may be correct and still not be the effective value for a particular system.

The exact stack depends on the machine. The documented sequence after the global INI can include debug.ini when the debugger is enabled; vertical.ini or horizont.ini; a monitor-class file such as vector.ini, raster.ini, or lcd.ini; an INI named for the driver’s source file; a BIOS-set INI; a parent-system INI; and finally the system’s own short-name INI. Files that do not apply are skipped. A clone can therefore inherit a parent configuration and then override it in its own file.

The loader also parses the global INI twice because the first pass can change path settings. The second pass checks the resulting configuration location. When several directories are listed in inipath, MAME searches them in order. If the same filename appears in more than one directory, the earlier directory has precedence; MAME saves INI files to the first directory in the list. This is a search-path precedence within a filename, distinct from the order of configuration scopes.

Reconstruct the stack for one system

Do not assume the name printed by a frontend is MAME’s short system name. Use the exact short name that the launcher passes to MAME. Then ask MAME which source file defines it and inspect the relevant INI paths:

mame -listsource sf2
mame pacman -showconfig

-listsource identifies driver source files, which tells you whether a source/<filename>.ini layer can apply. -showconfig prints configuration settings and is useful for seeing parsed values, but it does not by itself explain which file supplied each value. Pair it with verbose startup output and the known inipath; do not treat a flattened dump as a provenance report.

For an isolated comparison, start once with the normal configuration and once with INI loading disabled:

mame -verbose pacman
mame -noreadconfig -verbose pacman

The second run is a diagnostic baseline, not a recommended permanent launch mode. It suppresses the INI stack, so options normally stored in those files fall back to defaults unless explicitly supplied on the command line. It is not a guarantee that all machine-specific UI state is bypassed. If the symptom disappears only in that run, re-enable files and narrow down the responsible layer rather than leaving the emulator globally unconfigured.

Record the MAME version, executable path, working directory, exact command line, system short name, and inipath. A second installation or wrapper can silently point at a different INI directory or binary. On macOS, for example, the documented default search path includes per-user Application Support and ~/.mame locations before current-directory locations; do not assume a Windows layout or copy a path from another machine.

Use scopes for intent, not as mystery overrides

Each scope should represent a reason the setting differs. A rotation choice belongs in an orientation-specific file if it is truly shared by vertical games. A renderer preference common to a monitor class belongs in that class’s INI. An option shared by systems implemented in one driver source can go in its source/ file. BIOS-wide behavior, parent/clone inheritance, and one-system exceptions have their corresponding layers. Keep the global file for genuinely global defaults.

For example, a local cabinet might keep shared rotation settings in vertical.ini, then leave pacman.ini empty unless Pac-Man requires an actual exception. A clone-specific test should place the exception in the clone’s own short-name file rather than altering a global or parent setting that affects unrelated titles. MAME’s documented example uses this same inheritance idea: a clone can load its parent’s INI and then its own file, with the latter loaded later.

Be careful with the inipath list. Putting a writable working directory first and a managed, read-only preset directory second means the first directory can shadow a preset with the same filename and receives newly saved INIs. That may be intentional for a user profile, but it can also make a portable build appear to ignore the repository’s preset. Make both directories explicit and inspect the first matching copy before deleting or rewriting anything.

Separate INI values from machine UI state

Not every visible setting is only an INI option. MAME also saves configuration associated with a particular machine through the UI. The command-line reference specifically notes that a view selection saved through Video Options for a machine takes precedence over an initial view supplied by an INI file or command-line -view. This is why changing a launch argument may not visibly change the selected view. Treat it as machine-specific state, inspect the UI setting, and make a controlled change to confirm the behavior. Do not assume all saved machine state follows this exact rule; verify per option in the documentation for that setting.

This distinction matters in launcher-managed installations. Editing mame.ini may alter initial defaults, while a UI-saved system configuration can retain a selection from a previous session. If the issue is limited to one game, first test whether the option is stored in that game’s configuration. If the issue affects all games, inspect global and shared INIs first. Back up the affected settings file before clearing it, and never delete the entire configuration tree just to test a single view.

A repeatable fault-isolation procedure

Use a reversible sequence:

Capture the launch command and exact MAME build. Confirm the short system name and executable used by the frontend.
Run -listsource <system> when driver-family scope may matter. Determine whether the system is a clone and whether it selects a BIOS set.
Inspect each inipath directory in search order. Check the global, orientation, monitor type, source, BIOS, parent, and system files that apply. Keep a table of option, source file, observed value, and expected value.
Run -showconfig to inspect parsed configuration and -verbose to observe startup diagnostics. These answer different questions; neither should be mistaken for a complete explanation of machine-specific UI state.
Compare with a temporary -noreadconfig run. If needed, re-enable scopes one at a time by using a temporary INI path that contains only the controlled files. Avoid changing the user’s live files during this experiment.
For a saved view or another setting with UI persistence, test the UI layer independently. Change one value, exit cleanly, relaunch, and observe whether MAME restores the machine-specific state.
Move the final value to the narrowest scope that matches the reason for it. Retest both the target and at least one neighboring system that should remain unaffected.

Do not infer file loading from a filename merely existing on disk. A vertical.ini matters only for a system MAME classifies as vertical; a source-specific file requires the matching source name and search path; and a parent file matters only for a clone relationship. The verbose log, the driver’s source listing, and a small controlled launch provide stronger evidence than a broad directory search.

Acceptance checks for a configuration change

A configuration fix is complete when it survives a cold launch and the same option behaves as expected in three cases: the intended system, a related clone or system sharing the driver, and an unrelated system. Run once from the frontend and once from a terminal with the recorded command so wrapper-added flags are visible. Confirm that changing the command line has the expected effect, and that UI-saved machine settings are not masking the change. If inipath has multiple folders, confirm which copy was loaded and where a UI save was written.

For maintainability, keep a small change log next to a managed configuration bundle: MAME version, option, reason, intended scope, and test systems. Avoid keeping duplicate copies of the same INI filename in several search directories unless shadowing is deliberate. A short, explicit stack is easier to reproduce than a large collection of overrides whose effective values are unknown.

The practical rule is simple: diagnose a MAME setting as a resolution problem. Establish the binary, path list, applicable scopes, saved UI state, and command-line arguments first. Once that chain is explicit, most apparently ignored settings become ordinary precedence bugs with a testable fix.

Related:

Sources: