Skip to content

About

XInput interface for SDL controllers.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

xinput-sdl-wrapper

A drop-in replacement for xinput1_3.dll (also xinput1_4.dll and xinput9_1_0.dll) that reads controllers through SDL3's Gamepad API and presents them to the game as Xbox 360 pads. Use it to make PlayStation, Switch, generic DirectInput and other SDL-supported controllers work in games that only understand XInput.

It can also hide gamepads from DirectInput 8 using MinHook inline hooks, so the game sees each pad only once, through XInput, instead of twice or through the wrong API. No separate dinput8.dll proxy is needed.

Game  --XInputGetState-->  xinput1_3.dll (this project)  --SDL3-->  your controller
                                 |
                                 +-- MinHook: DirectInput 8 calls in the game process
                                     are filtered so gamepads are not enumerated/opened

Features

XInput wrapper

  • Up to 4 pads, hot-plug aware, stable slot assignment
  • Full button/stick/trigger mapping, rumble (low/high-frequency motors)
  • XInputGetStateEx (ordinal 100) with Guide button
  • Optional gamecontrollerdb.txt for extra mappings
  • Optional xinput_sdl.ini (swap A/B, disable rumble, debug logging)
  • Packet number only changes when the state changes (like real XInput)
  • No work in DllMain; lazy, thread-safe init
  • Static CRT: no VC++ redistributable required

DirectInput hiding (MinHook)

  • Gamepad-class devices are removed from DirectInput 8 enumeration and cannot be opened by the game
  • Keyboard, mouse and other non-pad devices are left untouched
  • Works by hooking in-process with MinHook: nothing is replaced on disk, and the real system dinput8.dll is used as-is
  • Calls made by SDL itself are not filtered, so SDL can still see the real devices that feed the XInput wrapper
  • No configuration of its own; reuses the Debug key from xinput_sdl.ini

Quick start (using a release/CI build)

  1. Find out what the game loads and its bitness (see below).
  2. Copy the matching DLL (xinput1_3.dll, ...) and SDL3.dll next to the game's .exe. 32-bit game -> 32-bit build; 64-bit game -> 64-bit build.
  3. Optionally copy xinput_sdl.ini and gamecontrollerdb.txt there too.
  4. Launch the game. DirectInput hiding is applied automatically from the same DLL; there is nothing else to install.

Which DLL name does the game use?

Check the exe's imports:

dumpbin /imports Game.exe | findstr /i "xinput dinput"

(or open it in Dependencies / PE-bear). Common values: XINPUT1_3.dll (DX9-era games), XINPUT1_4.dll (Win8+ era), XINPUT9_1_0.dll. If unsure, place copies under several names; unused ones are harmless.

The XInput DLL is what gets loaded, so it is also what carries the hooks. If the game never loads the XInput DLL you placed, the DirectInput hooks are not installed either.

Building

Requirements: CMake >= 3.15, a C++17 compiler (MSVC recommended; MinGW-w64 works), SDL3 development files (SDL3 >= 3.4.0) and MinHook.

MSVC + vcpkg

vcpkg install sdl3:x64-windows sdl3:x86-windows minhook:x64-windows minhook:x86-windows

:: 64-bit
cmake -S . -B build64 -A x64 -DXINPUT_DLL_NAME=xinput1_3 ^
  -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%\scripts\buildsystems\vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build64 --config Release

:: 32-bit
cmake -S . -B build32 -A Win32 -DXINPUT_DLL_NAME=xinput1_3 ^
  -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%\scripts\buildsystems\vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x86-windows
cmake --build build32 --config Release

Output lands in build*/bin/Release/ (xinput1_3.dll, SDL3.dll, xinput_sdl.ini, xinput_test.exe). MinHook is linked into the DLL, so there is no extra runtime file for it.

MinGW-w64 (32-bit example)

cmake -S . -B build -G Ninja -DXINPUT_DLL_NAME=xinput1_3 \
  -DCMAKE_PREFIX_PATH="/path/to/SDL3-3.x.y/i686-w64-mingw32;/path/to/minhook"
cmake --build build

Other options

Option Default Meaning
XINPUT_DLL_NAME xinput1_3 xinput1_3, xinput1_4 or xinput9_1_0
XINPUT_STATIC_SDL OFF Link SDL3 statically (needs a static SDL3 package, e.g. x64-windows-static)
XINPUT_BUILD_TEST ON Build xinput_test.exe

Testing without a game

