Add a controller equivalent of Key/Physical Key split in Input Map

[poyribn]

Describe the project you are working on

A game with controller support

Describe the problem or limitation you are having in your project

I want to support controllers in my game, but it's unneededly complicated because Godot considers these buttons the same button:

Godot	PlayStation	XBox	Nintendo
0	Cross	A	B
1	Circle	B	A
2	Square	X	Y
3	Triangle	Y	X

On both the XBox and Nintendo controllers, the (A) button is normally used as the Accept button and (B) is used for going Back.
But since the buttons are swapped between each controller, the buttons will be correct only on Nintendo or XBox but swapped on the other brand.

This gets even worse with the PlayStation controller, where the button placement is the same worldwide but the buttons are used differently in Japan:

PlayStation	Japan	America & Europa
Cross	Back	Accept
Circle	Accept	Back

(this difference is cultural:
In America and Europe we have the saying 'X marks the spot', which made (Cross) into the Accept button.
But in Japan they use their own versions of our ✅Checkmark and ❎Cross symbols:
they have ⭕Circle instead of ✅Checkmark and ❌Cross instead of ❎Cross, which determined their use of these buttons).

With a big amount of time and effort you can make sure to correctly support all these variations, but most people are lazy like me so they'll just prioritise one controller and accept that the button mapping will be wrong on the other controllers.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

To solve this problem, i propose a split between Physical and Logical Buttons in the Input Map, similar to how it is already done for Keyboard Keys.

Right now we only have Physical Buttons, which is problematic as described above, so we should add Logical Buttons:

0	Accept
1	Back
2
3

This solves the problem of inconsistent menu navigation between controllers without locking out the possibility of using these face buttons like a second D-Pad for certain types of games.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

In the Input Map's "Plus Button" dropdown, the option "Controller Button" should be renamed to "Physical Controller Button",
so that the new option could be named just "Controller Button".

This new option works as described in the previous section.

If this enhancement will not be used often, can it be worked around with a few lines of script?

This can be wored around with a Lot of lines of code
and buying all the controllers to be able to test that code.
I cannot do that even if i wanted since i have only Nintendo controllers in my household and buying the rest is too expensive right now.

Putting a feature this important in your game shouldn't be this complicated.

Is there a reason why this should be core and not an add-on in the asset library?

This feature is so impotrant for the players that it should be core.
This is basic accessibility which even normal players need.

[Mickeon]

I agree on the problem but I'm not sure about the means, especially if all the necessary Logical Buttons tend to be only two (Accept & Back).

Could there be a way to incorporate this in the already existing JoystickList constants, as JOY_ACCEPT and JOY_BACK? With an inner system similar to KEY_MASK_CMD, but would have to be compared at run-time for the current input device.

[miv391]

I copied here at the bottom of this comment my first proposal I wrote to a closed thread with the same topic as this. There is however at least one problem with that proposal. Currently the input map shows a description of a button, e.g. "DualShock Cross, Xbox A, Nintendo B". I don't how this text could be correctly handled in my proposal. Except of using logical buttons just like Sosasees proposes. Still I think that the game programmer and the players should be given the option to ignore manufacturer specific conventions. So I have a second proposal.

Second proposal

Add logical buttons like Sosasees proposes.

However, there is no one always correct way to handle the Accept/Back buttons. Examples:

• A Nintendo Switch version of a game is made. The game programmer wants to handle all controllers as if they are Nintendo controllers.
• A player, who mostly plays with Nintendo, is playing a PC game at friend's place and is using a PS5 controller. The player would like to use Nintendo style Accept/Back buttons without caring what button labels the controller has.
• A player uses her Nintendo Switch controller with a Godot game and expects Accept/Back buttons to work as she is used to.

So I suggest both global and controller device specific settings for how the Accept/Back buttons work. Then it is up to the game programmer to decide how to use those settings and what options are given to the player.

# Global setting
enum GlobalControllerScheme {ControllerNative, NintendoStyle, XboxStyle}

Input.set_global_joy_logical_button_scheme(global_scheme)

The schemes are:

• ControllerNative
  • Logical Accept/Back buttons depend on controller manufacturer. Nintendo controller's right button (A) is Accept, Xbox controller's bottom button (A) is Accept and so on.
  • This could be the best option for default scheme.
• NintendoStyle
  • Right button is always Accept and bottom button is always Back. Controller manufacturer has no effect.
• XboxStyle
  • Bottom button is always Accept and right button is always Back. Controller manufacturer has no effect.

The global setting would be useful when making a port to some specific system, for example to a Nintendo Switch or localizing a game to Japan.

# Device specific setting
enum ControllerScheme {GlobalScheme, ControllerNative, NintendoStyle, XboxStyle}

Input.set_joy_logical_button_scheme(device: int, scheme)

Device specific setting would be useful when a player wants to configure how the controller works without caring about the controller manufacturer. GlobalScheme means that the global scheme is used and no device specific overrides are made.

First proposal

I suggest adding a feature that allows swapping controller buttons 0 and 1 and adding the following methods to Input:

