Gamepad Controller Mapping & Test

Controller mapping is the process of translating a gamepad’s raw numbered inputs – “button 0,” “axis 2” – into named actions like A, B, or left stick, so the same physical press behaves consistently in every game, emulator, and browser. This page reads those raw signals live, lets you build a custom mapping profile, and exports it as JSON, CSV, an SDL string, or a RetroArch config.

What Is Controller Mapping, and Why Doesn’t “A” Always Mean “A”?

A controller doesn’t send button names to your computer. It sends numbers – “button 0 is pressed,” “axis 2 moved to 0.7.” Software then has to translate those numbers into something meaningful: button 0 becomes “A” on an Xbox pad, or “Cross” on a DualSense. That translation layer is controller mapping.

The reason it goes wrong is that the translation isn’t universal. Firmware revisions, the operating system’s driver, and the connection type (USB vs. Bluetooth) can each report the same physical button differently. A DualSense connected over USB-C and the same DualSense paired over Bluetooth can, in rare cases, expose slightly different report structures to the browser – which is why testers sometimes see inconsistent results between wired and wireless sessions on the same hardware. Getting mapping right matters for three practical reasons:

• Compatibility – games and emulators expect a consistent input scheme to interpret correctly.
• Accuracy – diagnosing a “broken” button is pointless if you’re actually reading the wrong input entirely.
• Accessibility – remapping lets players with limited mobility or reach move demanding inputs onto buttons they can comfortably use.

How the Browser Reads Your Controller: HID, the Gamepad API, and WebHID

Every browser-based mapping tool – including this one – is ultimately reading from HID, the Human Interface Device protocol that every USB and Bluetooth controller speaks at the hardware level. On top of HID sit two different things people often confuse:

• The Gamepad API – a W3C browser standard, supported in Chrome, Edge, and Firefox (Safari support is partial), that exposes controller state to web pages. This is what powers this tool.
• WebHID – a newer, lower-level browser API that can read raw HID report data directly, bypassing the Gamepad API’s standardization layer entirely. It’s used by specialist tools that need access to features the Gamepad API doesn’t expose, like adaptive trigger control, but has narrower browser support.

The Gamepad API reports two categories of data:

• Buttons – each carries a pressed boolean and a value between 0 and 1, which is why a trigger can act as both an on/off button and an analog input from the same signal.
• Axes – floating-point numbers, typically -1.0 to +1.0, used for stick position. A resting stick reports a value near 0.

The API attempts to standardize most controllers into a common layout, but firmware revisions and vendor-specific quirks mean two units of the exact same model can occasionally report different button indexes. That’s the entire reason a mapping test is worth running before you trust a configuration – especially on third-party or off-brand pads.

Polling rate matters here too. It’s the frequency at which the browser can observe a change in input state, and it’s a different measurement from mapping accuracy – a controller can be perfectly mapped and still feel laggy if its effective polling rate is low. If input feels delayed rather than mismapped, that’s a separate question best answered with our gamepad latency test.

How to Run a Controller Mapping Test, Step by Step

Reading Your Results Correctly

What you see	What it means
Button reports pressed: true/false	Digital input – simple on/off
Button also reports a value between 0–1	Analog-capable, common on triggers
Axis value near 0.00	Stick is centered / at rest
Axis stays off-zero at rest	Possible drift – confirm with our stick drift test
Trigger doesn’t reach 1.0 on a full pull	Reduced travel range – check with the trigger pressure test
DualSense trigger reports variable resistance-adjacent values	The Gamepad API can read trigger travel, but it cannot read or set DualSense adaptive trigger resistance – that’s a PlayStation-specific feature the browser has no access to
No gyro data appears anywhere	Expected – the Gamepad API doesn’t expose motion/gyro sensors at all, even on controllers that have them

Small centered dead zones are normal – they filter natural sensor noise, and controllers with Hall effect sensors typically show tighter, more stable at-rest readings than traditional potentiometer sticks. If you need to fine-tune exactly how large a dead zone should be, that’s a calibration task for our dedicated joystick deadzone test, not something to eyeball here.

