Crate gilrs

GilRs - Game Input Library for Rust

GilRs abstract platform specific APIs to provide unified interfaces for working with gamepads.

Main features:

• Unified gamepad layout—buttons and axes are represented by familiar names
• Support for SDL2 mappings including SDL_GAMECONTROLLERCONFIG environment variable which Steam uses
• Hotplugging—GilRs will try to assign new IDs for new gamepads and reuse same ID for gamepads which reconnected
• Force feedback (rumble)
• Power information (is gamepad wired, current battery status)

Example

use gilrs::{Gilrs, Button, Event};

let mut gilrs = Gilrs::new().unwrap();

// Iterate over all connected gamepads
for (_id, gamepad) in gilrs.gamepads() {
    println!("{} is {:?}", gamepad.name(), gamepad.power_info());
}

loop {
    // Examine new events
    while let Some(Event { id, event, time }) = gilrs.next_event() {
        println!("{:?} New event from {}: {:?}", time, id, event);
    }

    // You can also use cached gamepad state
    if gilrs[0].is_pressed(Button::South) {
        println!("Button South is pressed (XBox - A, PS - X)");
    }
}

Supported features

	Input	Hotplugging	Force feedback
Linux	✓	✓	✓
Windows (XInput)	✓	✓	✓
OS X	✕	✕	✕
Emscripten	✕	✕	n/a
Android	✕	✕	✕

Controller layout

original image by nicefrog

Mappings

GilRs use SDL-compatible controller mappings to fix on Linux legacy drivers that doesn't follow Linux Gamepad API and to provide unified button layout for platforms that doesn't make any guarantees about it. The main source is SDL_GameControllerDB, but library also support loading mappings from environment variable SDL_GAMECONTROLLERCONFIG (which Steam use).

Platform specific notes

Linux

On Linux, GilRs read (and write, in case of force feedback) directly from appropriate /dev/input/event* file. This mean that user have to have read and write access to this file. On most distros it shouldn't be a problem, but if it is, you will have to create udev rule.

To build GilRs, you will need pkg-config and libudev .pc file. On some distributions this file is packaged in separate archive (for example libudev-dev in Debian).

Re-exports

pub use ev::Axis;

pub use ev::Button;

pub use ev::Event;

pub use ev::EventType;

pub use ev::filter::Filter;

Modules

ev	Gamepad state and other event related functionality.
ff	Force feedback module.

Structs

ConnectedGamepadsIterator	Iterator over all connected gamepads.
ConnectedGamepadsMutIterator	Iterator over all connected gamepads.
Gamepad	Represents game controller.
Gilrs	Main object responsible of managing gamepads.
GilrsBuilder	Allow to create Gilrs with customized behaviour.
Mapping	Stores data used to map gamepad buttons and axes.

Enums

Error	Error type which can be returned when creating Gilrs.
MappingError	The error type for functions related to gamepad mapping.
MappingSource	Source of gamepad mappings.
PowerInfo	State of device's power supply.
Status	Status of gamepad's connection.