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 the 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());
}

let mut active_gamepad = None;

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

    // You can also use cached gamepad state
    if let Some(gamepad) = active_gamepad.map(|id| gilrs.gamepad(id)) {
        if gamepad.is_pressed(Button::South) {
            println!("Button South is pressed (XBox - A, PS - X)");
        }
    }
}

Supported features

	Input	Hotplugging	Force feedback
Linux/BSD (evdev)	✓	✓	✓
Windows	✓	✓	✓
OS X	✓	✓	✕
Wasm	✓	✓	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).

Cargo features

• serde-serialize - enable deriving of serde’s Serialize and Deserialize for various types.
• wgi - use Windows Gaming Input on Windows (enabled by default).
• xinput - use XInput on Windows.

Platform specific notes

Linux/BSD (evdev)

With evdev, 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. On FreeBSD generic HID gamepads use hgame(4) and special use Linux driver via webcamd.

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

Windows

Windows defaults to using Windows Gaming Input instead of XInput. If you need to use XInput you can disable the wgi feature (it’s enabled by default) and enable the xinput feature.

Windows Gaming Input requires an in focus window to be associated with the process to receive events. You can still switch back to using xInput by turning off default features and enabling the xinput feature.

Note: Some (Older?) devices may still report inputs without a window but this is not the case for all devices so if you are writing a terminal based game, use the xinput feature instead.

Wasm

Wasm implementation uses stdweb, or wasm-bindgen with the wasm-bindgen feature. For stdweb, you will need cargo-web to build gilrs for wasm32-unknown-unknown. For wasm-bindgen, you will need the wasm-bindgen cli or a tool like wasm-pack. Unlike other platforms, events are only generated when you call Gilrs::next_event().

Re-exports

pub use crate::ev::filter::Filter;

pub use crate::ev::Axis;

pub use crate::ev::Button;

pub use crate::ev::Event;

pub use crate::ev::EventType;

Modules

ev

Gamepad state and other event related functionality.

ff

Force feedback module.

Structs

ConnectedGamepadsIterator

Iterator over all connected gamepads.

Gamepad

Represents handle to game controller.

GamepadId

Gamepad ID.

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.

Traits

LinuxGamepadExt

Linux specific extension to Gamepad.