Bevy Input

Bevy provides two main ways to handle input:

1. Reading messages emitted automatically by Bevy's input systems
2. Polling a resource like ButtonInput, Axis, Touches or Gamepads

However, in practice most people would reach for something like bevy_enhanced_input which provides a 3rd, better way of handling input through observers.

Broadly, resources can be more useful when combining many inputs rather than reacting to a single one. You can accomplish anything with these 3 input styles.

Keyboard

To handle keyboard input we can use the ButtonInput<T> resource which has a set of convenient methods we can use to trigger behavior:

Internally, Bevy has builtin systems like keyboard_input_system, mouse_button_input_system. These input systems are reacting to events to set the state of these resources.

We can read these events in general by listening to KeyboardInput messages:

/// Track keyboard inputs — useful for debugging or keybinding tools
fn log_keyboard_input(mut keyboard_events: MessageReader<KeyboardInput>) {
  for event in keyboard_events.read() {
    println!(
      "Key pressed: {:?}, logical key: {:?}",
      event.key_code, event.logical_key
    );
  }
}

Or we can poll the resource to check for a more specific state:

/// Handle player jump
fn jump_input_system(input: Res<ButtonInput<KeyCode>>) {
  if input.just_pressed(KeyCode::Space) {
    info!("Jump!");
  }
}

Physical vs logical keys

Keyboard input has two separate fields representing the key:

// https://docs.rs/bevy/latest/bevy/input/keyboard/struct.KeyboardInput.html
pub struct KeyboardInput {
  pub key_code: KeyCode,
  pub logical_key: Key,
  pub state: ButtonState,
  pub text: Option<SmolStr>,
  pub repeat: bool,
  pub window: Entity,
}

The key_code represents the physical location of a key, while the logical_key is the mapping from this physical key to the winit key.

This is so we can have our physical keys mapped to alternative logical keys.

Bevy encourages us to use physical keys over logical keys. For example rebinding ESC to CAPS. The physical key would remain the same but the logical key would be different.

One example of this difference can would be if you are creating a text editor. If you listened to KeyboardInput events like before, using the key code might output gibberish if they used a different layout.

Modifiers

We can handle modifiers like shift or alt by checking for them before our key and set local variables to modify the input:

/// Handle combos or hotkeys, e.g., casting special ability
fn combo_key_system(input: Res<ButtonInput<KeyCode>>) {
  let shift = input.any_pressed([KeyCode::ShiftLeft, KeyCode::ShiftRight]);
  let ctrl = input.any_pressed([KeyCode::ControlLeft, KeyCode::ControlRight]);

  if ctrl && shift && input.just_pressed(KeyCode::KeyA) {
    info!("Special ability activated! (Ctrl + Shift + A)");
  }
}

Mouse

The mouse is handled in exactly the same way as your keyboard. Both the right and left clicks are combined in the ButtonInput<MouseButton> type:

/// Fire weapon using mouse input — standard FPS/twin-stick shooter logic
fn shoot_input_system(mouse: Res<ButtonInput<MouseButton>>) {
  if mouse.just_pressed(MouseButton::Left) {
    info!("Bang! Weapon fired.");
  }

  if mouse.pressed(MouseButton::Left) {
    info!("Holding trigger... continuing fire.");
  }

  if mouse.just_released(MouseButton::Left) {
    info!("Stopped firing.");
  }
}

For movement, mouse wheel and touchpad based inputs we don't use a resource but listen to the messages directly:

/// Track all mouse interactions — could power a UI system or camera control
fn mouse_debug_system(
  mut button_events: MessageReader<MouseButtonInput>,
  mut motion_events: MessageReader<MouseMotion>,
  mut cursor_events: MessageReader<CursorMoved>,
  mut wheel_events: MessageReader<MouseWheel>,
  mut pinch_events: MessageReader<PinchGesture>,
  mut rotation_events: MessageReader<RotationGesture>,
) {
  for event in button_events.read() {
    info!("Mouse button event: {:?}", event);
  }
  for event in motion_events.read() {
    info!("Mouse moved: {:?}", event);
  }
  for event in cursor_events.read() {
    info!("Cursor moved: {:?}", event);
  }
  for event in wheel_events.read() {
    info!("Mouse wheel used: {:?}", event);
  }
  for event in pinch_events.read() {
    info!("Pinch gesture detected (macOS only): {:?}", event);
  }
  for event in rotation_events.read() {
    info!("Rotation gesture detected (macOS only): {:?}", event);
  }
}

