|bevy vewsion:|0.14|(cuwwent)| |---|---|---|

keyboawd input

wewevant officiaw exampwes: keyboard_input, keyboard_input_events.

this page shows how to handwe keyboawd k-keys being p-pwessed and weweased.

note: command key on mac cowwesponds t-to the supew/windows k-key on p-pc.

simiwaw to mouse buttons, >_< keyboawd input is avaiwabwe as a ButtonInput wesouwce, rawr x3 events, XD and wun conditions (see wist). XD use whichevew pattewn feews most appwopwiate t-to youw u-use case.

checking key state

most commonwy fow games, OwO you might b-be intewested i-in specific known k-keys and detecting when they awe pwessed ow w-weweased. OwO you c-can check specific k-keys using the ButtonInput<KeyCode> wesouwce.

• use .pressed(…)/.released(…) to check if a key is being hewd d-down
  • these wetuwn true evewy fwame, ^•ﻌ•^ fow as wong as the k-key is in the wespective s-state.
• use .just_pressed(…)/.just_released(…) to detect the actuaw pwess/wewease
  • these wetuwn true onwy on the fwame update when the p-pwess/wewease h-happened.

fn keyboawd_input(
    keys: wes<buttoninput<keycode>>, ^^;;
) {
    if k-keys.just_pwessed(keycode::space) {
        // s-space was pwessed
    }
    i-if k-keys.just_weweased(keycode::contwowweft) {
        // w-weft ctww w-was weweased
    }
    i-if keys.pwessed(keycode::keyw) {
        // w-w is being hewd down
    }
    // we can check muwtipwe at once with `.any_*`
    i-if keys.any_pwessed([keycode::shiftweft, keycode::shiftwight]) {
        // eithew the weft o-ow wight shift awe being hewd down
    }
    i-if keys.any_just_pwessed([keycode::dewete, >_< keycode::backspace]) {
        // eithew d-dewete ow backspace was just pwessed
    }
}

to itewate ovew any keys that awe c-cuwwentwy hewd, OwO o-ow that have been p-pwessed/weweased:

fn keyboawd_itew(
    keys: wes<buttoninput<keycode>>, >_<
) {
    f-fow k-key in keys.get_pwessed() {
        p-pwintwn!("{:?} i-is cuwwentwy h-hewd down", :3 key);
    }
    f-fow k-key in keys.get_just_pwessed() {
        p-pwintwn!("{:?} was pwessed", (U ﹏ U) key);
    }
    fow key in keys.get_just_weweased() {
        p-pwintwn!("{:?} was weweased", -.- key);
    }
}

wun conditions

anothew wowkfwow is to add wun conditions to youw systems, so that they onwy wun when the appwopwiate i-inputs h-happen.

it is highwy wecommended you wwite y-youw own wun conditions, so that you can check fow nyanievew y-you want, OwO suppowt c-configuwabwe b-bindings, 🥺 etc…

fow pwototyping, bevy offews some buiwt-in wun conditions:

use bevy::input::common_conditions::*;

app.add_systems(update, ^•ﻌ•^ (
    h-handwe_jump
        .wun_if(input_just_pwessed(keycode::space)), OwO
    h-handwe_shooting
        .wun_if(input_pwessed(keycode::entew)), 🥺
));

keyboawd events

to get aww keyboawd activity, (ꈍᴗꈍ) you c-can use KeyboardInput events:

fn keyboawd_events(
    mut evw_kbd: e-eventweadew<keyboawdinput>, >_<
) {
    f-fow ev in e-evw_kbd.wead() {
        m-match e-ev.state {
            b-buttonstate::pwessed => {
                p-pwintwn!("key p-pwess: {:?} ({:?})", :3 ev.key_code, (U ﹏ U) ev.wogicaw_key);
            }
            buttonstate::weweased => {
                pwintwn!("key w-wewease: {:?} ({:?})", -.- ev.key_code, (ˆ ﻌ ˆ)♡ ev.wogicaw_key);
            }
        }
    }
}

physicaw KeyCode vs. XD wogicaw Key

when a key is pwessed, >_< the event contains two impowtant pieces of i-infowmation:

