shuyi_ui/

game.rs

//! [`Game`]: a whole game's UI behind one call per frame. The platform
//! feeds it raw key and controller-button events and the frame time and
//! shows the buffer it returns; a test drives it the same way without a
//! window.
//!
//! The game gives the screen it starts on and its [`GameHooks`]: the
//! screen the first key opens while no layout is chosen (a layout picker),
//! and the debug menu. Modules from outside the default engine join it
//! with [`Game::with_module`] ([`crate::module`]).

use crate::prelude::*;
use core::any::Any;
use core::fmt;

use shuyi_core::StateHash;

use shuyi_assets::audio::AudioManifest;
use shuyi_assets::dialogue::LineId;
use shuyi_assets::keymap::{ActionSet, Button, Chord, Key, UiAction};

use crate::audio::{AudioConfig, AudioRequest, MusicClock, MusicCommand, MusicState};
use crate::ctx::{Ctx, GameData, KeyPrompt, Keyboard};
use crate::debug;
use crate::frame::EngineColor;
use crate::frame::glyph_buffer::{Cell, GlyphBuffer, Rect};
use crate::frame_cap::{FrameCap, Pacing};
use crate::input::crank::{Crank, Notches, only_on_the_crank};
use crate::input::frame_seconds;
use crate::input::pad::{PadId, PadKind, PadState, Pads};
use crate::input::state::{Device, InputState};
use crate::log::{LogCategory, LogLevel};
use crate::module::{self, Hook, Install, InstalledModule, Module, ModuleError};
use crate::perf::{self, TagClass};
use crate::screen::{FrameInput, Screen, ScreenStack, Transition};
use shuyi_assets::font::CellWidths;

/// A keyboard or controller event as the platform reports it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum RawInputEvent {
    /// A key went down, with the Shift state at the time.
    Down(Chord),
    /// A key went up.
    Up(Key),
    /// A character was typed (the platform's text input: the keyboard's own
    /// layout and Shift applied), for text boxes such as a name. Comes with
    /// the key's own `Down`.
    Text(#[serde(with = "one_char")] char),
    /// A controller button went down on a pad of this kind (its binding
    /// position, from [`Pads::update`]).
    PadDown(Button, PadKind),
    /// A controller button went up on every pad.
    PadUp(Button),
}

/// A typed character in a file, as a string of one character: RON escapes a
/// string, and writes a `char` as it is, so a typed line break would break the
/// line it is written on.
mod one_char {
    use serde::de::Error;
    use serde::{Deserialize, Deserializer, Serializer};

    use crate::prelude::*;

    /// Serde hands it a reference, whatever a `char`'s size.
    pub fn serialize<C: Copy + Into<char>, S: Serializer>(
        c: &C,
        serializer: S,
    ) -> Result<S::Ok, S::Error> {
        serializer.serialize_str((*c).into().encode_utf8(&mut [0; 4]))
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<char, D::Error> {
        let text = String::deserialize(deserializer)?;
        let mut chars = text.chars();
        match (chars.next(), chars.next()) {
            (Some(c), None) => Ok(c),
            _ => Err(D::Error::custom("expected one character")),
        }
    }
}

impl RawInputEvent {
    /// This frame's controller events: what [`Pads::update`] reports for
    /// the pads `connected` now, releases first, each press with the kind
    /// of the pad that pressed it.
    pub fn from_pads(pads: &mut Pads, connected: &[(PadId, PadKind, PadState)]) -> Vec<Self> {
        let changes = pads.update(connected);
        let event = |(button, pressed)| {
            if pressed {
                let kind = pads.kind_holding(button, connected).unwrap_or_default();
                Self::PadDown(button, kind)
            } else {
                Self::PadUp(button)
            }
        };
        changes.into_iter().map(event).collect()
    }

    /// This frame's crank events: the crank turned `degrees` since the
    /// last frame (forwards positive), on a pad of `kind`; `docked` if it
    /// is folded away (then nothing, and a part notch is forgotten). Each
    /// notch is a press and a release of [`Button::CrankBack`] or
    /// [`Button::CrankForward`] ([`Crank`]).
    pub fn from_crank(crank: &mut Crank, degrees: f32, docked: bool, kind: PadKind) -> Vec<Self> {
        if docked {
            crank.dock();
            return Vec::new();
        }
        Self::crank_notches(crank.turn(degrees), kind)
    }

