Skip to content

Conversation

@riccardobl
Copy link
Member

@riccardobl riccardobl commented Jan 12, 2026

This PR aims to make gamepads reliable in jME on the lwjgl3 backend by upgrading GlfwJoystickInput to use GLFWGamepadState and by providing a new improved joystick input handler based on SDL.

tl;dr

Once this PR is merged, with all the joystick related AppSettings to their default, and DisableJoysticks=false:

  • most gamepads will just work as expected, no remapping or tweaking needed
  • every gamepad will look like an XBOX controller, so the dev always deal with a known layout
  • rumble will work
  • unrecognized gamepads won't be enabled at all unless it is added to the SDL_GameControllerDB (that can be shipped with the app), so they won't cause all the glitches that prompted us to to set DisableJoysticks to true by default
  • button.getName() will return a name that can be relied on to display ui hints (eg. A on xbox, vs CROSS on playstation)

Needs: #2581

In detail

This PR adds a few gamepad specific settings to AppSettings, most importantly JoysticksMapper, which can be used to choose between the following input handling behavior:

JOYSTICKS_LEGACY_MAPPER

This maintains the current half-broken jme behavior. Since there was community effort in building remapping for jme, this can be a good option to not break legacy code, but since it is very unpredictable, i would discourage it.

JOYSTICKS_XBOX_LEGACY_MAPPER (fixed but more compatible)

With this, the GlfwJoystickInput uses GLFWGamepadState to rebind gamepads to an Xbox-like layout automatically, if the gamepad is not known, it will fallback to use the jme own remapper.

GLFWGamepadState supports a lot of gamepads and platform specific quirks, but most of the rest of the behavior of the input handler is left untouched, this is a good option to get improved mappings without breaking code that depends on GlfwJoystickInput behavior or internals.

Rumble doesn't work since GLFW does not support it atm.

JOYSTICKS_XBOX_MAPPER (new input handler, best and recommended) (default)

This is a new input handler that is used by default, it is more solid than GlfwJoystickInput, and it is based on SDL (now available in lwjgl 3.4).

This has several improvements over the glfw implementation, including:

  • Rumble support
  • Meaningful button naming (eg. will use A,B,X,Y or CROSS,CIRCLE,SQUARE,TRIANGLE depending on whether the controller uses Xbox or PS conventions), while still being logically mapped to Xbox layout

If the gamepad is not recognized by SDL, it will be disabled, so the dev doesn't have to deal with it in the application.

All the new apps, and likely 99% of old apps, should be able to use this one with no issue.

JOYSTICKS_RAW_MAPPER (bring your own mapper)

This just returns the raw inputs, as seen by sdl. It should be used only if the application provides its own mapper, but it is otherwise not useful.

JOYSTICKS_XBOX_WITH_FALLBACK_MAPPER (bring your own mapper for incompatible gamepads)

Same of JOYSTICKS_XBOX_MAPPER but will fallback to JOYSTICKS_RAW_MAPPER for unrecognized gamepads.

Aliases

No more guessing what BUTTON_0 is etc.., JoystickButton and JoystickAxis have now BUTTON_XBOX_* and AXIS_XBOX_* aliases that makes binding a lot more intuitive.

Custom SDL_GameControllerDB

The app can ship a custom game controller db (eg from https://github.com/mdqinc/SDL_GameControllerDB ) by setting the AppSetting SDLGameControllerDBResourcePath (nb. it needs to be a path in the classpath).
This can be used to extend the list of supported gamepads.

If SDLGameControllerDBResourcePath is null or an empty string, whatever is bundled with glfw or SDL will be used instead.

@riccardobl riccardobl changed the title Fix gamepad weirdness by mapping them to Xbox-like layout Fix gamepad weirdness by remapping to Xbox-like layout Jan 12, 2026
@riccardobl riccardobl changed the title Fix gamepad weirdness by remapping to Xbox-like layout Fix gamepads weirdness by remapping to Xbox-like layout Jan 12, 2026
@riccardobl riccardobl added enhancement defect Something that is supposed to work, but doesn't. Less severe than a "bug" labels Jan 12, 2026
addButton( JoystickButton.BUTTON_XBOX_DPAD_UP, 96, 512 - 174, 40, 38 );
addButton( JoystickButton.BUTTON_XBOX_DPAD_RIGHT, 128, 512 - 208, 40, 38 );
addButton( JoystickButton.BUTTON_XBOX_DPAD_DOWN, 96, 512 - 239, 40, 38 );
addButton( JoystickButton.BUTTON_XBOX_DPAD_LEFT, 65, 512 - 208, 40, 38 );
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

binding dpad buttons is more intuitive, however the POV axis is still supported

@riccardobl riccardobl changed the title Fix gamepads weirdness by remapping to Xbox-like layout Fix gamepads weirdness by remapping to Xbox-like layout in lwjgl3 backend Jan 12, 2026
@yaRnMcDonuts yaRnMcDonuts added this to the v3.10.0 milestone Jan 20, 2026
@riccardobl riccardobl marked this pull request as draft January 22, 2026 14:06
@github-actions
Copy link

🖼️ Screenshot tests have failed.

The purpose of these tests is to ensure that changes introduced in this PR don't break visual features. They are visual unit tests.

📄 Where to find the report:

  • Go to the (failed run) > Summary > Artifacts > screenshot-test-report
  • Download the zip and open jme3-screenshot-tests/build/reports/ScreenshotDiffReport.html

⚠️ If you didn't expect to change anything visual:
Fix your changes so the screenshot tests pass.

If you did mean to change things:
Review the replacement images in jme3-screenshot-tests/build/changed-images to make sure they really are improvements and then replace and commit the replacement images at jme3-screenshot-tests/src/test/resources.

If you are creating entirely new tests:
Find the new images in jme3-screenshot-tests/build/changed-images and commit the new images at jme3-screenshot-tests/src/test/resources.

Note; it is very important that the committed reference images are created on the build pipeline, locally created images are not reliable. Similarly tests will fail locally but you can look at the report to check they are "visually similar".

See https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-screenshot-tests/README.md for more information

Contact @richardTingle (aka richtea) for guidance if required

@riccardobl riccardobl changed the title Fix gamepads weirdness by remapping to Xbox-like layout in lwjgl3 backend Fix gamepads with Xbox-like remapping and SDL lwjgl3 backend Jan 24, 2026
@riccardobl riccardobl changed the base branch from master to yaRnMcDonuts-patch-2 January 24, 2026 13:05
@riccardobl riccardobl marked this pull request as ready for review January 24, 2026 13:09
@riccardobl riccardobl changed the title Fix gamepads with Xbox-like remapping and SDL lwjgl3 backend Fix gamepads with Xbox-like remapping and SDL in lwjgl3 backend Jan 24, 2026
@riccardobl
Copy link
Member Author

Note: merge #2581 first, and then rebase this on master

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

defect Something that is supposed to work, but doesn't. Less severe than a "bug" enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants