How does MAME look for files?¶

Introduction ¶

Unlike typical desktop applications where you browse your disk and select a file to open or a location to save to, MAME has settings to tell it where to look for the files it needs. You can change these settings by starting MAME without specifying a system, selecting Configure Options from the system selection menu, and then selecting Configure Directories (remember to select Save Configuration if you want to keep your changes). You can also change settings by editing your mame.ini and ui.ini files directly, or specify settings on the command line. For information on available options for controlling where MAME searches for files, see Core Search Path Options.

Terminology ¶

It’s necessary to understand some MAME-specific terminology used in the explanations here:

System

A system is a complete machine that can be emulated by MAME. Some systems run fixed software, while others can load software from software list items and/or media files.

Device

An emulated component that can be used by multiple systems, or by other devices. Some devices require ROM dumps, and some devices allow software from additional software lists to be used with a system.

Parent system

MAME uses so-called parent/clone relationships to group related systems. One system in the group is chosen to be the parent and the others are called clones. (The choice of the parent system is somewhat arbitrary. It is not necessarily the original or definitive variant.)

BIOS system

A system configured with no software. This is mostly applicable for arcade systems that used interchangeable game cartridges or ROM boards. Note that this is not the same as the BIOS selection settings that allow you to select system boot ROMs or device firmware.

Software item

A software package described in a software list. Software items may consist of multiple parts that can be mounted independently. Due to the large variety of media supported by MAME, software parts may use different loaders. These include the ROM loader, typically used for cartridge media, and the image file loader, used for software parts consisting of a single media image (including floppy disk and cassette media).

Parent software item

Related software items are grouped using parent/clone relationships, in a similar way to related systems. This is usually used to group different versions or releases of the same piece of software. If a software item has a parent item, it will always be in the same software list.

Short name

MAME uses short names to uniquely identify systems and devices, to uniquely identify software lists, to uniquely identify software items within a software list, and to uniquely identify software parts within a software item.

You can see the short name for a system by highlighting it in the system selection menu, ensuring the info panel is visible on the right, and showing the General Info in the Infos tab. For example the short name for the Nintendo Virtual Boy is vboy. System and device short names can also be seen in the output of various command line verbs, including -listxml, -listfull, -listroms and -listcrc.

You can see the short names for a software item and the software list it belongs to by highlighting it in the software selection menu, ensuring the info panel is visible on the right, and showing the Software List Info in the Infos tab. For example the short name for Macintosh System Software 6.0.3 is sys603 and the short name of the software list it belongs to is mac_flop. Software list short names match their file names (for example the Sega Mega Drive/Genesis cartridge software list is called megadriv.xml and its short name is megadriv). You can also see the short names software lists, software items and parts by finding the name attributes in the XML software list files.

Search path options ¶

Most options for specifying locations to search allow multiple directories to be specified, separated by semicolon (;) characters. Environment variables are expanded, using CMD shell syntax on Windows, or Bourne shell syntax on UNIX-like systems.

Relative paths are interpreted relative to the current working directory at the time of use. If you start MAME by double-clicking it in Windows Explorer, the working directory is set to the folder containing the MAME executable. If you start MAME by double-clicking it in the macOS Finder or from most Linux desktop environments, the working directory will be set to your home directory.

Archive files ¶

MAME can load files from PKZIP and 7-Zip archives (these must have .zip and .7z file name extensions, respectively). A number of extensions to the PKZIP format are supported, including Zip64 for large archives, NTFS timestamps, and LZMA compression. Only ASCII or UTF-8 filenames are supported in PKZIP archives (7-Zip archives always use UTF-16 filenames).

MAME does not load files from nested archives. MAME will not load files stored in a PKZIP or 7-Zip archive which is itself contained within a PKZIP or 7-Zip archive. Multi-segment archives and encrypted archives are not supported. The legacy “implode” compression method in PKZIP archives is not supported.