For finer grained control over scrolling we can use check the MouseWheel event's unit type:

use bevy::input::mouse::MouseScrollUnit;

// Fine grained control over mouse wheel events
fn scroll_events(mut events: MessageReader<MouseWheel>) {
  for event in events.read() {
    match event.unit {
      MouseScrollUnit::Line => {
        info!(
          "Scroll (line units): vertical: {}, horizontal: {}",
          event.y, event.x
        );
      }
      MouseScrollUnit::Pixel => {
        info!(
          "Scroll (pixel units): vertical: {}, horizontal: {}",
          event.y, event.x
        );
      }
    }
  }
}

Touch

Touches represent a users interaction with a touchscreen enabled device.

When a user first touches their screen a TouchPhase::Started message is sent with a unique ID. When the user lifts their finger a matching TouchPhase::Ended message is sent with that same ID.

During movement, many TouchPhase::Moved messages are sent, or if the iOS screen changes a TouchPhase::Canceled is sent with the same ID matching system.

/// Handle touchscreen taps — perfect for mobile games
fn touch_input_system(touches: Res<Touches>) {
  for touch in touches.iter_just_pressed() {
    info!("Screen tapped at {:?}", touch.position());
  }
  for touch in touches.iter_just_released() {
    info!("Touch ended at {:?}", touch.position());
  }
  for touch in touches.iter_just_canceled() {
    info!("Touch canceled: {:?}", touch.id());
  }
  for touch in touches.iter() {
    info!("Ongoing touch at {:?}", touch.position());
  }
}

Touches also have messages representing any kind of touch input actions:

/// Lower-level touch events — for finer-grained control
fn raw_touch_event_system(mut touch_events: MessageReader<TouchInput>) {
  for event in touch_events.read() {
    info!("Raw touch input: {:?}", event);
  }
}

Gamepads

Gamepads have changed in Bevy 0.15 to unify keyboard and gamepad APIs.

Bevy uses the gilrs crate to handle gamepads.

Each Gamepad is assigned a unique ID so we can associate them with the input from a specific player.

fn gamepad_system(
  gamepads: Query<&Gamepad>,
  button_inputs: Res<ButtonInput<GamepadButton>>,
) {
  for gamepad in &gamepads {
    if button_inputs.just_pressed(GamepadButton::South) {
      // ...
    }
  }
}

Notice that gamepads also use a ButtonInput and have access to the same pressed, just_pressed and just_released methods.

Gamepad events

We have gamepad specific messages we can read such as when a player connects their controller or presses a button:

/// Detect connection, axis, and button changes individually
fn separate_gamepad_event_readers(
  mut connect_events: MessageReader<GamepadConnectionEvent>,
  mut axis_events: MessageReader<GamepadAxisChangedEvent>,
  mut button_events: MessageReader<GamepadButtonChangedEvent>,
) {
  for event in connect_events.read() {
    info!("Gamepad connection: {:?}", event);
  }
  for event in axis_events.read() {
    info!("Analog stick moved: {:?}", event);
  }
  for event in button_events.read() {
    info!("Button changed: {:?}", event);
  }
}

The problem with reading messages like this is that they will be potentially out of order. For example if the player A and then held down within the same frame, the above system would read them out of order.

If you care about ordering you would want to read the GamepadEvent and react to the message types. Bevy is going to use your GamepadSettings to filter messages for you. Most of these settings hold thresholds and limits for button presses and axis changes.

/// Read all gamepad events in one go — ideal for analytics or debugging
fn unified_gamepad_event_reader(
  mut gamepad_events: MessageReader<GamepadEvent>,
) {
  for event in gamepad_events.read() {
    match event {
      GamepadEvent::Connection(e) => info!("Gamepad connection: {:?}", e),
      GamepadEvent::Button(e) => info!("Gamepad button event: {:?}", e),
      GamepadEvent::Axis(e) => info!("Gamepad axis event: {:?}", e),
    }
  }
}

This solves whether we pressed A and then X as these will be read in the correct order now.

