pinch-points 0.8.0

//! Per-player tile cursors and keyboard input (spec §8.2, §8.3).
//!
//! Two-stage model: move a cursor, commit a direction. Out of the box
//! player 0 uses WASD + arrow keys and player 1 (versus) IJKL + numpad;
//! every one of those keys is rebindable in settings (see `binds`). Cursors
//! are tinted to the player's flag colour and shaped differently per player
//! for colour-vision accessibility (§8.3). Gamepads (§8.1) slot in here
//! once bevy_gilrs is enabled; the commit path is identical.

use crate::app::layout::{self, TILE};
use crate::app::palette;
use crate::app::settings::{CommitScheme, GameSettings};
use crate::app::{Screen, Sim};
use crate::sim::Direction;
use bevy::prelude::*;

#[derive(Component)]
pub struct Cursor {
    pub player: u8,
    pub x: u8,
    pub y: u8,
    /// Hold-to-repeat state (spec §8.4 wants the rates adjustable later).
    repeat: Timer,
    /// Seconds left of the red denied-placement flash.
    pub flash: f32,
}

impl Cursor {
    /// A cursor for `player`, parked at the origin until something centres
    /// it on a board.
    ///
    /// A constructor because the repeat timer is private to this module and
    /// two places build one: here, and the pad code's tests.
    pub(crate) fn seated(player: u8) -> Cursor {
        Cursor {
            player,
            x: 0,
            y: 0,
            repeat: Timer::from_seconds(0.0, TimerMode::Once),
            flash: 0.0,
        }
    }
}

pub struct KeyMap {
    pub moves: [(KeyCode, i16, i16); 4],
    pub places: [(KeyCode, Direction); 4],
    pub remove: KeyCode,
    pub clear_all: KeyCode,
}

/// How long a denied placement tints the cursor red.
pub(super) const FLASH_SECS: f32 = 0.25;

/// Keyboard layout for a seat, as bound in settings (spec §8.2 defaults:
/// seat 1 on WASD + arrows, seat 2 on IJKL + numpad).
///
/// `commit` is the §8.2 scheme in force: the one-hand preset overrides
/// seat 1's four commit keys with IJKL whatever they are bound to. It
/// exists for solo play, where the second seat's keys are free, so a
/// caller in versus passes [`CommitScheme::Arrows`] whatever is set.
pub fn keymap(settings: &GameSettings, player: u8, commit: CommitScheme) -> KeyMap {
    use crate::app::binds::Action;
    let seat = usize::from(player).min(crate::app::binds::BOUND_SEATS - 1);
    let binds = &settings.binds[seat];
    let places = if player == 0 && commit == CommitScheme::Ijkl {
        [
            (KeyCode::KeyI, Direction::Up),
            (KeyCode::KeyK, Direction::Down),
            (KeyCode::KeyJ, Direction::Left),
            (KeyCode::KeyL, Direction::Right),
        ]
    } else {
        [
            (binds.key(Action::PlaceUp), Direction::Up),
            (binds.key(Action::PlaceDown), Direction::Down),
            (binds.key(Action::PlaceLeft), Direction::Left),
            (binds.key(Action::PlaceRight), Direction::Right),
        ]
    };
    KeyMap {
        moves: [
            (binds.key(Action::MoveUp), 0, -1),
            (binds.key(Action::MoveDown), 0, 1),
            (binds.key(Action::MoveLeft), -1, 0),
            (binds.key(Action::MoveRight), 1, 0),
        ],
        places,
        remove: binds.key(Action::Remove),
        clear_all: binds.key(Action::ClearAll),
    }
}

/// Spawn one cursor per player. Shape differs per player (§8.3): player 0 is
/// an axis-aligned square, player 1 a diamond.
fn bracket_color(player: u8) -> Color {
    palette::player_color(player).lighter(0.08).with_alpha(0.9)
}

/// Whether `seat` is being played by somebody sitting at this machine.
///
/// A cursor is spawned for exactly the seats this keyboard, these pads and
/// this screen answer for: seat one alone in a puzzle, every human seat in
/// a local match, and precisely the local seat online. Bots have none, and
/// neither do rivals down a wire.
///
/// So it is the question "is this one mine?", which the beach asks before
/// it makes a noise: a knock for every post a bot puts down is a click
/// track, and hearing a rival's placements online is hearing something
/// that did not happen in this room.
///
/// A **replay** and a **spectated** match answer `false` for every seat,
/// because neither spawns a cursor at all. Banks, raids, gulls and the
/// horn still sound; posts go in and out in silence, and their rings and
/// puffs stand down with them.
pub fn seated_here(cursors: &Query<&Cursor>, seat: u8) -> bool {
    cursors.iter().any(|cursor| cursor.player == seat)
}