MAME may perform poorly with archives containing large numbers of files. Files compressed using the LZMA compression algorithm are inherently more CPU-intensive to decompress than files compressed using simpler algorithms. MAME does not take the archive layout into consideration when loading files from archives, so using “solid compression” often results in MAME decompressing the same data repeatedly when loading media.

How does MAME search for media?¶

Use the rompath option sets the folders where searches for ROM dumps, disk images, and other media. By default MAME looks for media in a folder called roms in the working directory. For the purpose of this discussion, floppy disk, cassette, paper tape and other media images that are not stored in CHD format are treated as ROM dumps.

When searching for system, device and software ROM dumps, MAME treats folders and archives inside the folders configured in you rompath setting as equivalent, but remember the limitation that MAME cannot load files from an archive contained within another archive. MAME looks for a folder first, then a PKZIP archive, and finally a 7-Zip archive. When searching for a ROM dump in an archive, MAME first looks for a file with the expected name and CRC. If no matching file is found, MAME looks for a file with the expected CRC ignoring the name. If no matching file is found, MAME finally looks for a file with the expected name, ignoring the CRC.

While MAME can load disk images in CHD format from inside archives, this is not recommended. CHD files contain compressed data stored in a format allowing random access. If a CHD format disk image is stored in a PKZIP or 7-Zip archive, MAME needs to load the entire file into memory in order to use it. For hard disk or LaserDisc images in particular, this will likely use an excessive amount of swap file space, hurting performance and possibly reducing the life expectancy of your disks or SSDs. It’s best to keep CHD format disk images in folders.

System ROMs ¶

For each folder configured in your rompath setting, MAME looks for system ROMs in the following locations:

A folder or archive matching the short name of the system itself.
A folder or archive matching the short name of the system’s parent system, if applicable.
A folder or archive matching the short name of the corresponding BIOS system, if applicable.

Using Shiritsu Justice Gakuen as an example, MAME will search for system ROMs as follows:

The short name of the system is jgakuen, so MAME will look for a folder called jgakuen, a PKZIP archive called jgakuen.zip, or a 7-Zip archive called jgakuen.7z.
The parent system is the European version of Rival Schools, which has the short name rvschool, so MAME will look for a folder called rvschool, a PKZIP archive called rvschool.zip, or a 7-Zip archive called rvschool.7z.
The corresponding BIOS system is the Capcom ZN2 board, which has the short name coh3002c, so MAME will look for a folder called coh3002c, a PKZIP archive called coh3002c.zip, or a 7-Zip archive called coh3002c.7z.

Device ROMs ¶

For each folder configured in your rompath setting, MAME looks for device ROMs in the following locations:

A folder or archive matching the short name of the device.
A folder or archive matching the short name of the device’s parent ROM device, if applicable.
A folder or archive matching the short name of the system.
A folder or archive matching the short name of the system’s parent system, if applicable.
A folder or archive matching the short name of the corresponding BIOS system, if applicable.

Using a Unitron 1024 Macintosh clone with a French Macintosh Plus keyboard with integrated numeric keypad attached as an example, MAME will look for the keyboard microcontroller ROM as follows:

The short name of the French Macintosh Plus keyboard is mackbd_m0110a_f, so MAME will look for a folder called mackbd_m0110a_f, a PKZIP archive called mackbd_m0110a_f.zip, or a 7-Zip archive called mackbd_m0110a_f.7z.
The parent ROM device is the U.S. Macintosh Plus keyboard with integrated numeric keypad, which has the short name mackbd_m0110a, so MAME will look for a folder called mackbd_m0110a, a PKZIP archive called mackbd_m0110a.zip, or a 7-Zip archive called mackbd_m0110a.7z.
The short name of the Unitron 1024 system is utrn1024, so MAME will look for a folder called utrn1024, a PKZIP archive called utrn1024.zip, or a 7-Zip archive called utrn1024.7z.
The parent system of the Unitron 1024 is the Macintosh Plus, which has the short name macplus, so MAME will look for a folder called macplus, a PKZIP archive called macplus.zip, or a 7-Zip archive called macplus.7z.
There is no corresponding BIOS system, so MAME will not search in any further locations.

