|
1 | | -# SDL_GameControllerDB |
| 1 | +# [unmaintained] SDL_GameControllerDB |
2 | 2 |
|
3 | 3 | [](https://travis-ci.org/gabomdq/SDL_GameControllerDB) |
4 | 4 |
|
5 | | -A community source database of game controller mappings to be used with SDL2 Game Controller functionality. |
6 | | - |
7 | | -## SDL Variants |
8 | | -### gamecontrollerdb.txt |
9 | | -For games or engines using the SDL >= 2.0.6 format. This is the most recent version. |
10 | | - |
11 | | -### gamecontrollerdb_205.txt |
12 | | -For games or engines using the SDL >= 2.0.5 format. There are no range or inversion modifiers (+,-,~). |
13 | | - |
14 | | -### gamecontrollerdb_204.txt |
15 | | -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. |
16 | | - |
17 | | -## Create New Mappings |
18 | | -A mapping looks like this : |
19 | | -``` |
20 | | -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, |
21 | | -``` |
22 | | -It is comprised of a controller GUID (`030000004c050000c405000000010000`), a name (`PS4 Controller`), button / axis mappings (`leftshoulder:b4`) and a platform (`platform:Mac OS X`). |
23 | | - |
24 | | -## Naming Convention |
25 | | -- If the controller has a unique name, use that (ex. XBox Controller, XBox One Controller). |
26 | | -- If the controller doesn't have a unique name, or when in doubt, use brand + model (ex. ACME GA09, 8Bitdo NES30 Pro). |
27 | | -- You can add `Wireless` for controllers with such an option. (ex. XBox Wireless Controller). |
28 | | - |
29 | | -## Mapping Tools |
30 | | -There are a few different tools that let you create mappings. |
31 | | - |
32 | | -### [SDL2 Gamepad Tool](http://www.generalarcade.com/gamepadtool/) |
33 | | -Third party cross-platform tool with GUI (Windows, macOS and Linux). Likely the easiest tool to use. |
34 | | - |
35 | | -### [SDL2 ControllerMap](https://www.libsdl.org/download-2.0.php) |
36 | | -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). |
37 | | - |
38 | | -### [Steam](http://store.steampowered.com) |
39 | | -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. |
40 | | - |
41 | | -``` |
42 | | -"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," |
43 | | -``` |
44 | | - |
45 | | -Unfortunately, Steam outputs the platform field at the beginning, so you will need to move it to the end manually. Move `platform:Windows,` or `platform:Mac OS X,` or `platform:Linux,` to the end of the mapping (with the trailing comma). |
46 | | - |
47 | | -You will also need check that the name is a good description of the controller. If relevant, include the controller's name and model number. |
48 | | - |
49 | | -## Standard Mappings |
50 | | -Some controllers are a little tricky to figure out. Here are the recommended mappings. |
51 | | - |
52 | | - |
53 | | - |
54 | | -# Usage |
55 | | -Download gamecontrollerdb.txt, place it in your app's directory and load it. |
56 | | - |
57 | | -For example : |
58 | | -``` |
59 | | -SDL_GameControllerAddMappingsFromFile("gamecontrollerdb.txt"); |
60 | | -``` |
61 | | - |
62 | | -## Upstream SDL Mappings |
63 | | -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. |
64 | | - |
65 | | -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. |
66 | | - |
67 | | -# For Contributors |
68 | | -## Check Your Mappings |
69 | | -The currently active version is gamecontrollerdb.txt. If your mappings work on older SDL versions, you can add them to the appropriate files. |
70 | | -Before submitting a new Pull Request, please run the `check.py` tool to make sure everything is in order. |
71 | | - |
72 | | -Run it with: |
73 | | -``` |
74 | | -python check.py gamecontrollerdb.txt |
75 | | -``` |
76 | | - |
77 | | -Once no issues are detected, run the script with the `--format` option to sort the database in the appropriate format. |
78 | | -``` |
79 | | -python check.py --format gamecontrollerdb.txt |
80 | | -``` |
81 | | - |
82 | | -You may now send a Pull Request. Tests are automatically run on Pull Requests, so you'll easily see if there is an issue. |
83 | | - |
84 | | -### Unit Tests |
85 | | -- GUID is correct length and is hexadecimal. |
86 | | -- GUID is in 2.0.5+ format. |
87 | | -- Platform is present and supported. |
88 | | -- Inversion and range modifiers are applied to axis fields. |
89 | | -- No duplicate mappings. |
90 | | -- No duplicate keys. |
91 | | -- Buttons conform to supported values. |
92 | | -- Hats aren't 0 or diagonals. |
93 | | -- No upstream official mappings are modified. |
94 | | -- All mappings end with a comma. |
95 | | - |
96 | | -### Formatting |
97 | | -- The database is sorted by platform, then by name. |
98 | | -- Individual mapping keys are sorted alphabetically. |
99 | | -- Names are parsed for extraneous spaces. |
100 | | - |
101 | | -### Options |
102 | | -``` |
103 | | -usage: check.py [-h] [--format] [--convert_guids] [--add_missing_platform] |
104 | | - [--import_header sdl_header] |
105 | | - input_file |
106 | | -
|
107 | | -positional arguments: |
108 | | - input_file database file to check, ex. gamecontrollerdb.txt |
109 | | -
|
110 | | -optional arguments: |
111 | | - -h, --help show this help message and exit |
112 | | - --format sorts, formats and removes duplicates |
113 | | - --convert_guids convert Windows and macOS GUIDs to the newer SDL 2.0.5 |
114 | | - format |
115 | | - --add_missing_platform |
116 | | - adds a platform field if it is missing on Windows and |
117 | | - Mac OS X 2.0.4 entries |
118 | | - --import_header sdl_header |
119 | | - imports and overrides mappings using |
120 | | - SDL_gamecontrollerdb.h |
121 | | -``` |
122 | | - |
123 | | -## Resources |
124 | | - |
125 | | -* [SDL2](http://www.libsdl.org) |
126 | | -* [SDL_GameControllerAddMappingsFromFile](http://wiki.libsdl.org/SDL_GameControllerAddMappingsFromFile) |
| 5 | +# The controller database has moved [here](https://github.com/p-groarke/SDL_GameControllerDB2). |
| 6 | +## Join us at the new repository for updates and fixes! |
0 commit comments