nightshade-api 0.51.0

//! Keyboard, mouse, and time queries, plus the movement helpers every game
//! rewrites.

use nightshade::prelude::*;

/// True while `key` is held down.
#[inline]
pub fn key_down(world: &World, key: KeyCode) -> bool {
    world.resources.input.keyboard.is_key_pressed(key)
}

/// True only on the frame `key` went down.
#[inline]
pub fn key_pressed(world: &World, key: KeyCode) -> bool {
    world.resources.input.keyboard.just_pressed(key)
}

/// True while the mouse button is held down.
#[inline]
pub fn mouse_down(world: &World, button: MouseButton) -> bool {
    let state = world.resources.input.mouse.state;
    match button {
        MouseButton::Left => state.contains(MouseState::LEFT_CLICKED),
        MouseButton::Right => state.contains(MouseState::RIGHT_CLICKED),
        MouseButton::Middle => state.contains(MouseState::MIDDLE_CLICKED),
        _ => false,
    }
}

/// True only on the frame the mouse button went down.
#[inline]
pub fn mouse_clicked(world: &World, button: MouseButton) -> bool {
    let state = world.resources.input.mouse.state;
    match button {
        MouseButton::Left => state.contains(MouseState::LEFT_JUST_PRESSED),
        MouseButton::Right => state.contains(MouseState::RIGHT_JUST_PRESSED),
        MouseButton::Middle => state.contains(MouseState::MIDDLE_JUST_PRESSED),
        _ => false,
    }
}

/// The cursor position in window pixels.
#[inline]
pub fn mouse_position(world: &World) -> Vec2 {
    world.resources.input.mouse.position
}

/// How far the cursor moved this frame.
#[inline]
pub fn mouse_delta(world: &World) -> Vec2 {
    world.resources.input.mouse.position_delta
}

/// How far the scroll wheel moved this frame: positive scrolling up or away,
/// negative toward you, 0.0 when still.
#[inline]
pub fn mouse_scroll(world: &World) -> f32 {
    world.resources.input.mouse.wheel_delta.y
}

/// True when the cursor is over a retained UI widget. Gate world clicks on this
/// so a press on a panel or button does not also place or pick in the scene.
#[inline]
pub fn pointer_over_ui(world: &World) -> bool {
    world
        .resources
        .retained_ui
        .interaction
        .hovered_entity
        .is_some()
}

/// A signed 1d input: -1.0 while `negative` is held, 1.0 while `positive` is
/// held, 0.0 otherwise or when both are held.
#[inline]
pub fn axis(world: &World, negative: KeyCode, positive: KeyCode) -> f32 {
    let mut value = 0.0;
    if key_down(world, negative) {
        value -= 1.0;
    }
    if key_down(world, positive) {
        value += 1.0;
    }
    value
}

/// WASD as a camera relative movement direction on the ground plane,
/// normalized so diagonals are not faster. Returns zero when nothing is held.
/// Multiply by speed and [`delta_time`] and add to a position.
pub fn wasd(world: &World) -> Vec3 {
    let forward_input = axis(world, KeyCode::KeyS, KeyCode::KeyW);
    let strafe_input = axis(world, KeyCode::KeyA, KeyCode::KeyD);
    if forward_input == 0.0 && strafe_input == 0.0 {
        return Vec3::zeros();
    }
    let camera_forward = crate::camera::camera_forward(world);
    let mut planar_forward = Vec3::new(camera_forward.x, 0.0, camera_forward.z);
    if planar_forward.magnitude_squared() < f32::EPSILON {
        planar_forward = Vec3::new(0.0, 0.0, -1.0);
    }
    let planar_forward = planar_forward.normalize();
    let right = nalgebra_glm::cross(&planar_forward, &Vec3::y());
    (planar_forward * forward_input + right * strafe_input).normalize()
}

/// Seconds the previous frame took, scaled by the global time scale and zero
/// while paused. Multiply rates by this for frame rate independent motion that
/// honors slow motion, fast forward, and pause.
#[inline]
pub fn delta_time(world: &World) -> f32 {
    world.resources.window.timing.delta_time
}

/// Seconds the previous frame took in real time, ignoring the global time scale
/// and pause. Use it for work that must keep running while the game is paused or
/// slowed, such as a pause menu animation.
#[inline]
pub fn real_delta_time(world: &World) -> f32 {
    world.resources.window.timing.raw_delta_time
}

/// Seconds since the program started.
#[inline]
pub fn elapsed_seconds(world: &World) -> f32 {
    world.resources.window.timing.uptime_milliseconds as f32 / 1000.0
}

