Controller button mapping on a Mac: what to know

You press a button on a controller, but the game responds as if you pressed something else. Or the game shows labels that do not match the letters printed on your controller. On a Mac, the browser, macOS, and the game can each describe controller inputs differently.

Test the controller outside the game first. The Gamepad Test shows whether button presses, sticks, and triggers register, helping you tell a controller connection problem from a game-specific mapping issue.

Check what each press registers as

1. Connect the controller to your Mac with a USB cable, or pair it in System Settings › Bluetooth.
2. Open the Gamepad Test in your browser. Press a controller button or move a stick so the browser can detect the controller.
3. Press one control at a time. Check the test for a matching button response, and move each stick and trigger to see whether those inputs change too.
4. Write down which test response follows each physical button. Then open the game’s controller settings and compare its actions with your notes.

Test each press separately at first. Holding several buttons together can make it harder to tell which input caused a response. If more than one controller is connected, disconnect the extra one while you test.

What the result means

Each press produces a clear response

The Mac and browser are receiving input from the controller. If a game still assigns the wrong action, the problem is likely in that game’s control settings or controller profile, not a dead button.

A response appears, but its label seems unfamiliar

Labels are not always the same as the symbols printed on a controller. A browser may identify a button by its position or by a standard button number. Meanwhile, a game may display its own labels or use a different controller layout. Compare the physical position and the response, not only the letter or number shown.

A button press produces no response

The controller may not be connected properly, the browser may not recognize its layout, or the button may have a fault. Reconnect it and test again. If the same button fails in multiple games and browsers, that points more strongly to the controller itself.

The test works, but the game does not

The controller is sending input, but the game may not support that controller, may have selected another input device, or may have saved a custom layout. Check the game’s controller settings before changing macOS settings.

How to fix a mapping problem

1. Check the game’s control settings. Open its controller or input menu and look for a layout, button assignment, or reset option. Choose the intended layout, or restore the default assignments, then test the controls in the game.
2. Check the controller in macOS. Open System Settings › Game Controllers if it appears. Select the controller to review available options. The settings shown depend on the controller and macOS version, and not every controller offers remapping there.
3. Reconnect the controller. For Bluetooth, open System Settings › Bluetooth, disconnect the controller, and pair it again. For USB, unplug it and reconnect it directly to the Mac rather than through a hub.
4. Quit apps that may be using the controller. Close other games, controller configuration apps, or browser tabs that could be responding to the same input. Reopen only the game you want to test.
5. Restart the game and browser. A game may keep an old controller profile after you reconnect or change settings. Quit it fully, reconnect the controller, and check the mapping again.
6. Test another browser or game. If the input works elsewhere, focus on the first game’s support or configuration. For more general steps when assignments appear wrong, see Controller buttons mapped wrong? What to do.

Why controller labels can differ

There is no single label set that every controller, browser, and game must show. A browser can report a standard layout when it recognizes a controller, but another controller may provide inputs in a layout the browser or game does not interpret the same way. The test helps you observe what the browser receives. It does not change the controller’s firmware or force every game to use the same assignments.

Also distinguish a button’s physical location from its printed symbol. Controllers from different families may put familiar symbols in different places. A game that displays one family’s labels can therefore look confusing even when the physical input works correctly.

When the controller may be faulty

If one button fails in the Gamepad Test, disconnect and reconnect the controller, then repeat the test. Try another browser or another device if possible. If the same physical button still does not register, while the other buttons do, the switch or controller hardware may be damaged. Check warranty coverage or arrange a repair or replacement.

Use the test to confirm which physical control responds, then make the final assignment in the game you plan to play.