====== How to Override a Controller Mapping ======

As shown in the [[en:tutorials:input:analog_joystick_gamepad_control|analog joystick page]], Orx uses the [[https://github.com/gabomdq/SDL_GameControllerDB|SDL Controller DB]] (via the GLFW3 library) to give common mapping between all sorts of gamepad/joystick controllers.

This makes adding controller support so much easier for a developer writing a game with Orx. It all just works out of the box.

We can now add/override gamepad mappings using the ''Input.MappingList'' config property.

For those rare cases having a very old or obscure controller, there are two good reasons to add a controller mapping to your Orx config:

  - The controller is not yet supported in the SDL Controller Database, and therefore Orx as well.
  - The controller config in the database is incorrect.

The SDL Database controller entries can be found here: https://github.com/gabomdq/SDL_GameControllerDB/tree/master/data

Here is an example mapping of a "generic" controller called "XInput Gamepad (GLFW)":

<code>
78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0,b:b1,x:b2,y:b3,leftshoulder:b4,rightshoulder:b5,back:b6,start:b7,leftstick:b8,rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4,righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8,
</code>

The mapping line above would be already compiled in GLFW.

In order to switch ''LBUMPER'' with ''RBUMPER'', and ''START'' with ''BACK'', the mapping line would become:

<code>
78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0,b:b1,x:b2,y:b3,leftshoulder:b5,rightshoulder:b4,back:b7,start:b6,leftstick:b8,rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4,righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8,
</code>

Take this new config, and add it to the the ''Input'' section:

<code ini>
[Input]
MappingList = 78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0,b:b1,x:b2,y:b3,leftshoulder:b5,rightshoulder:b4,back:b7,start:b6,leftstick:b8,rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4,righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8
</code>

Compile and try your controller. You should find the ''LBUMPER'' and ''RBUMPER'' switched, and ''START'' and ''BACK'' switched.

===== Multiple mapping line format =====

Controller mapping entries end in a comma on each line in the SDL database. In the Orx config list, you don't have to specify the trailing comma. You can specify the regular Orx config list seperator ''#'', or both. 

Any of the following are valid:

<code ini>
[Input]
MappingList = 03000000260900008888000000000000,Cyber Gadget GameCube Controller,a:b0,b:b1,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,lefttrigger:a5,leftx:a0,lefty:a1,rightshoulder:b6,righttrigger:a4,rightx:a2,righty:a3~,start:b7,x:b2,y:b3,platform:Windows, #
03000000a306000022f6000000000000,Cyborg V.3 Rumble Pad,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:+a3,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:-a3,rightx:a2,righty:a4,start:b9,x:b0,y:b3,platform:Windows,
</code>

<code ini>
[Input]
MappingList = "
03000000260900008888000000000000,Cyber Gadget GameCube Controller,a:b0,b:b1,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,lefttrigger:a5,leftx:a0,lefty:a1,rightshoulder:b6,righttrigger:a4,rightx:a2,righty:a3~,start:b7,x:b2,y:b3,platform:Windows,
03000000a306000022f6000000000000,Cyborg V.3 Rumble Pad,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:+a3,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:-a3,rightx:a2,righty:a4,start:b9,x:b0,y:b3,platform:Windows,
"
</code>

<code ini>
[Input]
MappingList = 03000000260900008888000000000000,Cyber Gadget GameCube Controller,a:b0,b:b1,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,lefttrigger:a5,leftx:a0,lefty:a1,rightshoulder:b6,righttrigger:a4,rightx:a2,righty:a3~,start:b7,x:b2,y:b3,platform:Windows #
03000000a306000022f6000000000000,Cyborg V.3 Rumble Pad,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:+a3,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:-a3,rightx:a2,righty:a4,start:b9,x:b0,y:b3,platform:Windows
</code>

===== Contributing to the DB =====

The [[https://github.com/gabomdq/SDL_GameControllerDB|SDL Database project]] would welcome contributions to the DB to benefit others. the GLFW3 project will take new controller mappings with each new edition. As Orx updates its GLFW plugin, it will make the new mappings available.

If contributing is not practical, at least it is possible to still add controller support for a developer's current games.

There is a [[http://www.generalarcade.com/gamepadtool/|downloadable tool available]] to make a mapping line from your controller. Available for Windows, Mac OS X and Linux.