diff options
author | 2022-03-10 02:55:40 +1100 | |
---|---|---|
committer | 2022-03-10 02:55:40 +1100 | |
commit | 422185fe558463a119cfdee25e2d4b6e5d71dc97 (patch) | |
tree | 10a01acb7c99b76a0cc575dabd4ce76ec9e3249f /docs/source | |
parent | bbb9ec846a44598159258d36f21bae42437ee290 (diff) |
docs: Added page describing how MAME searches for media.
Also made error messages for missing CHDs and missing files for software
parts using the image file loader show search paths, and changed the
(poorly named) bitbanger device to use the image file loader rather than
the ROM loader for software items.
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/commandline/commandline-all.rst | 72 | ||||
-rw-r--r-- | docs/source/usingmame/assetsearch.rst | 402 | ||||
-rw-r--r-- | docs/source/usingmame/index.rst | 1 | ||||
-rw-r--r-- | docs/source/usingmame/usingmame.rst | 11 |
4 files changed, 475 insertions, 11 deletions
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst index c34618b428a..aa91bd6307c 100644 --- a/docs/source/commandline/commandline-all.rst +++ b/docs/source/commandline/commandline-all.rst @@ -1,4 +1,4 @@ -.. _universal-command-line: +.. _mame-commandline-universal: Universal Commandline Options ============================= @@ -19,6 +19,8 @@ Verbs are actions to take upon something with the command (e.g. **mame -validate pacman** has *mame* as a command and *-validate* as a verb) +.. _mame-commandline-patterns: + Patterns -------- @@ -80,6 +82,8 @@ Terminal window, set the working directory to the location of the script (i.e. the folder containing MAME), and then start MAME. +.. _mame-commandline-coreverbs: + Core Verbs ---------- @@ -136,6 +140,9 @@ Core Verbs apple2_flop_orig.xml(137.3): mismatched tag + +.. _mame-commandline-configverbs: + Configuration Verbs ------------------- @@ -175,6 +182,8 @@ Configuration Verbs a sufficient description. +.. _mame-commandline-fronendverbs: + Frontend Verbs -------------- @@ -664,8 +673,8 @@ overwritten. romset apple2_flop_orig:autobahn is good ... -.. _osd-commandline-options: +.. _mame-commandline-osdoptions: OSD-related Options ------------------- @@ -919,6 +928,8 @@ Example: supporting both XInput and DirectInput controllers. +.. _mame-commandline-cliverbs: + OSD CLI Verbs ------------- @@ -961,6 +972,8 @@ OSD CLI Verbs any network adapters. +.. _mame-commandline-osdoutput: + OSD Output Options ------------------ @@ -987,6 +1000,8 @@ OSD Output Options led0 = 0 +.. _mame-commandline-configoptions: + Configuration Options --------------------- @@ -1025,6 +1040,8 @@ Configuration Options mame apple2ee -noreadconfig -sl6 diskii -sl7 cffa2 -hard1 TotalReplay.2mg +.. _mame-commandline-pathoptions: + Core Search Path Options ------------------------ @@ -1235,6 +1252,8 @@ Core Search Path Options mame -swpath c:\mame\software;c:\emu\mydisks +.. _mame-commandline-coreoutdir: + Core Output Directory Options ----------------------------- @@ -1362,6 +1381,8 @@ Core Output Directory Options mame -comment_directory c:\mame\comments +.. _mame-commandline-savestate: + Core State/Playback Options --------------------------- @@ -1706,6 +1727,8 @@ Core State/Playback Options mame neogeo -burnin +.. _mame-commandline-perf: + Core Performance Options ------------------------ @@ -1878,6 +1901,8 @@ Core Performance Options mame bgaregga -lowlatency +.. _mame-commandline-rotation: + Core Rotation Options --------------------- @@ -1978,6 +2003,8 @@ Core Rotation Options mame -flipy suprmrio +.. _mame-commandline-videooptions: + Core Video Options ------------------ @@ -2232,6 +2259,8 @@ Core Video Options mame dkong -nounevenstretch +.. _mame-commandline-fullscreen: + Core Full Screen Options ------------------------ @@ -2257,6 +2286,8 @@ Core Full Screen Options mame kof97 -video d3d -switchres -resolution 1280x1024 +.. _mame-commandline-windowoptions: + Core Per-Window Options ----------------------- @@ -2422,6 +2453,8 @@ Core Per-Window Options mame contra -view native +.. _mame-commandline-artwork: + Core Artwork Options -------------------- @@ -2475,6 +2508,8 @@ Core Artwork Options mame galaga -override_artwork puckman +.. _mame-commandline-screenoptions: + Core Screen Options ------------------- @@ -2569,6 +2604,8 @@ Core Screen Options mame pacman -effect scanlines +.. _mame-commandline-vectoroptions: + Core Vector Options ------------------- @@ -2649,12 +2686,14 @@ Core Vector Options mame asteroid -flicker 0.15 -Core Video OpenGL Debugging Options ------------------------------------ +.. _mame-commandline-opengloptions: + +Core Video OpenGL Feature Options +--------------------------------- These options are for compatibility in **-video opengl**. If you report -rendering artifacts you may be asked to try messing with them by the devs, but -normally they should be left at their defaults which results in the best +rendering artifacts you may be asked to try messing with them by the developers, +but normally they should be left at their defaults which results in the best possible video performance. .. Tip:: Examples are not provided for these options as MAMEdev will provide @@ -2693,6 +2732,8 @@ possible video performance. The default is ON. (**-gl_pbo**) +.. _mame-commandline-openglglsl: + Core Video OpenGL GLSL Options ------------------------------ @@ -2765,6 +2806,8 @@ Core Video OpenGL GLSL Options mame suprmrio -gl_glsl -glsl_shader_screen0 gaussx -glsl_shader_screen1 gaussy -glsl_shader_screen2 CRT-geom-halation +.. _mame-commandline-soundoptions: + Core Sound Options ------------------ @@ -2902,6 +2945,8 @@ Core Sound Options mame galaga -audio_latency 1 +.. _mame-commandline-inputoptions: + Core Input Options ------------------ @@ -3303,6 +3348,8 @@ Core Input Options mame contra -coin_impulse 1 +.. _mame-commandline-inputenable: + Core Input Automatic Enable Options ----------------------------------- @@ -3354,6 +3401,8 @@ Core Input Automatic Enable Options **-[no]joystick**, etc. +.. _mame-commandline-debugging: + Debugging Options ----------------- @@ -3556,6 +3605,8 @@ Debugging Options mame marble -debug -debugger_font "Comic Sans MS" -debugger_font_size 16 +.. _mame-commandline-commoptions: + Core Communication Options -------------------------- @@ -3631,6 +3682,8 @@ Core Communication Options mame arescue -comm_remotehost 192.168.1.3 -comm_remoteport 30100 -comm_framesync +.. _mame-commandline-miscoptions: + Core Misc Options ----------------- @@ -3827,6 +3880,8 @@ Core Misc Options mame galaga88 -nonvram_save +.. _mame-commandline-scripting: + Scripting Options ----------------- @@ -3916,8 +3971,11 @@ Scripting Options mame alcon -noplugin cheat +.. _mame-commandline-webserver: + HTTP Server Options ------------------- + .. _mame-commandline-http: **-[no]http** @@ -3958,6 +4016,8 @@ HTTP Server Options mame apple2 -http -http_port 6502 -http_root c:\users\me\appleweb\root +.. _mame-commandline-portaudio: + PortAudio Options ----------------- 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 fil |