    /// [`from_crank`](Self::from_crank) of a turn in whole `steps`
    /// ([`Crank::turn_steps`]): what a backend that reads a float hands on
    /// from its boundary.
    pub fn from_crank_steps(
        crank: &mut Crank,
        steps: i32,
        docked: bool,
        kind: PadKind,
    ) -> Vec<Self> {
        if docked {
            crank.dock();
            return Vec::new();
        }
        Self::crank_notches(crank.turn_steps(steps), kind)
    }

    /// A press and a release for each of `notches`.
    fn crank_notches(notches: Notches, kind: PadKind) -> Vec<Self> {
        let Some((button, times)) = Crank::presses(notches) else {
            return Vec::new();
        };
        (0..times)
            .flat_map(|_| [Self::PadDown(button, kind), Self::PadUp(button)])
            .collect()
    }
}

/// The result of one frame. `V` is the game's voice clip variant. Only
/// [`Game::frame`] builds one, so a field may come without breaking a game
/// (ADR-0039).
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub struct FrameOutput<'a, V> {
    /// What to show.
    pub buffer: &'a GlyphBuffer,
    /// Whether the game has asked to quit (it then ignores further input).
    pub quit: bool,
    /// Every audio request screens made this frame, in order. The platform
    /// plays the sounds; the music requests are already turned into
    /// [`music`].
    ///
    /// [`music`]: Self::music
    pub audio: &'a [AudioRequest<V>],
    /// What to do to the music this frame.
    pub music: &'a [MusicCommand],
    /// The player's music volume, 0–1: the platform multiplies the music's
    /// own volume by it, also for a track already playing.
    pub music_volume: f32,
    /// The player's sound volume, 0–1: the platform multiplies every
    /// sound's own volume by it.
    pub sound_volume: f32,
    /// Whether the game should fill the screen (the Fullscreen setting);
    /// the platform switches when this changes.
    pub fullscreen: bool,
    /// How loud voice clips play, 0–1
    /// ([`Settings::voice_volume`](crate::settings::Settings::voice_volume)). The
    /// platform applies it to the voice that is playing too.
    pub voice_volume: f32,
    /// The most frames a second to show (the player's frame cap): the
    /// platform paces its frames to it from the next.
    pub frame_cap: FrameCap,
    /// The serial of the cap's latest change ([`Ctx::frame_cap_serial`]):
    /// the platform reports it back once it has applied the cap
    /// ([`Game::set_pacing`]).
    pub frame_cap_serial: u32,
}

/// A screen the engine opens for the game, by name.
pub struct ScreenHook<G: GameData> {
    /// The screen's [`name`](Screen::name).
    pub name: &'static str,
    /// Makes the screen.
    pub open: fn(&Ctx<G>) -> Box<dyn Screen<G>>,
}

impl<G: GameData> Clone for ScreenHook<G> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<G: GameData> Copy for ScreenHook<G> {}

// check-text: not player text (debug output)
impl<G: GameData> fmt::Debug for ScreenHook<G> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "ScreenHook({})", self.name)
    }
}

/// Where the game has a say in the frame loop. [`Default`] has none.
#[derive(Debug)]
pub struct GameHooks<G: GameData> {
    /// What the first key press opens while no layout is chosen, on a
    /// platform with a keyboard (a layout picker): it opens over whatever
    /// shows, and the key does nothing else. Never while a screen of its
    /// name is open.
    pub first_key: Option<ScreenHook<G>>,
    /// What the Debug action ([`UiAction::Debug`]) opens with debug tools
    /// on ([`Ctx::debug_tools`]), unless the top screen is one of
    /// [`debug_screens`](Self::debug_screens).
    pub debug: Option<ScreenHook<G>>,
    /// The debug tools' screens, over which the Debug action does nothing.
    pub debug_screens: &'static [&'static str],
}

impl<G: GameData> Default for GameHooks<G> {
    fn default() -> Self {
        Self {
            first_key: None,
            debug: None,
            debug_screens: &[],
        }
    }
}

