From 37157461313b13a691722b83c87df8d2315457da Mon Sep 17 00:00:00 2001 From: Vas Crabb Date: Thu, 15 Jul 2021 04:09:18 +1000 Subject: 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. --- docs/source/advanced/ctrlr_config.rst | 229 ++++++++++++++++++++++++++++++++++ docs/source/advanced/index.rst | 19 +-- 2 files changed, 239 insertions(+), 9 deletions(-) create mode 100644 docs/source/advanced/ctrlr_config.rst (limited to 'docs/source/advanced') 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 + + + + + + + + + + + + + + + + + + + + +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 + + + + + + + + +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 + + + + KEYCODE_TAB OR KEYCODE_1 KEYCODE_5 + + + KEYCODE_ESC OR KEYCODE_2 KEYCODE_6 + + + + KEYCODE_C OR JOYCODE_1_BUTTON1 + + + KEYCODE_LSHIFT OR JOYCODE_1_BUTTON2 + + + KEYCODE_Z OR JOYCODE_1_BUTTON3 + + + KEYCODE_X OR JOYCODE_1_BUTTON4 + + + +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 + + + + + + KEYCODE_K + KEYCODE_J + + + + +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 -- cgit v1.2.3-70-g09d2