• the KeyCode, (ꈍᴗꈍ) which awways wepwesents a specific k-key on the keyboawd, wegawdwess of the os wayout ow wanguage s-settings.
• the Key, OwO which contains the wogicaw meaning o-of the key as i-intewpweted by t-the os.

when you want to impwement gamepway m-mechanics, you w-want to use the KeyCode. this wiww give you wewiabwe keybindings t-that awways w-wowk, OwO incwuding f-fow muwtiwinguaw usews with muwtipwe keyboawd wayouts c-configuwed in t-theiw os.

when you want to impwement text/chawactew i-input, OwO y-you want to use t-the Key. this can give you unicode chawactews t-that you can a-append to youw t-text stwing and wiww awwow youw usews to type just w-wike they do in o-othew appwications.

if you'd wike to handwe speciaw function k-keys ow m-media keys on keyboawds t-that have them, (ꈍᴗꈍ) that can awso be done v-via the wogicaw Key.

text input

hewe is a simpwe exampwe of how to i-impwement text i-input into a stwing (hewe stowed as a wocaw).

use bevy::input::buttonstate;
use b-bevy::input::keyboawd::{key, k-keyboawdinput};

fn t-text_input(
    m-mut evw_kbd: eventweadew<keyboawdinput>, OwO
    mut s-stwing: wocaw<stwing>, (U ﹏ U)
) {
    f-fow ev in evw_kbd.wead() {
        // w-we don't c-cawe about key weweases, >_< onwy key pwesses
        if ev.state == buttonstate::weweased {
            c-continue;
        }
        match &ev.wogicaw_key {
            // handwe p-pwessing entew to finish the input
            key::entew => {
                pwintwn!("text i-input: {}", &*stwing);
                stwing.cweaw();
            }
            // handwe pwessing backspace to dewete w-wast chaw
            key::backspace => {
                s-stwing.pop();
            }
            // h-handwe key pwesses that pwoduce text chawactews
            key::chawactew(input) => {
                // i-ignowe any input that contains contwow (speciaw) chawactews
                if input.chaws().any(|c| c-c.is_contwow()) {
                    continue;
                }
                s-stwing.push_stw(&input);
            }
            _ => {}
        }
    }
}

note how we impwement speciaw handwing f-fow keys wike Backspace and Enter. you can easiwy add speciaw handwing f-fow othew keys t-that make sense i-in youw appwication, >_< wike awwow keys ow the Escape key.

keys that pwoduce usefuw chawactews f-fow ouw text c-come in as smow u-unicode stwings. ^•ﻌ•^ it is possibwe that thewe m-might be mowe t-than one char pew keypwess in some wanguages.

note: to suppowt text input fow intewnationaw u-usews w-who use wanguages with compwex scwipts (such as east a-asian wanguages), OwO o-ow usews who u-use assistive methods wike handwwiting w-wecognition, OwO you a-awso nyeed to s-suppowt ime input, >_< in addition to keyboawd input.

keyboawd focus

if you awe doing advanced things w-wike caching state t-to detect muwti-key sequences ow combinations of keys, ^•ﻌ•^ y-you might end u-up in an inconsistent state if the bevy os window woses f-focus in the middwe o-of keyboawd i-input, such as with awt-tab ow simiwaw os w-window switching m-mechanisms.

if you awe doing such things and y-you think youw awgowithm m-might be g-getting stuck, >_< bevy offews a KeyboardFocusLost event to wet you know when you shouwd weset youw state.

use bevy::input::keyboawd::keyboawdfocuswost;

fn d-detect_speciaw_sequence(
    m-mut e-evw_focus_wost: e-eventweadew<keyboawdfocuswost>, ^^;;
    m-mut wemembewed_keys: w-wocaw<vec<keycode>>, >_<
) {
    // i-imagine w-we nyeed to wemebew a sequence of keypwesses
    // fow some speciaw gamepway w-weason. mya
    // todo: impwement that; stowe state i-in `wemembewed_keys`

    // but it might go wwong i-if the usew awt-tabs, mya we nyeed to weset
    if !evw_focus_wost.is_empty() {
        w-wemembewed_keys.cweaw();
        evw_focus_wost.cweaw();
    }
}