Software Item ROMs ¶

For each folder configured in your rompath setting, MAME looks for software item ROMs in the following locations:

A folder or archive matching the short name of the software item inside a folder matching the short name of the software list (or a folder matching the short name of the software item inside an archive matching the name of the software list).
A folder or archive matching the short name of the parent software item inside a folder matching the short name of the software list, if applicable (or a folder matching the short name of the parent software item in an archive matching the name of the software list).
A folder or archive matching the short name of the software item. (This is for convenience for software items that also run as stand-alone systems with the same short name, such as Neo Geo games.)
A folder or archive matching the short name of the parent software item, if applicable. (This is for convenience for software items that also run as stand-alone systems with the same short name, such as Neo Geo games.)

If you load the German version of Dune II from the Mega Drive/Genesis cartridge software list in the PAL Mega Drive console, MAME will look for the cartridge ROM as follows:

The short name of the software item for the German version of Dune II is dune2g and the short name of the Mega Drive/Genesis cartridge software list is megadriv, so MAME will look for a folder called dune2g, a PKZIP archive called dune2g.zip or a 7-Zip archive called dune2g.7z inside a folder called megadriv (or a folder called dune2g inside a PKZIP archive called megadriv.zip or a 7-Zip archive called megadriv.7z).
The parent software item is the general European PAL version of Dune II in the same software list, which has the short name dune2, so MAME will look for a folder called dune2, a PKZIP archive called dune2.zip or a 7-Zip archive called dune2.7z inside a folder called megadriv (or a folder called dune2 inside a PKZIP archive called megadriv.zip or a 7-Zip archive called megadriv.7z).
Next MAME will ignore the short name of the software list and use the short name of the software item only, looking for a folder called dune2g, a PKZIP archive called dune2g.zip or a 7-Zip archive called dune2g.7z.
Still ignoring the short name of the software list, MAME will use the short name of the parent software item only, looking for a folder called dune2, a PKZIP archive called dune2.zip or a 7-Zip archive called dune2.7z.

CHD format disk images ¶

MAME searches for system, device and software item CHD format disk images in almost the same way it searches for ROMs, with just a few differences:

For systems and software items, MAME will check the parent system or software item if applicable for alternate names for a disk image with the same content digest. This allows you to keep a single copy of a CHD format disk image for a parent system or software item and any clones that expect a disk image with the same content, irrespective of the name the clones expect.
For software items, MAME will look for CHD format disk images in a folder matching the short name of the software list. This is for convenience when all items in a software list only contain a single CHD format disk image each.
We recommend that you do not store CHD format disk images inside PKZIP or 7-Zip archives. However, if you do decide to do this, MAME will only find CHD format disk images inside archives with an expected name. This is because MAME uses the content digest from the CHD header, not the checksum of the CHD file itself. The checksum of the CHD file itself can vary depending on compression options.

To save space, MAME allows delta CHD files to be used for clone systems, devices with parent ROM devices and clone software items. The delta CHD file must use a CHD format disk image from the parent system, parent ROM device or parent software item as its parent CHD file. The space saved depends on how much content can be reused from the parent CHD file. MAME searches the same locations for parent CHD files that it would search for the disk image itself.

Loose software ¶

Many systems support loading media from a file by supplying the path on the command line for one of the media options. Relative paths are interpreted relative to the current working directory.

You can specify a path to a file inside a PKZIP or 7-Zip archive similarly to specifying a path to a file in a folder (keep in mind that you can have at most a single archive file in a path, as MAME does not support loading files from archives contained within other archives). If you specify a path to a PKZIP or 7-Zip archive, MAME will use the first file found in the archive (this depends on the order that files are stored in the archive – it’s most useful for archives containing a single file).

