NEOLearn

Keyboard

Read keys with ButtonInput<KeyCode> and ButtonInput<Key>, combine modifiers, and read typed text from KeyboardInput messages.

Updated October 20, 2026

On this page

The engine tracks every key in two resources, one by where the key is and one by what it types, and sends a KeyboardInput message for each press and release. Use the resources for gameplay and the messages for text.

Physical keys and logical keys#

ResourceKeys byUse it for
ButtonInput<KeyCode>Position on the keyboard. KeyCode::KeyW is the key where W is on a US layout, whatever the layout says.Movement and other controls that should stay in the same place on every layout (WASD is ZQSD on an AZERTY keyboard).
ButtonInput<Key>What the key means on the player's layout: Key::Character("?".into()), Key::Enter, Key::Escape.Shortcuts tied to a symbol, such as ? for help or + and - for zoom.
src/main.rs
use neo::{input::keyboard::Key, prelude::*};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Update, keys)
        .run();
}

fn keys(codes: Res<ButtonInput<KeyCode>>, keys: Res<ButtonInput<Key>>) {
    if codes.pressed(KeyCode::KeyW) {
        info!("W is held");
    }
    if codes.just_pressed(KeyCode::Space) {
        info!("Space was pressed this frame");
    }
    if codes.just_released(KeyCode::Space) {
        info!("Space was released this frame");
    }
    if keys.just_pressed(Key::Character("?".into())) {
        info!("show help");
    }
}

ButtonInput#

ButtonInput<T> is the same type for keys, mouse buttons and gamepad buttons.

MethodReturns
pressed(k)true while the key is held.
just_pressed(k)true only in the frame it went down.
just_released(k)true only in the frame it went up.
any_pressed([..]), all_pressed([..])Any or all of the keys held.
any_just_pressed([..]), any_just_released([..])Any of the keys changed this frame.
get_pressed(), get_just_pressed(), get_just_released()Iterators over the keys in each state.
clear_just_pressed(k)Consumes a press, so later systems in the frame don't see it. Returns whether it was set.
release_all(), reset_all()Releases everything, or forgets every key's state.

When the window loses keyboard focus (for example on Alt+Tab), the engine releases every held KeyCode, so keys don't stay stuck down.

Modifiers#

There are separate key codes for the left and right Shift, Ctrl, Alt and Super keys. Check both:

Rust
fn shortcut(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!("Ctrl+Shift+A");
    }
}

Keyboard messages and text#

Each press and release is a KeyboardInput message, in the order they happened:

FieldWhat it is
key_codeThe physical KeyCode.
logical_keyThe layout's Key.
stateButtonState::Pressed or ButtonState::Released. state.is_pressed() tests it.
textThe text the press produced, if any. It handles dead keys, so it can be two characters.
repeattrue when the system's key repeat generated the press.
windowThe window that received it.

Read typed characters like this:

Rust
use neo::input::keyboard::{Key, KeyboardInput};

fn typing(mut keys: MessageReader<KeyboardInput>) {
    for key in keys.read() {
        if !key.state.is_pressed() {
            continue;
        }
        if let Key::Character(c) = &key.logical_key {
            info!("typed '{c}'");
        }
    }
}

For a full text box, with a caret and selection, use the UI's text input widget instead; see Widgets. Input from an input method (IME), such as composed Chinese or Japanese text, arrives as Ime messages once Window::ime_enabled is true.

Run conditions#

neo::input::common_conditions has conditions that read ButtonInput for you:

Rust
use neo::input::common_conditions::{input_just_pressed, input_toggle_active};

app.add_systems(Update, (
    screenshot.run_if(input_just_pressed(KeyCode::F12)),
    draw_debug.run_if(input_toggle_active(false, KeyCode::F3)),
));

input_toggle_active(default, key) flips between on and off each time the key is pressed. See Run conditions.

In the browser#

Web builds read the keyboard from the page's canvas. With Window::prevent_default_event_handling set, which the gameplay kit's window does, the game keeps keys from the browser while it has focus, so Space doesn't scroll the page and F1 doesn't open the browser's help.

Examples: cargo run --example keyboard_input, keyboard_modifiers, keyboard_input_events and char_input_events.

Next steps#