Documentation

Linux Permission Denied - /dev/input/event*

On Linux, you may encounter "Permission denied" errors when trying to access gamepad devices. This is because the /dev/input/event* files require special permissions.

Solution: Add your user to the input group:

# Add user to input group
sudo usermod -a -G input $USER

# Log out and log back in for changes to take effect
# Or temporarily run with sudo for testing

Alternative: Run your application with elevated privileges (not recommended for production):

sudo java -jar your-game.jar

For Wayland users on KDE Plasma or other modern desktop environments, you may also need to ensure gamepad permissions are correctly configured in the system settings.

What Java version is required?

input4j requires Java 22 or later because it uses the Foreign Function & Memory API (FFM API) for native system calls. The FFM API was standardized in Java 22.

Make sure you're using a JDK distribution that includes the FFM API, such as:

• Oracle JDK 21+
• OpenJDK 21+
• Amazon Corretto 21+
• Azul Zulu JDK 21+

Does input4j work with game engines?

Yes! input4j is designed to work with any Java game engine or framework, including:

• LITIENGINE - The pure Java 2D game engine
• LibGDX - Popular cross-platform game framework
• JavaFX - Desktop application framework
• Slick2D - 2D game library
• Custom engines - Use input4j directly in your game loop

The library is framework-agnostic and provides a clean API that integrates easily with any input handling pattern.

Which game controllers are supported?

input4j supports a wide variety of game controllers across all platforms:

• Xbox controllers - Xbox One, Series X/S (via XInput on Windows)
• PlayStation controllers - DualShock 4, DualSense (via HID)
• Generic USB gamepads - Any HID-compliant controller
• Joysticks - Flight sticks, racing wheels, and specialized input devices

On Linux, the library uses the evdev interface which supports all HID-compliant devices. On macOS, IOKit provides broad controller compatibility.

Why no native DLL/SO files?

Unlike other Java input libraries that rely on JNI (Java Native Interface) and require native .dll, .so, or .dylib files, input4j uses the Foreign Function & Memory API. This allows direct calls to native functions without the overhead and complexity of JNI.

Benefits include:

• Simpler deployment - just add the JAR to your classpath
• No native library distribution headaches
• Better compatibility with Java's security model
• Type-safe native function calls at compile time

Can I use input4j for keyboard/mouse input?

input4j is specifically designed for gamepad and joystick input. For keyboard and mouse handling, use the native APIs provided by your game engine or framework:

• Java AWT/Swing KeyListener and MouseListener
• JavaFX input events
• LibGDX input API
• LITIENGINE input handling

How do I handle controller disconnects?

input4j provides device connection callbacks. Here's how to handle controller hot-plugging:

// Listen for device connections
InputDevices.onDeviceConnected(device -> {
    System.out.println("Controller connected: " + device.getName());
});

// Listen for disconnections  
device.onDisconnected(() -> {
    System.out.println("Controller disconnected!");
});