libgdx-controllers

libGDX gdx-controllers Extension (2.x)

Reference for the gdx-controllers 2.x extension — controller discovery, input polling, event-driven input, cross-controller mapping, and common patterns.

This covers gdx-controllers 2.x (the current standalone extension). The old 1.x API bundled with libGDX core is deprecated and has a completely different interface. Do NOT use the old API.

1.x vs 2.x — Critical Differences

	Old 1.x (DEPRECATED)	New 2.x (USE THIS)
Gradle group	com.badlogic.gdx:gdx-controllers	com.badlogicgames.gdx-controllers:gdx-controllers-core
ControllerListener	8 methods: povMoved, xSliderMoved, ySliderMoved, accelerometerMoved, etc.	5 methods only: connected, disconnected, buttonDown, buttonUp, axisMoved
Mapping	None — hardcode button numbers	controller.getMapping() → ControllerMapping
D-pad	PovDirection enum	Buttons via mapping.buttonDpadUp/Down/Left/Right
Package	com.badlogic.gdx.controllers	com.badlogic.gdx.controllers (same package, different artifact)

If you see PovDirection, xSliderMoved, ySliderMoved, or accelerometerMoved — that's the old 1.x API. Stop and switch to 2.x.

Gradle Dependencies

// In gradle.properties:
controllersVersion=2.2.5

// core module:
implementation "com.badlogicgames.gdx-controllers:gdx-controllers-core:$controllersVersion"

// desktop (lwjgl3) module:
implementation "com.badlogicgames.gdx-controllers:gdx-controllers-desktop:$controllersVersion"

// android module:
implementation "com.badlogicgames.gdx-controllers:gdx-controllers-android:$controllersVersion"

// ios module:
implementation "com.badlogicgames.gdx-controllers:gdx-controllers-ios:$controllersVersion"

The group ID is com.badlogicgames.gdx-controllers, NOT com.badlogic.gdx. The old com.badlogic.gdx:gdx-controllers is the deprecated 1.x API.

Controller Discovery

// Get all currently connected controllers
Array<Controller> controllers = Controllers.getControllers();

// Never assume a controller is available at startup
if (controllers.size > 0) {
    Controller controller = controllers.first();
    Gdx.app.log("Input", "Found: " + controller.getName());
}