Run from the folder containing the DLL and SDL3.dll:

xinput_test.exe xinput1_3.dll

It prints live state for slots 0-3 and rumbles slot 0 proportionally to the triggers. (xinput_test.exe must have the same bitness as the DLL.)

DirectInput hiding

Many games probe both DirectInput and XInput. With a PlayStation or Switch pad the game may then see the same physical controller twice (once as a DirectInput joystick with a generic layout, once as an XInput pad), or pick DirectInput and ignore XInput entirely. The hooks remove the DirectInput side of that so only the XInput wrapper is left.

What is hidden

DirectInput device type Hidden?
Joystick, Gamepad, Driving, Flight, First-person Yes
Supplemental (pedals, throttles, odd pads) Yes
Generic device (DI8DEVTYPE_DEVICE, e.g. generic HID) No (may not be a pad)
Keyboard, Mouse, Screen pointer, Remote, ... No

The policy is compiled in. To change it, edit the hide-policy constants in the source and rebuild.

How it works

MinHook patches the DirectInput 8 entry points in the game process so the results seen by the game are filtered. Hidden devices are skipped during enumeration and cannot be created by GUID. Because the hooks live inside the XInput DLL, they only exist in processes that load it.

SDL can use DirectInput as one of its own joystick backends, and SDL is what feeds the XInput wrapper, so calls coming from SDL are passed through unfiltered.

Configuration (xinput_sdl.ini)

Key Default Description
SwapAB 0 Swap A/B and X/Y (Nintendo layout)
Rumble 1 0 ignores game rumble
Debug 0 Log to OutputDebugString (use Sysinternals DebugView); also logs hook activity

All keys live in the [General] section.

gamecontrollerdb.txt (from SDL_GameControllerDB) placed next to the DLL is loaded automatically.

Design notes

  • SDL's own XInput backend is disabled (SDL_HINT_XINPUT_ENABLED=0). If SDL loaded xinput1_x.dll from the game folder it would find this DLL and recurse. Real Xbox pads still work via SDL's HIDAPI/RawInput/WGI backends.
  • Exports are defined in src/def/*.def, which gives undecorated names and fixed ordinals on both x86 (stdcall) and x64.
  • Own type definitions (src/xinput_types.h) are used instead of <xinput.h> to avoid SDK/MinGW declaration clashes.
  • Events: the wrapper polls SDL's event queue for hot-plug. If the game also uses the same SDL3.dll in the same process, the two would share one event queue; in that case build with XINPUT_STATIC_SDL=ON.
  • Hooks instead of a proxy DLL: MinHook is statically linked, so hiding needs no extra file next to the game and no replacement of the system dinput8.dll. It also means one DLL covers both XInput and DirectInput.
  • Loader lock: the DLL does no real work in DllMain; SDL and the hooks are initialised lazily on first use.

Limitations

  • Not implemented: XInputGetKeystroke (returns ERROR_EMPTY), audio device GUIDs, headset, real battery levels.
  • Games that detect Xbox pads through Raw Input / HID device paths (IG_) or load XInput by absolute path bypass this approach.
  • DirectInput hiding only covers DirectInput 8. Older DirectInput (dinput.dll), Raw Input, HID, WGI and SDL/GLFW running inside the game are not filtered.
  • Inline hooks can conflict with other software that hooks the same functions (overlays, other wrappers, injectors).
  • Do not use with online games / anti-cheat; DLL replacement and inline hooking are commonly flagged and may get you banned. Intended for single-player use.
  • Windows only.

Troubleshooting

Symptom Likely cause
Game ignores the DLL Wrong DLL name or bitness; check imports
Game crashes at start SDL3.dll missing/wrong bitness next to the exe, or a conflicting hook from another tool
Pad not detected Check it in xinput_test.exe; add a mapping to gamecontrollerdb.txt
Buttons mis-mapped Fix SDL mapping, or set SwapAB=1
No rumble Pad/driver lacks SDL rumble support; check Rumble=1
Pad appears twice / duplicate input Confirm the game uses DirectInput 8 and loads your XInput DLL (hooks come with it)
Pad still seen via DirectInput Game uses old dinput.dll, Raw Input, or its own SDL (see Limitations)
Game loses its keyboard/mouse Should not happen; enable Debug=1 and check which device was filtered
Need logs Debug=1 + DebugView (prefix [xinput-sdl])

License

MIT, see LICENSE.

About

XInput interface for SDL controllers.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages