Table of Contents

How to Override a Controller Mapping

As shown in the analog joystick page, Orx uses the 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:

  1. The controller is not yet supported in the SDL Controller Database, and therefore Orx as well.
  2. 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)”: 

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,

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: 

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,

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

[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

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: 

[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,

[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,
"

[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

Contributing to the DB

The 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 downloadable tool available to make a mapping line from your controller. Available for Windows, Mac OS X and Linux.