Fixing Wrong or Swapped Buttons

Some controllers – particularly region-specific PlayStation pads and off-brand third-party gamepads – report face buttons in a different order than expected (Circle behaving like “confirm” instead of “cancel,” matching Japanese UI convention rather than Western convention).

This isn’t a hardware fault. Fix it in four steps:

1. Run Discover Mode to see the raw index each button actually reports.
2. Open Map Mode and manually reassign the button to the correct action.
3. Save the profile so you don’t repeat this every session.
4. Re-run Test Mode to confirm the fix holds under rapid or combined presses.

If buttons aren’t swapped but genuinely unresponsive, that’s a different problem – start with our plain gamepad button test to isolate mapping versus a dead input.

Adapters add a second translation layer. If you’re using a Mayflash or 8BitDo adapter to bridge an older controller into a modern port, the adapter itself remaps the signal before your OS ever sees it – which can shift button indexes again on top of whatever the controller was already reporting. Always re-run Discover Mode after adding or changing an adapter rather than assuming a previously-saved profile still applies.

HID vs. XInput vs. DirectInput: Why PC Mapping Gets Confusing

HID is the protocol every controller speaks at the hardware level. XInput and DirectInput are two competing Windows-specific translation layers built on top of it, and which one a game expects is usually the actual root cause of “my mapping is wrong in this game but fine in that one.”

	XInput	DirectInput
Built on	HID, standardized by Microsoft for Xbox controllers	HID, but with no guaranteed standard order
Used natively by	Xbox controllers; the modern PC gaming standard	PlayStation pads and many generic controllers on PC
Button layout	Standardized (A, B, X, Y, triggers, bumpers)	Varies by device
Trigger reporting	Full analog range as a single axis pair	Often reported as separate buttons or inconsistent axes
Game support	Broadest – most modern PC games expect this	Common in older or non-Steam titles

A DualSense or DualShock controller can feel “unmapped” in a game that only speaks XInput not because the controller is broken, but because the game is reading a protocol the controller was never built to speak. DS4Windows solves this by translating a DirectInput device into a virtual XInput controller; Steam Input does the same thing automatically for anything launched through Steam.

Controller Mapping in Steam, RetroArch, and Emulators

Steam Input

Launching a game through Steam typically triggers automatic detection and remapping, applying its own translation layer regardless of whether the pad natively speaks XInput or DirectInput. Manual remapping is still available per-game in Steam’s own Controller Settings.

RetroArch and SDL GameControllerDB

Emulators built on SDL (Simple DirectMedia Layer) read mappings from a community-maintained file called gamecontrollerdb.txt. Each line follows the format GUID,name,mapping – for example, a PS4 pad’s entry might read a:b1,b:b2,leftx:a0,lefty:a1,..., tying each SDL button/axis name to a hardware index. The Export → SDL option on this page generates exactly that string, ready to paste into your emulator’s database file or config folder.

DS4Windows and third-party remappers

For PlayStation controllers on PC, DS4Windows intercepts the DirectInput signal and re-emits it as XInput, adding features like custom macros, touchpad gestures, and per-profile lighting – useful once you’ve confirmed via mapping test that your raw inputs are correct but a specific game still won’t recognize the controller.

Macros and Combo Mapping

Beyond simple one-to-one remapping, some tools let you assign a single input to trigger a sequence – one button press that fires multiple outputs or a timed combo. This is genuinely useful for accessibility (consolidating a demanding multi-button input into one comfortable press) and for automating repetitive non-competitive tasks.

Be careful where you use it. Many game publishers explicitly classify macro-mapped combos as a form of cheating in competitive or ranked play, since they can replicate frame-perfect input sequences a human can’t reliably reproduce manually. Check a specific game’s terms of service before relying on macros outside single-player or accessibility contexts – this is a policy risk, not a technical one, and it varies title by title.

Accessibility Controller Mapping

Remapping isn’t only a troubleshooting tool – it’s an accessibility one. A few patterns worth building into any profile meant for accessibility use:

