Keyboard
Read keys with ButtonInput<KeyCode> and ButtonInput<Key>, combine modifiers, and read typed text from KeyboardInput messages.
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#
| Resource | Keys by | Use 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. |
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.
| Method | Returns |
|---|---|
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:
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:
| Field | What it is |
|---|---|
key_code | The physical KeyCode. |
logical_key | The layout's Key. |
state | ButtonState::Pressed or ButtonState::Released. state.is_pressed() tests it. |
text | The text the press produced, if any. It handles dead keys, so it can be two characters. |
repeat | true when the system's key repeat generated the press. |
window | The window that received it. |
Read typed characters like this:
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:
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.