/// Tint flashing (denied) cursors red, and dim a cursor standing on a tile
/// that will refuse it.
///
/// A rock, a rival's post or an empty inventory is knowable before the
/// press, and a cursor that has gone quiet says so without a word; told
/// only afterwards, the brackets flash red and the player works out why.
/// Only where placing is the verb: in the editor the cursor paints tiles.
pub fn flash_cursors(
    time: Res<Time>,
    sim: Res<Sim>,
    screen: Res<State<Screen>>,
    mut cursors: Query<(&mut Cursor, &mut Sprite)>,
) {
    let board = &sim.0;
    let placing = matches!(screen.get(), Screen::Puzzle | Screen::Versus);
    for (mut cursor, mut sprite) in &mut cursors {
        if cursor.flash > 0.0 {
            cursor.flash -= time.delta_secs();
            sprite.color = Color::srgba(1.0, 0.25, 0.2, 0.95);
            continue;
        }
        let color = bracket_color(cursor.player);
        // A board can shrink under a cursor (`glide_cursors` guards the
        // same way). Off the board both questions below answer "no" on
        // their bounds check, which reads as "this tile refuses you" and
        // leaves the brackets dimmed until something recentres them.
        if cursor.x >= board.width() || cursor.y >= board.height() {
            sprite.color = color;
            continue;
        }
        // Only when it is the *tile* refusing. An empty inventory refuses
        // every tile on the beach, and a cursor dimmed everywhere reads as
        // broken rather than as a message; the arrow count in the header
        // says that one, and `out_of_signposts` tells the two apart.
        let seat = acts_for(*screen.get(), &cursor);
        let tile_refuses = placing
            && !board.can_place_signpost(seat, cursor.x, cursor.y)
            && !board.out_of_signposts(seat, cursor.x, cursor.y);
        sprite.color = if tile_refuses {
            color.with_alpha(0.34)
        } else {
            color
        };
    }
}

/// The post a seat has committed but the board has not taken yet.
///
/// Placing is two stages, move the cursor and commit a direction, and the
/// commit is instant, so there is nothing to preview. What there *is*,
/// between the press and the post, is a queue: a placement sits in
/// [`crate::app::PendingActions`] until the sim takes it. Locally that is
/// at most one fixed step; online it is until the lockstep commits the
/// frame, which on a stalled peer is as long as the stall.
#[derive(Component)]
pub struct PostGhost;

/// Draw one faint arrow per queued placement, the way a hint draws its own
/// ghost: the same art, the same near-transparency, under the real posts.
pub fn ghost_pending_posts(
    mut commands: Commands,
    sim: Res<Sim>,
    art: Res<crate::app::art::Art>,
    pending: Res<crate::app::PendingActions>,
    ghosts: Query<Entity, With<PostGhost>>,
) {
    // Rebuilt rather than diffed: there are at most six of them, and
    // `PendingActions` is taken mutably by the fixed-step driver every
    // tick, so change detection on it says nothing useful.
    for ghost in &ghosts {
        commands.entity(ghost).despawn();
    }
    let board = &sim.0;
    // Nothing is queued on a frozen board: `advance_sim` stops taking the
    // queue at the wave, so a placement pressed on the round's last frames
    // would otherwise leave its ghost on the held board for the whole of
    // the results card, advertising a post that will never go in.
    if board.round_over() {
        return;
    }
    for (seat, action) in pending.0.iter().enumerate() {
        let crate::sim::PlayerAction::Place { x, y, dir } = *action else {
            continue;
        };
        if x >= board.width() || y >= board.height() {
            continue;
        }
        // The board's outline, faint, and its arrow a little less so: the
        // post it will be, in the seat's colour, before it goes in.
        let color = palette::player_color(seat as u8).lighter(0.2);
        let size = Some(Vec2::splat(TILE * 0.94));
        commands
            .spawn((
                PostGhost,
                Sprite {
                    image: art.sign_shape.clone(),
                    color: color.with_alpha(0.22),
                    custom_size: size,
                    ..default()
                },
                Transform::from_translation(
                    layout::tile_center(board, x, y).extend(layout::z::SIGNPOST - 0.1),
                )
                .with_rotation(layout::dir_rotation(dir)),
            ))
            .with_child((
                Sprite {
                    image: art.sign_paint.clone(),
                    color: color.with_alpha(0.5),
                    custom_size: size,
                    ..default()
                },
                Transform::from_translation(Vec3::new(0.0, 0.0, 0.01)),
            ));
    }
}