• Consolidate actions so fewer distinct presses are required for common combos.
• Support one-handed play by moving essential actions onto whichever side is usable.
• Offer toggles instead of holds – turning “hold to sprint” into “tap to toggle sprint” removes sustained grip strain.
• Save and share profiles – a working accessible mapping for one controller model helps every other player using that same hardware, which is why naming and exporting profiles clearly (see Step 4 above) isn’t just organizational tidiness.

Mapping on Other Platforms: Linux and Mobile

Browser-based tools cover Windows and macOS well, but two platforms behave differently and are worth knowing about even though this specific page tests via browser:

• Linux reads controllers through the kernel’s evdev interface rather than XInput or DirectInput. Command-line tools like jstest show raw axis and button data, while GUI tools like antimicrox handle full remapping outside the browser entirely.
• Android supports the Gamepad API in Chrome over USB-OTG or Bluetooth pairing, but support is inconsistent across device manufacturers and controller models. iOS Safari does not support the Gamepad API at all, so browser-based mapping tests won’t run on an iPhone or iPad regardless of controller.

Export Formats Explained

Format	Best for	Notes
JSON	Backups, programmatic use	Full metadata, easiest to parse in custom tools or scripts
CSV	Manual editing	Opens cleanly in Excel/Sheets for quick review or annotation
SDL Mapping String	Emulators, SDL-based apps	Matches the GUID,name,mapping format used in gamecontrollerdb.txt
RetroArch Config	RetroArch specifically	Includes button binds, analog settings, and hotkeys in RetroArch’s expected structure

Controller Mapping Test vs. Other Gamepad Diagnostics

Mapping tells you which input is which – it’s a different question from whether that input is physically healthy. If your mapping is correct but something still feels off, one of these is the more accurate tool:

If you want to check…	Use this instead
Whether a button is simply responsive or dead	Gamepad Button Test
Whether a stick drifts at rest	Gamepad Stick Drift Test
How large your dead zone should be	Joystick Deadzone Test
Whether triggers reach full analog range	Gamepad Trigger Pressure Test
Whether rumble motors work	Gamepad Vibration Test
Input lag between press and register	Gamepad Latency Test
USB/Bluetooth dropouts	Gamepad Connection Stability Test

Troubleshooting Quick Reference

Problem	Try this
Controller not detected	Different USB port, press a button to wake it, check OS device manager, try another browser, confirm adapter drivers are installed
Buttons swapped or wrong	Discover Mode to view raw input, then correct it in Map Mode
Mapping works here but not in-game	Check whether the game expects XInput vs. DirectInput; try Steam Input or DS4Windows
Mapping resets after reconnecting	Save your profile – some browsers don’t persist Gamepad API state between sessions
Different results over Bluetooth vs. USB	Polling and driver behavior can differ by connection type; re-run the test wired to confirm the “true” mapping
Mapping shifted after adding an adapter	Adapters re-translate the signal; re-run Discover Mode rather than trusting a saved profile
Switch Pro Controller shows B where you expect A	Not a bug -Nintendo’s own convention places B at index 0; remap in Map Mode if you want an Xbox-style layout

Notes From Testing

Across repeated sessions with the controllers listed at the top of this page, a few patterns held consistently enough to be worth calling out directly: DualSense units connected over Bluetooth were the most likely to need a second Discover Mode pass after reconnecting, third-party 8BitDo pads behaved differently depending on which physical mode switch they were set to (Xinput vs. Switch vs. DirectInput), and Joy-Cons attached to a Switch Pro-style grip reported combined-press values that a single-pass Discover Mode consistently missed. None of this shows up as a “bug report” anywhere – it’s just what repeated real-world testing surfaces, which is exactly why re-running Discover Mode after any connection change is the one habit worth keeping regardless of controller brand.

This tool reads controller input locally through your browser’s Gamepad API. It does not modify firmware or system-level settings, and exported mapping files should always be validated inside your actual game or emulator before relying on them in competitive or critical use.

Frequently Asked Questions

Get quick responses to frequently asked questions regarding the  Gamepad Controller Mapping & Testing.