transition

kiln-tui/src/transition.rs

@@ -0,0 +1,134 @@
+//! Board-change wipe animation.
+//!
+//! When the player steps through a portal both the old and new boards are rendered
+//! into off-screen ratatui [`Buffer`]s at init time. Each frame [`TransitionAnimation::update`]
+//! advances the LFSR-driven reveal bitmap, and the [`Widget`] impl blends the two
+//! buffers — old cells for unrevealed positions, new cells for revealed ones.
+
+use kiln_core::Board;
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    widgets::Widget,
+};
+use crate::render::BoardWidget;
+
+/// How long the wipe lasts in seconds.
+pub const TRANSITION_DURATION: f32 = 0.25;
+
+/// Advance a 16-bit Galois LFSR one step.
+///
+/// Polynomial 0xB400 gives a maximal period of 65 535, covering every realistic
+/// terminal viewport (e.g. 256 × 200 = 51 200 cells).
+fn lfsr_step(state: u16) -> u16 {
+    let lsb = state & 1;
+    let s = state >> 1;
+    if lsb != 0 { s ^ 0xB400 } else { s }
+}
+
+/// Build a permutation of `[0, total)` using the 16-bit LFSR.
+///
+/// The LFSR visits every value in `1..=65535` exactly once per cycle.
+/// Mapping `state → state - 1` gives `0..=65534`; values in `[0, total)` are
+/// kept in encounter order. `total` must not exceed 65 535.
+fn lfsr_sequence(total: usize) -> Vec<u32> {
+    let mut seq = Vec::with_capacity(total);
+    let mut state: u16 = 1; // non-zero start; LFSR never visits 0
+    loop {
+        let idx = state as u32 - 1;
+        if (idx as usize) < total {
+            seq.push(idx);
+            if seq.len() == total { break; }
+        }
+        state = lfsr_step(state);
+        if state == 1 { break; } // full cycle — shouldn't happen for total <= 65535
+    }
+    seq
+}
+
+/// A board-to-board wipe animation driven by an LFSR.
+///
+/// Both boards are rendered into off-screen [`Buffer`]s once at construction.
+/// Each call to [`update`](TransitionAnimation::update) marks more screen cells
+/// as "revealed" (using the pre-computed LFSR order); the [`Widget`] impl blends
+/// old and new buffers cell by cell.
+pub struct TransitionAnimation {
+    /// Pre-rendered old board.
+    old_buf: Buffer,
+    /// Pre-rendered new board.
+    new_buf: Buffer,
+    /// LFSR-ordered permutation of screen-cell indices `[0, width×height)`.
+    reveal_order: Vec<u32>,
+    /// Which cells have been revealed (show `new_buf`).
+    revealed: Vec<bool>,
+    /// How many entries of `reveal_order` are currently revealed.
+    revealed_count: usize,
+    /// Elapsed seconds since the animation started.
+    pub elapsed: f32,
+}
+
+impl TransitionAnimation {
+    /// Render both boards into off-screen buffers and build the LFSR sequence.
+    ///
+    /// `area` must match the area that will be passed to the widget's `render` call.
+    pub fn new(old: &Board, new: &Board, area: Rect) -> Self {
+        let total = area.width as usize * area.height as usize;
+
+        let mut old_buf = Buffer::empty(area);
+        BoardWidget::new(old).render(area, &mut old_buf);
+
+        let mut new_buf = Buffer::empty(area);
+        BoardWidget::new(new).render(area, &mut new_buf);
+
+        let reveal_order = lfsr_sequence(total);
+
+        Self {
+            old_buf,
+            new_buf,
+            reveal_order,
+            revealed: vec![false; total],
+            revealed_count: 0,
+            elapsed: 0.0,
+        }
+    }
+
+    /// Advance the animation by `dt` seconds, marking newly-due cells as revealed.
+    ///
+    /// Returns `true` when the animation is complete (all cells revealed).
+    pub fn update(&mut self, dt: f32) -> bool {
+        self.elapsed += dt;
+        let total = self.revealed.len();
+        let target =
+            ((self.elapsed / TRANSITION_DURATION) * total as f32) as usize;
+        let target = target.min(total);
+
+        // Mark each newly revealed cell in the bitmap.
+        for &idx in &self.reveal_order[self.revealed_count..target] {
+            self.revealed[idx as usize] = true;
+        }
+        self.revealed_count = target;
+
+        self.elapsed >= TRANSITION_DURATION
+    }
+}
+
+impl Widget for &TransitionAnimation {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        let w = area.width as usize;
+        for row in 0..area.height {
+            for col in 0..area.width {
+                let idx = row as usize * w + col as usize;
+                // Out-of-range cells (e.g. after a terminal resize) default to new board.
+                let src = if self.revealed.get(idx).copied().unwrap_or(true) {
+                    &self.new_buf
+                } else {
+                    &self.old_buf
+                };
+                let pos = (area.x + col, area.y + row);
+                if let (Some(s), Some(d)) = (src.cell(pos), buf.cell_mut(pos)) {
+                    *d = s.clone();
+                }
+            }
+        }
+    }
+}