/// Owns the screens, input state, shared context and the console buffer.
pub struct Game<G: GameData> {
    stack: ScreenStack<G>,
    input: InputState<G::Action>,
    ctx: Ctx<G>,
    hooks: GameHooks<G>,
    buffer: GlyphBuffer,
    quit: bool,
    music: MusicState,
    /// This frame's audio requests and music commands.
    audio_out: Vec<AudioRequest<G::Voice>>,
    music_out: Vec<MusicCommand>,
    /// The fixed simulation steps due in the next frame
    /// ([`set_ticks`](Self::set_ticks)).
    ticks: u32,
    /// Whether the game came back from a suspend before the next frame
    /// ([`set_resumed`](Self::set_resumed)).
    resumed: bool,
    /// The installed modules, and what each declared, in install order.
    modules: Vec<Box<dyn Module<G>>>,
    installed: Vec<InstalledModule>,
}

impl<G: GameData> Game<G> {
    /// A game showing `root`, with the game's `hooks`.
    pub fn new(ctx: Ctx<G>, root: Box<dyn Screen<G>>, hooks: GameHooks<G>) -> Self {
        Self::with_stack(ctx, ScreenStack::new(root), hooks)
    }

    /// A game showing the screens of `stack`, with the game's `hooks`,
    /// already drawn. Music switches as the audio manifest's default switch
    /// says ([`AudioManifest::music_switch`]).
    pub fn with_stack(ctx: Ctx<G>, stack: ScreenStack<G>, hooks: GameHooks<G>) -> Self {
        let input = InputState::new(ctx.keymap.clone()).starting_on(ctx.device);
        let blank = ctx.game.blank_cell(&ctx.palette);
        let switch = ctx.game.audio_manifest().music_switch();
        let mut game = Self {
            stack,
            input,
            buffer: GlyphBuffer::with_spec(ctx.console, blank).with_widths(ctx.widths().clone()),
            ctx,
            hooks,
            quit: false,
            music: MusicState::with_switch(switch),
            audio_out: Vec::new(),
            music_out: Vec::new(),
            ticks: 0,
            resumed: false,
            modules: Vec::new(),
            installed: Vec::new(),
        };
        game.stack.own_top(&mut game.ctx);
        game.redraw();
        game
    }

    /// The same game with `module` installed after those it has: its
    /// [`install`](Module::install) runs, and the frame is drawn again
    /// with what it draws. Refused for a name already installed or a state
    /// another module put on the context.
    pub fn with_module(self, module: impl Module<G>) -> Result<Self, ModuleError> {
        self.with_modules([Box::new(module) as Box<dyn Module<G>>])
    }

    /// The same game with `modules` installed in order, as
    /// [`with_module`](Self::with_module) installs one.
    pub fn with_modules(
        mut self,
        modules: impl IntoIterator<Item = Box<dyn Module<G>>>,
    ) -> Result<Self, ModuleError> {
        for module in modules {
            self.install(module)?;
        }
        self.redraw();
        Ok(self)
    }

    fn install(&mut self, mut module: Box<dyn Module<G>>) -> Result<(), ModuleError> {
        let name = module.name();
        debug_assert!(
            module::is_snake_case(name),
            "a module's name is snake_case ASCII: {name:?}"
        );
        if self.installed.iter().any(|m| m.name == name) {
            return Err(ModuleError::SameName { name });
        }
        let mut install = Install::new(&mut self.ctx, name);
        module.install(&mut install);
        self.installed.push(install.finish()?);
        self.modules.push(module);
        Ok(())
    }

    /// The installed modules, in install order, with what each declared.
    pub fn modules(&self) -> &[InstalledModule] {
        &self.installed
    }

    /// Turns the debug tools (the Debug action) on or off
    /// ([`Ctx::debug_tools`]).
    #[must_use]
    pub fn with_debug_screens(mut self, on: bool) -> Self {
        self.ctx.debug_tools = on;
        self
    }

    /// Turns the screens' action guard on or off
    /// ([`ScreenStack::guard_actions`]): while it is on, a screen that
    /// declares its actions is handed only those. The test Harness turns
    /// it on.
    pub fn guard_actions(&mut self, on: bool) {
        self.stack.guard_actions(on);
    }

