mirage-engine 0.1.1

//! Actions: what a player can do, and the controls bound to each one.
//!
//! A game names its own actions — `Jump`, `Walk`, `Aim` — in up to three
//! vocabularies, one per kind: a button is pressed, released or down, an
//! axis reads one number, an axis2 reads two. [`InputActions`] holds the
//! three, and [`Game::InputActions`](crate::Game::InputActions) names the
//! set; [`NoInputActions`] is the set of a game that reads no input, and
//! [`Key`] is the prototype set that binds each key to itself. Every query
//! — `down`, `pressed`, `released`, `axis`, `axis2` — takes an action of
//! that set and no other.
//!
//! Each action declares its own default bindings, which may hold a key, a
//! mouse button, a pad button, a stick or a composite of them. An axis or
//! axis2 binding holds a deadzone —
//! [`AxisBinding::DEFAULT_DEADZONE`](crate::AxisBinding::DEFAULT_DEADZONE)
//! for a pad or joystick control, and zero for the rest — and a scale.
//! A [`PointerDelta`] lane, a [`WheelDelta`] lane and
//! [`Axis2Binding::pointer`](crate::Axis2Binding::pointer) read how far
//! they moved through that scale and nothing clamps what they read; every
//! other binding reads in its kind's own range.
//!
//! A game that rebinds reads [`bindings`](crate::FrameContext::bindings) for
//! what an action is bound to now, and shows each binding's text.
//! [`actuated_button`](crate::FrameContext::actuated_button),
//! [`actuated_axis`](crate::FrameContext::actuated_axis) and
//! [`actuated_axis2`](crate::FrameContext::actuated_axis2) then report
//! whatever the player just moved, which
//! [`rebind`](crate::FrameContext::rebind) takes. The engine keeps every
//! rebind in the platform's own store, under a name made from the title
//! [`Config::new`](crate::Config::new) was given.
//!
//! [`Cursor`] is what the pointer itself is drawn as, the closed set
//! [`set_cursor`](crate::FrameContext::set_cursor) takes for one frame; a
//! frame that sets none draws [`Cursor::Arrow`]. Where the UI sets a cursor
//! of its own, the UI's is drawn instead. [`Cursor::Held`] draws no pointer
//! and holds it in place, leaving a [`PointerDelta`] binding its
//! movement to read and [`pointer`](crate::FrameContext::pointer) the place
//! it was held at; the frame after it sets another cursor releases it.

pub use action::{
    InputAction, InputActions, InputAxis2Action, InputAxisAction, InputButtonAction,
    NoInputActions, NoInputAxes, NoInputAxes2, NoInputButtons,
};
pub use binding::{
    Axis2Binding, AxisBinding, ButtonAxis, ButtonAxis2, ButtonBinding, JoystickControl, Key,
    MouseButton, Pad, PadAxis, PointerDelta, Stick, WheelDelta,
};
pub use cursor::Cursor;

#[cfg(feature = "offscreen")]
pub use state::Switch;

pub(crate) use pad::Pads;
pub(crate) use state::WheelRate;

use core::num::NonZeroU32;
use core::time::Duration;

use winit::event::{DeviceEvent, WindowEvent};

use crate::math::Vec2;
use crate::platform::Store;
use state::Devices;
use table::{Rebound, Table};

/// State behind the input API: every action's bindings, what the devices
/// read, and where a rebind is kept.
pub(crate) struct Input {
    table: Table,
    devices: Devices,
    pads: Pads,
    store: Store,
    dirty: bool,
    /// How long after a press a second one still counts as a double click.
    double_click: Duration,
}

impl Input {
    /// The input a run starts with: the game's actions at their declared
    /// bindings, with whatever `store` kept of an earlier run over them.
    pub(crate) fn new<A: InputActions>(pads: Pads, store: Store, double_click: Duration) -> Self {
        Self {
            table: Table::new::<A>(store.read().as_deref()),
            devices: Devices::default(),
            pads,
            store,
            dirty: false,
            double_click,
        }
    }

    pub(crate) fn see(&mut self, event: &WindowEvent) {
        self.devices.see(event);
    }

    /// Takes what `event` reports of a device's own movement, which a held
    /// pointer moves by and a pointer the window still places ignores.
    pub(crate) fn see_device(&mut self, event: &DeviceEvent) {
        self.devices.see_device(event);
    }

    /// Holds the pointer in place or releases it, by what the platform did
    /// with it rather than by what the frame set.
    pub(crate) fn hold_pointer(&mut self, held: bool) {
        self.devices.hold_pointer(held);
    }

    /// Presses `control` or releases it in place of a window's event; only
    /// a session calls this.
    #[cfg(feature = "offscreen")]
    pub(crate) fn press(&mut self, control: Switch, down: bool) {
        self.devices.press(control, down);
    }

    /// Moves the pointer in place of a window's event; only a session calls
    /// this.
    #[cfg(feature = "offscreen")]
    pub(crate) fn point_at(&mut self, at: Vec2) {
        self.devices.point_at(at);
    }

