Skip to content

Mac controllers: a radial stick dead zone, value handlers off the main queue, and Nintendo face buttons by name - #382

Open
Unayung wants to merge 1 commit into
seedds:mainfrom
Unayung:mac-controller-deadzone-queue-names
Open

Unayung wants to merge 1 commit into
seedds:mainfrom
Unayung:mac-controller-deadzone-queue-names

Conversation

@Unayung

@Unayung Unayung commented Oct 27, 2026

Copy link
Copy Markdown
Contributor

Three general changes to the Mac front end's controller path. They were found while playing FINAL FANTASY RESONANCE and Super Mario Bros. Wonder on the Mac with a Switch Pro Controller, an 8BitDo SN30 Pro and a Steam Controller.

  • DM_PAD_STICK_DZ=<inner>[,<full>]: each stick reaches the game only past a radial dead zone <inner> (0 to 0.5). Its length is clamped to the unit circle and scaled so that a tilt of <full> already counts as full (pad_stick_shape in pad_slots.h). The problems it fixes:

    • GameController gives each axis up to ±1 on its own, so a diagonal reached the game longer than full tilt.
    • A worn stick resting a little off centre kept walking the character.
    • Some controllers' full tilt stops short of 1.0, so the game never saw a full run.

    Unset, the axes go as before. The farthest each left stick reaches is logged once per 0.05 from 0.5, which is how a player finds <full> for a controller (e.g. 0.10,0.9).

  • DM_PAD_QUEUE=1: the controllers' value handlers run on a serial queue of their own (handlerQueue), not the main queue, so AppKit work on the main thread (window and layer changes, menus, a resize) no longer holds controller input back. Connects, disconnects and focus changes stay on the main queue, so g_pad_mu now guards the slot table, the held controllers and their state.

  • Nintendo face buttons by name: a Nintendo controller (by product category or vendor name) whose four face buttons GameController names with the letters A, B, X and Y is mapped by those letters (pad_face_bit). A real Pro Controller came through with its own letters in GameController's positional buttons: its A, on the right, arrived as buttonA. So mapped by position, its A was the game's B. Other controllers, and a Nintendo controller without four distinct letters, stay mapped by position. The connect line says which.

Checked

  • tests/t_hid.c adds checks for the stick shaping (the dead zone, the clamp to the circle, <full>, a partial tilt, off) and the face-button mapping. make -C dm/host/tests GAME=0100606026F12000 run passes; t_hid gives 92 checks, 0 failed.
  • The Mac host builds (make -C dm/host GAME=0100606026F12000).
  • The Python tool tests pass, including test_env_switches.py: both switches are in docs/env_switches.tsv, written by dm/tools/env_switches.py.
  • regress.py impact: the change reaches every game through front_mac.m (present:*). pad_slots.h had no rule, so this adds one to dm/tools/impact_map.tsv.
  • On real controllers: the same code, with the same switches (DM_PAD_STICK_DZ=0.10,0.9 DM_PAD_QUEUE=1), has been in daily play in FINAL FANTASY RESONANCE and Super Mario Bros. Wonder builds based on 6034fca, with the three controllers above. This branch is that change ported to main. On main it is covered by the unit tests and a host build, not yet a long play session.
  • regress.py check could not run here: none of the games on this Mac has a smoke.tsv route (only Hades, Breath of the Wild and Tears of the Kingdom do). The chain does not change. Headless runs do not go through the window front end, so no smoke run would reach this code.

A follow-up question

The same play sessions used Pro Controllers read directly over IOKit HID (DM_PRO_HID), with HD rumble from the game's own values, because macOS's controller service overrides a shared device's rumble while a game is in front. Doing that means opening the controller seized, which takes it away from GameController, so the front end reads its input too. That conflicts with the route design haptics_apple.m just got for the DualShock 4 (#363). Would you take it as a separate PR, and in what shape?

🤖 Generated with Claude Code

https://claude.ai/code/session_018XsrnTnMEXD4jZMChLCZPK

…n queue, and Nintendo face buttons by name

Three general changes to the Mac front end's controller path, found while playing FINAL FANTASY RESONANCE and Super Mario Bros. Wonder with a Switch Pro Controller,
an 8BitDo SN30 Pro and a Steam Controller:

