# mdqinc/SDL_GameControllerDB for SDL Controller Mapping Compatibility

> mdqinc/SDL_GameControllerDB is a community-maintained text database that lets SDL2 and SDL3 applications load controller mappings through SDL's Game Controller functionality. It suits developers who need to support varied gamepads without recreating mappings individually.

**mdqinc/SDL_GameControllerDB** — A community sourced database of game controller mappings to be used with SDL Game Controller functionality

- Repository: https://github.com/mdqinc/SDL_GameControllerDB
- Website: http://libsdl.org
- Stars: 1,784 · Forks: 625
- Language: Python
- License: Zlib
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mdqinc-sdl-gamecontrollerdb

## What SDL_GameControllerDB Actually Provides

mdqinc/SDL_GameControllerDB addresses a specific SDL integration problem: applications can use SDL's standardized Game Controller or Gamepad API, but physical controllers expose different identifiers, buttons, axes, and platform-specific layouts. The repository supplies a community-sourced database intended for SDL2 and SDL3 Game Controller functionality. Its central file is gamecontrollerdb.txt, which applications load at runtime instead of treating every controller as a device with a custom input implementation.

The intended users are developers building games or applications with SDL who need controller mappings across the platforms supported by SDL. The README gives Mac OS X as one example platform in a mapping record and says the database is compatible with SDL v2.0.10 and newer. The repository does not claim to implement input handling itself. SDL performs the controller work, while this repository supplies mapping records that SDL can parse and apply.

This division makes the project useful when an application already depends on SDL. It does not help an application that uses another input abstraction unless that application has a separate mechanism for importing these records. The file is also a mapping database, not a library with an API, a runtime service, or a device driver.

## The Text Record Format Behind Each Controller Entry

Each mapping line contains several pieces of information in one SDL mapping string. The README's PS4 Controller example begins with the controller GUID, followed by a human-readable name, then button and axis assignments, and finally a platform field. The entry also ends with a trailing comma, which is part of the displayed mapping format.

The first field identifies the controller. For the example, the GUID is `030000004c050000c405000000010000`. The name is `PS4 Controller`. A binding such as `leftshoulder:b4` associates a logical SDL control with a controller button or axis identifier. Directional inputs use half-axis notation, including `dpdown:h0.4`, `dpleft:h0.8`, `dpright:h0.2`, and `dpup:h0.1`. Analog stick and trigger assignments use axis names such as `leftx:a0`, `lefty:a1`, `lefttrigger:a3`, and `righttrigger:a4`.

The `platform:Mac OS X` field records where the mapping applies. This makes the file a collection of platform-specific records rather than one controller definition that SDL can apply unchanged everywhere. A mapping contributor is asked to search by platform and GUID before adding an entry, because the README says an acceptable mapping should not already be present in the database.

The repository also includes `mapping_guide.png`, which provides a visual reference for translating controller controls toward the Xbox-style layout. The README specifically asks contributors to check that a mapping represents that layout as closely as possible.

## Loading SDL2 and SDL3 Mappings in an Application

The documented integration path is short. Download `gamecontrollerdb.txt`, place it in the application's directory, and load it through the SDL function appropriate to the SDL major version. For SDL2, the README gives this call:

```c
SDL_GameControllerAddMappingsFromFile("gamecontrollerdb.txt");
```

For SDL3, use the corresponding call documented by the repository:

```c
SDL_AddGamepadMappingsFromFile("gamecontrollerdb.txt");
```

The application should load the file before it expects the database entries to be available. The README does not show a full initialization sequence, an error-checking example, a platform-specific search path, or a packaged-resource procedure. Those details depend on the application and SDL integration. It also does not document whether callers should bundle the database, copy it at deployment time, or embed it in another format.

The database's declared compatibility starts at SDL v2.0.10. An application using an older SDL release would need to check that version before relying on this file. The README does not state what behavior results when the file is missing, malformed, or contains a mapping for an unknown GUID.

## Creating and Contributing a New Mapping

Mapping creation is supported by official SDL tools and by a third-party GUI utility. For SDL3, the README links to `testcontroller`; for SDL2, it links to `controllermap`. The README describes these as official tools for creating mappings on SDL-supported platforms, including Windows, Mac, Linux, iOS, and Android. It also lists `sdl2-gamepad-tool`, an open-source third-party tool with GUI releases for Windows, macOS, and Linux.