    /// Moves one lane of the pointer in place of a window's event; only a
    /// session calls this.
    #[cfg(feature = "offscreen")]
    pub(crate) fn move_pointer(&mut self, lane: PointerDelta, pixels: f32) {
        self.devices.move_pointer(lane.moving(pixels));
    }

    /// Turns one lane of the wheel in place of a window's event; only a
    /// session calls this.
    #[cfg(feature = "offscreen")]
    pub(crate) fn turn_wheel(&mut self, lane: WheelDelta, notches: f32) {
        self.devices.turn_wheel(lane.turning(notches));
    }

    /// The `Shift`, `Control` and `Alt` keys held down as of now, as the
    /// UI reads them, with `Control` as its command key.
    ///
    /// Only a session reads this: the keys a window holds down reach the
    /// UI through `egui-winit`. A window on `macOS` takes its command key
    /// from `Super`, which [`Key`] has no position for, so a session's
    /// `Control` is what a command reads there.
    #[cfg(all(feature = "ui", feature = "offscreen"))]
    pub(crate) fn ui_modifiers(&self) -> egui::Modifiers {
        let either = |left, right| {
            self.devices.holds(Switch::Key(left)) || self.devices.holds(Switch::Key(right))
        };
        let ctrl = either(Key::LeftControl, Key::RightControl);

        egui::Modifiers {
            alt: either(Key::LeftAlt, Key::RightAlt),
            ctrl,
            shift: either(Key::LeftShift, Key::RightShift),
            mac_cmd: false,
            command: ctrl,
        }
    }

    /// Where the pointer has been placed, ahead of the snapshot the game
    /// reads, or `None` where nothing has placed it yet; only a session
    /// reads this, for the press it passes to the UI.
    #[cfg(all(feature = "ui", feature = "offscreen"))]
    pub(crate) fn pointing_at(&self) -> Option<Vec2> {
        self.devices.pointing_at()
    }

    /// Closes the snapshot that every tick, and the frame that follows
    /// them, read from — at `at` on the run's own clock.
    pub(crate) fn sample(&mut self, at: Duration) {
        self.devices.sample(&mut self.pads, at, self.double_click);
    }

    /// Runs `tick` `count` times, on the edges since the last frame whose
    /// ticks ran.
    ///
    /// Each call reads the same edges; no later tick reads them again.
    pub(crate) fn ticks(&mut self, count: NonZeroU32, mut tick: impl FnMut(&Ticking<'_>)) {
        let ticking = Ticking { input: self };
        for _ in 0..count.get() {
            tick(&ticking);
        }
    }

    pub(crate) fn down<A: InputButtonAction>(&self, action: A) -> bool {
        self.devices.snapshot().down(self.table.resolve(action))
    }

    pub(crate) fn pressed<A: InputButtonAction>(&self, action: A) -> bool {
        self.devices.snapshot().pressed(self.table.resolve(action))
    }

    pub(crate) fn released<A: InputButtonAction>(&self, action: A) -> bool {
        self.devices.snapshot().released(self.table.resolve(action))
    }

    pub(crate) fn clicks<A: InputButtonAction>(&self, action: A) -> u32 {
        match self.pressed(action) {
            true => self.devices.clicks(self.table.resolve(action)),
            false => 0,
        }
    }

    pub(crate) fn axis<A: InputAxisAction>(&self, action: A) -> f32 {
        self.devices.snapshot().axis(self.table.resolve(action))
    }

    pub(crate) fn axis2<A: InputAxis2Action>(&self, action: A) -> Vec2 {
        self.devices.snapshot().axis2(self.table.resolve(action))
    }

    pub(crate) fn pointer(&self) -> Vec2 {
        self.devices.snapshot().pointer()
    }

    pub(crate) fn bindings<A: InputAction>(&self, action: A) -> Vec<A::Binding> {
        self.table.resolve(action).to_vec()
    }

    /// Binds `action` to `bindings` and marks the store to be written where
    /// that is not what the action already read through.
    pub(crate) fn rebind<A: InputAction>(&mut self, action: A, bindings: Vec<A::Binding>) {
        match self.table.rebind(action, bindings) {
            Rebound::Changed => self.dirty = true,
            Rebound::Unchanged => {}
        }
    }

    /// Writes the bindings where a rebind changed one since the last call,
    /// and nothing at all where none did.
    pub(crate) fn flush(&mut self) {
        if core::mem::take(&mut self.dirty) {
            self.store.write(&self.table.written());
        }
    }

    pub(crate) fn actuated_button(&self) -> Option<ButtonBinding> {
        self.devices.snapshot().actuated_button()
    }

    pub(crate) fn actuated_axis(&self) -> Option<AxisBinding> {
        self.devices.snapshot().actuated_axis()
    }

    pub(crate) fn actuated_axis2(&self) -> Option<Axis2Binding> {
        self.devices.snapshot().actuated_axis2()
    }

    /// Whether `action` went down since the last frame whose ticks ran.
    /// Only [`Ticking`] calls this.
    fn pressed_over_ticks<A: InputButtonAction>(&self, action: A) -> bool {
        self.devices.ticks().pressed(self.table.resolve(action))
    }

    /// Whether `action` came up since the last frame whose ticks ran. Only
    /// [`Ticking`] calls this.
    fn released_over_ticks<A: InputButtonAction>(&self, action: A) -> bool {
        self.devices.ticks().released(self.table.resolve(action))
    }

    /// Presses in a row the press these ticks read is the last of. Only
    /// [`Ticking`] calls this.
    fn clicks_over_ticks<A: InputButtonAction>(&self, action: A) -> u32 {
        match self.pressed_over_ticks(action) {
            true => self.devices.clicks(self.table.resolve(action)),
            false => 0,
        }
    }

    /// Ends the ticks of one frame. Only dropping a [`Ticking`] calls this.
    fn ticked(&mut self) {
        self.devices.ticked();
    }
}

/// The input the ticks of one frame read. [`Input::ticks`] is the only
/// source of one.
///
/// Dropping it ends those ticks, so no later tick reads an edge these ticks
/// already read.
pub(crate) struct Ticking<'a> {
    input: &'a mut Input,
}

