summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/usingmame
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/usingmame')
-rw-r--r--docs/source/usingmame/aboutromsets.rst24
-rw-r--r--docs/source/usingmame/assetsearch.rst398
-rw-r--r--docs/source/usingmame/commonissues.rst2
-rw-r--r--docs/source/usingmame/defaultkeys.rst78
-rw-r--r--docs/source/usingmame/index.rst1
-rw-r--r--docs/source/usingmame/mamemenus.rst286
-rw-r--r--docs/source/usingmame/ui.rst162
-rw-r--r--docs/source/usingmame/usingmame.rst17
8 files changed, 852 insertions, 116 deletions
diff --git a/docs/source/usingmame/aboutromsets.rst b/docs/source/usingmame/aboutromsets.rst
index 51c72d0ce41..3a5197a3159 100644
--- a/docs/source/usingmame/aboutromsets.rst
+++ b/docs/source/usingmame/aboutromsets.rst
@@ -68,6 +68,24 @@ If you hit problems with a set not working, there are several things to check--
ROMs and CHDs
-------------
-ROM chip data tends to be relatively small and gets loaded to system memory outright. Some games also used additional storage mediums such as hard drives, CD-ROMs, DVDs, and Laserdiscs. Those storage mediums are, for multiple technical reasons, not well-suited to being stored the same way as ROM data and won't fit completely in memory in some cases.
-
-Thus, a new format was created for these in the CHD file. **Compressed Hunks of Data**, or CHD for short, are designed very specifically around the needs of mass storage media. Some arcade games, consoles, and PCs will require a CHD to run. As CHDs are already compressed, they should **NOT** be stored in a ZIP or 7Z file as you would for ROM images.
+ROM chip data tends to be relatively small and are loaded into system memory in
+their entirety. Some games also used additional storage media such as hard
+disks, CD-ROMs, DVDs, and LaserDiscs. Those storage media are, for multiple
+technical reasons, not well-suited to being stored the same way as ROM data and
+won’t fully fit in memory in some cases.
+
+Thus, a new format was created for these in the CHD file. **Compressed Hunks of
+Data** files, or CHD files for short, are designed very specifically around the
+needs of mass storage media. Some arcade games, consoles, and PCs will require
+one or more CHD files to run. As CHD files are already compressed, they
+**should not** be stored PKZIP or 7-Zip archives as ROM images would be.
+
+To save space when multiple variants of a system or software item are present,
+MAME supports *delta CHD* files. A delta CHD file only stores the parts of the
+data that differ from its *parent CHD* file. This allows large space savings
+when different variants share a lot of data. Delta CHD files can only be used
+for clone systems, devices with a parent ROM device, and clone software items.
+A delta CHD file must use a (non-delta) CHD file from the parent system, parent
+ROM device or parent software item as its parent CHD file. The parent CHD file
+must be present to use a delta CHD file, or MAME will not be able to read the
+shared data from it.
diff --git a/docs/source/usingmame/assetsearch.rst b/docs/source/usingmame/assetsearch.rst
new file mode 100644
index 00000000000..325d4bcfd7e
--- /dev/null
+++ b/docs/source/usingmame/assetsearch.rst
@@ -0,0 +1,398 @@
+.. _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, 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:
+
+.. 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.
diff --git a/docs/source/usingmame/commonissues.rst b/docs/source/usingmame/commonissues.rst
index bd7a29f31af..50f81671934 100644
--- a/docs/source/usingmame/commonissues.rst
+++ b/docs/source/usingmame/commonissues.rst
@@ -309,7 +309,7 @@ You can try changing the
:ref:`lightgunprovider <mame-commandline-lightgunprovider>` setting (depending
on which kind of device you’re having issues with) from ``rawinput`` to one of
the other options such as ``dinput`` or ``win32``. See
-:ref:`osd-commandline-options` for details on input provider options
+:ref:`mame-commandline-osdoptions` for details on input provider options
.. _ExternalOPL:
diff --git a/docs/source/usingmame/defaultkeys.rst b/docs/source/usingmame/defaultkeys.rst
index d66c6556a4a..9892c86cb1f 100644
--- a/docs/source/usingmame/defaultkeys.rst
+++ b/docs/source/usingmame/defaultkeys.rst
@@ -35,8 +35,8 @@ and saving/loading save states.
If you are running with -debug, this key sends a ‘break’ in emulation.
- When the on-screen display is visible, you can use the following
- keys to control it:
+ When a slider control is visible, you can use the following keys to control
+ it:
* **Up** - select previous parameter to modify.
* **Down** - select next parameter to modify.
@@ -63,7 +63,8 @@ and saving/loading save states.
Highlight first or last UI menu option.
**[** **]**
Move to previous or next group in UI menus that support it (e.g. move to the
- inputs for the previous or next device in the Input (this Machine) menu).
+ inputs for the previous or next device in the **Input Assignments (this
+ System)** menu).
**Enter**/**Joystick 1 Button 1**
Select currently highlighted UI menu option.
**Space**
@@ -71,13 +72,6 @@ and saving/loading save states.
**Delete**
Clear/reset to default when highlighting an entry on the input
configuration, cheat options, and plugin options pages.
-**P**
- Pauses the emulated machine.
-**Left Shift+P**
- While paused, advances to next frame. If rewind is enabled, a new rewind
- save state is also captured.
-**Left Shift+~**
- While paused, loads the most recent rewind save state.
**F1**
Power the machine on for machines that have specific power button behavior.
**F2**
@@ -115,8 +109,10 @@ and saving/loading save states.
* **Home**/**End** - move to top/bottom of list.
* **Left**/**Right** - change color displayed.
* **R** - rotate tiles 90 degrees clockwise.
- * **-**/**+** - increase/decrease the number of tiles per row.
- * **0** - restore the default number of tiles per row.
+ * **-**/**+** - increase/decrease the number of tiles per row (hold Shift to
+ restrict to integer scale factors).
+ * **0** - restore the default number of tiles per row (hold Shift to
+ restrict to integer scale factors).
* **Enter** - switch to tilemap viewer.
Tilemap mode:
@@ -131,18 +127,20 @@ and saving/loading save states.
* **Enter** - switch to palette/colortable mode.
Note: Not all systems have decoded graphics and/or tilemaps.
-**Left Ctrl+F5**
- Toggle Filter.
- (*SDL MAME only*)
-**Left Alt+Left Ctrl+F5**
- Toggle HLSL Post-Processing.
- (*Windows non-SDL MAME only*)
+**Left Shift+F4**
+ While paused, loads the most recent rewind save state.
+**F5**
+ Pauses the emulated machine.
+**Left Shift+F5**
+ While paused, advances to next frame. If rewind is enabled, a new rewind
+ save state is also captured.
**F6**
- Toggle cheat mode. (if started with “-cheat”)
-**Left Ctrl+F6**
- Decrease Prescaling.
-**Left Ctrl+F7**
- Increase Prescaling.
+ Create a save state. Requires an additional keypress to identify the state,
+ similar to the load option above. If an existing save state is present, it
+ will also appear in the selection menu to allow overwriting of that save
+ state.
+**Left Shift+F6**
+ Create a quick save state.
**F7**
Load a save state. You will be prompted to press a key or select from the
menu to determine which save state you wish to load.
@@ -152,16 +150,27 @@ and saving/loading save states.
receive a warning that the save state may not be valid when attempting to
save or load.*
**Left Shift+F7**
- Create a save state. Requires an additional keypress to identify the state,
- similar to the load option above. If an existing save state is present, it
- will also appear in the selection menu to allow overwriting of that save
- state.
+ Load a quick save state.
**F8**
Decrease frame skipping on the fly.
+**Left Shift+F8**
+ Toggle cheat mode. (if started with “-cheat”)
+**Left Alt+F8**
+ Decrease Prescaling.
+ (*SDL MAME only*)
**F9**
Increase frame skipping on the fly.
+**Left Alt+F9**
+ Increase Prescaling.
+ (*SDL MAME only*)
**F10**
Toggle speed throttling.
+**Left Alt+F10**
+ Toggle HLSL Post-Processing.
+ (*Windows non-SDL MAME only*)
+**Left Alt+F10**
+ Toggle Filter.
+ (*SDL MAME only*)
**F11**
Toggles speed display.
**Left Shift+F11**
@@ -176,14 +185,9 @@ and saving/loading save states.
Begin recording AVI video.
**Left Alt+F12**
Take HLSL Rendered Snapshot.
-**Insert**
+**Insert** (Windows non-SDL MAME)/**Page Down** (SDL MAME)
Fast forward. While held, runs game with throttling disabled and with the
maximum frameskip.
- (*Windows non-SDL MAME only*)
-**Page Down**
- Fast forward. While held, runs game with throttling disabled and with the
- maximum frameskip.
- (*SDL MAME only*)
**Left Alt+Enter**
Toggles between full-screen and windowed mode.
**Scroll Lock**/**Forward Delete** (Mac Desktop)/**fn-Delete** (Mac Laptop)
@@ -704,8 +708,8 @@ All the keys below are fully configurable in the user interface. This list shows
the standard keyboard configuration.
Note that controls can vary widely by computer type, so not all keys are shown
-here. See the “Input (this Machine)” section of MAME’s configuration menu for
-details for the machine you are currently using.
+here. See the **Input Assignments (this system)** section of MAME’s Input
+Settings menu for details for the machine you are currently using.
**Tab**
@@ -740,5 +744,5 @@ All the keys are fully configurable in the user interface.
Note that controls can vary widely by machine type, so default keys are not
shown here and defaults will vary considerably based on the manufacturer and
-style. See the “Input (this Machine)” section of MAME’s configuration menu for
-details for the machine you are currently using.
+style. See the **Input Assignments (this system)** section of MAME’s Input
+Settings menu for details for the machine you are currently using.
diff --git a/docs/source/usingmame/index.rst b/docs/source/usingmame/index.rst
index e1a2ae8f5b1..615d3f34c4b 100644
--- a/docs/source/usingmame/index.rst
+++ b/docs/source/usingmame/index.rst
@@ -13,6 +13,7 @@ documentation for your platform of choice.
ui
defaultkeys
mamemenus
+ assetsearch
frontends
aboutromsets
commonissues
diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index ca40b5668ed..ebade1e5188 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -1,9 +1,287 @@
+.. _menus:
+
MAME Menus
==========
-If you started MAME without any command line parameters, you'll be shown the
-system selection menu immediately. While the keys listed above will let you
-navigate the menus, you can also use a mouse.
+.. contents:: :local:
+
+
+.. _menus-intro:
+
+Introduction
+------------
+
+To show the :ref:`main menu <menus-main>` while running an emulated system in
+MAME, press the **Show/Hide Menu** key or button (**Tab** by default). If the
+emulated system has keyboard inputs, you may need to press the
+**Toggle UI Controls** key or button (**Scroll Lock**, or **Forward Delete** on
+macOS, by default) to enable user interface controls first. You can dismiss a
+menu by pressing the **UI Back** key or button (**Escape** by default).
+Dismissing a menu will return to its parent menu, or to the running system in
+the case of the main menu.
+
+You can hide a menu and return to the running system by pressing the
+**Show/Hide Menu** key or button. Pressing the **Show/Hide Menu** key or button
+again will jump back to the same menu. This is useful when testing changes to
+settings.
+
+Emulated system inputs are ignored while menus are displayed. You can still
+pause or resume the running system while most menus are displayed by pressing
+the **Pause** key or button (**F5** on the keyboard by default).
+
+If you start MAME without specifying a system on the command line, the system
+selection menu will be shown (assuming the
+:ref:`ui option <mame-commandline-ui>` is set to **cabinet**). The system
+selection menu is also shown if you select **Select New System** from the main
+menu during emulation.
+
+For more information on navigating menus, :ref:`see the relevant section
+<ui-menus>`.
+
+
+.. _menus-main:
+
+Main menu
+---------
+
+The main menu is shown when you press the **Show/Hide Menu** key or button while
+running an emulated system or while the system information screen is displayed.
+It provides access to menus used to change settings, control various features,
+and show information about the running system and MAME itself.
+
+If you press the **Show/Hide Menu** key or button to show the main menu while
+the system information screen is displayed, the emulated system will not start
+until the main menu is dismissed (either by selecting **Start System**, pressing
+the **UI Back** key or button, or pressing the **Show/Hide Menu** key or
+button). This can be useful for mounting media images or changing DIP switches
+and machine configuration settings before the emulated system starts.
+
+Input Settings
+ Shows the :ref:`Input Settings <menus-inputopts>` menu, where you can assign
+ controls to emulated inputs, adjust analog control settings, control toggle
+ inputs, and test input devices.
+DIP Switches
+ Shows the DIP Switches menu, where configuration switches for the running
+ system can be changed. This item is not shown if the running system has no
+ DIP switches.
+Machine Configuration
+ Shows the Machine Configuration menu, where various settings specific to the
+ emulated system can be changed. This item is not shown if the running
+ system has no configuration settings.
+Bookkeeping
+ Shows uptime, coin counter and ticket dispenser statistics (if relevant) for
+ the running system.
+System Information
+ Shows information about the running system as emulated in MAME, including
+ CPU, sound and video devices.
+Warning Information
+ Shows information about imperfectly emulated features of the running system.
+ This item is not shown if there are no relevant warnings.
+Media Image Information
+ Shows information about mounted media images (if any). This item is only
+ shown if the running system has one or more media devices (e.g. floppy disk
+ drives or memory card slots).
+File Manager
+ Shows the File Manager menu, where you can mount new or existing media image
+ files, or unmount currently mounted media images. This item is only shown
+ if the running system has one or more media devices (e.g. floppy disk
+ drives or memory card slots).
+Tape Control
+ Shows the Tape Control menu, where you can control emulated cassette tape
+ mechanisms. This item is only shown for systems that use cassette tape
+ media.
+Pseudo Terminals
+ Shows the status of any pseudo terminal devices in the running system (used
+ to connect the emulated system to host pseudo terminals, for example via
+ emulated serial ports). This item is not shown if there are no pseudo
+ terminal devices in the running system.
+BIOS Selection
+ Shows the BIOS Selection menu, where you can select the BIOS/boot
+ ROM/firmware for the system and slot cards it contains. This item is not
+ shown if no BIOS options are available.
+Slot Devices
+ Shows the Slot Devices menu, where you can choose between emulated
+ peripherals. This item is not shown for systems that have no slot devices.
+Barcode Reader
+ Shows the Barcode Reader menu, where you can simulate scanning barcodes with
+ emulated barcode readers. This item is not shown if there are no barcode
+ readers in the running system.
+Network Devices
+ Shows the Network Devices menu, where you can set up emulated network
+ adapters that support bridging to a host network. This item is not shown if
+ there are no network adaptors that support bridging in the running system.
+Slider Controls
+ Shows the Slider Controls menu, where you can adjust various settings,
+ including video adjustments and individual sound channel levels.
+Video Options
+ Shows the Video Options menu, where you can change the view for each
+ screen/window, as well as for screenshots.
+Crosshair Options
+ Shows the Crosshair Options menu, where you can adjust the appearance of
+ crosshairs used to show the location of emulated light guns and other
+ absolute pointer inputs. This item is not shown if the emulated system has
+ no absolute pointer inputs.
+Cheat
+ Shows the Cheat menu, for controlling the built-in cheat engine. This item
+ is only shown if the built-in chat engine is enabled. Note that the cheat
+ plugin’s menu is accessed via the Plugin Options menu.
+Plugin Options
+ Shows the Plugin Options menu, where you can access settings for enabled
+ plugins. This item is not shown if no plugins are enabled, or if the main
+ menu is shown before the emulated system starts (by pressing the Show/Hide
+ Menu key/button while the system information screen is displayed).
+External DAT View
+ Shows the info viewer, which displays information loaded from various
+ external support files. This item is not shown if the :ref:`data plugin
+ <plugins-data>` is not enabled, or if the main menu is shown before the
+ emulated system starts (by pressing the Show/Hide Menu key/button while the
+ system information screen is displayed).
+Add To Favorites/Remove From Favorites
+ Adds the running system to the favourites list, or removes it if it’s
+ already in the favourites list. The favourites list can be used as a
+ filter for the system selection menu.
+About MAME
+ Shows the emulator version, data model, and copyright license information.
+Select New System
+ Shows the system selection menu, where you can select a system to start a
+ new emulation session. This item is not shown if the main menu is shown
+ before the emulated system starts (by pressing the Show/Hide Menu key/button
+ while the system information screen is displayed).
+Close Menu/Start System
+ Closes the main menu, returning control of the running system. Shows
+ **Start System** if the main menu is shown before the emulated system
+ starts (by pressing the Show/Hide Menu key/button while the system
+ information screen is displayed).
+
+
+.. _menus-inputopts:
+
+Input Settings menu
+-------------------
+
+The Input Settings provides options for assigning controls to emulated inputs,
+adjusting analog control settings, controlling toggle inputs, and testing input
+devices. You can reach the Input Settings menu by selecting **Input Settings**
+from the :ref:`main menu <menus-main>`. The items shown on this menu depend on
+available emulated inputs for the running system. Available emulated inputs may
+depend on slot options, machine configuration settings and DIP switch settings.
+
+Input Assignments (this system)
+ Lets you select assign controls to emulated inputs for the running system.
+ See the section on :ref:`configuring inputs <ui-inptcfg>` for more details.
+ This item is not shown if the running system has no enabled inputs that can
+ be assigned controls.
+Analog Input Adjustments
+ Shows the Analog Input Adjustments menu, where you can adjust sensitivity,
+ auto-centring speed and inversion settings for emulated analog inputs, and
+ see how the emulated analog inputs respond to controls with your settings.
+ For more details, see the :ref:`analog input settings <ui-inptcfg-analog>`
+ section for more details. This item is not shown if the running system has
+ no enabled analog inputs.
+Keyboard Selection
+ Shows the :ref:`Keyboard Selection menu <menus-keyboard>`, where you can
+ select between emulated and natural keyboard modes, and enable and disable
+ keyboard and keypad inputs for individual emulated devices. This item is
+ not shown if the running system has no keyboard or keypad inputs.
+Toggle Inputs
+ Shows the :ref:`Toggle Inputs menu <menus-inputtoggle>`, where you can view
+ and adjust the state of multi-position or toggle inputs. This item is not
+ shown if the running system has no enabled toggle inputs.
+Input Assignments (general)
+ Lets you select assign user interface controls, or assign default controls
+ for all emulated systems. See the section on :ref:`configuring inputs
+ <ui-inptcfg>` for more details.
+Input Devices
+ Shows the :ref:`Input Devices menu <menus-inputdevices>`, which lists the
+ input devices recognised by MAME.
+
+
+.. _menus-inputtoggle:
+
+Toggle Inputs menu
+------------------
+
+The Toggle Inputs menu shows the current state of multi-position or toggle
+inputs. Common examples include mechanically locking Caps Lock keys on
+computers, and two-position gear shit levers on driving games. You can reach
+the Toggle Inputs menu by selecting **Toggle Inputs** from the :ref:`Input
+Settings menu <menus-inputopts>`. Note that available emulated inputs may
+depend on slot options, machine configuration settings and DIP switch settings.
+
+Inputs are grouped by the emulated device they belong to. You can move between
+devices using the **Next Group** and **Previous Group** keys or buttons. Names
+of inputs are shown on the left, and the current settings are shown on the
+right.
+
+To change the state of an input, highlight it and use the **UI Left** and **UI
+Right** keys or buttons, or click the arrows beside the current setting.
+
+
+.. _menus-keyboard:
+
+Keyboard Selection menu
+-----------------------
+
+The Keyboard Selection menu lets your switch between emulated and natural
+keyboard modes, and enable or disable keyboard inputs for individual emulated
+devices. You can reach the Keyboard Selection menu by selecting **Keyboard
+Selection** from the :ref:`Input Settings menu <menus-inputopts>`.
+
+In emulated keyboard mode, keyboard and keypad inputs behave like any other
+digital inputs, responding to their assigned controls. In natural keyboard
+mode, MAME attempts to translate typed characters to emulated keystrokes. The
+initial keyboard mode is set using the :ref:`natural option
+<mame-commandline-natural>`.
+
+There are a number of unavoidable limitations in natural keyboard mode:
+
+* The emulated system must to support it.
+* The selected keyboard *must* match the keyboard layout selected in the
+ emulated software.
+* Keystrokes that don’t produce characters can’t be translated. (e.g. pressing a
+ modifier key on its own, such as **Shift** or **Control**).
+* Holding a key until the character repeats will cause the emulated key to be
+ pressed repeatedly as opposed to being held down.
+* Dead key sequences are cumbersome to use at best.
+* Complex input methods will not work at all (e.g. for Chinese/Japanese/Korean).
+
+Each emulated device in the system that has keyboard and/or keypad inputs is
+listed on the menu, allowing keyboard/keypad inputs to be enabled or disabled
+for individual devices. By default, keyboard/keypad inputs are enabled for the
+first device with keyboard inputs (if any), and for all other devices that have
+keypad inputs but no keyboard inputs. The enabled keyboard/keypad inputs are
+automatically saved to the configuration file for the system when the emulation
+session ends.
+
+
+.. _menus-inputdevices:
+
+Input Devices menu
+------------------
+
+The Input Devices menu lists input devices recognised by MAME and enabled with
+your current settings. Recognised input devices depend on the
+:ref:`keyboardprovider <mame-commandline-keyboardprovider>`, :ref:`mouseprovider
+<mame-commandline-mouseprovider>`, :ref:`lightgunprovider
+<mame-commandline-lightgunprovider>` and :ref:`joystickprovider
+<mame-commandline-joystickprovider>` options. Classes of input devices can be
+enabled or disabled using the :ref:`mouse <mame-commandline-nomouse>`,
+:ref:`lightgun <mame-commandline-nolightgun>` and :ref:`joystick
+<mame-commandline-nojoystick>` options. You can reach the Input Devices menu by
+selecting **Input Devices** from the :ref:`Input Settings menu
+<menus-inputopts>` or the General Settings menu.
-[todo: This needs SERIOUS expansion. Waiting on answer to a few questions..]
+Input devices are grouped by device class (for example keyboards or light guns).
+You can move between device classes using the **Next Group** and **Previous
+Group** keys or buttons. For each device, the device number (within its class)
+is shown on the left, and the name is shown on the right.
+Select a device to show the supported controls for the device. The name of
+each control is displayed on the left and its current state is shown on the
+right. When an analog axis control is highlighted, its state is also shown in
+graphical form below the menu. Digital control states are either zero
+(inactive) or one (active). Analog axis input states range from -65,536 to
+65,536 with the neutral position at zero. You can also select **Copy Device
+ID** to copy the device’s ID to the clipboard. This is useful for setting up
+:ref:`stable controller IDs <devicemap>` in :ref:`controller configuration files
+<ctrlrcfg>`.
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst
index 1956ca939cd..94c7eba413d 100644
--- a/docs/source/usingmame/ui.rst
+++ b/docs/source/usingmame/ui.rst
@@ -11,7 +11,7 @@ MAME’s User Interface
Introduction
------------
-MAME provides a simple user interface for selecting a system and software to
+MAME provides a simple user interface for selecting the system and software to
run and changing settings while running an emulated system. MAME’s user
interface is designed to be usable with a keyboard, game controller, or pointing
device, but will require a keyboard for initial configuration.
@@ -20,13 +20,13 @@ The default settings for the most important controls to know when running an
emulated system, and the settings they correspond to in case you want to change
them, are as follows:
-Scroll Lock, or Forward Delete on macOS (UI Toggle)
+Scroll Lock, or Forward Delete on macOS (Toggle UI Controls)
For emulated systems with keyboard inputs, enable or disable UI controls.
(MAME starts with UI controls disabled for systems with keyboard inputs
unless the :ref:`ui_active option <mame-commandline-uiactive>` is on.)
-Tab (Config Menu)
+Tab (Show/Hide Menu)
Show or hide the menu during emulation.
-Escape (UI Cancel)
+Escape (UI Back and UI Cancel)
Return to the system selection menu, or exit if MAME was started with a
system specified (from the command line or using an
:ref:`external front-end <frontends>`).
@@ -60,10 +60,11 @@ Return/Enter keypad Enter (UI Select)
Select the highlighted menu item.
Forward Delete, or Fn+Delete on some compact keyboards (UI Clear)
Clear setting or reset to default value.
-Escape (UI Cancel)
+Escape (UI Back and UI Cancel)
Clear the search if searching the menu, otherwise close the menu, returning
- to the previous menu, or returning to the emulated machine for the main menu
- (there’s usually an item at the bottom of the menu for the same purpose).
+ to the previous menu, or returning to the emulated system in the case of the
+ main menu (there’s usually an item at the bottom of the menu for the same
+ purpose).
Home (UI Home)
Highlight the first menu item and scroll to the top of the menu.
End (UI End)
@@ -91,14 +92,24 @@ most important UI controls have joystick assignments by default:
* Move the first joystick left or right in the X axis to adjust settings.
* Press the first button on the first joystick to select the highlighted menu
item.
+* If the first joystick has at least three buttons, press the second button on
+ the first joystick to close the menu, returning to the previous menu, or
+ returning to the emulated system in the case of the main menu (there’s usually
+ an item at the bottom of the menu for the same purpose).
+
+For gamepad-style controllers, the left analog thumb stick and directional pad
+usually control UI navigation. Depending on the controller, the right analog
+thumb stick, triggers and additional buttons may automatically be assigned to UI
+inputs. Check the **User Interface** input assignments menu to see how controls
+are assigned.
If you want to be able to use MAME with a game controller without needing a
keyboard, you’ll need to assign joystick buttons (or combinations of buttons) to
these controls as well:
-* **Config Menu** to show or dismiss the menu during emulation
-* **UI Cancel** to close menus, return to the system selection menu, or exit
- MAME
+* **Show/Hide Menu** to show or hide the menu during emulation
+* **UI Back** to close menus
+* **UI Cancel** to return to the system selection menu or exit MAME
* **UI Clear** isn’t essential for basic emulation, but it’s used to clear or
reset some settings to defaults
* **UI Home**, **UI End**, **UI Page Up**, **UI Page Down**, **UI Previous
@@ -125,16 +136,38 @@ pointing device:
* Click menu items to highlight them.
* Double-click menu items to select them.
* Click the left- or right-pointing triangle to adjust settings.
-* For menus with too many items to fit on the screen, click the upward- or
- downward-pointing triangle at the top or bottom to scroll up or down by one
- screen at a time.
+* For menus or text boxes with too many items or lines to fit on the screen,
+ press on the upward- or downward-pointing triangle at the top or bottom to
+ scroll up or down.
* Use vertical scrolling gestures to scroll menus or text boxes with too many
items or lines to fit on the screen.
* Click toolbar items to select them, or hover over them to see a description.
If you have enough additional mouse buttons, you may want to assign button
-combinations to the **Config Menu**, **Pause** and/or **UI Cancel** inputs to
-make it possible to use MAME without a keyboard.
+combinations to the **Show/Hide Menu**, **Pause**, **UI Back** and/or
+**UI Cancel** inputs to make it possible to use MAME without a keyboard.
+
+
+.. _ui-menus-touch:
+
+Using a touch screen
+~~~~~~~~~~~~~~~~~~~~
+
+MAME has basic support for navigating menus using a touch screen:
+
+* Tap menu items to highlight them.
+* Double-tap menu items to select them.
+* Swipe left or right (horizontally) on the highlighted menu item to adjust the
+ setting if applicable.
+* Swipe up or down (vertically) to scroll menus or text boxes with too many
+ items to fit on the screen.
+* For menus or text boxes with too many items or lines to fit on the screen,
+ press on the upward- or downward-pointing triangle at the top or bottom to
+ scroll up or down.
+
+Note that for SDL-based MAME, the
+:ref:`enable_touch <mame-scommandline-enabletouch>` option must be switched on
+to use touch screen support.
.. _ui-inptcfg:
@@ -145,26 +178,31 @@ Configuring inputs
MAME needs a flexible input system to support the control schemes of the vast
array of systems it emulates. In MAME, inputs that only have two distinct
states, on and off or active and inactive, are called *digital inputs*, and all
-other inputs are called *analog inputs*, even if this is not strictly true.
+other inputs are called *analog inputs*, even if this is not strictly true (for
+example multi-position switches are called analog inputs in MAME).
To assign MAME’s user interface controls or the default inputs for all systems,
-select **Input (general)** from the main menu during emulation, or select
-**Configure Options** from the system selection menu and then select **General
-Inputs**. From there, select a category.
-
-To assign inputs for the currently running machine, select **Input (this
-Machine)** from the main menu during emulation. Inputs are grouped by device
-and sorted by type. You can move between devices with the next group and
-previous group keys/buttons (**[** and **]** on the keyboard by default).
+select **Input Settings** from the main menu during emulation and then select
+**Input Assignments (general)** from the Input Settings menu, or select
+**General Settings** from the system selection menu and then select **Input
+Assignments** from the General Settings menu. From there, select a category.
+
+To assign inputs for the currently running system, select **Input Settings**
+from the main menu during emulation and then select **Input Assignments (this
+system)** from the Input Settings menu. Inputs are grouped by device and sorted
+by type. You can move between devices with the next group and previous group
+keys/buttons (opening/closing brackets **[** and **]** on the keyboard by
+default).
The input assignment menus show the name of the emulated input or user interface
-control on the left, and the input (or combination of inputs) assigned to it on
-the right.
+control on the left, and the controls (or combination of controls) assigned to
+it on the right.
To adjust the sensitivity, auto-centre speed and inversion settings, or to see
-how emulated analog controls react to your inputs, select **Analog Controls**
-from the main menu during emulation. (This item only appears on the main menu
-for systems with analog controls.)
+how emulated analog controls react to your inputs, select **Input Settings**
+from the main menu during emulation, and then select **Analog Input
+Adjustments** from the Input Settings Menu (this item only appears on the Input
+Settings menu for systems with analog controls).
.. _ui-inptcfg-digital:
@@ -173,7 +211,7 @@ Digital input settings
~~~~~~~~~~~~~~~~~~~~~~
Each emulated digital input has a single assignment setting. For flexibility,
-MAME can combine host inputs (keys, buttons and joystick axes) using logical
+MAME can combine controls (keys, buttons and joystick axes) using logical
**and**, **not** and **or** operations. This is best illustrated with some
examples:
@@ -195,11 +233,12 @@ Kbd P Kbd Shift or Kbd P Kbd Right Shift
(In technical terms, MAME uses Boolean sum of products logic to combine inputs.)
When a digital input setting is highlighted, the prompt below the menu shows
-whether selecting it will set the assignment or append an **or** operation to
-it. Press **UI Left/Right** before selecting the setting to switch between
-setting or appending an **or** operation. Press **UI Clear** (**Delete** or
-**Forward Delete** by default) to clear the setting or restore the default
-assignment.
+whether selecting it will replace the current assignment or append an **or**
+operation to it. Press **UI Left/Right** before selecting the setting to switch
+between replacing the assignment or appending an **or** operation to it. Press
+**UI Clear** (**Delete** or **Forward Delete** by default) to clear the
+highlighted setting, or restore the default assignment if it is currently
+cleared.
When you select a digital input setting, MAME will wait for you to enter an
input or a combination of inputs for a logical **and** operation:
@@ -209,10 +248,7 @@ input or a combination of inputs for a logical **and** operation:
* Press a key or button or move an analog control twice to add a **not** item to
the **and** operation. Pressing the same key or button or moving the same
analog control additional times toggles the **not** on and off.
-* Pressing **UI Cancel** (**Escape** by default) *before* activating any other
- controls clears the setting or restores the default assignment.
-* Pressing **UI Cancel** *after* activating another control leaves the setting
- unchanged.
+* Press **UI Cancel** (**Escape** by default) to leave the setting unchanged.
* The new setting is shown below the menu. Wait one second after activating an
input to accept the new setting.
@@ -242,14 +278,14 @@ Each emulated analog input has three assignment settings:
input. The axis setting uses the name of the input with the suffix “Analog”.
For example the axis setting for the steering wheel in Ridge Racer is called
**Steering Wheel Analog**.
-* Use the *increment setting* assign an input (or combination of inputs) to
+* Use the *increment setting* assign a control (or combination of controls) to
increase the value of the emulated analog input. The increment setting uses
the name of the input with the suffix “Analog Inc”. For example the increment
setting for the steering wheel in Ridge Racer is called **Steering Wheel
Analog Inc**. This is a digital input setting – if an analog axis is
assigned to it, MAME will not increase the emulated input value at a
proportional speed.
-* Use the *decrement setting* assign an input (or combination of inputs) to
+* Use the *decrement setting* assign a control (or combination of controls) to
decrease the value of the emulated analog input. The decrement setting uses
the name of the input with the suffix “Analog Dec”. For example the decrement
setting for the steering wheel in Ridge Racer is called **Steering Wheel
@@ -272,12 +308,12 @@ You can assign one or more analog axes to the axis setting for an emulated
analog input. When multiple axes are assigned to an axis setting, they will be
added together, but absolute position controls will override relative position
controls. For example suppose for Arkanoid you assign the **Dial Analog** axis
-setting to **Mouse X or Joy 1 LSX or Joy 1 RSX** on a mouse Xbox-style
+setting to **Mouse X or Joy 1 LSX or Joy 1 RSX** on a mouse and Xbox-style
controller. You will be able to control the paddle with the mouse or either
analog stick, but the mouse will only take effect if both analog sticks are in
the neutral position (centred) on the X axis. If either analog stick is *not*
centred on the X axis, the mouse will have no effect, because a mouse is a
-relative position control while a joystick is an absolute position control.
+relative position control while joysticks are absolute position controls.
For absolute position controls like joysticks and pedals, MAME allows you to
assign either the full range of an axis or the range on one side of the neutral
@@ -311,10 +347,10 @@ Mouse X or Joy 1 LT or Joy 1 RT Reverse
direction to the left trigger.
Joy 1 LB Joy 1 LSX
Use horizontal movement of the left analog stick to control the emulated
- input, but *only* while holding the left shoulder button. If the right
+ input, but *only* while holding the left shoulder button. If the left
shoulder button is released while the left analog stick is not centred
- horizontally, the emulated input will hold its value until the right
- shoulder button is pressed again (a “sticky” control).
+ horizontally, the emulated input will hold its value until the left shoulder
+ button is pressed again (a “sticky” control).
not Joy 1 RB Joy 1 RSX or Joy 1 RB Joy 1 RSX Reverse
Use horizontal movement of the right analog stick to control the emulated
input, but invert the control if the right shoulder button is held.
@@ -333,23 +369,21 @@ When you select an axis setting, MAME will wait for you to enter an input:
direction of the control on or off.
* When appending to a setting, move an analog control other than the last
assigned control or press a key or button to add an **or** operation.
-* Pressing **UI Cancel** (**Escape** by default) *before* activating any other
- controls clears the setting or restores the default assignment.
-* Pressing **UI Cancel** *after* activating another control leaves the setting
- unchanged.
+* Pressing **UI Cancel** (**Escape** by default) leaves the setting unchanged.
* The new setting is shown below the menu. Wait one second after moving an
analog control to accept the new setting.
To adjust sensitivity, auto-centring speed and inversion settings for emulated
-analog inputs, or to see how they respond to your settings, select **Analog
-Controls** from the main menu during emulation. Settings for emulated analog
+analog inputs, or to see how they respond to controls with your settings, select
+**Input Settings** from the main menu during emulation, and then select **Analog
+Input Adjustments** from the Input Settings Menu. Settings for emulated analog
inputs are grouped by device and sorted by type. You can move between devices
-with the next group and previous group keys/buttons (**[** and **]** on the
-keyboard by default). The state of the emulated analog inputs is shown below
-the menu, and reacts in real time. Press the **On Screen Display** key or
-button (the backtick/tilde key by default on a US ANSI QWERTY keyboard) to hide
-the menu to make it easier to test without changing settings. Press the same
-key or button to show the menu again.
+with the next group and previous group keys/buttons (opening/closing brackets
+**[** and **]** on the keyboard by default). The state of the emulated analog
+inputs is shown below the menu, and reacts in real time. Press the **On Screen
+Display** key or button (the backtick/tilde key by default on a US ANSI QWERTY
+keyboard) to hide the menu to make it easier to test without changing settings.
+Press the same key or button to show the menu again.
Each emulated input has four settings on the **Analog Controls** menu:
@@ -387,7 +421,7 @@ The system and software selection menus
If you start MAME without specifying a system on the command line, the system
selection menu will be shown (assuming the
:ref:`ui option <mame-commandline-ui>` is set to **cabinet**). The system
-selection menu is also shown if you select **Select New Machine** from the main
+selection menu is also shown if you select **Select New System** from the main
menu during emulation. Selecting a system that uses software lists shows the
similar software selection menu.
@@ -407,7 +441,7 @@ The system and software selection menus have the following parts:
* The list of systems or software in the centre. For the system selection menu,
there are configuration options below the list of systems. Clones are shown
with a different text colour (grey by default). You can right-click a system
- name as a shortcut to show the machine configuration options for the system.
+ name as a shortcut to show the System Settings menu for the system.
Systems or software items are sorted by full name or description, keeping
clones immediately below their parents. This may appear confusing if your
@@ -454,8 +488,8 @@ Navigation controls
In addition to the usual :ref:`menu navigation controls <ui-menus>`, the system
and software selection menus have additional configurable controls for
navigating the multi-pane layout, and providing alternatives to toolbar buttons
-if you don’t want to use a pointing device. The default additional controls (on
-a US ANSI QWERTY keyboard), and the settings they correspond to, are:
+if you don’t want to use a pointing device. The default additional controls
+(with a US ANSI QWERTY keyboard), and the settings they correspond to, are:
Tab (UI Focus Next)
Move focus to the next area. The order is system/software list,
@@ -481,6 +515,8 @@ or info source with left/right. When focus is on the info/image tabs,
left/right switch between tabs. When focus is on the image/info tabs or source,
you can scroll the info using up, down, page up, page down, home and end.
+You can move focus to an area by clicking on it with the middle mouse button.
+
.. _ui-simpleselmenu:
@@ -488,7 +524,7 @@ The simple system selection menu
--------------------------------
If you start MAME without specifying a system on the command line (or choose
-**Select New Machine** from the main menu during emulation) with the
+**Select New System** from the main menu during emulation) with the
:ref:`ui option <mame-commandline-ui>` set to **simple**, the simple system
selection menu will be shown. The simple system selection menu shows fifteen
randomly selected systems that have ROM sets present in your configured
diff --git a/docs/source/usingmame/usingmame.rst b/docs/source/usingmame/usingmame.rst
index f808199cb52..4fa014fe3da 100644
--- a/docs/source/usingmame/usingmame.rst
+++ b/docs/source/usingmame/usingmame.rst
@@ -3,7 +3,7 @@ Using MAME
If you want to dive right in and skip the command line, there's a nice graphical
way to use MAME without the need to download and set up a front end. Simply
-start MAME with no parameters, by doubleclicking the **mame.exe** file or
+start MAME with no parameters, by double-clicking the **mame.exe** file or
running it directly from the command line. If you're looking to harness the
full power of MAME, keep reading further.
@@ -14,7 +14,7 @@ to missing glyphs.
If you are a new MAME user, you could find this emulator a bit complex at
first. Let's take a moment to talk about software lists, as they can simplify
matters quite a bit. If the content you are trying to play is a documented
-entry on one of the MAME sotware lists, starting the content is as easy as
+entry on one of the MAME software lists, starting the content is as easy as
**mame.exe** *<system>* *<software>*
@@ -79,18 +79,19 @@ gives a basic summary of command line options for MAME, as explained above.
**mame.exe -showusage**
gives you the (quite long) list of available command line options for MAME.
-The main options are described, in the :ref:`universal-command-line` section of
-this manual.
+The main options are described, in the :ref:`mame-commandline-universal` section
+of this manual.
**mame.exe -showconfig**
gives you a (quite long) list of available configuration options for MAME.
-These optons can always be modified at command line, or by editing them in
+These options can always be modified at command line, or by editing them in
mame.ini which is the main configuration file for MAME. You can find a
-description of some configuration options in the :ref:`universal-command-line`
-section of the manual (in most cases, each configuration option has a
-corresponding command line option to configure and modify it).
+description of some configuration options in the
+:ref:`mame-commandline-universal` section of the manual (in most cases, each
+configuration option has a corresponding command line option to configure and
+modify it).
**mame.exe -createconfig**