The repository's contribution criteria are more restrictive than simply supplying a working device. A contributor must confirm that the device is a gamepad, verify that the mapping represents the Xbox layout according to the mapping guide, and check whether an acceptable mapping already exists by platform and GUID. The contributor is also asked to ensure that adding the mapping improves the experience without degrading it for other users. Names should describe the controller accurately and, when relevant, include the controller name and model number.

Contributions go through a pull request or an issue. For a pull request, the README asks contributors to enable "Allow edits from maintainers" on the fork. It also explicitly says not to submit AI-generated comments or content in issues or pull requests. The repository contains `duplicates.py`, but the README does not describe its command-line interface or explain how it is used in the contribution workflow.

## Maintenance, Compatibility, and Project Boundaries

The repository is not archived, and its last push was on 2026-10-02. That indicates recent repository activity at the time represented by the project data, but it does not establish a release cadence or a guarantee that every controller mapping is correct. The README lists no GitHub releases, so there is no documented versioned package to compare against the current `gamecontrollerdb.txt`.

Maintenance has a specific operational meaning here. A mapping can change when controller hardware, firmware, SDL behavior, or community verification needs change. However, the README does not define a schema version, compatibility matrix by SDL release, rollback procedure, or changelog format. It also does not state how quickly mappings are reviewed or whether there is a formal test suite for individual entries. Applications that depend on the file should therefore treat updates as data changes and review the file before replacing a bundled copy.

The repository is licensed under Zlib. That identifier permits use under the license's terms, but this review does not provide legal advice. The licensing implication for a distributed application depends on how the database is copied, modified, and shipped, so the license file should be inspected directly for the applicable obligations.

## When SDL_GameControllerDB Is the Wrong Choice

The main wrong-tool case is an application that does not use SDL's Game Controller or Gamepad functionality. Loading the file requires the relevant SDL mapping function, and the repository provides no alternative loader for another framework, operating-system API, or raw input backend.

It is also insufficient as a guarantee of controller support. A present mapping does not establish that every button, trigger, directional input, or platform combination will behave as intended. The README's contribution checks are procedural and editorial. It asks contributors to verify layout quality and duplication, but it does not publish a per-controller certification record, automated hardware matrix, or promised test result.

Developers should also account for deployment. The README says to place `gamecontrollerdb.txt` in the application's directory, but it does not specify installer behavior, sandboxed application paths, mobile packaging, or updates after installation. An application that cannot ship or update a data file needs a different integration strategy or an additional packaging layer.

A real alternative is to use SDL's own controller creation and mapping workflow without this community file. SDL provides `controllermap` for SDL2 and `testcontroller` for SDL3, which can be used to create mappings. The difference is scope: this repository supplies existing community records for loading into applications, while the official SDL tools help produce mappings. A third option is to maintain a private mapping file for a tightly controlled device set, accepting the work of naming, deduplicating, updating, and validating each entry.

## Conclusion

Adopt SDL_GameControllerDB when your application uses SDL controller handling and needs a broad community mapping source. Do not treat the file as a universal compatibility guarantee, because the README does not document controller testing coverage, mapping quality validation, or a rollback procedure. Verify first that your SDL version is compatible, that the required controller GUID is present for each target platform, and that the mapping behaves correctly in the application.

## FAQ

### How do I load SDL_GameControllerDB in SDL2?

Download `gamecontrollerdb.txt`, place it in the application's directory, and load it with `SDL_GameControllerAddMappingsFromFile("gamecontrollerdb.txt")`. The README documents compatibility with SDL v2.0.10 and newer.

### How do I use SDL_GameControllerDB with SDL3?

Place `gamecontrollerdb.txt` in the application's directory and load it with `SDL_AddGamepadMappingsFromFile("gamecontrollerdb.txt")`. The README lists this as the SDL3 loading function.

### How do I create a controller mapping for mdqinc/SDL_GameControllerDB?

The README points SDL2 users to `controllermap` and SDL3 users to `testcontroller`. It also lists `sdl2-gamepad-tool` as a third-party GUI tool, and asks contributors to check the Xbox-style mapping guide and search by platform and GUID before submitting a mapping.

## Sources

- [Issues](https://github.com/mdqinc/SDL_GameControllerDB/issues)
- [License: Zlib](https://github.com/mdqinc/SDL_GameControllerDB/blob/master/LICENSE)
- [mdqinc/SDL_GameControllerDB on GitHub](https://github.com/mdqinc/SDL_GameControllerDB)
- [Project website](http://libsdl.org)
- [README](https://github.com/mdqinc/SDL_GameControllerDB/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mdqinc-sdl-gamecontrollerdb