    /// Every action held back from a screen that doesn't declare it, with
    /// the screen's name ([`ScreenStack::undeclared`]).
    pub fn undeclared_actions(&self) -> &[(&'static str, G::Action)] {
        self.stack.undeclared()
    }

    /// Tells the game what music is sounding, for [`Ctx::music_clock`]: the
    /// cue and the seconds since the track really started, or `None` in
    /// silence. The platform knows (a track starts once its file has
    /// loaded) and calls this before every [`frame`](Self::frame), so
    /// screens read a clock at most one frame old. The music's fades learn
    /// from it when a new track sounds ([`MusicState::heard`]).
    pub fn set_music_playing(&mut self, playing: Option<(&str, f64)>) {
        let manifest = self.ctx.game.audio_manifest();
        self.ctx.music_clock =
            playing.and_then(|(cue, elapsed)| MusicClock::from_elapsed(manifest, cue, elapsed));
        self.music.heard(self.ctx.music_clock.as_ref());
    }

    /// Tells the game which line's voice clip is sounding, for
    /// [`Ctx::voice_playing`], or `None` in silence. The platform knows
    /// (a clip sounds once its file has loaded, and until it ends) and
    /// calls this before every [`frame`](Self::frame), as it does
    /// [`set_music_playing`](Self::set_music_playing).
    pub fn set_voice_playing(&mut self, line: Option<&LineId>) {
        if self.ctx.voice_playing.as_ref() != line {
            self.ctx.voice_playing = line.cloned();
        }
    }

    /// Tells the game how the platform paces its frames: the frame cap it
    /// applied with its serial, and the frames a second it measured
    /// ([`Pacing`]). The platform calls this before every
    /// [`frame`](Self::frame), as it does
    /// [`set_music_playing`](Self::set_music_playing), so a request for a
    /// cap is confirmed ([`Ctx::frame_cap_status`]) and a screen can show
    /// the frame rate ([`Ctx::pacing`]).
    pub fn set_pacing(&mut self, report: Pacing) {
        self.ctx.set_pacing(report);
    }

    /// Says how many fixed simulation steps are due in the next
    /// [`frame`](Self::frame) (ADR-0003 §2): its screen reads them as
    /// [`FrameInput::ticks`]. The platform's `App` counts them from its
    /// clock and calls this before every frame; a frame after none has 0.
    pub fn set_ticks(&mut self, ticks: u32) {
        self.ticks = ticks;
    }

    /// Says the system resumed the game from a suspend before the next
    /// [`frame`](Self::frame): its screen reads it as
    /// [`FrameInput::resumed`], and a tick stage's
    /// [`TickDriver`](crate::tick::TickDriver) forgets the presses it kept
    /// from before. That frame lets go of every key and button held before
    /// the suspend ([`InputState::release_all`]) before it applies its
    /// events, so a key let go while suspended doesn't stay held, and one
    /// pressed in that frame counts. The platform's `App` calls it on the
    /// system's `Resume`.
    pub fn set_resumed(&mut self) {
        self.resumed = true;
    }

    /// Lets go of every key and button held now ([`InputState::release_all`]):
    /// the next frame reports their actions let go, and one still down
    /// counts once it is pressed again. The platform's `App` calls it on
    /// the system's `FocusLost`, since a window without focus hears no
    /// release.
    pub fn forget_held_input(&mut self) {
        self.input.release_all();
    }

    /// Flips the Fullscreen setting, as a window's own shortcut does. The
    /// platform then switches the window on the next frame, and an options
    /// screen shows the new value. Does nothing where the game isn't in a
    /// window ([`PlatformFacts::windowed`](crate::PlatformFacts::windowed)
    /// false): a device that is always full screen.
    pub fn toggle_fullscreen(&mut self) {
        if self.ctx.platform.windowed {
            let _ = self.ctx.change_settings(|s| s.fullscreen = !s.fullscreen);
        }
    }

    /// Tells the modules that declared [`Hook::Reloaded`], in install order,
    /// that the files at `changed` changed on disk (paths in the bundle).
    /// The platform's `App` calls it before the frame's update, in a build
    /// with debug tools on. After a quit, nothing.
    pub fn reloaded(&mut self, changed: &[String]) {
        if self.quit {
            return;
        }
        for (module, installed) in self.modules.iter_mut().zip(&self.installed) {
            if installed.hooks.contains(&Hook::Reloaded) {
                module.reloaded(&mut self.ctx, changed);
            }
        }
    }

    /// Runs one frame: applies `events` (in order), advances input by `dt`
    /// seconds, updates the top screen with the resulting actions, collects
    /// its audio requests and redraws. After a quit, frames do nothing. In
    /// a frame the platform measures ([`Ctx::begin_perf_frame`]) it times
    /// the update and the drawing, and with memory scopes
    /// ([`Ctx::set_memory_scopes`]) it tags what each allocates `update`
    /// and `draw` ([`crate::perf`]).
    pub fn frame(&mut self, events: &[RawInputEvent], dt: f32) -> FrameOutput<'_, G::Voice> {
        self.audio_out.clear();
        self.music_out.clear();
        // Nonsense frame times pass no time, for the screens, the clock and
        // the music alike.
        let dt = frame_seconds(dt);
        let ticks = core::mem::take(&mut self.ticks);
        let resumed = core::mem::take(&mut self.resumed);
        if !self.quit {
            // The update's and the drawing's times, in a frame the
            // platform measures, and with memory scopes their tags
            // (crate::perf).
            let tagged = self.ctx.enter_tag(TagClass::Phase, "update");
            let start = self.ctx.perf_now_in_frame();
            self.step(events, dt, (ticks, resumed));
            let drawing = self.ctx.perf_now_in_frame();
            perf::leave_tag(tagged);
            let tagged = self.ctx.enter_tag(TagClass::Phase, "draw");
            self.redraw();
            let drawn = self.ctx.perf_now_in_frame();
            perf::leave_tag(tagged);
            self.ctx.set_perf_frame_times(start, drawing, drawn);
            self.collect_audio(dt);
        }
        FrameOutput {
            buffer: &self.buffer,
            quit: self.quit,
            audio: &self.audio_out,
            music: &self.music_out,
            music_volume: self.ctx.settings().music_factor(),
            sound_volume: self.ctx.settings().sound_factor(),
            fullscreen: self.ctx.settings().fullscreen,
            voice_volume: self.ctx.settings().voice_factor(),
            frame_cap: self.ctx.settings().frame_cap,
            frame_cap_serial: self.ctx.frame_cap_serial(),
        }
    }

