summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/advanced/ctrlr_config.rst47
-rw-r--r--docs/source/conf.py4
-rw-r--r--docs/source/debugger/general.rst15
-rw-r--r--docs/source/plugins/autofire.rst18
-rw-r--r--docs/source/plugins/inputmacro.rst14
-rw-r--r--docs/source/techspecs/memory.rst18
-rw-r--r--docs/source/usingmame/commonissues.rst2
-rw-r--r--docs/source/usingmame/defaultkeys.rst11
-rw-r--r--docs/source/usingmame/mamemenus.rst282
-rw-r--r--docs/source/usingmame/ui.rst100
10 files changed, 410 insertions, 101 deletions
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst
index f05a3d164b7..6fdeddc8a8a 100644
--- a/docs/source/advanced/ctrlr_config.rst
+++ b/docs/source/advanced/ctrlr_config.rst
@@ -41,8 +41,9 @@ Basic structure
Controller configuration files follow a similar format to the system
configuration files that MAME uses to save things like input settings and
-bookkeeping data. This example shows the overall structure of a controller
-configuration file:
+bookkeeping data (created in the folder specified using the
+:ref:`cfg_directory option <mame-commandline-cfgdirectory>`). This example
+shows the overall structure of a controller configuration file:
.. code-block:: XML
@@ -127,21 +128,21 @@ left and right arrows will be replaced with the numeric 8, 2, 4 and 6 keys on
the numeric keypad, respectively.
Note that substitutions specified using ``remap`` elements only apply to inputs
-that use MAME’s default assignment for the control type. That is, they only
-apply to default assignments for control types set in the “Inputs (general)”
-menu. They *do not* apply to default input assignments set in driver/device I/O
-port definitions (using the ``PORT_CODE`` macro).
+that use MAME’s default assignment for the input type. That is, they only apply
+to default assignments for control types set in the “Input Assignments
+(general)” menus. They *do not* apply to default control assignments set in
+driver/device I/O port definitions (using the ``PORT_CODE`` macro).
MAME applies ``remap`` elements found inside any applicable ``system`` element.
.. _ctrlrcfg-typeoverride:
-Overriding defaults by control type
------------------------------------
+Overriding defaults by input type
+---------------------------------
Use ``port`` elements with ``type`` attributes but without ``tag`` attributes to
-override the default host input assignments for a controls:
+override the default control assignments for emulated inputs by type:
.. code-block:: XML
@@ -183,10 +184,10 @@ P1 Button 4 (Player 1 Controls)
X key, or joystick 1 button 4
Note that this will only apply for inputs that use MAME’s default assignment for
-the control type. That is, ``port`` elements without ``tag`` attributes only
-override default assignments for control types set in the “Inputs (general)”
-menu. They *do not* override default input assignments set in driver/device I/O
-port definitions (using the ``PORT_CODE`` macro).
+the input type. That is, ``port`` elements without ``tag`` attributes only
+override default assignments for control types set in the “Input Assignments
+(general)” menus. They *do not* override default control assignments set in
+driver/device I/O port definitions (using the ``PORT_CODE`` macro).
MAME applies ``port`` elements without ``tag`` attributes found inside any
applicable ``system`` element.
@@ -194,22 +195,22 @@ applicable ``system`` element.
.. _ctrlrcfg-ctrloverride:
-Overriding defaults for specific controls
------------------------------------------
+Overriding defaults for specific inputs
+---------------------------------------
Use ``port`` elements with ``tag``, ``type``, ``mask`` and ``defvalue``
-attributes to override defaults for specific controls. These ``port`` elements
+attributes to override defaults for specific inputs. These ``port`` elements
should only occur inside ``system`` elements that apply to particular systems or
source files (i.e. they should not occur inside ``system`` elements where the
-``name`` attribute has the value ``default``). The default host input
-assignments can be overridden, as well as the toggle setting for digital
-controls.
+``name`` attribute has the value ``default``). The default control assignments
+can be overridden, as well as the toggle setting for digital inputs.
The ``tag``, ``type``, ``mask`` and ``defvalue`` are used to identify the
affected input. You can find out the values to use for a particular input by
-changing its assigned host input, exiting MAME, and checking the values in the
-system configuration file. Note that these values are not guaranteed to be
-stable, and may change between MAME versions.
+changing its control assignment, exiting MAME, and checking the values in the
+system configuration file (created in the folder specified using the
+:ref:`cfg_directory option <mame-commandline-cfgdirectory>`). Note that these
+values are not guaranteed to be stable, and may change between MAME versions.
Here’s an example that overrides defaults for 280-ZZZAP:
@@ -225,5 +226,5 @@ Here’s an example that overrides defaults for 280-ZZZAP:
</input>
</system>
-This sets the host inputs to steer left and right to the K and J keys,
+This sets the controls to steer left and right to the K and J keys,
respectively, and disables the toggle setting for the gear shift input.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b3a6351f058..32f1fdd03be 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -63,9 +63,9 @@ copyright = u'1997-2022, MAMEdev and contributors'
# built documents.
#
# The short X.Y version.
-version = '0.244'
+version = '0.245'
# The full version, including alpha/beta/rc tags.
-release = '0.244'
+release = '0.245'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/source/debugger/general.rst b/docs/source/debugger/general.rst
index e7d82c3ad1c..cdaf9ca4019 100644
--- a/docs/source/debugger/general.rst
+++ b/docs/source/debugger/general.rst
@@ -546,6 +546,21 @@ Examples:
Back to :ref:`debugger-general-list`
+.. _debugger-command-time:
+
+time
+----
+
+Prints the total elapsed emulated time to the debugger console.
+
+Examples:
+
+``time``
+ Prints the elapsed emulated time.
+
+Back to :ref:`debugger-general-list`
+
+
.. _debugger-command-quit:
quit
diff --git a/docs/source/plugins/autofire.rst b/docs/source/plugins/autofire.rst
index 56adef9b66f..3b22a9021e7 100644
--- a/docs/source/plugins/autofire.rst
+++ b/docs/source/plugins/autofire.rst
@@ -50,9 +50,9 @@ Button 1* or the equivalent for another player, but it might have have a
different name. On Konami’s Gradius games, *P1 Button 2* is the primary fire
button.
-Select **Hotkey** to set the input combination you’ll use to activate the
-autofire button. This can be any combination that MAME supports for activating
-a digital input.
+Select **Hotkey** to set the control (or combination of controls) you’ll use to
+activate the autofire button. This can be any combination that MAME supports
+for activating a digital input.
**On frames** and **Off frames** are the number of consecutive emulated video
frames that the emulated button will be held and released for, respectively.
@@ -81,10 +81,10 @@ immediately.
Notes and potential pitfalls
----------------------------
-Autofire buttons act as if they’re wired in parallel with MAME’s regular inputs.
-This means that if you set the activation hotkey for an autofire button to a
-button or key that’s also assigned to one of the emulated inputs directly, you
-may get unexpected results. Using Gradius as an example:
+Autofire buttons act as if they’re wired in parallel with MAME’s regular
+controls. This means that if you set the activation hotkey for an autofire
+button to a button or key that’s also assigned to one of the emulated inputs
+directly, you may get unexpected results. Using Gradius as an example:
* Suppose you set button 1 on your controller to fire, and set an autofire
hotkey to button 1 as well. Holding the button down to shoot will not trigger
@@ -97,8 +97,8 @@ may get unexpected results. Using Gradius as an example:
powerup because the powerup button is also being held down along with the
autofire button.
-It is suggested you choose input combinations for autofire hotkeys that are not
-assigned to any other emulated inputs in the system.
+It is recommended that you choose control combinations for autofire hotkeys that
+are not assigned to any other emulated inputs in the system.
Autofire is not necessarily desirable in all situations. For example using
autofire in Super-X with the blue “lightning” weapon equipped at high power
diff --git a/docs/source/plugins/inputmacro.rst b/docs/source/plugins/inputmacro.rst
index 99f8a3448fc..dd66fef205e 100644
--- a/docs/source/plugins/inputmacro.rst
+++ b/docs/source/plugins/inputmacro.rst
@@ -57,10 +57,10 @@ whole:
press the UI Clear key to type a new name. Press the UI Select key before
moving to another menu item to save the new name; press the UI Cancel key
(Escape/Esc on the keyboard by default) to change discard the new name.
-* Select **Activation sequence** to set the key or button combination you want
- to use to activate the macro. Keep in mind that regular input settings still
- apply, so you probably want to use a combination that isn’t being used for any
- other emulated input in the system.
+* Select **Activation combination** to set the control (or combination of
+ controls) you want to use to activate the macro. Keep in mind that regular
+ input assignments still apply, so you will probably want to use a combination
+ that isn’t being used for any other emulated input in the system.
* Set **On release** to specify what should happen if the activation sequence is
released before the macro completes. When set to *Stop immediately*, any
emulated inputs activated by the macro will be released immediately, and no
@@ -133,7 +133,7 @@ thing could be achieved using the :ref:`plugins-autofire`, but this demonstrates
a simple looping macro:
* **Name**: P1 Autofire
-* **Activation sequence**: Kbd Space
+* **Activation combination**: Kbd Space
* **On release**: Stop immediately
* **When held**: Loop to step 2
* **Step 1**:
@@ -159,7 +159,7 @@ This allows you to run in Konami Track & Field by holding a single button. This
takes most of the skill (and fun) out of the game:
* **Name**: P1 Sprint
-* **Activation sequence**: Kbd Shift
+* **Activation combination**: Kbd Shift
* **On release**: Stop immediately
* **When held**: Loop to step 2
* **Step 1**:
@@ -188,7 +188,7 @@ This macro allows you to perform a right-facing Shōryūken (Dragon Punch) by
pressing a single key:
* **Name**: 1P Shoryuken LP
-* **Activation sequence**: Kbd M
+* **Activation combination**: Kbd M
* **On release**: Complete macro
* **When held**: Prolong step 6
* **Step 1**:
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index 260e39e566e..9d7eb3c1b29 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -126,7 +126,8 @@ A memory share can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved. That class behaves like a pointer but also has the
``target()``, ``length()``, ``bytes()``, ``endianness()``,
-``bitwidth()`` and ``bytewidth()`` methods for share information.
+``bitwidth()`` and ``bytewidth()`` methods for share information. The
+desired size is specified in bytes.
.. code-block:: C++
@@ -154,12 +155,17 @@ A memory bank is a named memory zone indirection that can be mapped in
address spaces. It points to ``nullptr`` when created.
``configure_entry`` associates an entry number and a base pointer.
``configure_entries`` does the same for multiple consecutive entries
-spanning a memory zone. Alternatively ``set_base`` sets the base for
-entry 0 and selects it.
+spanning a memory zone.
-``set_entry`` allows to dynamically and efficiently select the current
-active entry, ``entry()`` gets that selection back, and ``base()`` gets
-the associated base pointer.
+``set_base`` sets the base address for the active entry. If there are
+no entries, entry 0 (zero) is automatically created and selected. Use
+of ``set_base`` should be avoided in favour of pre-configured entries
+unless there are an impractically large number of possible base
+addresses.
+
+``set_entry`` dynamically and efficiently selects the active entry,
+``entry()`` returns the active entry number, and ``base()`` gets the
+associated base pointer.
.. code-block:: C++
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 08cf7b30184..f7a7e8ba682 100644
--- a/docs/source/usingmame/defaultkeys.rst
+++ b/docs/source/usingmame/defaultkeys.rst
@@ -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**
@@ -706,8 +707,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**
@@ -742,5 +743,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/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index ca40b5668ed..0673528214d 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -1,9 +1,283 @@
+.. _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 **Config Menu** key or button (**Tab** by default). If the
+emulated system has keyboard inputs, you may need to press the **UI Toggle** 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 Cancel** 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 **Config
+Menu** key or button. Pressing the **Config 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 (**P** 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 **Config 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 **Config 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 Cancel** key or button, or pressing the **Config 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
+ 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 Config 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 Config 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 Config 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 Config 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 (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 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 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:`main menu <menus-main>` 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.
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst
index 1956ca939cd..f7ca2a41aa1 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.
@@ -62,8 +62,9 @@ Forward Delete, or Fn+Delete on some compact keyboards (UI Clear)
Clear setting or reset to default value.
Escape (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)
@@ -92,6 +93,10 @@ most important UI controls have joystick assignments by default:
* Press the first button on the first joystick to select the highlighted menu
item.
+For gamepad-style controllers, the left analog thumb stick usually controls UI
+navigation. You may find it convenient to assign directional pad controls to UI
+navigation in addition to or in place of the left thumb stick.
+
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:
@@ -145,26 +150,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 +183,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 +205,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:
@@ -211,7 +222,7 @@ input or a combination of inputs for a logical **and** operation:
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
+* Press **UI Cancel** *after* activating another control 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 +253,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 +283,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 +322,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.
@@ -341,15 +352,16 @@ When you select an axis setting, MAME will wait for you to enter an input:
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 +399,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 +419,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 +466,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,
@@ -488,7 +500,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