Skip to content
Projects

mdqinc/SDL_GameControllerDB

View on GitHub

mdqinc/SDL_GameControllerDB has 1,793 GitHub stars and 628 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-08 01:23 UTC. Last push 2026-11-02.

How these counts are measured

A community sourced database of game controller mappings to be used with SDL Game Controller functionality

1,793 stars628 forks +1 in 24h

Measured star growth

in 24h
+1
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

README.md

Original

SDL_GameControllerDB

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

Usage

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

SDL2:

SDL_GameControllerAddMappingsFromFile("gamecontrollerdb.txt");

SDL3:

SDL_AddGamepadMappingsFromFile("gamecontrollerdb.txt");

The database is compatible with SDL v2.0.10 and newer.

Creating 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 includes controller GUID (030000004c050000c405000000010000), a name (PS4 Controller), button / axis mappings (leftshoulder:b4) and a platform (platform:Mac OS X).

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.

Mapping Guide

SDL Game Controller Mapping Guide

Mapping Tools

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

SDL2 Gamepad Tool

Open-source third party cross-platform tool with GUI (Windows, macOS and Linux releases)

SDL

testcontroller (SDL3) and controllermap (SDL2) utilities are the official tools to create these mappings on all SDL supported platforms (Windows, Mac, Linux, iOS, Android, etc).

Contributing

First, please confirm for yourself

  • Your device is a gamepad
  • Your mapping best represents the Xbox layout per the mapping guide
  • An acceptable mapping is not already present in the DB, searching by platform and GUID
  • Adding the mapping to the db improves, and does not degrade the experience of using the gamepad

Contribute by opening a pull request, or creating an issue. If you are opening a pull request, ensure "Allow edits from maintainers" is enabled on your fork. Please do not submit AI-generated comments or content in issues or pull requests.

Resources

SDL2

SDL3

Explore related projects

Asabeneh/30-Days-Of-Python

The 30 Days of Python programming challenge is a step-by-step guide to learn the Python programming language in 30 days. This challenge may take more than 100 days. Follow your own pace. These videos may help too: https://www.youtube.com/channel/UC7PNRuno1rzYPb1xLa4yktw

78,370 stars

grafana/grafana

The open and composable observability and data visualization platform. Visualize metrics, logs, and traces from multiple sources like Prometheus, Loki, Elasticsearch, InfluxDB, Postgres and many more.

77,752 stars

redis/redis

For developers, who are building real-time data-driven applications, Redis is the preferred, fastest, and most feature-rich cache, data structure server, and document and vector query engine.

77,288 stars

apache/superset

Apache Superset is a Data Visualization and Data Exploration Platform

75,448 stars