/// Carry each cursor to the tile it now sits on, and breathe.
///
/// Teleported by whichever input system moved it, the cursor is correct to
/// the tile and wrong to the eye: at the hold-repeat rate it reads as a
/// thing being redrawn rather than steered. It is placed here instead,
/// once, from the tile the input systems agreed on.
///
/// Long jumps still snap. A round starting, a level loading and a board
/// changing size all move a cursor halfway across the beach, and sliding
/// it there would draw a line through a board it is no longer on.
pub fn glide_cursors(
    time: Res<Time>,
    sim: Res<Sim>,
    settings: Res<GameSettings>,
    mut cursors: Query<(&Cursor, &mut Transform)>,
) {
    let board = &sim.0;
    // Frame-rate independent: the same fraction of the way there per
    // second whatever the frame took.
    let closed = 1.0 - (-time.delta_secs() * 26.0).exp();
    let t = time.elapsed_secs();
    for (cursor, mut transform) in &mut cursors {
        if cursor.x >= board.width() || cursor.y >= board.height() {
            continue;
        }
        let target = layout::tile_center(board, cursor.x, cursor.y);
        let here = transform.translation.truncate();
        let at = if settings.reduced_motion || here.distance(target) > TILE * 2.0 {
            target
        } else {
            here.lerp(target, closed)
        };
        transform.translation = at.extend(layout::z::CURSOR);
        // A slow breath, phased per seat so six cursors on one beach do
        // not pulse as one.
        transform.scale = Vec3::splat(if settings.reduced_motion {
            1.0
        } else {
            1.0 + 0.035 * (t * 3.4 + f32::from(cursor.player)).sin()
        });
    }
}

/// One player's tile cursor: corner brackets in the owner's colour. Odd
/// seats rotate 45 degrees (a diamond) so overlapping cursors stay distinct.
fn cursor_sprite(commands: &mut Commands, art: &crate::app::art::Art, player: u8) {
    let rotation = if player % 2 == 1 {
        Quat::from_rotation_z(std::f32::consts::FRAC_PI_4)
    } else {
        Quat::IDENTITY
    };
    commands.spawn((
        Cursor::seated(player),
        Sprite {
            image: art.bracket.clone(),
            color: bracket_color(player),
            custom_size: Some(Vec2::splat(TILE * if player % 2 == 1 { 0.80 } else { 1.0 })),
            ..default()
        },
        Transform::from_translation(Vec3::new(0.0, 0.0, layout::z::CURSOR)).with_rotation(rotation),
    ));
}

pub fn spawn_cursors(commands: &mut Commands, art: &crate::app::art::Art, players: u8) {
    for player in 0..players {
        cursor_sprite(commands, art, player);
    }
}

pub fn spawn_puzzle_cursor(mut commands: Commands, art: Res<crate::app::art::Art>) {
    spawn_cursors(&mut commands, &art, 1);
}

/// A puzzle's cursors: one, or two in co-op, where the second is a second
/// pair of hands for the same seat's arrows (see [`crate::app::Coop`]).
pub fn spawn_stage_cursors(
    mut commands: Commands,
    art: Res<crate::app::art::Art>,
    coop: Res<crate::app::Coop>,
    campaign: Res<crate::app::Campaign>,
) {
    let hands = if coop.in_play(&campaign) { 2 } else { 1 };
    spawn_cursors(&mut commands, &art, hands);
}

/// The seat a cursor's placements belong to. A puzzle has one, whoever's
/// hands are on the cursor: co-op's second cursor places the first seat's
/// arrows.
pub fn acts_for(screen: Screen, cursor: &Cursor) -> u8 {
    if screen == Screen::Puzzle {
        0
    } else {
        cursor.player
    }
}

/// Versus cursors: online spawns only the local seat's cursor (rivals'
/// placements arrive over the wire); local play seats two keyboard players
/// plus one per extra connected gamepad.
pub fn spawn_versus_cursors(
    mut commands: Commands,
    art: Res<crate::app::art::Art>,
    source: crate::app::session::RoundSource,
) {
    let crate::app::session::RoundSource {
        online,
        playback,
        config,
        daily,
        resuming,
        pads,
        ..
    } = source;
    // Before `load_versus` takes the resumed round, which is why this can
    // still read it. Its table is the round's own: one cursor per human
    // seat, and none for the AI's, or a keypress on the AI's keys steered
    // its crabs over the head of the bot.
    //
    // By seat, not by head-count: the AI's seats need not be the top ones.
    // An online seat given up on mid-round passes to the AI where it sits,
    // and its code says so, so counting heads put a cursor on that seat
    // and left the human above it with none.
    if let Some(round) = &resuming.0 {
        for (seat, bot) in round.bots[..usize::from(round.seats)].iter().enumerate() {
            if bot.is_none() {
                cursor_sprite(&mut commands, &art, seat as u8);
            }
        }
        return;
    }
    let daily_config = crate::app::match_setup::MatchConfig::daily();
    let config = if daily.active {
        &daily_config
    } else {
        &*config
    };
    // A replay has no cursor, for the same reason a spectator has none:
    // there is no seat here to place from. Cursor movement was never
    // recorded, so one drawn over a replay sits in the middle of the board
    // looking broken.
    if playback.0.is_some() {
        return;
    }
    if online.0.is_none() && config.armed {
        // Configured match: one cursor per human seat.
        spawn_cursors(&mut commands, &art, config.seats - config.bots);
        return;
    }
    if let Some(session) = &online.0 {
        // A spectator has no cursor: there is no seat for it to place from.
        // Nor does a seat a bot drives from this machine: the keys here are
        // not what plays it.
        if let Some(seat) = session.session.seat()
            && !session.bot
        {
            cursor_sprite(&mut commands, &art, seat);
        }
        return;
    }
    spawn_cursors(&mut commands, &art, (pads.iter().count() as u8).max(2));
}

