summaryrefslogtreecommitdiffstats
path: root/docs/source/usingmame/assetsearch.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/usingmame/assetsearch.rst')
-rw-r--r--docs/source/usingmame/assetsearch.rst402
1 files changed, 402 insertions, 0 deletions
diff --git a/docs/source/usingmame/assetsearch.rst b/docs/source/usingmame/assetsearch.rst
new file mode 100644
index 00000000000..a8002db1c69
--- /dev/null
+++ b/docs/source/usingmame/assetsearch.rst
@@ -0,0 +1,402 @@
+.. _assetsearch:
+
+How does MAME look for files?
+=============================
+
+.. contents:: :local:
+
+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 :ref:`mame-commandline-pathoptions`.
+
+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 :ref:`rompath <mame-commandline-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, whcih 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.)
+* Any folders and archives that would be searched for system or device ROMs for
+ the system or device that the software list belongs to. This is for
+ historical reasons due to the way software list support was originally added
+ to MESS and will be removed in a future version of MAME.
+
+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**.
+* The short name of the PAL Mega Drive system is ``megadriv``, so MAME will look
+ for a folder called **megadriv**, a PKZIP archive called **megadriv.zip**, or
+ a 7-Zip archive called **megadriv.7z**.
+* The parent system of the PAL Mega Drive is the North American Genesis system,
+ which has the short name ``genesis``, so MAME will look for a folder called
+ **genesis**, a PKZIP archive called **genesis.zip**, or a 7-Zip archive called
+ **genesis.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.
+
+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:
+
+.. code-block:: bash
+
+ 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:
+
+.. code-block:: bash
+
+ 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:
+
+.. code-block:: bash
+
+ 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.