/// A gamepad button. `South`/`East`/`West`/`North` are the face buttons (A/B/X/Y
/// on Xbox), with `LeftTrigger`/`RightTrigger` as the shoulder bumpers and
/// `LeftTrigger2`/`RightTrigger2` as the analog triggers.
#[cfg(feature = "gamepad")]
pub use nightshade::prelude::gilrs::Button as GamepadButton;

/// A gamepad analog axis: the two sticks (`LeftStickX`/`Y`, `RightStickX`/`Y`)
/// and the trigger axes (`LeftZ`/`RightZ`).
#[cfg(feature = "gamepad")]
pub use nightshade::prelude::gilrs::Axis as GamepadAxis;

/// True while `button` is held on the active gamepad.
#[cfg(feature = "gamepad")]
pub fn gamepad_button_down(world: &mut World, button: GamepadButton) -> bool {
    query_active_gamepad(world).is_some_and(|gamepad| gamepad.is_pressed(button))
}

/// True only on the frame `button` went down on the active gamepad.
#[cfg(feature = "gamepad")]
pub fn gamepad_button_pressed(world: &World, button: GamepadButton) -> bool {
    world.resources.input.gamepad.just_pressed(button)
}

/// An analog axis on the active gamepad, normalized to about -1.0 to 1.0.
#[cfg(feature = "gamepad")]
pub fn gamepad_axis(world: &mut World, axis: GamepadAxis) -> f32 {
    query_active_gamepad(world)
        .map(|gamepad| gamepad.value(axis))
        .unwrap_or(0.0)
}

/// The left stick as a 2d vector, x to the right and y up.
#[cfg(feature = "gamepad")]
pub fn gamepad_left_stick(world: &mut World) -> Vec2 {
    Vec2::new(
        gamepad_axis(world, GamepadAxis::LeftStickX),
        gamepad_axis(world, GamepadAxis::LeftStickY),
    )
}

/// The right stick as a 2d vector, x to the right and y up.
#[cfg(feature = "gamepad")]
pub fn gamepad_right_stick(world: &mut World) -> Vec2 {
    Vec2::new(
        gamepad_axis(world, GamepadAxis::RightStickX),
        gamepad_axis(world, GamepadAxis::RightStickY),
    )
}

/// True when a gamepad is connected and active.
#[cfg(feature = "gamepad")]
pub fn gamepad_connected(world: &mut World) -> bool {
    query_active_gamepad(world).is_some()
}

/// Maps a friendly button name to a gilrs button, so a string-based command and
/// a language binding can name a button without the enum. Accepts the face
/// letters (a/b/x/y or cross/circle/square/triangle) and the position names.
#[cfg(feature = "gamepad")]
pub(crate) fn gamepad_button_from_name(name: &str) -> Option<GamepadButton> {
    Some(match name.to_ascii_lowercase().as_str() {
        "south" | "a" | "cross" => GamepadButton::South,
        "east" | "b" | "circle" => GamepadButton::East,
        "west" | "x" | "square" => GamepadButton::West,
        "north" | "y" | "triangle" => GamepadButton::North,
        "left_shoulder" | "lb" => GamepadButton::LeftTrigger,
        "right_shoulder" | "rb" => GamepadButton::RightTrigger,
        "left_trigger" | "lt" => GamepadButton::LeftTrigger2,
        "right_trigger" | "rt" => GamepadButton::RightTrigger2,
        "select" | "back" => GamepadButton::Select,
        "start" => GamepadButton::Start,
        "mode" | "guide" => GamepadButton::Mode,
        "left_thumb" | "l3" => GamepadButton::LeftThumb,
        "right_thumb" | "r3" => GamepadButton::RightThumb,
        "dpad_up" => GamepadButton::DPadUp,
        "dpad_down" => GamepadButton::DPadDown,
        "dpad_left" => GamepadButton::DPadLeft,
        "dpad_right" => GamepadButton::DPadRight,
        _ => return None,
    })
}

/// Maps a friendly axis name to a gilrs axis, for the string-based command form.
#[cfg(feature = "gamepad")]
pub(crate) fn gamepad_axis_from_name(name: &str) -> Option<GamepadAxis> {
    Some(match name.to_ascii_lowercase().as_str() {
        "left_x" => GamepadAxis::LeftStickX,
        "left_y" => GamepadAxis::LeftStickY,
        "right_x" => GamepadAxis::RightStickX,
        "right_y" => GamepadAxis::RightStickY,
        "left_z" => GamepadAxis::LeftZ,
        "right_z" => GamepadAxis::RightZ,
        _ => return None,
    })
}