- DM_PAD_STICK_DZ=<inner>[,<full>]: each stick goes to the game past a radial dead zone <inner> (0 to 0.5), its length clamped to the unit circle and scaled so a tilt
  of <full> counts as full (pad_stick_shape in pad_slots.h). GameController gives each axis up to ±1 on its own, so a diagonal reached the game longer than full tilt;
  a worn stick resting a little off centre walked the character; and some controllers' full tilt stops short of 1.0, so the game never saw a full run. Unset, the axes go
  as before. The farthest each left stick reaches is logged once per 0.05 from 0.5, which is how a player finds <full> for a controller.
- DM_PAD_QUEUE=1: the controllers' value handlers run on a serial queue of their own (handlerQueue) instead of the main queue, so AppKit work on the main thread
  (window and layer changes, menus, a resize) does not hold controller input back. The slot table, the held controllers and their state are now guarded by g_pad_mu,
  since connects, disconnects and focus changes stay on the main queue.
- A Nintendo controller (by its product category or vendor name) whose four face buttons GameController names with the letters A, B, X and Y is mapped by those
  letters (pad_face_bit). A real Pro Controller came through with its own letters in GameController's positional buttons (its A, on the right, as buttonA), so mapped
  by position its A was the game's B. Other controllers, and a Nintendo one without four distinct letters, stay by position. The connect line says which.

tests/t_hid.c checks the stick shaping (dead zone, the clamp to the circle, <full>, a partial tilt, off) and the face-button mapping; docs/env_switches.tsv lists both
switches.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_018XsrnTnMEXD4jZMChLCZPK
@v0lumehi

Copy link
Copy Markdown
Contributor

Heads-up: #388 proposes treating controls as data that every UI writes (#388 (comment)): the key and button maps (#386's DM_KEYMAP / DM_PAD_MAP) in one per-game store, so a controls page in any launcher and an in-app panel never disagree. The dead zone and face-button-by-name work here is the engine side underneath and fits as it is. If any of it becomes a player choice, it would be a row in the shared schema.