# enable/disable automatic swapping
Input.use_automatic_joy_ok_cancel_swapping(automatic_swap: boolean)

# enable/disable swapping for specific controller
Input.swap_joy_ok_cancel(device: int, swap: boolean)
boolean Input.is_joy_ok_cancel_swapped(device: int) -> boolean

If the controller is detected to be a Nintendo controller, buttons 0 and 1 would be swapped automatically. This automatic action could also be disabled. Then if the player is using a Nintendo Controller, Ok (A) and Cancel (B) would work like usual with that controller (assuming that the player usually plays Nintendo games).

Now the programmer would have the following options:

• Use automatic swapping. Nintendo controllers would work like they usually work with Nintendo's games.
  • If the game is localized to Japan, the programmer could also swap PS controller buttons.
• Do not use automatic swapping. All controllers are equal, only the button location is important, not the button label or controller manufacturer.
  • For example the game uses ABXY buttons for moving instead of making UI selections.
• Give the player an option to explicitly swap / not swap the buttons.
  • For example an Xbox owner is playing at friend's place using friend's Nintendo Pro controller and just wants the controller to work like an Xbox controller.

I also suggest that the Input.get_joy_name() would be changed to return more easily processed data if technically possible. Currently game programmer needs to have all possible game controllers to know what strings this method can return and then doing string parsing to figure out if the controller is for example Nintendo's controller. Maybe Input.get_joy_name cound return a dictionary like this:

{"family": "Nintendo", "type": "Nintendo Pro Controller"}

The few controller families could be listed in the documentation and I guees that most often the game programmer would not need to care about the exact controller type.

[poyribn]

@miv391 thanks, this seems like a way better proposal than what i originally had: the same goal but executed much better.
i have just come up with an incremental improvement for it:

a game could be designed to have 2 buttons be pressable with the same thumb (e.g. many Parkour games are designed to have the Run Button be pressable with the same thumb as the Jump Button). To make this kind of control scheme easily possible on all controller types, it should be possible to swap the buttons on the XY row as well, so that we can make sure that the Run Button would always be upper-left next to the Jump Button.

[miv391]

I think in this case the game programmer should use the physical buttons just as they already work. The right button seems to always be index 1 and the top button is index 3. (I only have a Nintendo Pro Controller and an old Xbox controller so I can't be 100% sure...) So in this case the jump button would be button 1 (B in Xbox and A in Nintendo) and the run button would be button 3 (Y in Xbox and X in Nintendo).

[Meorge]

With godotengine/godot#112680, the joypad type (Xbox, PlayStation, Nintendo, etc) will be able to be queried. Perhaps to handle the discrepancy between accept and cancel for Nintendo and other platforms, events in the input map could have a specific scheme (or set of schemes) associated with them, similarly to how a specific device index can be specified?

[Nintorch]

See also godotengine/godot#103744

[poyribn]

Oh wow, that's a 3‑years‑old proposal, that i wouldn't make today because back then, i haven't decided my house style for how face buttons should be mapped for menu navigation in my games:

	jump to top menu
jump to left menu		Accept/ Forward
	Cancel/ Back

※ This mapping is based on a mix of ergonomics and directional metaphors, and is written at the bottom of the game screen, in a strip that's usually named "status bar" in desktop apps.

※ The use of the face buttons for menu navigation may change per context but i believe the meanings i have written above are good defaults unless playtesting proves otherwise.

But please don't think it means i now dismiss the importance of this proposal.
While i — the original submitter of this proposal — no longer need it implemented, i know many other devs would still like to follow platform conventions for the connected controller (not a house style which ignores button labels and uses directional metaphors instead).

[poyribn]

API designs that work well for one input method may not work well for other input methods, and this is no exception.

There are so many valid ways that a game designer could reconcile the differences in vendor‑specific face button layouts, that accounting for all of them in the API could easily be over‑engineered.

Unlike for keyboards on which the whole layout is different in each language, major differences in gamepad layout that devs may want to treat differently are only on the face buttons.

This means that these functions are enough for devs to reconcile the differences in gamepad layout:

• Get input for both all 4 physical face buttons (Up, Right, Down, Left) and the 2 logical face buttons (Accept, Cancel)
  [❌ Partially implemented: Only physical layout]
• Query the vendor which invented this face buttons layout:
  Microsoft / Nintendo / Sony /
  Blank (if face buttons are unlabelled)
  [⭕ Implemented, except for the Blank layout which i suspect doesn't exist on any real controller]
• Query the locale to choose the Japanese or Western Sony layout.
  Though today, this is only useful to create a deliberately old‑school control scheme because since the PlayStation 5, Sony mandates its Western gamepad layout worldwide.
  [⭕ Implemented]
• A Godot documentation page about reconciling differences in vendor‑specific face buttons layout, which lists all supported layouts (Microsoft, Nintendo, Sony, Blank) and shows the differences between them
  [❌ Not written]

We don't need the ability to query inputs for a complete physical gamepad layout and logical gamepad layout separately. We just need to add the 2 logical buttons (Accept, Cancel) to the existing physical gamepad layout for input queries, as that is the only place where the physical and logical gamepad layout may not be the same.