37 releases
0.11.0 | Sep 15, 2024 |
---|---|
0.10.9 | Jul 28, 2024 |
0.10.6 | Mar 16, 2024 |
0.10.4 | Dec 3, 2023 |
0.3.1 | Sep 23, 2016 |
#6 in Game dev
110,521 downloads per month
Used in 158 crates
(50 directly)
380KB
9K
SLoC
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 ID for new gamepads and reuse the same ID for gamepads which reconnected
- Force feedback (rumble)
- Power information (is gamepad wired, current battery status)
The project's main repository is on GitLab although there is also a GitHub mirror. Please use GitLab's issue tracker and merge requests.
This repository contains submodule; after you clone it, don't forget to run
git submodule init; git submodule update
(or clone with --recursive
flag)
or you will get compile errors.
Example
[dependencies]
gilrs = "0.11.0"
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 (XInput) | ✓ | ✓ | ✓ |
OS X | ✓ | ✓ | ✕ |
Wasm | ✓ | ✓ | n/a |
Android | ✕ | ✕ | ✕ |
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).
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()
.
See ./gilrs/examples/wasm/README.md
for running the examples using Wasm.
License
This project is licensed under the terms of both the Apache License (Version 2.0) and the MIT license. See LICENSE-APACHE and LICENSE-MIT for details.
Dependencies
~0.3–25MB
~356K SLoC