    /// Advances the sounds' fades, moves the screens' audio requests into
    /// this frame's output and runs the music state machine. In debug
    /// builds, a cue the manifest lacks is a bug in the screen and panics,
    /// and so does a looped cue played without a handle, which nothing
    /// could stop (a release build plays it once). The engine's widgets
    /// play the game's [`AudioConfig`](crate::audio::AudioConfig) cues
    /// whatever sounds it has, so one the manifest lacks is silence: a game
    /// with no sounds has quiet menus.
    fn collect_audio(&mut self, dt: f32) {
        self.ctx.audio.advance(dt);
        self.audio_out = self.ctx.audio.take();
        for problem in self.ctx.audio.take_problems() {
            self.ctx.log(LogLevel::Warn, LogCategory::Audio, problem);
        }
        for request in &self.audio_out {
            let manifest = self.ctx.game.audio_manifest();
            debug_assert!(
                is_known(manifest, request)
                    || is_widget_cue(&self.ctx.game.audio_config(), request)
                    || request
                        .cue()
                        .is_some_and(|cue| self.ctx.audio.knows_added(cue)),
                "audio request for a cue not in the audio manifest: {request:?}"
            );
            debug_assert!(
                !plays_a_loop(manifest, request),
                "play_sound of the looped cue {:?}: start it with start_sound, whose handle stops it",
                request.cue().unwrap_or_default()
            );
            self.music.request(request, &mut self.music_out);
        }
        self.music.update(dt, &mut self.music_out);
    }

