summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author Tomer Verona <tverona@hotmail.com>2016-09-12 18:35:36 -0700
committer Tomer Verona <tverona@hotmail.com>2016-09-12 18:35:36 -0700
commit2bd18d5fea66bedcde02da1b2c17d83c4640a782 (patch)
tree21a026c276f83cd6a3619d49ca85cba088485e5b /docs
parent597626d0593e84868d5d9887c1f44b96222bdd49 (diff)
Support for configuring device to conrtoller id
This change adds support for configuring device to conrtoller id. This allows for stable controller ids even if USB devices are plugged / unplugged, system is rebooted, etc. See documentation for additional context.
Diffstat (limited to 'docs')
-rw-r--r--docs/source/advanced/devicemap.rst81
-rw-r--r--docs/source/advanced/index.rst3
2 files changed, 83 insertions, 1 deletions
diff --git a/docs/source/advanced/devicemap.rst b/docs/source/advanced/devicemap.rst
new file mode 100644
index 00000000000..2b52ef00c78
--- /dev/null
+++ b/docs/source/advanced/devicemap.rst
@@ -0,0 +1,81 @@
+Stable Controller IDs
+===============================
+
+By default, the mapping between devices and controller IDs is not stable. For instance, a gamepad controller may be assigned to "Joy 1" initially, but after a reboot, it may get re-assigned to "Joy 3".
+
+The reason is that MAME enumerates attached devices and assigns controller IDs based on the enumeration order. Factors that can cause controller IDs to change include plugging / unplugging USB devices, changing ports / hubs and even system reboots.
+
+It is quite cumbersome to ensure that controller IDs are always correct.
+
+That's where the "mapdevice" configuration setting comes into the picture. This setting allows you to map a device name to a controller ID, ensuring that the specified device always maps to the same controller ID in MAME.
+
+Usage of mapdevice
+------------------
+The "mapdevice" xml element is specified under the input xml element in the configuration. It requires two attributes, "device" and "controller".
+
+The "device" attribute specifies the name of the device to match. It may also be a substring of the name. To see the list of available devices, enable verbose output and available devices will then be listed to the console at startup (more on this below).
+
+The "controller" attribute specifies the MAME controller ID. It is made up of a controller class (i.e. "JOYCODE", "GUNCODE", "MOUSECODE") and controller index. For example: "JOYCODE_1".
+
+Example
+-------
+Here's an example:
+
+| <mameconfig version="10">
+| <system name="default">
+| <input>
+| **<mapdevice device="VID_D209&amp;PID_1601" controller="GUNCODE_1" />**
+| **<mapdevice device="VID_D209&amp;PID_1602" controller="GUNCODE_2" />**
+| **<mapdevice device="XInput Player 1" controller="JOYCODE_1" />**
+| **<mapdevice device="XInput Player 2" controller="JOYCODE_2" />**
+|
+| <port type="P1_JOYSTICK_UP">
+| <newseq type="standard">
+| JOYCODE_1_YAXIS_UP_SWITCH OR KEYCODE_8PAD
+| </newseq>
+| </port>
+| ...
+|
+
+In the above example, we have four device mappings specified:
+
+The first two mapdevice entries map player 1 and 2 lightguns to Gun 1 and Gun 2, respectively. We use a substring of the full raw device names to match each devices. Note that, since this is XML, we needed to escape the '&' in the name using '&amp;'.
+
+The last two mapdevices entries map player 1 and player 2 gamepad controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput devices.
+
+Listing Available Devices
+-------------------------
+How did we obtain the device names in the above example? Easy!
+
+We simply set verbose to 1 in mame.ini:
+
+| #
+| # CORE DEBUGGING OPTIONS
+| #
+| **verbose 1**
+|
+
+Then, when MAME is started, it will list available devices to the console. For example:
+
+| Input: Adding Gun #0:
+| Input: Adding Gun #1:
+| Input: Adding Gun #2: HID-compliant mouse (\\?\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Input: Adding Gun #3: HID-compliant mouse (\\?\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Input: Adding Gun #4: HID-compliant mouse (\\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Input: Adding Gun #5: HID-compliant mouse (\\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Input: Adding Gun #6: HID-compliant mouse (\\?\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows).
+| Input: Adding Joy #0: ATRAK Device #1
+| Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows).
+| Input: Adding Joy #1: ATRAK Device #2
+| Input: Adding Joy #2: XInput Player 1
+| Input: Adding Joy #3: XInput Player 2
+|
+
+Furthermore, when devices are mapped using mapdevice, you'll see that in the verbose logging too, such as:
+
+| Mapped device 'HID-compliant mouse (\\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})' to Gun #0
+| Mapped device 'HID-compliant mouse (\\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})' to Gun #1
+| Mapped device 'XInput Player 1' to Joy #0
+| Mapped device 'XInput Player 2' to Joy #1
+|
diff --git a/docs/source/advanced/index.rst b/docs/source/advanced/index.rst
index d40a328fe2f..8ce1dfee49c 100644
--- a/docs/source/advanced/index.rst
+++ b/docs/source/advanced/index.rst
@@ -9,4 +9,5 @@ Advanced configuration
shiftertoggle
bgfx
hlsl
- glsl \ No newline at end of file
+ glsl
+ devicemap \ No newline at end of file