├── .github └── workflows │ └── check.yml ├── LICENSE ├── README.md ├── duplicates.py ├── gamecontrollerdb.txt └── mapping_guide.png /.github/workflows/check.yml: -------------------------------------------------------------------------------- 1 | name: Data check 2 | on: 3 | push: 4 | branches: [master] 5 | jobs: 6 | duplicates: 7 | runs-on: ubuntu-latest 8 | steps: 9 | - uses: actions/checkout@v2 10 | - run: | 11 | python duplicates.py 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (C) 1997-2025 Sam Lantinga 2 | 3 | This software is provided 'as-is', without any express or implied 4 | warranty. In no event will the authors be held liable for any damages 5 | arising from the use of this software. 6 | 7 | Permission is granted to anyone to use this software for any purpose, 8 | including commercial applications, and to alter it and redistribute it 9 | freely, subject to the following restrictions: 10 | 11 | 1. The origin of this software must not be misrepresented; you must not 12 | claim that you wrote the original software. If you use this software 13 | in a product, an acknowledgment in the product documentation would be 14 | appreciated but is not required. 15 | 2. Altered source versions must be plainly marked as such, and must not be 16 | misrepresented as being the original software. 17 | 3. This notice may not be removed or altered from any source distribution. 18 | 19 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # SDL_GameControllerDB 2 | 3 | A community sourced database of game controller mappings to be used with SDL2 and SDL3 Game Controller functionality. 4 | 5 | # Usage 6 | Download gamecontrollerdb.txt, place it in your app's directory and load it. 7 | 8 | SDL2: 9 | ```c 10 | SDL_GameControllerAddMappingsFromFile("gamecontrollerdb.txt"); 11 | ``` 12 | 13 | SDL3: 14 | ```c 15 | SDL_AddGamepadMappingsFromFile("gamecontrollerdb.txt"); 16 | ``` 17 | 18 | The database is compatible with SDL v2.0.10 and newer. 19 | 20 | ## Create New Mappings 21 | A mapping looks like this: 22 | ``` 23 | 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, 24 | ``` 25 | It includes controller GUID (`030000004c050000c405000000010000`), a name (`PS4 Controller`), button / axis mappings (`leftshoulder:b4`) and a platform (`platform:Mac OS X`). 26 | 27 | Please make sure to check that the name is a good description of the controller. If relevant, include the controller's name and model number. 28 | 29 | ## Mapping Guide 30 | 31 | ![SDL Game Controller Mapping Guide](mapping_guide.png) 32 | 33 | ## Mapping Tools 34 | There are a few different tools that let you create mappings. 35 | 36 | ### [SDL2 Gamepad Tool](http://www.generalarcade.com/gamepadtool/) 37 | Third party cross-platform tool with GUI (Windows, macOS and Linux) 38 | 39 | *While convenient, this tool has fallen out of date as SDL has amended and added new features for gamepad support (see [#478](https://github.com/gabomdq/SDL_GameControllerDB/issues/476)). Maps authored with this tool require maintainer scrutiny to ensure they will not break support for explicit mappings the SDL project provides.* 40 | 41 | ### [SDL](https://github.com/libsdl-org/SDL/releases/latest) 42 | [testcontroller (SDL3)](https://github.com/libsdl-org/SDL/blob/main/test/testcontroller.c) and [controllermap (SDL2)](https://github.com/libsdl-org/SDL/blob/SDL2/test/controllermap.c) utilities are the official tools to create these mappings on all SDL supported platforms (Windows, Mac, Linux, iOS, Android, etc). 43 | 44 | ``` 45 | "SDL_GamepadBind" "030000004c050000c405000000010000,PS4 Controller,platform:Windows,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," 46 | ``` 47 | 48 | ## Resources 49 | 50 | * [SDL](http://www.libsdl.org) 51 | * [SDL_GameControllerAddMappingsFromFile](http://wiki.libsdl.org/SDL_GameControllerAddMappingsFromFile) 52 | -------------------------------------------------------------------------------- /duplicates.py: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: Zlib 2 | 3 | import difflib 4 | import sys 5 | 6 | CROSS_PLATFORM=False 7 | 8 | cdict = {} 9 | for i, l in enumerate(open("gamecontrollerdb.txt")): 10 | l = l.strip() 11 | if l.startswith("#") or not l: 12 | continue 13 | 14 | c = l.split(",") 15 | key = tuple([c[0]]+[ce for ce in c[1:] if "platform:" in ce]) 16 | if CROSS_PLATFORM: 17 | key = c[0] 18 | 19 | if key in cdict: 20 | print("Duplicate:", c[1], "at line", i + 1) 21 | out = list(difflib.unified_diff(cdict[key], sorted(c), n=0))[3:] 22 | out = [o for o in out if not o.startswith("@@")] 23 | print("\t", " ".join(out)) 24 | if not CROSS_PLATFORM: 25 | sys.exit(1) 26 | cdict[key] = sorted(c) -------------------------------------------------------------------------------- /mapping_guide.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdqinc/SDL_GameControllerDB/742a6ba670834180fad930f0852ee121f7085daf/mapping_guide.png --------------------------------------------------------------------------------