Plan for a joystick config menu

gfx_sdl2 supports SDL2's gamepad button/axis mapping system, which supports nearly all gamepads, but not non-gamepad joysticks. And currently there's no way to remap buttons if the SDL2 layout is problematic, when using a backend other than gfx_sdl2, or to map specific gamepad buttons to keyboard keys to play OHR games which have scripted keyboard controls and weren't written with gamepad support.

It was previously proposed to maintain our own database of common gamepads, but that's redundant to SDL's database. But the gap that still needs filling is player customisation of controls for their own device, and ideally also assigning controllers to players, or disabling of controllers.

This article does not meet the standard of quality we would like to have. Feel free to revise it and make it better by using the edit link at the top of the page. This tag should be removed when an editor feels it is of high quality.

WARNING: parts of this article are obsolete.

Three Levels Of Mapping

We could have up to three levels of mapping, although should not have three different mapping UIs, but rather allow mapping a button/axis to a control or to a keyboard key or to a standardised gamepad button.

The first level of mapping is axis-order and button order to gamepad scancodes like joy:A and axis:Y, for games that have been written for gamepad support. This mapping needs to be joystick-specific. It does not need to be game-specific.

Secondly, mapping gamepad buttons to controls -- builtin ones like Use and Left, and custom controls like a 'Search' function (not yet implemented as of writing).

However, thirdly we definitely also should have the ability to map axis/button to keyboard scancode for older keyboard-only games.

Axis and Button order

Every joystick provides 2 or more axes and some number of buttons. It is likely that axis 0 is a good axis for horizontal movement, and it is likely that axis 1 is a good axis for vertical movement, but these are by no means certain. On joysticks with many axes the best pair of axes for movement is impossible to guess for certain. The same holds true of buttons. you can sometimes assume that buttons 0 and 1 would make good Confirm/Cancel buttons, but this is never certain.

Here is an example mapping for a simple 2-axis 6-button joystick:

[joy::Joystick Name]
a0 = 0
a1 = 1
b0 = 3
b1 = 2
b2 = 1
b3 = 0
b4 = 4
b5 = 5

Mapping Buttons to keys

It should be possible to map axis changes and buttons to keyboard scancodes. Here is an example config

[joykey]
a0- = Left
a0+ = Right
a1- = Up
a1+ = Down
b0 = SPACE
b1 = ESC

Where to handle the mapping?

Joystick identification is backend-specific. SDL and DirectX give different names or GUIDs to the same joysticks, and names even change across different OSes.

Identifying joysticks by name also means that if a new joystick is detected that has never been configured before (and isn't supported by SDL as a gamepad), the user can be dumped directly into the joystick configuration screen.

Backcompat With old Games

In the DOS days virtually all old games were playable with joysticks (if you were lucky enough to have a joystick where axis 0 and 1 made a reasonable x and y and button 0 and 1 made a reasonable accept/cancel, and if you could stand the oversensitive buttons). Later, joystick support was broken for many years.

Support for multiple joysticks was particularly broken, and apparently never used by anyone.

A config file proposal

A possible file layout might look something like this:

[joy::Joymon6ButtonPro]
a0 = 0
a1 = 1
b0 = 4
b1 = 6
b2 = 2
b3 = 1

[joy::OmegaMultiInfinibutton99]
a0 = 4
a1 = 5
b0 = 12
b1 = 15

[joykeys]
a0- = Left
a0+ = Right
a1- = Up
a1+ = Down
b0 = SPACE
b1 = ESC

[joykeys:bellchaos]
a0- = Left
a0+ = Right
a1- = Up
a1+ = Down
b0 = Z
b1 = X
b2 = ESC

Config User-Interface

These two levels of mapping might make for a somewhat confusing user interface for joystick configuration. That is probably somewhat unavoidable. Here are a few thoughts about how to make config less painful.

I would like it if the button mapping user-interface was snes-centric. It could encourage players to map their buttons in an order resembling snes controllers.

However we also want an XBox-compatible UI layout (see inputtest.rpg), since the large majority of gamepads look like this.