/// Snap every cursor to the board centre (used right after a mode spawns its
/// cursors over a fresh board).
pub fn center_cursors(sim: Res<Sim>, mut cursors: Query<(&mut Cursor, &mut Transform)>) {
    center_on(&sim.0, &mut cursors);
}

/// The centring itself, for callers that swap the board mid-screen (the
/// editor's resize and paste) and are not a system of their own. Movement
/// only clamps on a step, so a cursor left standing on a tile the new
/// board does not have would stay there until it was moved, and be
/// painted on in the meantime.
pub fn center_on(board: &crate::sim::Board, cursors: &mut Query<(&mut Cursor, &mut Transform)>) {
    for (mut cursor, mut transform) in cursors {
        cursor.x = board.width() / 2;
        cursor.y = board.height() / 2;
        transform.translation =
            layout::tile_center(board, cursor.x, cursor.y).extend(layout::z::CURSOR);
    }
}

/// Movement with hold-to-repeat, for every cursor; active in every phase.
pub fn move_cursor(
    keys: Res<ButtonInput<KeyCode>>,
    time: Res<Time>,
    sim: Res<Sim>,
    settings: Res<GameSettings>,
    screen: Res<State<Screen>>,
    online: Res<crate::app::net::Online>,
    mut cursors: Query<&mut Cursor>,
) {
    let board = &sim.0;
    // Versus shares the keyboard, so IJKL belongs to the second seat there
    // whatever the one-hand preset says, and so does a co-op puzzle, whose
    // second cursor is on it.
    let shared = *screen.get() == Screen::Versus || cursors.iter().any(|c| c.player == 1);
    let commit = if shared {
        CommitScheme::Arrows
    } else {
        settings.commit
    };
    for mut cursor in &mut cursors {
        // Online: the one local cursor always answers to the primary keys.
        // Local: the keyboard has two seats; 3 and up are gamepad-only.
        let map = if online.0.is_some() {
            keymap(&settings, 0, commit)
        } else if cursor.player < 2 {
            keymap(&settings, cursor.player, commit)
        } else {
            continue;
        };
        let any_just = map.moves.iter().any(|(k, ..)| keys.just_pressed(*k));
        let any_held = map.moves.iter().any(|(k, ..)| keys.pressed(*k));
        let mut step = false;
        if any_just {
            step = true;
            cursor.repeat = Timer::from_seconds(settings.repeat_delay, TimerMode::Once);
        } else if any_held {
            cursor.repeat.tick(time.delta());
            if cursor.repeat.is_finished() {
                step = true;
                cursor.repeat = Timer::from_seconds(settings.repeat_interval, TimerMode::Once);
            }
        }
        if step {
            let (mut dx, mut dy) = (0i16, 0i16);
            for (key, kx, ky) in map.moves {
                if keys.pressed(key) {
                    dx += kx;
                    dy += ky;
                }
            }
            let nx = (i16::from(cursor.x) + dx).clamp(0, i16::from(board.width()) - 1) as u8;
            let ny = (i16::from(cursor.y) + dy).clamp(0, i16::from(board.height()) - 1) as u8;
            cursor.x = nx;
            cursor.y = ny;
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::app::play_input::*;
    use crate::app::settings::GameSettings;
    use crate::app::{PendingActions, PlacementDenied};
    use crate::sim::PlayerAction;
    use crate::sim::{TileKind, classic_arena};
    use bevy::prelude::KeyCode;

    /// A board, a settings resource, and one cursor per seat: the smallest
    /// world the input systems will run in. No art, so no sprites: these
    /// check the decisions, not the drawing.
    fn beach(seats: u8) -> App {
        let mut app = App::new();
        app.add_plugins(bevy::state::app::StatesPlugin);
        app.init_state::<Screen>();
        app.insert_resource(State::new(Screen::Versus));
        app.insert_resource(Sim(classic_arena(false, seats.max(2))));
        app.insert_resource(GameSettings::default());
        app.init_resource::<ButtonInput<KeyCode>>();
        app.init_resource::<Time>();
        app.init_resource::<PendingActions>();
        app.init_resource::<crate::app::net::Online>();
        app.add_message::<PlacementDenied>();
        for player in 0..seats {
            app.world_mut().spawn((
                Cursor {
                    player,
                    x: 5,
                    y: 4,
                    repeat: Timer::from_seconds(0.0, TimerMode::Once),
                    flash: 0.0,
                },
                Transform::default(),
            ));
        }
        app
    }

    /// A Tide Pool stage granting one arrow, in setup, with `hands`
    /// cursors on it: co-op when there are two.
    fn stage(hands: u8) -> App {
        use crate::app::{Campaign, CampaignKind, LoadLevel, Phase};
        let levels = crate::sim::campaign_levels();
        let index = levels
            .iter()
            .position(|level| level.posts == 1)
            .expect("a one-arrow stage");
        let builtins = levels.len();
        let mut app = App::new();
        app.add_plugins(bevy::state::app::StatesPlugin);
        app.init_state::<Screen>();
        app.insert_resource(State::new(Screen::Puzzle));
        app.init_state::<Phase>();
        app.insert_resource(Sim(levels[index].board()));
        app.insert_resource(Campaign {
            kind: CampaignKind::TidePool,
            levels,
            index,
            builtins,
        });
        app.insert_resource(GameSettings::default());
        app.init_resource::<crate::app::keycaps::KeyCaps>();
        app.init_resource::<crate::app::progress::Progress>();
        app.init_resource::<ButtonInput<KeyCode>>();
        app.add_message::<PlacementDenied>();
        app.add_message::<LoadLevel>();
        app.add_systems(Update, setup_input);
        for player in 0..hands {
            app.world_mut()
                .spawn((Cursor::seated(player), Transform::default()));
        }
        app
    }

    /// Put `player`'s cursor on `(x, y)`.
    fn park(app: &mut App, player: u8, (x, y): (u8, u8)) {
        let mut query = app.world_mut().query::<&mut Cursor>();
        for mut cursor in query.iter_mut(app.world_mut()) {
            if cursor.player == player {
                (cursor.x, cursor.y) = (x, y);
            }
        }
    }

    /// Two empty tiles of the stage, for the two hands to stand on.
    fn two_sand_tiles(app: &App) -> [(u8, u8); 2] {
        let board = &app.world().resource::<Sim>().0;
        let sand: Vec<(u8, u8)> = board
            .tiles()
            .filter(|&(x, y, kind)| kind == TileKind::Empty && board.can_place_signpost(0, x, y))
            .map(|(x, y, _)| (x, y))
            .collect();
        [sand[0], sand[sand.len() - 1]]
    }

    /// Co-op is one pool of arrows between two pairs of hands: the second
    /// cursor, on the second seat's keys, places the same seat's arrows,
    /// is refused once the pool is spent, and can pick up or re-point an
    /// arrow its partner put down.
    #[test]
    fn two_hands_share_one_pool_of_arrows() {
        let mut app = stage(2);
        let [a, b] = two_sand_tiles(&app);
        park(&mut app, 0, a);
        park(&mut app, 1, b);
        let count = |app: &App| app.world().resource::<Sim>().0.signpost_count(0);

        tap(&mut app, KeyCode::ArrowUp);
        assert_eq!(count(&app), 1, "P1 spends the one arrow");

        tap(&mut app, KeyCode::Numpad8);
        assert_eq!(count(&app), 1, "and there is none left for P2");
        assert!(
            app.world()
                .resource::<Sim>()
                .0
                .signpost_at(b.0, b.1)
                .is_none(),
            "P2's tile stays bare"
        );

        // P2 walks over and picks up P1's arrow, then puts it down again
        // pointing another way: it is the pair's, not P1's.
        park(&mut app, 1, a);
        tap(&mut app, KeyCode::Numpad0);
        assert_eq!(count(&app), 0, "P2 lifts P1's arrow");
        tap(&mut app, KeyCode::Numpad6);
        let post = app
            .world()
            .resource::<Sim>()
            .0
            .signpost_at(a.0, a.1)
            .expect("placed");
        assert_eq!((post.owner, post.dir), (0, Direction::Right));
    }

    /// Alone, the second seat's keys do nothing to a puzzle, and the
    /// one-hand preset still commits on IJKL; with a partner the preset
    /// stands down, since IJKL is the partner's.
    #[test]
    fn the_one_hand_preset_gives_way_to_a_partner() {
        for (hands, placed) in [(1, true), (2, false)] {
            let mut app = stage(hands);
            app.world_mut().resource_mut::<GameSettings>().commit = CommitScheme::Ijkl;
            let [a, _] = two_sand_tiles(&app);
            park(&mut app, 0, a);
            tap(&mut app, KeyCode::KeyI);
            let board = &app.world().resource::<Sim>().0;
            assert_eq!(
                board.signpost_at(a.0, a.1).is_some(),
                placed,
                "{hands} hand(s): IJKL commits for P1 only when nobody else has it"
            );
        }
    }

    fn tap(app: &mut App, key: KeyCode) {
        let mut keys = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
        keys.reset_all();
        keys.press(key);
        app.update();
        app.world_mut()
            .resource_mut::<ButtonInput<KeyCode>>()
            .reset_all();
    }

    fn cursor_at(app: &mut App, player: u8) -> (u8, u8) {
        app.world_mut()
            .query::<&Cursor>()
            .iter(app.world())
            .find(|c| c.player == player)
            .map(|c| (c.x, c.y))
            .expect("seat has a cursor")
    }

    /// `seated_here` is the rule three systems ask before they act:
    /// whether a post knocks, whether its ring is drawn, and whose pad a
    /// raid reaches. It answers for the seats with a cursor and no others,
    /// which leaves out the bots, the rivals down a wire, and a replay.
    #[test]
    fn only_the_seats_with_a_cursor_are_ours() {
        #[derive(Resource, Default)]
        struct Answers([bool; crate::sim::MAX_PLAYERS]);

        let mut app = beach(2);
        app.init_resource::<Answers>();
        app.add_systems(
            Update,
            |cursors: Query<&Cursor>, mut answers: ResMut<Answers>| {
                for seat in 0..crate::sim::MAX_PLAYERS {
                    answers.0[seat] = seated_here(&cursors, seat as u8);
                }
            },
        );
        app.update();
        let answers = &app.world().resource::<Answers>().0;
        assert!(answers[0] && answers[1], "the two seated players are ours");
        assert!(
            answers[2..].iter().all(|here| !here),
            "and nobody else is: {answers:?}"
        );
    }

    /// The snap [`glide_cursors`] keeps for long jumps, and the glide it
    /// keeps for everything else.
    #[test]
    fn a_long_jump_snaps_and_a_short_one_glides() {
        let mut app = beach(2);
        app.add_systems(Update, glide_cursors);
        // The board never changes under this test, so every tile centre it
        // needs can be read once, before the borrow checker gets involved.
        let (home, next_door, corner) = {
            let board = &app.world().resource::<Sim>().0;
            (
                layout::tile_center(board, 5, 4),
                layout::tile_center(board, 6, 4),
                layout::tile_center(board, 0, 0),
            )
        };
        // A frame has to pass for the glide to have a delta to work with.
        app.update();

        let mut place = |x: u8, y: u8| {
            let mut seats = app.world_mut().query::<&mut Cursor>();
            let world = app.world_mut();
            for mut cursor in seats.iter_mut(world) {
                if cursor.player == 0 {
                    cursor.x = x;
                    cursor.y = y;
                }
            }
            app.world_mut()
                .resource_mut::<Time>()
                .advance_by(std::time::Duration::from_millis(16));
            app.update();
            let mut at = app.world_mut().query::<(&Cursor, &Transform)>();
            let world = app.world();
            at.iter(world)
                .find(|(cursor, _)| cursor.player == 0)
                .map(|(_, t)| t.translation.truncate())
                .expect("seat one has a cursor")
        };

        // One tile over: on its way, not there yet.
        let stepped = place(6, 4);
        assert_ne!(stepped, home, "it did not move at all");
        assert!(
            stepped.distance(next_door) > 1.0,
            "one tile should glide, not snap: {stepped:?}"
        );
        // Right across the board: there in one frame.
        let jumped = place(0, 0);
        assert!(
            jumped.distance(corner) < 0.01,
            "a long jump has to snap: {jumped:?} vs {corner:?}"
        );
    }

    /// The keyboard drives two seats and only two: seats three and up wait
    /// for a pad rather than mirroring seat two's hands.
    #[test]
    fn the_keyboard_seats_two_and_stops() {
        let mut app = beach(4);
        app.add_systems(Update, move_cursor);

        // Seat 1 on W, seat 2 on I: the two default layouts.
        tap(&mut app, KeyCode::KeyW);
        assert_eq!(cursor_at(&mut app, 0), (5, 3), "seat 1 moved up");
        assert_eq!(cursor_at(&mut app, 1), (5, 4), "and only seat 1");

        tap(&mut app, KeyCode::KeyI);
        assert_eq!(cursor_at(&mut app, 1), (5, 3), "seat 2 moved up");
        assert_eq!(
            (cursor_at(&mut app, 2), cursor_at(&mut app, 3)),
            ((5, 4), (5, 4)),
            "seats 3 and 4 are pad seats and ignored the keyboard"
        );
    }

    /// Online there is one cursor, it may hold any seat, and it answers to
    /// the primary layout: a P4 online still plays on WASD.
    #[test]
    fn an_online_seat_plays_on_the_primary_keys() {
        let mut app = beach(0);
        app.world_mut().spawn((
            Cursor {
                player: 3,
                x: 5,
                y: 4,
                repeat: Timer::from_seconds(0.0, TimerMode::Once),
                flash: 0.0,
            },
            Transform::default(),
        ));
        app.add_systems(Update, move_cursor);

        // Offline, seat 4 is a pad seat and the keyboard does nothing.
        tap(&mut app, KeyCode::KeyA);
        assert_eq!(cursor_at(&mut app, 3), (5, 4));

        // A session that talks to nobody: `move_cursor` only asks whether
        // one exists, and an ephemeral socket keeps the test off the wire.
        let transport = crate::transport::UdpTransport::host(0).expect("ephemeral port");
        let lockstep = crate::sim::Lockstep::new(3, vec![0, 3], crate::sim::DEFAULT_DELAY);
        app.insert_resource(crate::app::net::Online(Some(
            crate::app::net::OnlineSession::new(
                transport,
                lockstep,
                4,
                crate::transport::MatchTerms::default(),
            ),
        )));
        tap(&mut app, KeyCode::KeyA);
        assert_eq!(cursor_at(&mut app, 3), (4, 4), "the same key now moves it");
    }

    /// A commit key queues a placement for the seat that pressed it, and a
    /// refused tile queues nothing, flashes the cursor, and says so.
    #[test]
    fn a_refused_placement_flashes_instead_of_queueing() {
        let mut app = beach(2);
        app.add_systems(Update, versus_input);
        app.world_mut()
            .resource_mut::<Sim>()
            .0
            .set_tile(5, 4, TileKind::Empty);

        // Empty sand: the arrow keys are seat 1's commit keys.
        tap(&mut app, KeyCode::ArrowUp);
        assert_eq!(
            app.world().resource::<PendingActions>().0[0],
            PlayerAction::Place {
                x: 5,
                y: 4,
                dir: Direction::Up
            }
        );
        assert_eq!(
            app.world().resource::<PendingActions>().0[1],
            PlayerAction::None,
            "seat 2 pressed nothing"
        );

        // A rock refuses, and the refusal is reported rather than silently
        // dropped.
        app.world_mut().resource_mut::<PendingActions>().0[0] = PlayerAction::None;
        app.world_mut()
            .resource_mut::<Sim>()
            .0
            .set_tile(5, 4, TileKind::Rock);
        tap(&mut app, KeyCode::ArrowUp);
        assert_eq!(
            app.world().resource::<PendingActions>().0[0],
            PlayerAction::None,
            "nothing was queued onto a rock"
        );
        let flash = app
            .world_mut()
            .query::<&Cursor>()
            .iter(app.world())
            .find(|c| c.player == 0)
            .map(|c| c.flash)
            .unwrap();
        assert!(flash > 0.0, "the cursor flashed red");
        assert_eq!(
            app.world()
                .resource::<Messages<PlacementDenied>>()
                .iter_current_update_messages()
                .count(),
            1
        );
    }

    /// Under the default scheme the two keyboard seats share no keys; the
    /// single-hand preset deliberately reuses IJKL and is guarded to solo
    /// modes elsewhere.
    #[test]
    fn default_keyboard_seats_do_not_collide() {
        let collect = |player: u8| -> Vec<KeyCode> {
            let map = keymap(&GameSettings::default(), player, CommitScheme::Arrows);
            let mut keys: Vec<KeyCode> = map.moves.iter().map(|(k, ..)| *k).collect();
            keys.extend(map.places.iter().map(|(k, _)| *k));
            keys.push(map.remove);
            keys.push(map.clear_all);
            keys
        };
        let p1 = collect(0);
        for key in collect(1) {
            assert!(!p1.contains(&key), "{key:?} is bound for both seats");
        }
    }

    /// A finished online match with the results card up, over a real
    /// socket: seat 0 hosts (with the beacon it carried out of the lobby),
    /// anything else joins.
    fn results_card(seat: u8, from_lobby: bool, series_on: bool) -> App {
        use crate::app::net::{Online, OnlineSession};
        use crate::app::tournament::Tournament;
        use crate::sim::{DEFAULT_DELAY, Lockstep};
        use crate::transport::{Announcer, MatchTerms, UdpTransport};

        let mut app = beach(2);
        app.init_resource::<Tournament>();
        app.init_resource::<crate::app::lobby::Homecoming>();
        app.init_resource::<crate::app::pause::PauseMenu>();
        app.add_systems(Update, versus_over_input);
        let host = seat == 0;
        let transport = match host {
            true => UdpTransport::host(0).expect("game socket"),
            false => UdpTransport::join(("127.0.0.1", 47999)).expect("join"),
        };
        let mut session = OnlineSession::new(
            transport,
            Lockstep::new(seat, vec![0, 1], DEFAULT_DELAY),
            2,
            MatchTerms::default(),
        );
        session.home.from_lobby = from_lobby;
        // A host formed in the lobby always carries the beacon out of it:
        // the two are set together at the launch.
        if host && from_lobby {
            session.stay_on_air(Announcer::new(0xB0A7).expect("announcer"));
        }
        if series_on {
            *app.world_mut().resource_mut::<Tournament>() =
                Tournament::start(crate::app::tournament::SeriesLength::BestOfFive);
        }
        app.world_mut().resource_mut::<Online>().0 = Some(session);
        app
    }

    /// Where a tap on the results card actually lands, transition applied.
    fn pressing_enter(app: &mut App) -> Screen {
        tap(app, KeyCode::Enter);
        // One more, to let the state transition apply.
        app.update();
        *app.world().resource::<State<Screen>>().get()
    }

    /// The end of a lobby match is a door back to the lobby, not out to the
    /// menu. The table came in together and goes back together, still
    /// connected, so the next game is a keypress rather than a
    /// rediscovery.
    #[test]
    fn the_end_of_a_lobby_match_walks_the_table_back_to_the_lobby() {
        use crate::app::lobby::Homecoming;
        use crate::app::net::Online;

        for seat in [0, 1] {
            let mut app = results_card(seat, true, false);
            assert_eq!(pressing_enter(&mut app), Screen::Lobby, "seat {seat}");
            let homecoming = app.world().resource::<Homecoming>();
            let returned = homecoming.0.as_ref().expect("the table came home");
            assert_eq!(returned.host, seat == 0);
            assert!(
                app.world().resource::<Online>().0.is_none(),
                "the session was handed over whole, not left behind"
            );
            if seat == 0 {
                assert!(
                    returned.announcer.is_some(),
                    "and the beacon came with it, to announce the beach open again"
                );
            }
        }
    }

    /// The direct `PINCH_HOST`/`PINCH_JOIN` pair never went through a
    /// lobby, so there is none to go back to: its Enter still means the
    /// menu, and nothing is left waiting in `Homecoming` for a lobby that
    /// is never opened.
    #[test]
    fn a_direct_pair_has_no_lobby_to_go_back_to() {
        use crate::app::lobby::Homecoming;

        let mut app = results_card(0, false, false);
        assert_eq!(pressing_enter(&mut app), Screen::Menu);
        assert!(app.world().resource::<Homecoming>().0.is_none());
    }

    /// Mid-series the card is a doorway between rounds, and Enter keeps
    /// its old meanings: the host calls the next round, and a joiner's
    /// Enter is still its way out, since the series plays on without it.
    /// Only once the series is over does the table walk home together.
    #[test]
    fn a_running_series_still_owns_enter() {
        use crate::app::lobby::Homecoming;

        let mut app = results_card(1, true, true);
        assert_eq!(
            pressing_enter(&mut app),
            Screen::Menu,
            "leaving a series is leaving"
        );
        assert!(app.world().resource::<Homecoming>().0.is_none());

        let mut app = results_card(0, true, true);
        assert_eq!(
            pressing_enter(&mut app),
            Screen::Interlude,
            "the host calls the next round instead"
        );
        assert!(app.world().resource::<Homecoming>().0.is_none());
    }

    /// With the pause card up over the results card, Enter is the card's.
    /// It used to reach both: the host's "Back to menu" called the next
    /// round for the whole table first, then left it.
    #[test]
    fn the_pause_card_keeps_its_enter() {
        let mut app = results_card(0, true, true);
        app.world_mut()
            .resource_mut::<crate::app::pause::PauseMenu>()
            .open = true;
        assert_eq!(pressing_enter(&mut app), Screen::Versus);
    }

    /// The Enter that ends the match must not also start the next one.
    ///
    /// A host lands back in the lobby with its peers still aboard, and
    /// there Enter is the launch key: one press that both left the results
    /// card and reached `host_tick` would deal a fresh round before anybody
    /// had read the scores. What prevents it is the order the engine runs
    /// in, so that is what this checks, with the real input plugin: a press
    /// is cleared in `PreUpdate` and the state transition lands after it,
    /// so the screen a keypress arrives on is the only one that sees it.
    #[test]
    fn one_press_is_only_ever_read_by_one_screen() {
        use bevy::input::ButtonState;
        use bevy::input::keyboard::{Key, KeyboardInput};

        #[derive(Resource, Default)]
        struct SeenInTheLobby(bool);

        let mut app = App::new();
        app.add_plugins((bevy::state::app::StatesPlugin, bevy::input::InputPlugin));
        app.init_state::<Screen>();
        app.insert_resource(State::new(Screen::Versus));
        app.init_resource::<SeenInTheLobby>();
        app.add_systems(
            Update,
            (
                // Standing in for the results card: Enter leaves for the
                // lobby, exactly as `versus_over_input` does.
                (|keys: Res<ButtonInput<KeyCode>>, mut next: ResMut<NextState<Screen>>| {
                    if keys.just_pressed(KeyCode::Enter) {
                        next.set(Screen::Lobby);
                    }
                })
                .run_if(in_state(Screen::Versus)),
                // Standing in for `host_tick`, where Enter launches.
                (|keys: Res<ButtonInput<KeyCode>>, mut seen: ResMut<SeenInTheLobby>| {
                    seen.0 |= keys.just_pressed(KeyCode::Enter);
                })
                .run_if(in_state(Screen::Lobby)),
            ),
        );

        app.world_mut().write_message(KeyboardInput {
            key_code: KeyCode::Enter,
            logical_key: Key::Enter,
            state: ButtonState::Pressed,
            text: None,
            repeat: false,
            window: Entity::PLACEHOLDER,
        });
        app.update();
        // The key is never released: a player's finger is still on it as
        // the lobby comes up, which is the whole worry.
        app.update();
        app.update();
        assert_eq!(
            *app.world().resource::<State<Screen>>().get(),
            Screen::Lobby
        );
        assert!(
            !app.world().resource::<SeenInTheLobby>().0,
            "the lobby read the Enter that was meant for the results card"
        );
    }
}