Struct Input 

pub struct Input { /* private fields */ }

Keyboard state for the current frame.

Implementations

impl Input

pub fn is_blocked(&self) -> bool

Whether game input is currently blocked by an open UI element.

pub fn pressed(&self, key: Key) -> bool

true in the frame the key went down. OS key repeat is ignored.

Examples found in repository

examples/hello.rs (line 15)

    fn update(&mut self, ctx: &mut Context) {
        if ctx.input.pressed(Key::Space) {
            // A pitch that rises over time, so every beep sounds different.
            let pitch = 300.0 + (ctx.time.elapsed() as f32 * 50.0) % 900.0;
            ctx.audio.play_tone(pitch.round(), 0.15);
        }
        if ctx.input.pressed(Key::F1) {
            ctx.speech.repeat_last();
        }
        if ctx.input.pressed(Key::Escape) {
            ctx.quit();
        }
    }

pub fn pressed_or_repeated(&self, key: Key) -> bool

true in the frame the key went down and whenever the operating system sends a key repeat while it is held. This is what text fields and menus use.

pub fn held(&self, key: Key) -> bool

true as long as the key is held down.

pub fn released(&self, key: Key) -> bool

true in the frame the key was let go.

pub fn held_for(&self, key: Key) -> Option<f32>

How long the key has been held in seconds, or None if it is up.

pub fn repeating(&self, key: Key, delay: f32, every: f32) -> bool

Game-controlled key repeat with your own timing, independent of OS settings.

Returns true when the key is pressed, then again after delay seconds and from then on every every seconds while it stays held. Perfect for walking on a grid:

if ctx.input.repeating(Key::Up, 0.3, 0.3) {
    // take one step forward
}

Examples found in repository

examples/bell_catcher.rs (line 243)

    fn update(&mut self, ctx: &mut Context) {
        if self.over {
            if ctx.ui.closed("over") {
                ctx.switch_scene(Title);
            }
            return;
        }
        if ctx.pressed(Key::Escape) {
            ctx.switch_scene(Title);
            return;
        }
        if ctx.pressed(Key::S) {
            ctx.speak(format!("{} bells, {} lives", self.score, self.lives));
        }
        for (key, step) in [(Key::Left, -1), (Key::Right, 1)] {
            if ctx.input.repeating(key, 0.3, 0.15) {
                let lane = (self.lane + step).clamp(-LANES, LANES);
                if lane == self.lane {
                    ctx.play("edge");
                } else {
                    self.lane = lane;
                    ctx.audio.sound("step").at(vec3(step as f32 * 0.5, 0.0, 0.0)).random_pitch(0.9, 1.1).play();
                }
            }
        }

        let dt = ctx.time.delta();
        if self.left < 0.0 {
            self.left += dt;
            if self.left >= 0.0 {
                self.drop_bell();
            }
            return;
        }
        self.left -= dt;
        self.next_ring -= dt;
        if self.left <= 0.0 {
            self.land(ctx);
        } else if self.next_ring <= 0.0 {
            self.ring(ctx);
        }
    }

examples/beacon.rs (line 68)

    fn update(&mut self, ctx: &mut Context) {
        if ctx.pressed(Key::Escape) {
            ctx.push_scene(Pause);
        }
        if ctx.pressed(Key::Left) || ctx.pressed(Key::Right) {
            let degrees = if ctx.pressed(Key::Left) { -45.0 } else { 45.0 };
            let facing = ctx.physics.turn(self.player, degrees);
            ctx.speak(math::direction_name(facing));
        }

        let forward = ctx.input.repeating(Key::Up, 0.35, 0.35);
        let backward = ctx.input.repeating(Key::Down, 0.35, 0.35);
        if forward || backward {
            let step = if forward { 1.0 } else { -1.0 };
            if ctx.physics.move_forward(self.player, step).blocked {
                ctx.play("wall");
            } else {
                ctx.audio.sound("step").random_pitch(0.85, 1.15).play();
            }
        }

        if ctx.pressed(Key::C) {
            let position = ctx.physics.position(self.player);
            match ctx.physics.nearest_with_tag(position, "beacon") {
                Some(beacon) => {
                    let text = ctx.physics.describe(self.player, beacon);
                    ctx.speak(text);
                }
                None => ctx.speak("No beacons left"),
            }
        }
        if ctx.pressed(Key::F) {
            let facing = ctx.physics.facing(self.player);
            ctx.speak(format!("Facing {}", math::direction_name(facing)));
        }

        if let Some(beacon) = ctx.physics.entered_tag(self.player, "beacon") {
            ctx.physics.remove(beacon);
            self.beacons.retain(|b| *b != beacon);
            ctx.play("found");
            if self.beacons.is_empty() {
                self.finish(ctx);
            } else {
                ctx.speak(format!("Beacon found! {} left.", self.beacons.len()));
            }
        }
        if ctx.ui.closed("done") {
            ctx.quit();
        }
    }

pub fn axis(&self, negative: Key, positive: Key) -> f32

-1.0, 0.0 or 1.0 depending on which of two held keys is down, e.g. ctx.input.axis(Key::Left, Key::Right) for running in a side scroller.

Examples found in repository

