fix: Correct inverted Android D-pad Up/Down (AXIS_HAT_Y double-inversion) - #128
Merged
spydon merged 1 commit intoAug 25, 2026
Conversation
GhagSagar23
changed the title
GhagSagar23
marked this pull request as ready for review
August 17, 2026 07:00
spydon
added a commit
that referenced
this pull request
Aug 25, 2026
…ick (#129) Follow-up to #128, which fixed the same double inversion for the d-pad hat axis but left the analog sticks inconsistent with it. Also closes the second symptom reported in #123. ## Stick Y axis was double inverted `gamepads_android`'s `EventListener` registers `AXIS_Y`, `AXIS_RZ` and `AXIS_RY` with `invert = true`, so a physical stick-up already arrives in Dart as `+1.0`. `AndroidMapping.normalizeAxis` negated it a second time: ```dart if (axis == GamepadAxis.leftStickY || axis == GamepadAxis.rightStickY) { return [NormalizedAxis(axis, -value)]; } ``` The result was `leftStickY = -1.0` for up on Android, while the same gesture gives `+1.0` on iOS, macOS and Web. That contradicts the convention documented on `GamepadAxis` and `PlatformMapping` ("Left/Down = -1, Right/Up = +1"), so cross-platform game code moved the player in opposite directions. After #128 the file also argued both ways: "EventListener already inverted it" for the hat axis, and the opposite three lines above for the sticks. ## RX/RY right stick events were dropped `EventListener` reports `AXIS_RX` and `AXIS_RY` (added in #111 for non-Xbox layouts such as the DJI RC Pro), but they were missing from `_axisMap`. Unmatched analog keys fall through to `normalizeDpadAxis`, which returns `const []` for anything that is not a hat axis, so those events were discarded. On a DJI RC Pro the right stick produced no normalized events at all. Both are mapped to `rightStickX`/`rightStickY`, the same aliasing pattern already used for `AXIS_BRAKE`/`AXIS_GAS`. ## Guarding the cross-package invariant `AndroidMapping`'s correctness depends on the `invert = true` flags staying in the separately versioned Kotlin plugin, and until now the only trace of that was a comment on the Dart side. `EventListener.kt` is the more obvious place for a contributor to "fix" against Android's documentation, and doing so would silently re-invert everything without a single test failing, since the tests only exercise the Dart half. Added a counterpart comment next to `supportedAxes` pointing back at the Dart mapping. `AXIS_WHEEL` is still reported by `EventListener` and still unmapped, since there is no matching `GamepadAxis`. It stays available through the raw event API. ## Changes - `packages/gamepads/lib/src/mappings/android_mapping.dart` - `packages/gamepads/lib/src/mappings/platform_mapping.dart`, the Y-axis contract no longer lists Android as a platform that must negate - `packages/gamepads_android/.../EventListener.kt`, comment only - `packages/gamepads/test/mappings_test.dart`, stick assertions corrected, new RX/RY test - `packages/gamepads/test/gamepad_normalizer_test.dart`, the `AXIS_Y` test asserted the buggy `-1.0` ## Verification `melos analyze` is clean, `dart format` reports no changes, and all 80 tests in `packages/gamepads` pass. Hardware confirmation on a physical Android device is still worth doing before release. https://claude.ai/code/session_019aEP4Np5vqDw5BkgGYyHe7
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #123.
On Android, pressing the D-pad Up emitted
GamepadButton.dpadDown(value 1.0), and Down emitteddpadUp. Root cause is a double inversion of the D-pad Y hat axis:gamepads_android'sEventListenerregistersAXIS_HAT_Ywithinvert = true(EventListener.kt:27), so the value delivered to Dart is already flipped to up = +1.0 / down = −1.0 — the opposite of Android's nativeAXIS_HAT_Y(up = −1.0 / down = +1.0).AndroidMapping.normalizeDpadAxisstill mapped per Android's native convention (value > 0 → dpadDown,value < 0 → dpadUp), so the two flips compounded.AXIS_HAT_Xis not inverted natively, so D-pad left/right were unaffected — matching the report.Change
Corrected the sign comparison in a single canonical location — the
AXIS_HAT_Ybranch ofAndroidMapping.normalizeDpadAxis— sodpadUpfires onvalue > 0anddpadDownonvalue < 0, with a comment citing #123.EventListener.ktis intentionally left unchanged to avoid re-introducing a double-inversion.packages/gamepads/lib/src/mappings/android_mapping.dartpackages/gamepads/test/mappings_test.dart— both-directionAXIS_HAT_YregressionFix-location decision (maintainer call welcome)
The reporter raised a genuine design choice for where to fix this:
EventListener.kt): drop theAXIS_HAT_Yinversion → raw/unnormalized values would then follow Android's1.0 == down.android_mapping.dart, this PR): keeps the library's existing1.0 == upraw convention.This PR takes option 2 to preserve the current raw-value convention (no breaking change) and because the mapping is pure Dart and directly unit-testable. Happy to switch to the Kotlin approach if you prefer — but the fix must live in exactly one place; applying it in both would double-invert and silently reintroduce the bug.
Tests
Added a both-direction regression to
AndroidMapping > "normalizes hat d-pad axes":AXIS_HAT_Y = +1.0(physical up) →dpadUp = 1.0,dpadDown = 0.0AXIS_HAT_Y = -1.0(physical down) →dpadDown = 1.0,dpadUp = 0.0This fails on the pre-fix code (which returned
dpadDown = 1.0for+1.0) and passes after the fix.Deferred
leftStickY/rightStickY): the reporter separately observed up reading-1.0. Left untouched here — confirm it's a genuine inversion vs. Android's native joystick convention before changing; tracked as a follow-up reusing this PR's convention decision.fix:PR title (CONTRIBUTING.md, "Creating a release").Coordination
Thanks @fescrb for the precise root-cause analysis. You'd offered to submit this — glad to defer to you or just help with review; sharing this as a ready-to-go option while the fix-location question is settled.