Gamepad
Gamepads are entities with a Gamepad component. Read buttons, triggers and sticks, react to connections, tune dead zones and make a gamepad rumble.
Each connected gamepad is an entity with a Gamepad component and a Name (the name the operating system gives it). Query for Gamepad to read it; there's no global gamepad resource, so local multiplayer works the same way as one player.
Gamepad support is on in NEO's builds on the desktop and the web (the browser's Gamepad API). Phones and tablets use touch controls instead; see Touch.
Buttons and sticks#
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Update, read_gamepads)
.run();
}
fn read_gamepads(gamepads: Query<(Entity, &Name, &Gamepad)>) {
for (entity, name, gamepad) in &gamepads {
if gamepad.just_pressed(GamepadButton::South) {
info!("{name} ({entity}) pressed South");
}
let stick = gamepad.left_stick();
if stick.length() > 0.1 {
info!("move {stick}");
}
let throttle = gamepad.get(GamepadButton::RightTrigger2).unwrap_or(0.0);
if throttle > 0.0 {
info!("throttle {throttle}");
}
}
}| Method | Returns |
|---|---|
pressed(b), just_pressed(b), just_released(b) | A button's digital state, like ButtonInput. |
get(input) | An axis or a button's analog value: -1.0..=1.0 for sticks, 0.0..=1.0 for buttons and triggers. None if the gamepad doesn't have it. |
left_stick(), right_stick(), dpad() | A Vec2 for each stick and the D-pad. |
digital(), analog() | The underlying ButtonInput<GamepadButton> and Axis<GamepadInput>. |
vendor_id(), product_id() | The USB ids, when the platform reports them. |
Buttons are named by position, so the same code works on every controller:
GamepadButton | Xbox | PlayStation |
|---|---|---|
South, East, West, North | A, B, X, Y | Cross, Circle, Square, Triangle |
LeftTrigger, RightTrigger | LB, RB | L1, R1 |
LeftTrigger2, RightTrigger2 | LT, RT | L2, R2 |
LeftThumb, RightThumb | Stick presses | L3, R3 |
Select, Start, Mode | View, Menu, Guide | Share, Options, PS |
DPadUp, DPadDown, DPadLeft, DPadRight | D-pad | D-pad |
Axes are LeftStickX, LeftStickY, RightStickX, RightStickY, LeftZ, RightZ and Other(n).
Connections#
When a gamepad connects, the engine spawns its entity and inserts Gamepad and Name. When it disconnects, it removes Gamepad but keeps the entity, so a pad that reconnects keeps its settings. Read GamepadConnectionEvent messages to react:
use neo::input::gamepad::{GamepadConnection, GamepadConnectionEvent};
fn connections(mut events: MessageReader<GamepadConnectionEvent>) {
for event in events.read() {
match &event.connection {
GamepadConnection::Connected { name, .. } => info!("{name} connected as {}", event.gamepad),
GamepadConnection::Disconnected => info!("{} disconnected", event.gamepad),
}
}
}GamepadButtonChangedEvent, GamepadAxisChangedEvent and GamepadButtonStateChangedEvent report each change, and GamepadEvent carries all of them in order.
Dead zones and thresholds#
Every gamepad entity also has a GamepadSettings component (it's required by Gamepad). It decides when an analog value counts:
| Field | What it holds |
|---|---|
default_axis_settings | An AxisSettings: the dead zone (values near zero become 0.0; default ±0.05), the live zone and a change threshold. |
default_button_settings | A ButtonSettings: the press threshold (default 0.75) and release threshold (default 0.65) that turn an analog button into pressed or released. |
axis_settings, button_settings | Per-axis and per-button overrides. |
use neo::input::gamepad::GamepadSettings;
fn wider_dead_zone(mut settings: Query<&mut GamepadSettings, Added<GamepadSettings>>) {
for mut s in &mut settings {
s.default_axis_settings.set_deadzone_upperbound(0.15);
s.default_axis_settings.set_deadzone_lowerbound(-0.15);
}
}Rumble#
Write a GamepadRumbleRequest message to make a gamepad vibrate. Requests add up while they overlap.
use core::time::Duration;
use neo::input::gamepad::{GamepadRumbleIntensity, GamepadRumbleRequest};
fn rumble(gamepads: Query<(Entity, &Gamepad)>, mut rumble: MessageWriter<GamepadRumbleRequest>) {
for (entity, gamepad) in &gamepads {
if gamepad.just_pressed(GamepadButton::East) {
rumble.write(GamepadRumbleRequest::Add {
gamepad: entity,
intensity: GamepadRumbleIntensity::strong_motor(0.5),
duration: Duration::from_millis(300),
});
}
if gamepad.just_pressed(GamepadButton::Start) {
rumble.write(GamepadRumbleRequest::Stop { gamepad: entity });
}
}
}GamepadRumbleIntensity has strong_motor(x), weak_motor(x), MAX, or set strong_motor and weak_motor yourself. If the platform can't rumble a gamepad, nothing happens and the engine logs a warning.
Examples: cargo run --example gamepad_input, gamepad_input_events and gamepad_rumble.