Bevy Input

There are two ways to handle input in Bevy:

1. Reacting to the events emitted automatically by Bevy's input systems
2. Querying a resource like ButtonInput, Axis, Touches or Gamepads

Events are useful to handle many types of input at the same time, which can be useful for ordering the input relatively within the same frame.

Events help us create logic such as:

Run this system every time ANY key is pressed

Resources on the other hand, give us more control over the type of input state. Reading events can be too broad when we want to trigger state specific logic like:

Make my character jump anytime the SPACE key has just been pressed

Bevy has a different resource for each type of input:

There are some useful libraries for managing your inputs:

• leafwing-input-manager
• bevy_pancam
• bevy_mod_picking

Bevy has decided to upstream both the leafwing-input-manager and bevy_mod_picking eventually in a future version.

Keyboard

To handle keyboard input we 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, and others are calling ButtonInput<T>::press or ButtonInput<T>::release to trigger the events for that particular input type.

These get added to the ButtonInput<T> resource and are read to check if something was pressed or not.

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

fn keyboard_system(mut keyboard_events: EventReader<KeyboardInput>) {
  for event in keyboard_events.read() {
    println!(
      "KeyCode: {:?} ScanCode {:?}",
      event.key_code, event.logical_key
    );
  }
}

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

fn jump_system(input: Res<ButtonInput<KeyCode>>) {
  if input.just_pressed(KeyCode::Space) {
    // Jumping!
  }
}

Physical vs logical keys

Keyboard input has two separate fields representing the key:

pub struct KeyboardInput {
  pub key_code: KeyCode,
  pub logical_key: Key,
  pub state: ButtonState,
  pub window: Entity,
}

• The key_code represents the physical location of a key
• 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:

// This system prints when `Ctrl + Shift + A` is pressed
fn keyboard_input_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!("Just pressed 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:

fn shooting_system(mouse_button_input: Res<ButtonInput<MouseButton>>) {
  if mouse_button_input.just_pressed(MouseButton::Left) {
    // Start firing bullets
  }

  if mouse_button_input.pressed(MouseButton::Left) {
    // Continue firing bullets
  }

  if mouse_button_input.just_released(MouseButton::Left) {
    // Stop firing bullets
  }
}

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

fn listen_to_all_mouse_based_events(
  mut mouse_button_input_events: EventReader<MouseButtonInput>,
  mut mouse_motion_events: EventReader<MouseMotion>,
  mut cursor_moved_events: EventReader<CursorMoved>,
  mut mouse_wheel_events: EventReader<MouseWheel>,
  mut pinch_gesture_events: EventReader<PinchGesture>,
  mut rotation_gesture_events: EventReader<RotationGesture>,
) {
  for event in mouse_button_input_events.read() {
    info!("{:?}", event);
  }

  for event in mouse_motion_events.read() {
    info!("{:?}", event);
  }

  for event in cursor_moved_events.read() {
    info!("{:?}", event);
  }

  for event in mouse_wheel_events.read() {
    info!("{:?}", event);
  }

  // This event will only fire on macOS
  for event in pinch_gesture_events.read() {
    info!("{:?}", event);
  }

  // This event will only fire on macOS
  for event in rotation_gesture_events.read() {
    info!("{:?}", event);
  }
}

Touch

Touches represent a users interaction with a touchscreen enabled device.

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

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

fn touch_system(touches: Res<Touches>) {
  for touch in touches.iter_just_pressed() {
    info!(
      "just pressed touch with id: {:?}, at: {:?}",
      touch.id(),
      touch.position()
    );
  }

  for touch in touches.iter_just_released() {
    info!(
      "just released touch with id: {:?}, at: {:?}",
      touch.id(),
      touch.position()
    );
  }

  for touch in touches.iter_just_canceled() {
    info!("canceled touch with id: {:?}", touch.id());
  }

  // you can also iterate all current touches and retrieve their state like this:
  for touch in touches.iter() {
    info!("active touch: {:?}", touch);
    info!("  just_pressed: {}", touches.just_pressed(touch.id()));
  }
}

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

fn touch_event_system(mut touch_events: EventReader<TouchInput>) {
  for event in touch_events.read() {
    info!("{:?}", event);
  }
}

Gamepads

Gamepads will be changing in Bevy 0.15 to unify keyboard and gamepad APIs. This will be updated with the breaking changes when it's released.

Each Gamepad is assigned a unique ID so we can associate them with the input from a specific player. We can list these IDs by asking the Gamepads resource:

fn gamepad_system(
  gamepads: Res<Gamepads>,
  button_inputs: Res<ButtonInput<GamepadButton>>,
) {
  for gamepad in gamepads.iter() {
    let button = GamepadButton::new(gamepad, GamepadButtonType::South);
    if button_inputs.just_pressed(button) {
      // ...
    }
  }
}

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

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

fn gamepad_events(
    mut gamepad_connection_events: EventReader<GamepadConnectionEvent>,
    mut gamepad_axis_events: EventReader<GamepadAxisChangedEvent>,
    mut gamepad_button_events: EventReader<GamepadButtonChangedEvent>,
) {
    for event in gamepad_connection_events.read() {
        // ...
    }

    for event in gamepad_axis_events.read() {
        // ...
    }

    for event in gamepad_button_events.read() {
        // ...
    }
}

The problem with reading events 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.

To ensure in-frame ordering we can read from the more general GamepadEvent and switch on the type:

fn gamepad_ordered_events(mut gamepad_events: EventReader<GamepadEvent>) {
  for gamepad_event in gamepad_events.read() {
    match gamepad_event {
      GamepadEvent::Connection(connection_event) => {
        info!("{:?}", connection_event)
      }
      GamepadEvent::Button(button_event) => info!("{:?}", button_event),
      GamepadEvent::Axis(axis_event) => info!("{:?}", axis_event),
    }
  }
}

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),
}

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

fn gamepad_system_with_rumble(
  gamepads: Res<Gamepads>,
  button_inputs: Res<ButtonInput<GamepadButton>>,
  mut rumble_requests: EventWriter<GamepadRumbleRequest>,
) {
  for gamepad in gamepads.iter() {
    // ...
    rumble_requests.send(GamepadRumbleRequest::Add {
      gamepad,
      intensity: GamepadRumbleIntensity::strong_motor(0.1),
      duration: Duration::from_secs(5),
    });
  }
}

The GamepadRumbleRequest::Add event 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.

Rumble features are provided by the bevy_gltf crate.

Window

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

Before 0.14 Bevy had a ReceivedCharacter event that was sent by the winit library that looked like this:

// This system prints out all char events as they come in
// ReceivedCharacter comes from `bevy_window` not `bevy_input`
fn print_characters_pressed(
  mut events: EventReader<ReceivedCharacter>
) {
  for event in events.read() {
    info!("{:?}: '{}'", event, event.char);
  }
}

However this has been deprecated while winit overhauls their keyboard system.

The better alternative that has better cross platform support is to listen for KeyboardInput and use the logical_key:

// Listening to every keyboard event
fn keyboard_system(mut keyboard_events: EventReader<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: EventReader<CursorMoved>) {
  for ev in cursor_evr.read() {
    println!(
      "New cursor position: X: {}, Y: {}, in Window ID: {:?}",
      ev.position.x, ev.position.y, ev.window
    );
  }
}