examples/platformer.rs (line 67)

    fn update(&mut self, ctx: &mut Context) {
        if ctx.pressed(Key::Escape) {
            ctx.quit();
        }

        // The lift goes up for 4 seconds and down for 4 seconds.
        let lift_up = (ctx.time.elapsed() % 8.0) < 4.0;
        ctx.physics.set_velocity(self.lift, vec3(0.0, 0.0, if lift_up { 2.0 } else { -2.0 }));

        let run = ctx.input.axis(Key::Left, Key::Right);
        let mut velocity = ctx.physics.velocity(self.player);
        velocity.x = run * 6.0;
        ctx.physics.set_velocity(self.player, velocity);
        if ctx.pressed(Key::Space) && ctx.physics.jump(self.player, 2.5) {
            ctx.play("jump");
        }
        let running = ctx.physics.on_ground(self.player) && run != 0.0;
        self.run_sound.set_volume(if running { 0.6 } else { 0.0 });

        if let Some(speed) = ctx.physics.landed(self.player) {
            ctx.audio.sound("land").volume((speed / 12.0).clamp(0.2, 1.0)).play();
            if speed > 15.0 {
                ctx.speak("Ouch!");
            }
        }
        if let Some((other, _)) = ctx.physics.collided(self.player)
            && ctx.physics.tag(other) == "crate"
        {
            ctx.play_on(other, "push");
        }
        if let Some(coin) = ctx.physics.entered_tag(self.player, "coin") {
            ctx.physics.remove(coin); // its looping sound stops by itself
            self.score += 1;
            ctx.audio.sound("coin").pitch(1.5).play();
            ctx.speak(format!("{} of {COINS} coins", self.score));
            if self.score == COINS {
                ctx.ui.message("won", "You collected every coin! Press enter to quit.");
            }
        }
        if ctx.ui.closed("won") {
            ctx.quit();
        }

        if ctx.pressed(Key::S) {
            let x = ctx.physics.position(self.player).x;
            ctx.speak(format!("Score {}, position {x:.0}", self.score));
        }
    }

examples/flight.rs (line 90)

    fn update(&mut self, ctx: &mut Context) {
        if ctx.pressed(Key::Escape) {
            ctx.quit();
        }
        if ctx.pressed(Key::Left) || ctx.pressed(Key::Right) {
            let facing = ctx.physics.turn(self.drone, if ctx.pressed(Key::Left) { -30.0 } else { 30.0 });
            ctx.speak(math::direction_name(facing));
        }
        if ctx.pressed(Key::PageUp) || ctx.pressed(Key::PageDown) {
            let pitch = ctx.physics.tilt(self.drone, if ctx.pressed(Key::PageUp) { 30.0 } else { -30.0 });
            ctx.speak(describe_pitch(pitch));
        }

        // Smooth flight: 4 meters per second while a key is held.
        let speed = 4.0 * ctx.time.delta();
        let forward = ctx.input.axis(Key::Down, Key::Up);
        if forward != 0.0 {
            let result = ctx.physics.move_forward(self.drone, forward * speed);
            self.fly(ctx, result);
        }
        let rise = ctx.input.axis(Key::Q, Key::E);
        if rise != 0.0 {
            let result = ctx.physics.move_up(self.drone, rise * speed);
            self.fly(ctx, result);
        }

        if ctx.pressed(Key::C) {
            let position = ctx.physics.position(self.drone);
            match ctx.physics.nearest_with_tag(position, "bird") {
                Some(bird) => {
                    let text = ctx.physics.describe(self.drone, bird); // e.g. "2 o'clock, 9 meters, 6 meters above"
                    ctx.speak(text);
                }
                None => ctx.speak("No birds left"),
            }
        }
        if ctx.pressed(Key::F) {
            let (facing, pitch) = (ctx.physics.facing(self.drone), ctx.physics.pitch(self.drone));
            ctx.speak(format!("Facing {}, {}", math::direction_name(facing), describe_pitch(pitch)));
        }
        if ctx.pressed(Key::H) {
            let height = ctx.physics.position(self.drone).z;
            ctx.speak(format!("{height:.0} meters high"));
        }

        if let Some(bird) = ctx.physics.entered_tag(self.drone, "bird") {
            ctx.physics.remove(bird);
            self.birds -= 1;
            ctx.play("found");
            if self.birds == 0 {
                ctx.ui.message("done", "You found every bird!");
            } else {
                ctx.speak(format!("Bird found! {} left.", self.birds));
            }
        }
        if ctx.ui.closed("done") {
            ctx.quit();
        }
    }

pub fn movement(&self) -> Vec2

Movement direction from the arrow keys or WASD: x is right, y is forward. Diagonals are normalized, so moving diagonally is not faster.

pub fn movement_3d(&self) -> Vec3

Like Input::movement, plus z for up (Page Up or E) and down (Page Down or Q), for flying, swimming or climbing. x is right, y is forward, z is up. Diagonals are normalized.

pub fn any_pressed(&self) -> bool

true if any key went down this frame.

pub fn keys_pressed(&self) -> &[Key]

Keys that went down this frame in the order they were pressed (including OS repeats).

pub fn text(&self) -> &str

Text typed this frame, respecting keyboard layout and shift state.

pub fn modifiers(&self) -> Modifiers

Current state of shift, control and alt.

pub fn raw(&self) -> RawInput<'_>

Unblocked view of the input, even while a UI element is open.

pub fn held_duration(&self, key: Key) -> Option<Duration>

Duration the key has been held, using a real Duration.

Trait Implementations

impl Debug for Input

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Input

fn default() -> Self

Returns the “default value” for a type.