impl Ticking<'_> {
    pub(crate) fn down<A: InputButtonAction>(&self, action: A) -> bool {
        self.input.down(action)
    }

    pub(crate) fn pressed<A: InputButtonAction>(&self, action: A) -> bool {
        self.input.pressed_over_ticks(action)
    }

    pub(crate) fn released<A: InputButtonAction>(&self, action: A) -> bool {
        self.input.released_over_ticks(action)
    }

    pub(crate) fn clicks<A: InputButtonAction>(&self, action: A) -> u32 {
        self.input.clicks_over_ticks(action)
    }

    pub(crate) fn axis<A: InputAxisAction>(&self, action: A) -> f32 {
        self.input.axis(action)
    }

    pub(crate) fn axis2<A: InputAxis2Action>(&self, action: A) -> Vec2 {
        self.input.axis2(action)
    }

    pub(crate) fn pointer(&self) -> Vec2 {
        self.input.pointer()
    }
}

impl Drop for Ticking<'_> {
    fn drop(&mut self) {
        self.input.ticked();
    }
}

mod action;
mod binding;
mod cursor;
mod pad;
mod state;
mod table;

#[cfg(test)]
mod tests {
    use super::*;
    use winit::event::{DeviceId, ElementState};

    /// The interval these tests count a double click by.
    const DOUBLE_CLICK: Duration = Duration::from_millis(400);

    /// More than one tick in a frame, so a test can check what each tick
    /// reads.
    const TICKS: NonZeroU32 = match NonZeroU32::new(3) {
        Some(ticks) => ticks,
        None => NonZeroU32::MIN,
    };

    /// A run reading through the keyboard as its own vocabulary, keeping
    /// nothing between runs.
    fn input() -> Input {
        Input::new::<Key>(Pads::silent(), Store::bindings(None), DOUBLE_CLICK)
    }

    /// The primary mouse button pressed, which is the one control a test can
    /// press: `winit` keeps a keyboard event's platform field private, so no
    /// other crate builds one.
    fn click() -> WindowEvent {
        WindowEvent::MouseInput {
            device_id: DeviceId::dummy(),
            state: ElementState::Pressed,
            button: winit::event::MouseButton::Left,
        }
    }

    /// What each of the `count` ticks of one frame reads for `action`.
    fn pressed_per_tick(input: &mut Input, count: NonZeroU32, action: Key) -> Vec<bool> {
        let mut read = Vec::new();
        input.ticks(count, |ticking| read.push(ticking.pressed(action)));
        read
    }

    #[test]
    fn only_a_rebind_that_changed_something_leaves_the_store_to_write() {
        let mut input = input();

        input.rebind(Key::Space, vec![Key::Space.into()]);
        assert!(!input.dirty, "what it read through already is no change");

        input.rebind(Key::Space, vec![Key::Enter.into()]);
        assert!(input.dirty);
        input.flush();

        assert!(!input.dirty, "so the store is written once, not per call");
        assert_eq!(input.bindings(Key::Space), vec![Key::Enter.into()]);
    }

    #[test]
    fn the_ticks_of_one_frame_read_an_edge_and_the_ticks_after_them_read_none() {
        let mut input = input();
        input.rebind(Key::Space, vec![MouseButton::Left.into()]);

        input.see(&click());
        input.sample(Duration::ZERO);
        input.sample(Duration::ZERO);

        assert_eq!(
            pressed_per_tick(&mut input, TICKS, Key::Space),
            [true; 3],
            "every tick of the frame that reads the press reads it"
        );

        input.sample(Duration::ZERO);
        assert_eq!(
            pressed_per_tick(&mut input, TICKS, Key::Space),
            [false; 3],
            "and the ticks that follow read it no more"
        );
    }
}