How to add a new controller to SDL gamecontrollerbd.txt

MINIBITS · July 17, 2026, 1:00pm

I have a cheap Chinese Controller that reports as

{ –[[00000188FFE17560]]
gamepad_unknown = true,
gamepad_name = "USB Joystick ",
gamepad_guid = “030000008f0e00000300000000000000”,
userid = 0,
gamepad = 0,
text = "USB Joystick ",
gamepad_guid_info = { –[[00000188FFE175F0]]
vendor = 3727,
bus = 3,
crc = 0,
version = 0,
product = 3
}
}

The GUID is already in the gamecontrollerdb.txt, but the mapping is wrong. I’ve tried to add an extra line for my controller with the same GUID and the controller name to fix the mapping. This does not work. It gives a warning that the GUID is already registered. It seems that only the GUID is checked to find the correct mapping.

Wouldn’t it be better to check for GUID AND controller name in the first step, and if not found, check for the GUID only?

Mathias_Westerdahl · July 17, 2026, 1:21pm

Hi!
The GUID as specified is from SDL public database, so it’s unlikely we’ll change the actual mapping,

You can use the GDC tool to output an SDL compliant entry.

The 030000008f0e00000300000000000000 is the generic fallback (no crc, no version) which may match multiple of their devices. As you see here we mimic SDL in testing different GUID’s.

The device name is part of the CRC in the GUID as seen here.

MINIBITS · July 17, 2026, 1:33pm

ok. will check.

Where can I report other new controller mappings? Checking my controllers now.

Mathias_Westerdahl · July 17, 2026, 2:17pm

We accept PR’s on our GitHub

MINIBITS · July 20, 2026, 1:46pm

I also have here a 8Bitdo Ultimate 2C Wireless Controller. Pretty new one. The gamepad is listed in the gamecontrollerdb.txt, but “example-gamepad-master” does not detect it.

I can create an SDL entry with the GDC tool and now it gets detected. The created GUID is different to all other 8Bitdo Ultimate 2C Wireless entries in the database.

So I checked GitHub - General-Arcade/sdl2-gamepad-tool: SDL2 Gamepad Tool · GitHub, it uses the same database and it detects the controller out of the box. This tool also allows to create a new mapping. Different to the GDC tool, the SDL gamepad tool creates a mapping string including the crc.

Maybe I miss something :). Anway when I have more time I will debug the dmengine too see why this is not working here.

Mathias_Westerdahl · July 20, 2026, 2:48pm

Yeah, it starts to sound like our GUID generation still differs from how our guids are generated.
Please open a tick on GitHub, add the guid ourgdc tool generates, and the guid the SDL tool generates, so we can compare them.
I don’t think we have that particular controller, but we’ll try to find one so that we can verify the gui generation between the tools.

EDIT: I’ve gotten hold of such a controller, will debug now

Mathias_Westerdahl · July 26, 2026, 8:43am

I have now updated the 1.13.1 BETA with gamepad changes.
I’ve tested a 8Bitdo Ultimate 2C Wireless Controller. on both macOS and Windows and it works well for me.

Please give this release a try!

To answer the OP “how to add a new controller to SDL gamecontrollerdb.txt”, we recommend using the SDL Gamepad Tool.

MINIBITS · July 26, 2026, 9:42am

I’ve updated to the new beta and tested example-gamepad, but still the same problem.

INFO:INPUT: Gamepad 0 ‘Xbox Controller’ guid=03000000c82d00000a31000000000000 using raw fallback (legacy=true).
DEBUG:SCRIPT: main.script: input focus acquired
DEBUG:SCRIPT: controllers.gui_script: ready
DEBUG:SCRIPT: CONNECTED,
{ –[[00000223797473B0]]
userid = 0,
gamepad_unknown = true,
gamepad = 0,
text = “Xbox Controller”,
gamepad_name = “Xbox Controller”,
gamepad_guid = “03000000c82d00000a31000000000000”,
gamepad_guid_info = { –[[0000022379747400]]
vendor = 11720,
crc = 0,
bus = 3,
product = 12554,
version = 0
}
}

Tested SDL Gampad tool and it gets detected. See screenshot. I did a test to use the same gamepad db from the SDL tool with example-gamepad, but did not solve the problem.

Mathias_Westerdahl · July 26, 2026, 9:51am

What OS are you using?
Are you connecting the controller via Bluetooth, USB- dongle or USB-wire?

MINIBITS · July 26, 2026, 10:03am

Windows 10 and via Dongle.

Mathias_Westerdahl · July 26, 2026, 3:52pm

I’ve pushed another fix to the beta.
Please try again!

MINIBITS · July 26, 2026, 4:07pm

Yeah, this works Now I see also the CRC and have the same GUID as in the SDL tool

MINIBITS · July 26, 2026, 4:20pm