Start the Nintendo Entertainment System/Famicom system with the file amazon_diet_EN.nes mounted in the cartridge slot:

mame nes -cart amazon_diet_EN.nes

Start the Osborne-1 system with the first file in the archive os1xutls.zip mounted in the first floppy disk drive:

mame osborne1 -flop1 os1xutils.zip

Start the Macintosh Plus system with the file system tools.img in the archive sys603.zip mounted in the first floppy disk drive:

mame macplus -flop1 "sys603.zip/system tools.img"

Diagnosing missing media ¶

When starting a system from MAME’s system selection menu or software selection menu, MAME will list any missing system or device ROM dumps or disk images, as long as at least one ROM dump or disk image for the system is present. For clone systems, at least one ROM dump or disk image unique to the clone must be present for MAME to list missing ROM dumps and disk images.

If all system and device ROM dump and disk images are present and the system is being started with a software item, MAME will check that ROM dumps and disk images for the software item are present. If at least one ROM dump or disk image for the software item is present, MAME will list any missing ROM dumps or disk images.

For example if you try to start the Macintosh Plus system and the keyboard microcontroller ROM dump is missing, MAME displays the following error message:

Required ROM/disk images for the selected system are missing or incorrect. Please acquire the correct files or select a different system.

341-0332-a.bin (mackbd_m0110a) - not found

Press any key to continue.

The name of the missing ROM dump is shown (341-0332-a.bin), as well as the short name of the device it belongs to (mackbd_m0110a). When a missing ROM dump or disk image is not specific to the selected system, the short name of the system or device it belongs to is shown.

If you start a system in MAME from a command prompt, MAME will show where it searched for any ROM dumps or disk images that were not found.

Using the example of a Unitron 1024 Macintosh clone with a French keyboard connected, MAME will show the following error messages if no ROMs are present:

mame utrn1024 -kbd frp
342-0341-a.u6d NOT FOUND (tried in utrn1024 macplus)
342-0342-a.u8d NOT FOUND (tried in utrn1024 macplus)
341-0332-a.bin NOT FOUND (tried in mackbd_m0110a_f mackbd_m0110a utrn1024 macplus)

MAME used the system short name utrn1024 and the parent system short name macplus when searching for system ROMs. When searching for the keyboard microcontroller ROM, MAME used the device short name mackbd_m0110a_f, the parent ROM device short name mackbd_m0110a, the system short name utrn1024, and the parent system short name macplus.

Software parts that use the ROM loader (typically cartridge media) show similar messages when ROM dumps are not found. Using the example of the German version of Dune II on a PAL Mega Drive, MAME will show the following error messages if no ROMs are present:

mame megadriv dune2g
mpr-16838-f.u1 NOT FOUND (tried in megadriv\dune2g megadriv\dune2 dune2g dune2 megadriv genesis)
Fatal error: Required files are missing, the machine cannot be run.

MAME searched for the cartridge ROM using:

The software list short name megadriv and the software item short name dune2g.
The software list short name megadriv and the parent software item short name dune2.
The software item short name dune2g only.
The parent software item short name dune2 only.
The locations that would be searched for the PAL Mega Drive system (the system short name megadriv and the parent system short name genesis).

Software parts that use the image file loader (including floppy disk and cassette media) only check for media after ROM images are loaded, and missing media files are shown differently. Using the example of Macintosh System 6.0.3, MAME will show these error messages if the software is missing:

mame macplus -flop1 sys603:flop1
:fdc:0:35dd: error opening image file system tools.img: No such file or directory (generic:2) (tried in mac_flop\sys603 sys603 macplus)
Fatal error: Device Apple/Sony 3.5 DD (400/800K GCR) load (-floppydisk1 sys603:flop1) failed: No such file or directory

The error messages show where MAME searched for the image file in the same format. In this case, it used the software list short name mac_flop and the software short name sys603, the software short name sys603 only, and the locations that would be searched for system ROMs.