Skip to content
A community sourced database of game controller mappings to be used with SDL2 Game Controller functionality
Branch: master
Clone or download
Pull request Compare This branch is 2 commits behind gabomdq:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

A community source database of game controller mappings to be used with SDL2 Game Controller functionality.

SDL Variants


For games or engines using the SDL >= 2.0.6 format. This is the most recent version.


For games or engines using the SDL >= 2.0.5 format. There are no range or inversion modifiers (+,-,~).


For games or engines using the SDL 2.0.4 format. GUIDs are different depending on the platform. Note that SDL > 2.0.4 can still read this format.

Create New Mappings

A mapping looks like this :

030000004c050000c405000000010000,PS4 Controller,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b12,leftshoulder:b4,leftstick:b10,lefttrigger:a3,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:a4,rightx:a2,righty:a5,start:b9,x:b0,y:b3,platform:Mac OS X,

It is comprised of a controller GUID (030000004c050000c405000000010000), a name (PS4 Controller), button / axis mappings (leftshoulder:b4) and a platform (platform:Mac OS X).

Naming Convention

  • If the controller has a unique name, use that (ex. XBox Controller, XBox One Controller).
  • If the controller doesn't have a unique name, or when in doubt, use brand + model (ex. ACME GA09, 8Bitdo NES30 Pro).
  • You can add Wireless for controllers with such an option. (ex. XBox Wireless Controller).

Mapping Tools

There are a few different tools that let you create mappings.

SDL2 Gamepad Tool

Third party cross-platform tool with GUI (Windows, macOS and Linux). Likely the easiest tool to use.

SDL2 ControllerMap

The controllermap utility provided with SDL2 is the official tool to create these mappings, it runs on all the platforms SDL runs (Windows, Mac, Linux, iOS, Android, etc).


In Steam's Big Picture mode, configure your joystick. Then look in [steam_installation_directory]/config/config.vdf in your Steam installation directory for the SDL_GamepadBind entry. It is one of the last entries, it will look something like this.

"SDL_GamepadBind"		"030000004c050000c405000000010000,PS4 Controller,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b12,leftshoulder:b4,leftstick:b10,lefttrigger:a3,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:a4,rightx:a2,righty:a5,start:b9,x:b0,y:b3,"

Unfortunately, Steam does not output the platform field, so you will need to add it manually. At the end of the generated entry, add platform:Windows, or platform:Mac OS X, or platform:Linux, (with the trailing comma).

Standard Mappings

Some controllers are a little tricky to figure out. Here are the recommended mappings.

mapping standard


Download gamecontrollerdb.txt, place it in your app's directory and load it.

For example :


Upstream SDL Mappings

This project includes all mappings from the latest SDL_gamecontrollerdb.h. The community db adds a superset of mappings to the official ones, it does not modify them in any way.

If you ever wish to modify one of these mappings, you will need to send a PR directly to the SDL project. The changes will get pulled in the community db when a new SDL release occurs.

For Contributors

Check Your Mappings

The currently active version is gamecontrollerdb.txt. If your mappings work on older SDL versions, you can add them to the appropriate files. Before submitting a new Pull Request, please run the tool to make sure everything is in order.

Run it with:

python gamecontrollerdb.txt

Once no issues are detected, run the script with the --format option to sort the database in the appropriate format.

python --format gamecontrollerdb.txt

You may now send a Pull Request. Tests are automatically run on Pull Requests, so you'll easily see if there is an issue.

Unit Tests

  • GUID is correct length and is hexadecimal.
  • GUID is in 2.0.5+ format.
  • Platform is present and supported.
  • Inversion and range modifiers are applied to axis fields.
  • No duplicate mappings.
  • No duplicate keys.
  • Buttons conform to supported values.
  • Hats aren't 0 or diagonals.
  • No upstream official mappings are modified.
  • All mappings end with a comma.


  • The database is sorted by platform, then by name.
  • Individual mapping keys are sorted alphabetically.
  • Names are parsed for extraneous spaces.


usage: [-h] [--format] [--convert_guids] [--add_missing_platform]
                [--import_header sdl_header]

positional arguments:
  input_file            database file to check, ex. gamecontrollerdb.txt

optional arguments:
  -h, --help            show this help message and exit
  --format              sorts, formats and removes duplicates
  --convert_guids       convert Windows and macOS GUIDs to the newer SDL 2.0.5
                        adds a platform field if it is missing on Windows and
                        Mac OS X 2.0.4 entries
  --import_header sdl_header
                        imports and overrides mappings using


You can’t perform that action at this time.