diff options
author | 2021-07-15 04:09:18 +1000 | |
---|---|---|
committer | 2021-07-15 13:54:40 +1000 | |
commit | 37157461313b13a691722b83c87df8d2315457da (patch) | |
tree | 8034c6f33776f5a8bfc8f6c69af879975061bd0a /docs/source/advanced | |
parent | 66554d3b84f5fec60dcf5d896283a1a04487c0e0 (diff) |
API cleanups and miscellaneous fixes.
emu/ioport.cpp: Allow controller files to override input sequences for
inputs that don't use defaults, and to override the toggle setting for
digital inputs.
emu/config.cpp: Expose configuration level (mostly matters for
controller files), improved verbose diagnostic messages, and moved a few
things out of the global and preprocessor namespaces.
docs: Added documentation for some controller configuration file
features. The device mapping feature documentation will be merged in at
some point.
util/unicode.cpp, emu/input.cpp: API cleanups.
Diffstat (limited to 'docs/source/advanced')
-rw-r--r-- | docs/source/advanced/ctrlr_config.rst | 229 | ||||
-rw-r--r-- | docs/source/advanced/index.rst | 19 |
2 files changed, 239 insertions, 9 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 |