    /// One frame's update: `events` in order, `dt` seconds, and the fixed
    /// steps due with whether the game just resumed.
    fn step(&mut self, events: &[RawInputEvent], dt: f32, (ticks, resumed): (u32, bool)) {
        // Bindings changed between frames (a test rebinding keys).
        self.sync_keymap();
        // A key let go while the game was suspended never came up: let go
        // of everything held before, ahead of this frame's presses.
        if resumed {
            self.input.release_all();
        }
        let mut pressed = Vec::new();
        let mut text = Vec::new();
        let mut buttons_down = Vec::new();
        let mut buttons_up = Vec::new();
        // Until a layout is chosen no key acts: the first one opens the
        // game's first-key screen over whatever is showing and does nothing
        // else; that screen then takes the keys. Without a keyboard, never.
        let first_key = self.hooks.first_key.filter(|hook| {
            self.ctx.platform.keyboard == Keyboard::Present
                && self.ctx.layout().is_none()
                && !self.stack.names().contains(&hook.name)
                && events.iter().any(|e| matches!(e, RawInputEvent::Down(_)))
        });
        for &event in events {
            // Any key or any controller button ends the wait for one.
            let press = matches!(event, RawInputEvent::Down(_) | RawInputEvent::PadDown(..));
            let ends_wait = press && self.ctx.key_prompt == KeyPrompt::Waiting;
            if ends_wait {
                self.ctx.key_prompt = KeyPrompt::Pressed;
            }
            match event {
                RawInputEvent::Down(_) if first_key.is_some() => self.input.keyboard_used(),
                RawInputEvent::Down(chord) => {
                    self.input.key_down(chord);
                    pressed.push(chord);
                }
                RawInputEvent::Up(key) => self.input.key_up(key),
                // Control characters (Enter, Backspace, Escape on some
                // platforms) are keys, not text.
                RawInputEvent::Text(c) if !c.is_control() => text.push(c),
                RawInputEvent::Text(_) => {}
                RawInputEvent::PadDown(button, kind) => {
                    self.input.pad_down(button, kind);
                    if ends_wait {
                        // The wait takes it: nothing when let go either
                        // (a chord button's action).
                        self.input.pad_taken(button);
                    }
                    buttons_down.push(button);
                }
                RawInputEvent::PadUp(button) => {
                    self.input.pad_up(button);
                    buttons_up.push(button);
                }
            }
        }
        self.ctx.clock_s += f64::from(dt);
        self.ctx.device = self.input.device();
        let actions = self.input.update(dt);
        let held = self.held();
        for (module, installed) in self.modules.iter_mut().zip(&self.installed) {
            if installed.hooks.contains(&Hook::BeforeUpdate) {
                module.before_update(&mut self.ctx, dt);
            }
        }
        let debug = self.hooks.debug.filter(|_| {
            self.ctx.debug_tools
                && actions.iter().any(|a| a.ui() == Some(UiAction::Debug))
                && !self
                    .stack
                    .top_name()
                    .is_some_and(|n| self.hooks.debug_screens.contains(&n))
        });
        if let Some(hook) = first_key {
            self.open(hook);
        }
        if let Some(hook) = debug {
            self.open(hook);
        } else {
            // A chord button gives its own action when let go or after the
            // chord window: that is pad input too.
            let from_pad = !buttons_down.is_empty()
                || (!actions.is_empty() && matches!(self.ctx.device, Device::Pad(_)));
            // The actions that went down and came up, for the fixed steps.
            let downs = self.input.presses().to_vec();
            let ups = self.input.released().to_vec();
            let input = FrameInput::new(actions, dt, held)
                .with_presses(downs, ups)
                .with_typing(pressed, text)
                .with_buttons(buttons_down, buttons_up)
                .with_pad(from_pad)
                .with_ticks(ticks)
                .with_resumed(resumed);
            self.quit = self.stack.update(&mut self.ctx, &input);
            self.sync_keymap();
        }
    }

    /// Hands the top screen `action` alone, in an update of its own with no
    /// time passing, as if a key bound to it had just been pressed: an
    /// action from outside the keys and buttons, such as an entry of the
    /// platform's own menu (the Playdate's system menu, ticket 1035). The
    /// screen does with it what it does with the key, or nothing. Its
    /// sounds come out with the next frame. No step is due in it: a tick
    /// stage keeps it as a tap (pressed, and let go unless a key holds it)
    /// for its next step. After a quit, nothing.
    pub fn act(&mut self, action: G::Action) {
        if self.quit {
            return;
        }
        let held = self.held();
        let from_pad = matches!(self.ctx.device, Device::Pad(_));
        let input = FrameInput::new(vec![action], 0.0, held).with_pad(from_pad);
        self.quit = self.stack.update(&mut self.ctx, &input);
        self.sync_keymap();
        self.redraw();
    }

    /// Opens `hook`'s screen over the top one, which hears it is covered.
    fn open(&mut self, hook: ScreenHook<G>) {
        let screen = (hook.open)(&self.ctx);
        self.stack.apply_in(&mut self.ctx, Transition::Push(screen));
    }

    /// The actions whose keys or buttons are held.
    fn held(&self) -> Vec<G::Action> {
        G::Action::ALL
            .iter()
            .copied()
            .filter(|&a| self.input.is_held(a))
            .collect()
    }

    /// Hands `ctx`'s keymap to the input if it changed (a layout was
    /// picked, keys were rebound), so the new keys work from the next press.
    fn sync_keymap(&mut self) {
        if *self.input.keymap() != self.ctx.keymap {
            self.input.set_keymap(self.ctx.keymap.clone());
        }
    }

    /// Prints the characters `widths` has wide in two cells, as the font
    /// atlas the frame is drawn with has them ([`CellWidths::of`]), in the
    /// language text is shown in ([`Ctx::widths`], which the frame's
    /// [`GlyphBuffer::widths`] follow). The frame is drawn again if that
    /// changed them. The platform calls it once the game has loaded, with
    /// its look's atlas, and again after its files change.
    ///
    /// [`CellWidths::of`]: shuyi_assets::font::CellWidths::of
    pub fn set_widths(&mut self, widths: CellWidths) {
        self.ctx.set_widths(widths);
        if self.buffer.widths() != self.ctx.widths() {
            self.redraw();
        }
    }

    /// Clears the buffer and draws the stack into it, then the modules
    /// over it, then, with debug tools on, the debug view's gizmos over
    /// everything: after a change made from outside the frame loop (a test
    /// changing the context). The buffer takes the widths of the language
    /// text is shown in first ([`Ctx::widths`]).
    pub fn redraw(&mut self) {
        if self.buffer.widths() != self.ctx.widths() {
            self.buffer.set_widths(self.ctx.widths().clone());
        }
        let blank = self.ctx.game.blank_cell(&self.ctx.palette);
        self.buffer.fill_rect(self.buffer.bounds(), blank);
        self.stack.draw(&self.ctx, &mut self.buffer);
        for (module, installed) in self.modules.iter().zip(&self.installed) {
            if installed.hooks.contains(&Hook::DrawOver) {
                module.draw_over(&self.ctx, &mut self.buffer);
            }
        }
        self.draw_crank_hint();
        self.draw_gizmos();
    }

    /// With debug tools on, asks the screens drawn for the debug view's
    /// gizmos ([`Screen::debug_draw`], ADR-0085), keeps the channels they
    /// offer for the debug menu, and paints those of the channels on over
    /// everything. It asks with no channel on too: that is how a channel
    /// is offered. With debug tools off, nothing is asked.
    fn draw_gizmos(&mut self) {
        if !self.ctx.debug_tools {
            return;
        }
        let mut gizmos = self
            .ctx
            .debug_view
            .gizmos()
            .within(self.buffer.pixel_bounds());
        self.stack.debug_draw(&self.ctx, &mut gizmos);
        self.ctx.debug_view.offer(gizmos.offered());
        if !gizmos.is_empty() {
            debug::glyph::paint_gizmos(&self.ctx.palette, &gizmos, &mut self.buffer);
        }
    }

    /// The hint to unfold the crank, on the last row, while it is docked
    /// and an action the top screen requires can only be pressed by
    /// winding it: a docked crank gives no notches.
    fn draw_crank_hint(&mut self) {
        if !self.ctx.crank_docked {
            return;
        }
        let needs_crank = self.stack.top_actions().is_some_and(|actions| {
            actions
                .into_iter()
                .filter(|action| action.is_required())
                .any(|action| only_on_the_crank(&self.input.keymap().buttons_for(action)))
        });
        if !needs_crank {
            return;
        }
        let hint = if self.ctx.game.lang().has(CRANK_HINT) {
            self.ctx.text(CRANK_HINT)
        } else {
            CRANK_HINT_ENGLISH
        };
        let ink = self.ctx.palette.engine(EngineColor::Warning);
        let paper = self.ctx.palette.engine(EngineColor::Panel);
        let (width, y) = (
            i32::from(self.buffer.width()),
            i32::from(self.buffer.height()) - 1,
        );
        self.buffer
            .fill_rect(Rect::new(0, y, width, 1), Cell::new(' ', ink, paper));
        let len = self.buffer.text_cells(hint);
        self.buffer
            .print((width - len).max(0) / 2, y, hint, ink, paper);
    }

    /// The top-most screen of type `T` on the stack, if it opts in
    /// ([`Screen::as_any`]).
    pub fn screen<T: Any>(&self) -> Option<&T> {
        self.stack.find()
    }

    /// The state hash of the top-most screen that has one
    /// ([`Screen::state_hash`]).
    pub fn state_hash(&self) -> Option<StateHash> {
        self.stack.state_hash()
    }

    /// [`screen`](Self::screen), mutable, for scripted tests.
    pub fn screen_mut<T: Any>(&mut self) -> Option<&mut T> {
        self.stack.find_mut()
    }

    /// The music state machine (which track plays).
    pub fn music(&self) -> &MusicState {
        &self.music
    }

    /// The input state (held keys, the keymap in use).
    pub fn input(&self) -> &InputState<G::Action> {
        &self.input
    }

    /// The last frame drawn.
    pub fn buffer(&self) -> &GlyphBuffer {
        &self.buffer
    }

    /// Whether the game has asked to quit.
    pub fn quit_requested(&self) -> bool {
        self.quit
    }

    /// The shared context.
    pub fn ctx(&self) -> &Ctx<G> {
        &self.ctx
    }

    /// The shared context, to change settings mid-run (tests and tools;
    /// screens get theirs in [`Screen::update`]).
    pub fn ctx_mut(&mut self) -> &mut Ctx<G> {
        &mut self.ctx
    }

    /// Ends the game, handing back the shared context (and so its storage).
    pub fn into_ctx(self) -> Ctx<G> {
        self.ctx
    }

    /// Name of the top screen, or `None` once the last one has closed.
    pub fn top_screen(&self) -> Option<&'static str> {
        self.stack.top_name()
    }

    /// Names of the open screens, bottom first.
    pub fn screens(&self) -> Vec<&'static str> {
        self.stack.names()
    }
}

/// The text key of the hint to unfold the crank.
pub const CRANK_HINT: &str = "crank.unfold";

/// The hint in English, for a game whose text has no [`CRANK_HINT`].
// check-text: the engine's fallback, for a game that says nothing else
const CRANK_HINT_ENGLISH: &str = "Unfold the crank to go on";

/// Whether `request` names a cue of the right kind in `manifest`.
/// Whether `request` plays a cue the engine's widgets play: `config`'s.
fn is_widget_cue<V>(config: &AudioConfig, request: &AudioRequest<V>) -> bool {
    let AudioRequest::PlaySound { cue, .. } = request else {
        return false;
    };
    [
        config.move_cue,
        config.select_cue,
        config.cancel_cue,
        config.denied_cue,
        config.cursor_cue,
    ]
    .contains(&cue.as_str())
}

fn is_known<V>(manifest: &AudioManifest, request: &AudioRequest<V>) -> bool {
    match request {
        AudioRequest::PlaySound { cue, .. } | AudioRequest::StartSound { cue, .. } => {
            manifest.sounds.contains_key(cue)
        }
        AudioRequest::PlayMusic { cue, .. } => manifest.music.contains_key(cue),
        AudioRequest::StopSound { .. }
        | AudioRequest::SoundVolume { .. }
        | AudioRequest::PauseSounds
        | AudioRequest::ResumeSounds
        | AudioRequest::StopMusic
        | AudioRequest::StopMusicWith { .. }
        | AudioRequest::PlayVoice { .. }
        | AudioRequest::StopVoice
        | AudioRequest::PreloadVoices { .. }
        | AudioRequest::AddSound { .. }
        | AudioRequest::RemoveSound { .. } => true,
    }
}

/// Whether `request` plays a looped sound cue once, with no handle to
/// stop it.
fn plays_a_loop<V>(manifest: &AudioManifest, request: &AudioRequest<V>) -> bool {
    matches!(request, AudioRequest::PlaySound { cue, .. }
        if manifest.sounds.get(cue).is_some_and(|s| s.looped))
}

#[cfg(test)]
mod tests;