v0lumehi added a commit to v0lumehi/NX2Apple that referenced this pull request Oct 27, 2026
…ntroller (LNPANDY#70)

The Controls page had only the per-button choice, so playing with an Xbox or a
Nintendo controller by its printed letters took four changes by hand. It now has
a layout, each one only a DM_PAD_MAP value (the host is unchanged):

- Standard layout, the default: nothing passed. The host reads the face buttons
  by position in the Nintendo layout (front_mac.m pad_read); for PlayStation and
  other controllers.
- By label: A=B,B=A,X=Y,Y=X. GameController reports both families by their
  letters: an Xbox controller's are Apple's diamond, and a real Pro Controller's
  A, on the right, arrives as buttonA (seedds/nxnative#382). The host's
  positional reading turns each into the other letter, so one swap serves both,
  and for a Nintendo controller it is also its position.
- Custom: the buttons chosen by hand. Changing a button switches to it, starting
  from what the buttons sent in the layout before.
- Auto: By label or Standard from GCController.productCategory of the controller
  connected at Play (Nintendo, Switch Pro, Joy-Con/JoyCon or Xbox in the name).
  The note says the limit: one map for every controller, so two kinds at once
  cannot both be right; a per-controller choice belongs in the host (LNPANDY#382).

The page shows the connected controller and what Auto picks for it, following
connects and disconnects. The layout is stored with the rest of the controls;
settings saved before it load as Custom when they had buttons set, else Standard.
A preset counts as one change in Settings.

The tests check each layout's DM_PAD_MAP, Auto's choice for stand-in categories,
an edit switching to Custom, old saved settings, and the swap played through the
host's reading for both families; a mutation of the swap fails them. swift build
-c release is clean, swift test passes (55, 3 skipped), and the visual QA renders
the page scrolled to the layout by the controller's focus, Auto with a stand-in
Xbox controller and By label with none. Not checked with a real controller.
LNPANDY pushed a commit to LNPANDY/NX2Apple that referenced this pull request Oct 27, 2026
…ntroller (#70)

The Controls page had only the per-button choice, so playing with an Xbox or a
Nintendo controller by its printed letters took four changes by hand. It now has
a layout, each one only a DM_PAD_MAP value (the host is unchanged):

- Standard layout, the default: nothing passed. The host reads the face buttons
  by position in the Nintendo layout (front_mac.m pad_read); for PlayStation and
  other controllers.
- By label: A=B,B=A,X=Y,Y=X. GameController reports both families by their
  letters: an Xbox controller's are Apple's diamond, and a real Pro Controller's
  A, on the right, arrives as buttonA (seedds/nxnative#382). The host's
  positional reading turns each into the other letter, so one swap serves both,
  and for a Nintendo controller it is also its position.
- Custom: the buttons chosen by hand. Changing a button switches to it, starting
  from what the buttons sent in the layout before.
- Auto: By label or Standard from GCController.productCategory of the controller
  connected at Play (Nintendo, Switch Pro, Joy-Con/JoyCon or Xbox in the name).
  The note says the limit: one map for every controller, so two kinds at once
  cannot both be right; a per-controller choice belongs in the host (#382).

The page shows the connected controller and what Auto picks for it, following
connects and disconnects. The layout is stored with the rest of the controls;
settings saved before it load as Custom when they had buttons set, else Standard.
A preset counts as one change in Settings.

The tests check each layout's DM_PAD_MAP, Auto's choice for stand-in categories,
an edit switching to Custom, old saved settings, and the swap played through the
host's reading for both families; a mutation of the swap fails them. swift build
-c release is clean, swift test passes (55, 3 skipped), and the visual QA renders
the page scrolled to the layout by the controller's focus, Auto with a stand-in
Xbox controller and By label with none. Not checked with a real controller.
@Serendipper

Copy link
Copy Markdown

Another data point for this path. It may matter for the DM_PRO_HID question.

A Pro-compatible pad over Bluetooth: GameController reports it as vendor Pro Controller, category Switch Pro Controller. Its buttons, D-pad and motion come through, but both thumbsticks stay at exactly 0. A standalone GameController probe with no game running logged every face button and 61 D-pad events, but no leftThumbstick / rightThumbstick events while both sticks were moved. In Pokémon Scarlet, the left stick couldn't pass character creation.

The raw 0x30 reports still carry the sticks. I read them through a non-exclusive IOHIDManager, the way motion_pro_mac.h reads motion:

  • they are 12-bit, at bytes 6–11;
  • the left stick covered the full 0–4095 range on both axes;
  • the values are exactly 2048 / 2047 at rest and exactly 0 / 4095 at full tilt.
0x30 L 4095,2170 R 2047,2047
0x30 L 2048,2048 R 3479,3784
0x30 L 2048,2048 R 2628,   0

The idealized values suggest a third-party pad, or calibration data macOS rejects, so GameController drops the sticks. A dead zone or queue change wouldn't help here, because no stick values reach the handlers at all.

What I did, without seizing the device: motion_pro_mac.h also decodes the sticks from the reports it already receives. pad_read takes them for that player only after the raw sticks pass half tilt while all four GameController axes are 0, and logs that once. A pad whose GameController sticks work never switches, and buttons and rumble stay on GameController. It's about 20 lines, in #470's second commit (105cfd9), together with #415's face-button mapping. Both sticks work in Scarlet with it.

The decode is uncalibrated, centred on 2048. That fits this pad but would be wrong for a genuine Pro Controller, which never takes this path. If your DM_PRO_HID route lands, it could cover this case too, using the pad's SPI calibration when it has valid data. I'm happy to move my change onto that or drop it.

Mac: Apple M4, macOS 27.0.1.

🤖 Generated with Claude Code

@github-actions github-actions Bot added host The Horizon host: SVCs, services, threads, memory (dm/host) mac The Mac front end and app (dm/mac, front_mac.m) tools Tools and scripts (dm/tools, scripts) docs Documentation labels Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation host The Horizon host: SVCs, services, threads, memory (dm/host) mac The Mac front end and app (dm/mac, front_mac.m) tools Tools and scripts (dm/tools, scripts)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants