Crate gamepads

source ·
Expand description

Library providing information about connected gamepads.

Overview

To use gamepads, first create a Gamepads instance using Gamepads::new().

Then, on each tick, run Gamepads::poll() to poll gamepad state, followed by Gamepads::all() or Gamepads::get() to retrieve information about connected gamepads. See Gamepad for how to access button and axis information on gamepads.

Usage

The gamepads crate is on crates.io and can be used by adding gamepads to your dependencies in your project’s Cargo.toml. Or more simply, just run cargo add gamepads.

Here is a complete example that creates a new Rust project, adds a dependency on gamepads, creates the source code printing gamepad information, and then runs the program.

First, create the project in a new directory:

$ mkdir gamepads-example
$ cd gamepads-example
$ cargo init

Second, add a dependency on gamepads:

$ cargo add gamepads

Third, edit src/main.rs. Delete what’s there and replace it with this:

use gamepads::Gamepads;

fn main() {
    let mut gamepads = Gamepads::new();
    loop {
        gamepads.poll();

        for gamepad in gamepads.all() {
            println!("Gamepad id: {:?}", gamepad.id());
            for button in gamepad.all_currently_pressed() {
                println!("Pressed button: {:?}", button);
            }
            println!("Left thumbstick: {:?}", gamepad.left_stick());
            println!("Right thumbstick: {:?}", gamepad.right_stick());
        }

        std::thread::sleep(std::time::Duration::from_millis(500));
   }
}

Fourth, run it with cargo run:

$ cargo run
[...]
Gamepad id: GamepadId(0)
Pressed button: ActionRight
Pressed button: ActionTop
Left thumbstick: (0.3252289, -0.98961794)
Right thumbstick: (0.0, 0.0)

Usage as a macroquad web plugin

See the documentation in the README for how to use gamepads with macroquad.

Example showing gamepad iteration

use gamepads::{Button, Gamepads};

let mut gamepads = Gamepads::new();

loop {
    gamepads.poll();

    for gamepad in gamepads.all() {
        // Use just_pressed_buttons() or currently_pressed_buttons().
        for button in gamepad.all_just_pressed() {
            println!("Button just pressed: {button:?}");
            match button {
                Button::DPadUp => println!("Going up!"),
                Button::ActionDown => println!("Shooting!"),
                _ => {}
            }

            // Individual buttons can be checked using
            // is_just_pressed() / is_currently_pressed():
            if gamepad.is_currently_pressed(Button::FrontLeftLower) {
                println!("Front left lower button is currently pressed");
            }
        }
         
        println!("Left stick: {:?}", gamepad.left_stick());
        println!("Right stick: {:?}", gamepad.right_stick());
    }
}

Example showing gamepad lookup by id and haptic feedback

use std::collections::HashMap;
use gamepads::{Button, Gamepads, GamepadId};

struct Player {
    position: (f32, f32),
}

let mut gamepads = Gamepads::new();
let mut players: HashMap<GamepadId, Player> = HashMap::new();
loop {
    gamepads.poll();

    for gamepad in gamepads.all() {
        if let Some(player) = players.get_mut(&gamepad.id()) {
            player.position.0 += gamepad.left_stick_x();
            player.position.1 += gamepad.left_stick_y();
            if player.position.0.abs() > 10. {
                // Player has fallen out of map - give haptic feedback.
                gamepads.rumble(gamepad.id(), 500, 0, 0.4, 0.6);
                player.position.0 = 0.;
            }
        } else if gamepad.is_currently_pressed(Button::ActionDown) {
            println!("New player joining with gamepad {:?}", gamepad.id());
            players.insert(gamepad.id(), Player { position: (0., 0.) });
        }
    }
}

Structs

  • Gamepad
    An individual gamepad allowing access to information about button presses, thumbstick positions and its gamepad id.
  • GamepadId
    An opaque gamepad identifier.
  • Gamepads
    Context for obtaining gamepad information.

Enums