However, between these different message types this system won't fully respect in-frame relative ordering. Meaning that if you care about whether a GamepadEvent::Button happened before a GamepadEvent::Axis then you might not be able to rely on these messages.

Instead you can use the equivalent RawGamepadEvent type and filter the messages yourself.

Gamepad axis

Gamepads use a slightly different system with an Axis<T> resource. Axis<GamepadAxis> represents the different types of axis we have available on our controllers:

pub enum GamepadAxisType {
  // The horizontal value of the left stick.
  LeftStickX,
  // The vertical value of the left stick.
  LeftStickY,
  // The value of the left `Z` button.
  LeftZ,
  // The horizontal value of the right stick.
  RightStickX,
  // The vertical value of the right stick.
  RightStickY,
  // The value of the right `Z` button.
  RightZ,
  // Non-standard support for other axis
  // types (i.e. HOTAS sliders, potentiometers, etc).
  Other(u8),
}

Gamepad haptics

You can add haptic feedback by writing messages to request it:

/// Provide rumble feedback — simulate an explosion or impact
fn rumble_feedback_system(
  gamepads: Query<(Entity, &Gamepad)>,
  mut rumble_writer: MessageWriter<GamepadRumbleRequest>,
) {
  for (entity, gamepad) in &gamepads {
    if gamepad.just_pressed(GamepadButton::RightTrigger2) {
      let event = GamepadRumbleRequest::Add {
        gamepad: entity,
        intensity: GamepadRumbleIntensity::strong_motor(0.5),
        duration: Duration::from_millis(300),
      };

      rumble_writer.write(event);

      info!("Rumble triggered!");
    }
  }
}

The GamepadRumbleRequest::Add message triggers a force-feedback motor, controlling how long the vibration should last, the motor to activate, and the vibration strength. GamepadRumbleRequest::Stop immediately stops all motors.

Window

There are also messages that come from the bevy_window that are related to input and may also be used to trigger your game logic.

For example we can listen to KeyboardInput messages to get the logical_key that was pressed:

/// Listening to every keyboard message
fn keyboard_system(mut keyboard_events: MessageReader<KeyboardInput>) {
  for event in keyboard_events.read() {
    println!(
      "KeyCode: {:?} ScanCode {:?}",
      event.key_code, event.logical_key
    );
  }
}

Mouse events such as CursorMoved are also sent from the window itself:

fn cursor_events(mut cursor_evr: MessageReader<CursorMoved>) {
  for ev in cursor_evr.read() {
    println!(
      "New cursor position: X: {}, Y: {}, in Window ID: {:?}",
      ev.position.x, ev.position.y, ev.window
    );
  }
}

Bevy enhanced input

There is some gotchas when it comes to input handling that can be troublesome for those starting out.

If you use avian and you run your input handling in an Update schedule, you will run into some frame issues because avian is running in FixedUpdate schedule which runs before that.

There are other common issues that can be eliminated by making your inputs observers which trigger their behavior right away on certain events instead of in a specific schedule and so are less susceptible to scheduling issues.

There is an awesome library that will do this for you and is likely to be upstreamed by Bevy in the future: bevy_enhanced_input.

It allows us to define a set of actions that will produce event when their bindings are fired:

pub fn add_car_controls(event: On<Add, Car>, mut commands: Commands) {
  commands.entity(event.event_target()).insert(actions!(Car[
    (
      Action::<AirRollLeftAction>::new(),
      bindings![KeyCode::KeyQ, GamepadButton::East],
    ),
    (
      Action::<AirRollRightAction>::new(),
      bindings![KeyCode::KeyE, GamepadButton::West],
    ),
  ]));
}

Then we can use observers to react to different parts of the lifecycle of a button press:

pub fn on_air_roll_left(
  event: On<Fire<AirRollLeftAction>>,
  mut cars: Query<
    (&Car, &Transform, &mut AngularVelocity),
    (Without<Dodging>, With<Jumping>),
  >,
) {
  let Ok((car, transform, mut angular_velocity)) = cars.get_mut(event.context) else {
    return;
  };

  let forward = *transform.forward();
  let current_roll = angular_velocity.0.dot(forward);
  let target_roll = -car.air_roll_rate;

  angular_velocity.0 += forward * (target_roll - current_roll);
}