blockworx/tutorial/

replay.rs

//! `--replay` playback state for the main editor UI. Unlike the tutorial
//! [`Player`](super::player::Player), which runs a separate `Session` inside
//! a floating window, replay drives the *app's own* document and tool with the
//! script's `SimFrame`s — the real canvas, toolbar, and overlays are the
//! video. This struct owns only what the app lacks: the level, the streaming
//! lowerer, the sim clock, and the synthetic pointer the script implies.
//!
//! Replay is an authoring tool: it plays the script once through, then the
//! app drops into interactive author mode on the end state. There is no
//! transport UI and no input blocking; a lowering error prints on the
//! console and ends playback the same way.

use std::time::Duration;

use egui::{Rect, vec2};

use blockworx_doc::document::{DocIndex, Document};

use crate::grid::GRID_SIZE;
use crate::schema::lower::SourceIds;
use crate::script::driver::{SimClock, SimDriver, Speed};
use crate::script::lowering::{Lowering, SimFrame};
use crate::script::step::CueScope;

use super::level::Level;

pub struct Replay {
    level: Level,
    lowering: Lowering,
    /// The level file's own `"b1"` spellings, resolved to what the bridge
    /// minted when the app opened this level — the cues' only handle on
    /// them.
    ids: SourceIds,
    clock: SimClock,
    /// The synthetic pointer and queued editor commit the script implies; the
    /// app applies the frames to its own document through it.
    driver: SimDriver,
    /// The script ran out of frames.
    finished: bool,
    /// A doc-anchored step named a missing object — a level bug, reported on
    /// the console; playback ends there.
    stopped: bool,
}

impl Replay {
    pub fn new(level: Level, ids: SourceIds) -> Self {
        let lowering = Lowering::new(&level.script);
        Self {
            level,
            lowering,
            ids,
            clock: SimClock::default(),
            driver: SimDriver::default(),
            finished: false,
            stopped: false,
        }
    }

    pub fn level(&self) -> &Level {
        &self.level
    }

    /// The cue/camera clock: sim frames fed so far, in script time.
    pub fn clock(&self) -> Duration {
        self.clock.elapsed()
    }

    pub(crate) fn driver(&mut self) -> &mut SimDriver {
        &mut self.driver
    }

    /// What this level's cues resolve against: the app's own document, and
    /// the level file's id spellings the app's load minted ids for.
    pub fn cue_scope<'a>(&'a self, doc: &'a Document, index: &'a mut DocIndex) -> CueScope<'a> {
        CueScope::new(index.view(doc), &self.ids)
    }

    /// Bank `dt` real time and return how many sim frames came due. 0 once
    /// playback has ended.
    pub fn begin_show(&mut self, dt: Duration) -> u32 {
        if self.done() {
            return 0;
        }
        self.clock.begin_show(dt, Speed::NORMAL)
    }

    /// The next due frame of synthetic input, resolving doc-anchored targets
    /// against the app's current document. `None` when the script just
    /// finished or a target failed to resolve (reported on the console).
    pub fn next_frame(&mut self, doc: &Document, index: &mut DocIndex) -> Option<SimFrame> {
        let Self {
            lowering,
            ids,
            clock,
            level,
            finished,
            stopped,
            ..
        } = self;
        match lowering.next(&CueScope::new(index.view(doc), ids)) {
            Ok(Some(frame)) => {
                clock.tick();
                Some(frame)
            }
            Ok(None) => {
                *finished = true;
                None
            }
            Err(e) => {
                tracing::error!(
                    "replay of `{}` stopped: demo step {} names a missing object ({:?})",
                    level.id,
                    e.step,
                    e.target
                );
                *stopped = true;
                None
            }
        }
    }

    /// Playback has ended — one full pass (or a console-reported error) —
    /// and every queued editor commit has been delivered, so the app can
    /// drop into interactive author mode.
    pub fn done(&self) -> bool {
        self.stopped || (self.finished && !self.driver.enter_pending())
    }
}

/// The `instruct` text over the live canvas: centered on the viewport on a
/// translucent card, in screen space (fixed size regardless of zoom).
pub fn draw_instruction(
    painter: &egui::Painter,
    viewport: Rect,
    text: &str,
    visuals: &egui::Visuals,
) {
    if text.is_empty() {
        return;
    }
    let galley = painter.layout(
        text.to_owned(),
        egui::FontId::proportional(18.0),
        visuals.text_color(),
        viewport.width() - 4.0 * GRID_SIZE,
    );
    let card = Rect::from_center_size(viewport.center(), galley.size() + vec2(24.0, 16.0));
    painter.rect_filled(card, 8.0, visuals.window_fill.gamma_multiply(0.85));
    painter.galley(card.min + vec2(12.0, 8.0), galley, visuals.text_color());
}

#[cfg(test)]
mod tests {
    use super::*;

    fn test_level() -> Level {
        Level::parse(
            r#"level "replay-test" title="T" {
                instructions "i"
                script {
                    camera x=0 y=0 w=10 h=10
                    pause secs=1.0
                }
            }"#,
        )
        .unwrap()
    }

    /// A document with nothing in it: the test level resolves no target.
    fn empty() -> (Document, DocIndex) {
        (Document::default(), DocIndex::default())
    }

    #[test]
    fn finished_script_reports_done_and_stops_advancing() {
        let mut replay = Replay::new(test_level(), SourceIds::default());
        let (doc, mut index) = empty();
        assert!(!replay.done());
        // Drain the script (a 1 s pause = 60 frames).
        while replay.next_frame(&doc, &mut index).is_some() {}
        assert!(replay.done());
        assert_eq!(replay.begin_show(Duration::from_secs(1)), 0);
    }

    #[test]
    fn done_waits_for_a_queued_editor_commit() {
        let mut replay = Replay::new(test_level(), SourceIds::default());
        let (doc, mut index) = empty();
        while replay.next_frame(&doc, &mut index).is_some() {}
        replay.driver().queue_enter();
        assert!(!replay.done(), "the queued Enter still owes a frame");
        assert!(replay.driver().idle_interaction().enter_pressed);
        assert!(replay.done());
    }
}