Keyboard Input

Relevant official examples: keyboard_input, keyboard_input_events.

This page shows how to handle keyboard keys being pressed and released.

If you are interested in text input, see the Character Input page instead.

Note: Command Key on Mac corresponds to the Super/Windows Key on PC.

Checking Key State

Most commonly, you might be interested in specific known keys and detecting when they are pressed or released. You can check specific Key Codes or Scan Codes using the Input<KeyCode> / Input<ScanCode> resources.

fn keyboard_input(
    keys: Res<Input<KeyCode>>,
) {
    if keys.just_pressed(KeyCode::Space) {
        // Space was pressed
    }
    if keys.just_released(KeyCode::LControl) {
        // Left Ctrl was released
    }
    if keys.pressed(KeyCode::W) {
        // W is being held down
    }
    // we can check multiple at once with `.any_*`
    if keys.any_pressed([KeyCode::LShift, KeyCode::RShift]) {
        // Either the left or right shift are being held down
    }
    if keys.any_just_pressed([KeyCode::Delete, KeyCode::Back]) {
        // Either delete or backspace was just pressed
    }
}

Keyboard Events

To get all keyboard activity, you can use KeyboardInput events:

fn keyboard_events(
    mut key_evr: EventReader<KeyboardInput>,
) {
    use bevy::input::ButtonState;

    for ev in key_evr.iter() {
        match ev.state {
            ButtonState::Pressed => {
                println!("Key press: {:?} ({})", ev.key_code, ev.scan_code);
            }
            ButtonState::Released => {
                println!("Key release: {:?} ({})", ev.key_code, ev.scan_code);
            }
        }
    }
}

These events give you both the Key Code and Scan Code.

Key Codes and Scan Codes

Keyboard keys can be identified by Key Code or Scan Code.

Key Codes represent the logical meaning of each key (usually the symbol/letter, or function it performs). They are dependent on the keyboard layout currently active in the user's OS. Bevy represents them with the KeyCode enum.

Scan Codes represent the physical key on the keyboard, regardless of the system layout. Bevy represents them using ScanCode, which contains an integer ID. The exact value of the integer is meaningless and OS-dependent, but a given physical key on the keyboard will always produce the same value, regardless of the user's language and keyboard layout settings.

Best Practices for Key Bindings

Here is some advice for how to implement user-friendly remappable key-bindings for your game, that can work well for international users or those with non-QWERTY keyboard layouts.

This section assumes that you have implemented some sort of system to allow the user to reconfigure their keybindings. You want to prompt the user to press their preferred key for a given in-game action, so you can store/remember it and later use it for gameplay.

The problem is that, if you simply use Key Codes, then users might accidentally switch their OS keyboard layout mid-game and suddenly have their keyboard not work as expected.

You should detect and store the user's chosen keys using Scan Codes, and use Scan Codes for detecting keyboard input during gameplay.

Key Codes can still be used for UI purposes, like to display the chosen key to the user.