summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/advanced/ctrlr_config.rst229
-rw-r--r--docs/source/advanced/index.rst19
-rw-r--r--docs/source/commandline/commandline-all.rst16
3 files changed, 248 insertions, 16 deletions
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst
new file mode 100644
index 00000000000..f05a3d164b7
--- /dev/null
+++ b/docs/source/advanced/ctrlr_config.rst
@@ -0,0 +1,229 @@
+.. _ctrlrcfg:
+
+Controller Configuration Files
+==============================
+
+.. contents:: :local:
+
+
+.. _ctrlrcfg-intro:
+
+Introduction
+------------
+
+Controller configuration files can be used to modify MAME’s default input
+settings. Controller configuration files may be supplied with an input device
+to provide more suitable defaults, or used as profiles that can be selected for
+different situations. MAME includes a few sample controller configuration files
+in the **ctrlr** folder, designed to provide useful defaults for certain
+arcade-style controllers.
+
+Controller configuration files are an XML application, using the ``.cfg``
+filename extension. MAME searches for controller configuration files in the
+directories specified using the ``ctrlrpath`` option. A controller
+configuration file is selected by setting the ``ctrlr`` option to its filename,
+excluding the ``.cfg`` extension (e.g. set the ``ctrlr`` option to
+``scorpionxg`` to use **scorpionxg.cfg**). It is an error if the specified
+controller configuration file does not exist, or if it contains no sections
+applicable to the emulated system.
+
+Controller configuration files use implementation-dependent input tokens. The
+values available and their precise meanings depend on the exact version of MAME
+used, the input devices connected, the selected input provider modules
+(``keyboardprovider``, ``mouseprovider``, ``lightgunprovider`` and
+``joystickprovider`` options), and possibly other settings.
+
+
+.. _ctrlrcfg-structure:
+
+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:
+
+.. code-block:: XML
+
+ <?xml version="1.0"?>
+ <mameconfig version="10">
+ <system name="default">
+ <input>
+ <!-- settings affecting all emulated systems go here -->
+ </input>
+ </system>
+ <system name="neogeo">
+ <input>
+ <!-- settings affecting neogeo and clones go here -->
+ </input>
+ </system>
+ <system name="intellec4.cpp">
+ <input>
+ <!-- settings affecting all systems defined in intellec4.cpp go here -->
+ </input>
+ </system>
+ </mameconfig>
+
+The root of a controller configuration file must be a ``mameconfig`` element,
+with a ``version`` attribute specifying the configuration format version
+(currently ``10`` – MAME will not load a file using a different version). The
+``mameconfig`` element contains one or more ``system`` elements, each of which
+has a ``name`` attribute specifying the system(s) it applies to. Each
+``system`` element contains an ``input`` element which holds the actual
+``remap`` and ``port`` configuration elements, which will be described later.
+
+When launching an emulated system, MAME will apply configuration from ``system``
+elements where the value of the ``name`` attribute meets one of the following
+criteria:
+
+* If the ``name`` attribute has the value ``default``, it will always be applied
+ (including for the system/software selection menus).
+* If the value of the ``name`` attribute matches the system’s short name, the
+ short name of its parent system, or the short name of its BIOS system (if
+ applicable).
+* If the value of the ``name`` attribute matches the name of the source file
+ where the system is defined.
+
+For example, for the game “DaeJeon! SanJeon SuJeon (AJTUE 990412 V1.000)”,
+``system`` elements will be applied if their ``name`` attribute has the value
+``default`` (applies to all systems), ``sanjeon`` (short name of the system
+itself), ``sasissu`` (short name of the parent system), ``stvbios`` (short
+name of the BIOS system), or ``stv.cpp`` (source file where the system is
+defined).
+
+As another example, a ``system`` element whose ``name`` attribute has the value
+``zac2650.cpp`` will be applied for the systems “The Invaders”, “Super Invader
+Attack (bootleg of The Invaders)”, and “Dodgem”.
+
+Applicable ``system`` elements are applied in the order they appear in the
+controller configuration file. Settings from elements that appear later in the
+file may modify or override settings from elements that appear earlier. Within
+a ``system`` element, ``remap`` elements are applied before ``port`` elements.
+
+
+.. _ctrlrcfg-substitute:
+
+Substituting default controls
+-----------------------------
+
+You can use a ``remap`` element to substitute one host input for another in
+MAME’s default input configuration. For example, this substitutes keys on the
+numeric keypad for the cursor direction keys:
+
+.. code-block:: XML
+
+ <input>
+ <remap origcode="KEYCODE_UP" newcode="KEYCODE_8PAD" />
+ <remap origcode="KEYCODE_DOWN" newcode="KEYCODE_2PAD" />
+ <remap origcode="KEYCODE_LEFT" newcode="KEYCODE_4PAD" />
+ <remap origcode="KEYCODE_RIGHT" newcode="KEYCODE_6PAD" />
+ </input>
+
+The ``origcode`` attribute specifies the token for the host input to be
+substituted, and the ``newcode`` attribute specifies the token for the
+replacement host input. In this case, assignments using the cursor up, down,
+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).
+
+MAME applies ``remap`` elements found inside any applicable ``system`` element.
+
+
+.. _ctrlrcfg-typeoverride:
+
+Overriding defaults by control type
+-----------------------------------
+
+Use ``port`` elements with ``type`` attributes but without ``tag`` attributes to
+override the default host input assignments for a controls:
+
+.. code-block:: XML
+
+ <input>
+ <port type="UI_CONFIGURE">
+ <newseq type="standard">KEYCODE_TAB OR KEYCODE_1 KEYCODE_5</newseq>
+ </port>
+ <port type="UI_CANCEL">
+ <newseq type="standard">KEYCODE_ESC OR KEYCODE_2 KEYCODE_6</newseq>
+ </port>
+
+ <port type="P1_BUTTON1">
+ <newseq type="standard">KEYCODE_C OR JOYCODE_1_BUTTON1</newseq>
+ </port>
+ <port type="P1_BUTTON2">
+ <newseq type="standard">KEYCODE_LSHIFT OR JOYCODE_1_BUTTON2</newseq>
+ </port>
+ <port type="P1_BUTTON3">
+ <newseq type="standard">KEYCODE_Z OR JOYCODE_1_BUTTON3</newseq>
+ </port>
+ <port type="P1_BUTTON4">
+ <newseq type="standard">KEYCODE_X OR JOYCODE_1_BUTTON4</newseq>
+ </port>
+ </input>
+
+This sets the following default input assignments:
+
+Config Menu (User Interface)
+ Tab key, or 1 and 2 keys pressed simultaneously
+UI Cancel (User Interface)
+ Escape key, or 2 and 6 keys pressed simultaneously
+P1 Button 1 (Player 1 Controls)
+ C key, or joystick 1 button 1
+P1 Button 2 (Player 1 Controls)
+ Left Shift key, or joystick 1 button 2
+P1 Button 3 (Player 1 Controls)
+ Z key, or joystick 1 button 3
+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).
+
+MAME applies ``port`` elements without ``tag`` attributes found inside any
+applicable ``system`` element.
+
+
+.. _ctrlrcfg-ctrloverride:
+
+Overriding defaults for specific controls
+-----------------------------------------
+
+Use ``port`` elements with ``tag``, ``type``, ``mask`` and ``defvalue``
+attributes to override defaults for specific controls. 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.
+
+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.
+
+Here’s an example that overrides defaults for 280-ZZZAP:
+
+.. code-block:: XML
+
+ <system name="280zzzap">
+ <input>
+ <port tag=":IN0" type="P1_BUTTON2" mask="16" defvalue="0" toggle="no" />
+ <port tag=":IN1" type="P1_PADDLE" mask="255" defvalue="127">
+ <newseq type="increment">KEYCODE_K</newseq>
+ <newseq type="decrement">KEYCODE_J</newseq>
+ </port>
+ </input>
+ </system>
+
+This sets the host inputs 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/advanced/index.rst b/docs/source/advanced/index.rst
index 187ddac7267..9c73762697c 100644
--- a/docs/source/advanced/index.rst
+++ b/docs/source/advanced/index.rst
@@ -2,13 +2,14 @@ Advanced configuration
----------------------
.. toctree::
- :titlesonly:
+ :titlesonly:
- multiconfig
- paths
- shiftertoggle
- bgfx
- hlsl
- glsl
- devicemap
- linux-lightguns
+ multiconfig
+ paths
+ shiftertoggle
+ bgfx
+ hlsl
+ glsl
+ ctrlr_config
+ devicemap
+ linux-lightguns
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index 7979d98b3a8..de46760271a 100644
--- a/docs/source/commandline/commandline-all.rst
+++ b/docs/source/commandline/commandline-all.rst
@@ -32,7 +32,6 @@ patterns to avoid having your shell try to expand them against filenames (e.g.
.. _mame-commandline-paths:
-
File Names and Directory Paths
------------------------------
@@ -1087,7 +1086,7 @@ Core Search Path Options
.. _mame-commandline-artpath:
-**-artpath** *<path>* *<path>*
+**-artpath** *<path>*
Specifies one or more paths within which to find external layout and artwork
files. Multiple paths can be specified by separating them with semicolons.
@@ -1104,8 +1103,9 @@ Core Search Path Options
**-ctrlrpath** *<path>*
- Specifies one or more paths within which to find default input configuration
+ Specifies one or more paths within which to find controller configuration
files. Multiple paths can be specified by separating them with semicolons.
+ Used in conjunction with the ``-ctrlr`` option.
The default is ``ctrlr`` (that is, a directory ``ctrlr`` in the current
working directory).
@@ -2942,11 +2942,13 @@ Core Input Options
**-ctrlr** *<controller>*
- Enables support for special controllers. Configuration files are loaded from
- the ctrlrpath. They are in the same format as the .cfg files that are
- saved, but only control configuration data is read from the file.
+ Specifies a controller configuration file, typically used to set more
+ suitable default input assignments for special controllers. Directories
+ specified using the ``ctrlrpath`` option are searched. Controller
+ configuration files use a similar format to ``.cfg`` used to save system
+ settings. See :ref:`ctrlrcfg` for more details.
- The default is ``NULL`` (no controller file).
+ The default is ``NULL`` (no controller configuration file).
Example:
.. code-block:: bash