Introduce new joypad features provided by SDL3 (WIP)

[Nintorch]

Partially based on #88590

Closes godotengine/godot-proposals#2829
Closes godotengine/godot-proposals#8519
Closes godotengine/godot-proposals#6930
Closes godotengine/godot-proposals#3799
Potentially closes #98008

Supersedes #88590
Supersedes #89193

Since SDL joypad driver was merged recently ( #106218 ), this PR adds support for new SDL joypad features that weren't previously possible due to older custom joypad implementations. These features include accelerometer, gyroscope, LED lights, touchpads and more.

The features that need to be done before this PR is ready for review/merge, i.e. the roadmap:

• Accelerometer/gyroscope enabling and getting
• SDL_GamepadHasSensor
• SDL_SetGamepadLED
• SDL_GetGamepadStringForAxis and SDL_GetGamepadStringForButton
• Input.get_joy_model() (because JoyType enum already exists) and Input.get_joy_scheme() (see SDL_GetGamepadType)
• SDL_GetGamepadPowerInfo
• SDL_GetGamepadSensorDataRate
• SDL_GetGamepadConnectionState
• SDL_JoystickType
• SDL_GetNumJoystickButtons, SDL_GetNumJoystickAxes
• SDL_GetJoystickVendor, SDL_GetJoystickProduct for Input.get_joy_info() (see Get joypad's vendor ID, product ID and name on Windows for XInput devices. #98861 ) Moved to Fix Input.get_joy_info() regression after the SDL input driver PR #108214
• Touchpad functions
• Dualsense adaptive triggers (see Any plans on Dualsense adaptive trigger support? libsdl-org/SDL#5125 and Xbox One Trigger Impulse via the Widnows Runtime API libsdl-org/SDL#4859 (comment) )
• • https://github.com/ValveSoftware/Proton/blob/ea07c02886cd1b1527761fb2222538fb9a92af33/lsteamclient/steamworks_sdk_157/isteamdualsense.h
• • I can't test it myself, because I don't have a Dualsense
• Xbox rumble triggers support
• Make sure Joycons work properly, including accelerometer and gyroscope
• Separate JoyScheme entry for horizontal joycons and fix the names for face buttons
• Accelerometer/gyroscope calibration methods (Input.start_joy_motion_calibration(), Input.step_joy_motion_calibration(), Input.stop_joy_motion_calibration(), Input.clear_joy_motion_calibration())
• SDL_SetJoystickPlayerIndex to set the physical joypad's player indication (LED light count for Switch and Wii controllers, LED color for PlayStation, no action for other controllers) Didn't work for my joycon controllers and my Dualshock 4, even though the method returned true
• Make all of the code thread safe, if it's not already (see bruvzg's PR)
• Input.get/set_joy_motion_calibration() to save/load calibration settings, uses Dictionary to do that
• Warn the user on Input.stop_joy_motion_calibration() if there are no/not enough calibration steps
• Input.get_joy_model_axis/button_name()
• Linux support
• macOS support
• Add new files to the SDL update script
• Update the example project below
• Documentation with examples
• • Documentation for joypad device types (SDL_JoystickType): https://learn.microsoft.com/en-us/windows/win32/xinput/xinput-and-controller-subtypes
• • Input.get_joy_info() fields
• • Sensor documentation: https://wiki.libsdl.org/SDL3/SDL_SensorType (BTW Horizontal joycons' yaw and roll axes are swapped, needs to be reported to SDL github) Just checked again, they're not
• • How accelerometer's gravity is calculated: https://developer.android.com/reference/android/hardware/SensorEvent#values
• • Mention that people will need some sort of driver for Xbox trigger rumble to work, there's an SDL github issue where that's described

TODO when Godot starts supporting SDL for other platforms:

• Android support
• iOS support
• Web support?

TODO for separate PRs:

• Rework Godot's hat functionality (at the moment it only supports 1 hat) (also see Hats on HOTAS are mapped as d-pad #83322 and HOTAS Problem (some axes and buttons not recognized) and godot closing on remove joy mapping (Thrustmaster TWCS Trottle) #65330 ), SDL_GetNumJoystickHats
• Input.get_pov_hat_vector() (see Add InputEventJoypadHat godot-proposals#9850 )
• SDL_GetJoystickBall, SDL_GetNumJoystickBalls
• Hat (see Add InputEventJoypadHat godot-proposals#9850 ) and ball events
• Add new hat and ball functionality to InputMap
• Proper Joycon support?
• Fix potential memory leak in Input.get_joy_name()
• Replace InputEvent classes boilerplate code with something more simple
• Godot events for accelerometer/gyroscope (InputEventJoypadAccelerometer, InputEventJoypadGyroscope) Sensor events don't exist for mobile devices, so I don't think they should exist for joypads
• Touchpad events
• Battery/power events That's not something the player can control, so no need to add these events

Features that need to be discussed whether they should be implemented or not:

• SDL_GetJoystickSerial
• SDL_GetJoystickFirmwareVersion
• SDL_GetGamepadPath
• SDL_GetGamepadSteamHandle (for https://godotsteam.com/classes/input/ ?) Handled by Fix Input.get_joy_info() regression after the SDL input driver PR #108214
• Input.send_joy_packet() SDL_SendJoystickEffect

Here's a small project to test new joypad features (in case someone might build this WIP PR from scratch) :
JoypadTest.zip

(P.S. I opened this PR so early, because I want to let people know that this is being worked on and that I'm working on it :D)

[Calinou]

Supersedes #88590

Note that #88590 also implements DualSense adaptive triggers, which isn't on the roadmap of this PR currently. This could be done in a separate PR in any case, but I thought I'd mention it as SDL supports adaptive triggers.

[Nintorch]

Supersedes #88590

Note that #88590 also implements DualSense adaptive triggers, which isn't on the roadmap of this PR currently. This could be done in a separate PR in any case, but I thought I'd mention it as SDL supports adaptive triggers.

Good catch, thank you, I'll add that to the roadmap!

[Meorge]

I'm especially excited to see Joy-Con support listed here. I think those are really fun little controllers, so much so that I started making my own C++ library for interfacing with them and a Godot GDExtension based off of that - however, obviously being a GDExtension, it doesn't mesh very well with Godot's built-in APIs. Having the support be more built-in to the engine would be awesome!

I'm not sure how much overlap there is between SDL's Joy-Con support and what my library does, but if a lot of the Joy-Con-specific features don't have SDL APIs, I may be able to help on that front 😄

[Nintorch]

I made a list of features that need discussion before implementing, so if you think any of the listed features are important to have built into the engine, you can let me know!

[mubinulhaque]

Feature request for a separate PR: querying for separate keyboards and mice (SDL_GetKeyboards and SDL_GetMice respectively)

[Calinou]

Feature request for a separate PR: querying for separate keyboards and mice (SDL_GetKeyboards and SDL_GetMice respectively)

Multi-keyboard/mouse support seems subpar in SDL 3 from what I've heard, so it may not be worth the effort. This is based on what I've seen in the Perfect Dark PC port Discord (people have tried implementing it there, but quickly regretted it).

[LunaCapra]

Will the gamepad type for GameCube controllers be included? It seems to be the only one not added from SDL_GamepadType.

[Meorge]

I'm still very excited for Joy-Con support and would love to contribute where I can, but thinking about it more, I think specialized support for its features would fit better as a separate PR (if not some kind of plugin/addon). 😅

Maintainers should have more of a say in this of course, but I could see it being helpful to split this up into multiple smaller PRs so that each individual one is easier to test and verify.

That all being said, for this PR (whether it ends up being split later or not) I can certainly test its functionality on macOS. Let me know if/when you'd like me to give that a shot! 😄

[Nintorch]

Will the gamepad type for GameCube controllers be included? It seems to be the only one not added from SDL_GamepadType.

Godot is currently using the latest stable release of SDL (3.2.16), which doesn't support GameCube controllers :( https://github.com/libsdl-org/SDL/blob/c9a6709bd21750f1ad9597be21abace78c6378c9/include/SDL3/SDL_gamepad.h

[LunaCapra]

Will the gamepad type for GameCube controllers be included? It seems to be the only one not added from SDL_GamepadType.

Godot is currently using the latest stable release of SDL (3.2.16), which doesn't support GameCube controllers :( https://github.com/libsdl-org/SDL/blob/c9a6709bd21750f1ad9597be21abace78c6378c9/include/SDL3/SDL_gamepad.h

That's a shame. Maybe in the future then!

[Meorge]

I know this is still marked as a draft, so these may be things you're aware of and are planning on fixing, but just in case: I got excited and decided to pull it to test on macOS, and ran into some compilation errors.

In joypad_sdl.cpp, a few switch statements don't have default cases or otherwise handle all of the possible values:

drivers/sdl/joypad_sdl.cpp:335:10: error: enumeration values 'INVALID', 'SDL_MAX', and 'MAX' not handled in switch [-Werror,-Wswitch]
  335 |         switch (p_axis) {
      |                 ^~~~~~
drivers/sdl/joypad_sdl.cpp:335:10: note: add missing switch cases
  335 |         switch (p_axis) {
      |                 ^
  336 |                 case JoyAxis::LEFT_X:
drivers/sdl/joypad_sdl.cpp:451:10: error: enumeration values 'INVALID', 'SDL_MAX', and 'MAX' not handled in switch [-Werror,-Wswitch]
  451 |         switch (p_button) {
      |                 ^~~~~~~~
drivers/sdl/joypad_sdl.cpp:451:10: note: add missing switch cases
  451 |         switch (p_button) {
      |                 ^
  452 |                 case JoyButton::A:
2 errors generated.

If I add default cases to those switch statements, I get errors about the parameters in ScePadTriggerEffectParam not all being initialized:

[ 74%] In file included from core/input/.scu/scu_core_input.gen.cpp:1:
./core/input/input.cpp:1224:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
 1224 |         SETUP_TRIGGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MODE_OFF);
      |         ^
./core/input/input.cpp:1213:40: note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                                                \
      |                                               ^
[ 74%] ./core/input/input.cpp:1236:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
 1236 |         SETUP_TRIGGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MODE_FEEDBACK);
      |         ^
./core/input/input.cpp:1213:40: note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                                                \
[ 74%]                                               ^
./core/input/input.cpp:1257:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
 1257 |         SETUP_TRIGGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MODE_WEAPON);
      |         ^
./core/input/input.cpp:1213:40: note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                                                \
      |                                               ^
[ 74%] ./core/input/input.cpp:1279:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
 1279 |         SETUP_TRIGGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MODE_VIBRATION);
      |         ^
./core/input/input.cpp:1213:40: note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                   [ 74%]                        \
      |                                               ^
[ 74%] ./core/input/input.cpp:1291:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
 1291 |         SETUP_TRIGGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MODE_MULTIPLE_POSITION_FEEDBACK);
      |         ^
[ 74%]  note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                                                \
      |                                               ^
./core/input/input.cpp:1320:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
[ 74%] E_SLOPE_FEEDBACK);GGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MOD
      |         ^
./core/input/input.cpp:1213:40: note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                                                \
      |                                               ^
[ 74%] ./core/input/input.cpp:1337:2: error: missing field 'padding' initializer [-Werror,-Wmissing-field-initializers]
 1337 |         SETUP_TRIGGER_EFFECT(SCE_PAD_TRIGGER_EFFECT_MODE_MULTIPLE_POSITION_VIBRATION);
      |         ^
./core/input/input.cpp:1213:40: note: expanded from macro 'SETUP_TRIGGER_EFFECT'
 1213 |         ScePadTriggerEffectParam effect = { 0 };                                                                                                \
      |                                               ^
[ 77%] 7 errors generated.

[Nintorch]

I haven't tried to compile on macOS yet, but I think I fixed these 2 errors, I hope it should now compile!

[Meorge]

Thanks! It compiles now, but unfortunately I get a segmentation fault immediately upon starting Godot... I may be able to look further into that soon

---

LLDB is giving this output for the location of the segfault:

Godot Engine v4.5.beta.custom_build.3a143d442 (2025-07-02 18:50:15 UTC) - https://godotengine.org
Process 33797 stopped
* thread #1, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=2, address=0x16f5ffff8)
    frame #0: 0x000000010307d4e0 godot.macos.editor.dev.arm64`dlmalloc(bytes=80) at SDL_malloc.c:4615:52
   4612     if (bytes <= MAX_SMALL_REQUEST) {
   4613       bindex_t idx;
   4614       binmap_t smallbits;
-> 4615       nb = (bytes < MIN_REQUEST)? MIN_CHUNK_SIZE : pad_request(bytes);
   4616       idx = small_index(nb);
   4617       smallbits = gm->smallmap >> idx;
   4618
Target 0: (godot.macos.editor.dev.arm64) stopped.

The backtrace seems to give an infinite loop?

(lldb) bt
  * thread #1, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=2, address=0x16f5ffff8)
  * frame #0: 0x000000010307d4e0 godot.macos.editor.dev.arm64`dlmalloc(bytes=80) at SDL_malloc.c:4615:52
    frame #1: 0x0000000103081e94 godot.macos.editor.dev.arm64`dlcalloc(n_elements=1, elem_size=80) at SDL_malloc.c:4837:9
    frame #2: 0x0000000103084554 godot.macos.editor.dev.arm64`SDL_calloc(nmemb=1, size=80) at SDL_malloc.c:6471:11
    frame #3: 0x00000001030a14e0 godot.macos.editor.dev.arm64`SDL_CreateMutex at SDL_sysmutex.c:34:26
    frame #4: 0x00000001030a1894 godot.macos.editor.dev.arm64`SDL_CreateSemaphore(initial_value=0) at SDL_syssem.c:75:23
    frame #5: 0x0000000103090bdc godot.macos.editor.dev.arm64`SDL_CreateCondition at SDL_syscond.c:58:21
    frame #6: 0x00000001030a18a0 godot.macos.editor.dev.arm64`SDL_CreateSemaphore(initial_value=0) at SDL_syssem.c:76:26
    frame #7: 0x0000000103090bdc godot.macos.editor.dev.arm64`SDL_CreateCondition at SDL_syscond.c:58:21
    frame #8: 0x00000001030a18a0 godot.macos.editor.dev.arm64`SDL_CreateSemaphore(initial_value=0) at SDL_syssem.c:76:26
    frame #9: 0x0000000103090bdc godot.macos.editor.dev.arm64`SDL_CreateCondition at SDL_syscond.c:58:21
    ...
    frame #1322: 0x00000001030a18a0 godot.macos.editor.dev.arm64`SDL_CreateSemaphore(initial_value=0) at SDL_syssem.c:76:26
    frame #1323: 0x0000000103090bdc godot.macos.editor.dev.arm64`SDL_CreateCondition at SDL_syscond.c:58:21
    frame #1324: 0x00000001030a18a0 godot.macos.editor.dev.arm64`SDL_CreateSemaphore(initial_value=0) at SDL_syssem.c:76:26
    frame #1325: 0x0000000103090bdc godot.macos.editor.dev.arm64`SDL_CreateCondition at SDL_syscond.c:58:21
    frame #1326: 0x00000001030a18a0 godot.macos.editor.dev.arm64`SDL_CreateSemaphore(initial_value=0) at SDL_syssem.c:76:26
    frame #1327: 0x0000000103090bdc godot.macos.editor.dev.arm64`SDL_CreateCondition at SDL_syscond.c:58:21
    ...

[Nintorch]

This PR should likely fix your issue: #107963
It happened to you because I haven't rebased this PR yet, I will do that once all features are ready!

EDIT: Decided to rebase now!

[Meorge]

Thanks for the rebase! With that, the editor is now building, and I'm able to run the demo project.

It looks like the instance of JoypadSDL being used by the game process doesn't receive the joystick/gamepad-added events, which causes the joypads to be registered as not attached, and thus the special methods to not work. Here's my console output with some print_line statements I added to track the state:

> godot --editor --path "/Users/malcolmanderson/Downloads/JoypadTest"
Godot Engine v4.5.beta.custom_build.898c22fd8 (2025-07-03 08:10:03 UTC) - https://godotengine.org
construct joypadsdl (FOR EDITOR)
Metal 3.2 - Forward+ - Using Device #0: Apple - Apple M4 Pro (Apple9)

joystick added event
get_sdl_joystick: p_pad_idx = 0, max is 16, attached = true
Event for joypad 0: 1619 (SDL_EVENT_GAMEPAD_ADDED)
Event for joypad 0: 1543 (SDL_EVENT_JOYSTICK_BATTERY_UPDATED)
[0]
DualSense Wireless Controller 050057564c050000e60c00001be36d04

(GAME STARTED)
Godot Engine v4.5.beta.custom_build.898c22fd8 (2025-07-03 08:10:03 UTC) - https://godotengine.org
construct joypadsdl
Metal 3.2 - Forward+ - Using Device #0: Apple - Apple M4 Pro (Apple9)

get_sdl_joystick: p_pad_idx = 0, max is 16, attached = false
ERROR: JoypadSDL::get_joypad_features: joy == nullptr
   at: get_joypad_features (drivers/sdl/joypad_sdl.cpp:584)
   GDScript backtrace (most recent call first):
       [0] _ready (res://test_2.gd:4)

Note that after GAME STARTED, a new JoypadSDL is constructed (print_line() in JoypadSDL::JoypadSDL() is run), but the SDL_EVENT_GAMEPAD_ADDED event is not caught by it, so it's not able to update its copy of the joypads array.

That's my hypothesis for what's going on at the moment, at least. I know you may still be working on putting together the core functionality for the PR, but please let me know if there's anything else I can test or results I can provide to help with the macOS support!

[Nintorch]

That's weird, because I haven't changed the "joystick added" event functionality in this PR, so it should work just fine. Do you have this bug if you test Godot 4.5 beta 2?

[Meorge]

If I run commit efb40c1 (the commit on which this PR appears to currently be based) and comment out most of the code in the test project's test_2.gd file:

No errors appear, and the gamepad does show up as connected:

With this PR's commit, I get the error again:

ERROR: JoypadSDL::get_joypad_features: joy == nullptr
   at: get_joypad_features (drivers/sdl/joypad_sdl.cpp:584)
   GDScript backtrace (most recent call first):
       [0] _ready (res://test_2.gd:4)

Note that it's including line 4 of test_2.gd in the backtrace, but it seems to actually be attempting to point to line 3, where _ready() is defined.

I'm expecting to be busy this weekend, so I don't know how much time I'll have for it the next few days, but soon after I should hopefully be able to dive deeper into it.

[Nintorch]

Let's hope I will encounter this bug on macOS myself so I can try to fix it 😅

[Meorge]

Indeed, that may well be more efficient 😅 But please don't hesitate to let me know if there are any specific tests or things you'd like me to take a look at, and I'll do so as soon as I can! I'm really looking forward to having this rich controller support 😄