Tested another gamepad. This is cheap chinese crap sold many year ago by HAMA. Does not work in the example-gampad. Reports:

INFO:INPUT: Gamepad 0 'USB Joystick ’ guid=030000008f0e00000300000000000000
DEBUG:SCRIPT: main.script: input focus acquired
DEBUG:SCRIPT: controllers.gui_script: ready
DEBUG:SCRIPT: CONNECTED,
{ –[[000002BE09C07290]]
gamepad_unknown = false,
gamepad_guid_info = { –[[000002BE09C07680]]
product = 3,
bus = 3,
crc = 0,
vendor = 3727,
version = 0
},
gamepad_name = “PS3 Controller”,
text = “PS3 Controller”,
gamepad = 0,
gamepad_guid = “030000008f0e00000300000000000000”,
userid = 0
}

In the SDL Tool it works and is detected as HAMA.

Mathias_Westerdahl · July 26, 2026, 4:49pm

I’ll see what I can do, as I don’t have such a device.

Mathias_Westerdahl · July 27, 2026, 6:56am

I see that your “Delete Local Mapping” is enabled.
The tool should only enable that button only when gamecontrollerdb.local.txt contains a mapping for the base GUID.

Have you created your own mapping for that controller?
Does the controller work in the SDL Gamepad Tool if you temporarily delete that mapping?

MINIBITS · July 27, 2026, 7:38am

Oh yeah, you’re right. I had that once. But in the meantime I deleted the SDL tool again. Apparently the tool stores the mapping in a Windows AppData folder. My mistake. Sorry. I should have figured that out myself. I’ve deleted it again now. The controller is recognized as a PS3 controller, but the mapping is just wrong.

So right now it seems to work fine.

In the evening I will test this one here on Android
https://www.amazon.de/dp/B0DXPMVCWC

Mathias_Westerdahl · July 27, 2026, 7:41am

Ok, great!
So to support the Hama device, we recommend you to create a PR for the gamecontrollerdb.txt.
We will then pull their latest updates into our next release.

MINIBITS · July 27, 2026, 10:43am

More testing

I’ve created a mapping for my Hama controller in SDL GamePad Tool. The mapping string is

0300ed338f0e00000300000000000000,Hama Double Action AirGrip,platform:Windows,crc:33ed,a:b2,b:b3,x:b0,y:b1,guide:b8,start:b9,leftstick:b10,rightstick:b11,leftshoulder:b4,rightshoulder:b5,dpup:h0.1,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,leftx:a0,lefty:a1,rightx:a3,righty:a2,lefttrigger:b6,righttrigger:b7,

and the controller works. So I’ve copied the same string to the defold database, but the controller is still recognized as PS3 Conroller and the mapping is wrong.

I’ve delete the local mapping in the SDL Tool, copied the string to the default gamecontrollerdb.txt of the SDL tool. Now the same problem as in defold. Controller gets recognized as PS3 Controller and mapping is wrong.

The mapping string reported by the SDL includes the CRC and is complete different to all other entries from the gamecontrollerdb.txt. So it seems in the SDL tool can support the controller, but only if you create a local mapping. The SDL tool first checks for local mappings and uses the CRC for this. If nothing is found, it checks the gamecontrollerdb.txt, but doesn’t use the CRC here. The reason for this handling is probably that the CRC is system-dependent. Makes sense, but it’s not really a solution to support controllers via gamecontrollerdb.txt that pretend to be something they’re not with a fake GUID

Next, I’ve used defold gdc.exe to create a mapping string for the Hama controller:
030000008f0e00000300000000000000,USB Joystick ,a:b2,b:b3,x:b0,y:b1,back:b9,start:b8,leftstick:b10,rightstick:b11,leftshoulder:b6,rightshoulder:b7,dpup:b12,dpdown:b14,dpleft:b15,dpright:b13,leftx:a0,lefty:a1,rightx:a3,righty:a2,lefttrigger:b4,righttrigger:b5,platform:Windows,

copied it to the defold gamecontrollerdb.txt, but does not get detected. Still PS3 and wrong mapping.

Summary: It’s possible to map the controller in the SDL tool, but the mapping string can’t simply be copied into the gamecontrollerdb.txt. In Defold, it wasn’t able to create a mapping for the controller.

Mathias_Westerdahl · July 27, 2026, 11:22am

Hi, can you upload a version of the test project, with the modified database in it?

MINIBITS · July 28, 2026, 1:38pm

I was able to use the Hama Controller, but just if I add the GUID string as the first line in the gamecontrollerdb.txt. If I add it to the end, it will report as PS3 Controller and has a wrong mapping. So I think defold will just check for the GUID and not GUID and CRC. This chinese crap reports with a fake PS3 GUID and defold uses the first matching GUID mapping in the list.