blocks: a falling-block game on intuiTUIve¶

Round 1: rata-tetris¶

The clone is examples/blocks.rs, a rebuild of rata-tetris (Nathanyel Wood, MIT; ratatui 0.29, the most-downloaded ratatui Tetris on crates.io whose source is short enough to follow screen by screen). quantonganh's tetris-tui is better known but draws with crossterm alone, so it was not the model.

What was built (919 lines: about 545 the game model with no framework in it, 195 the look, 150 the app; tests 390 lines in tests/blocks.rs, 15 tests):

• The original's screens, at its places on its fixed 64x28 screen, centred: the start screen (block-letter title and the zoom tip), the playing screen (statistics with each piece's art and count, LINES - 000, the board, TOP and SCORE, NEXT, LEVEL 00), the paused screen (the board hidden, as on the NES), the game-over screen (its lettering, "Reach level n, and cleared n lines.", "New top score set at n!" or "You scored n points."), and "Terminal must be at least 64 x 28!" below that size. Its ten level palettes (xterm colours) recolour the pieces every level.
• Its rules: a 10x20 field, a shuffled bag of seven (seeded here), its rotation matrices with no kicks (it has no SRS), gravity in NES frames (48 at level 0 down to 1, its table), a level every ten lines, 40/100/300/1200 times the level plus one, lock on contact (no lock delay), top-out when a new piece cannot fall, the ghost (┌┐ in the piece's colour, as its bordered Block drew it), the cleared rows' 300 ms + 100 ms a row pause, and a top score kept in a file.
• Its keys: Space starts, pauses, resumes and plays again; ← → move; ↓ soft drop; ↑ slam (hard drop); PageUp/PageDown rotate; q quits.
• Added: a hold panel (c, once a piece; the original has none), and the cleared rows flash (lit/dark every four frames; the original shows them still). Fixed on the way: the original takes input during the clear pause.
• The clock: one every(17 ms) tick is a NES frame (the original's timer multiplies frames by 17 ms). The model counts frames; a View signal with PartialEq means a frame where nothing shown changed draws nothing. Tests seed the bag, script keys with Driver::press and step the clock with Driver::advance, so each run is the same game.

Bespoke drawing: the playfield only, and it is not a widget: a text node whose markup is twenty rows of ten [color(n) on color(234)]██[/] cells (25 lines). The side panels are plain label/text nodes in .borders(..) boxes, placed with layers and .inset.

Left out: sound (rata-tetris ships fourteen WAVs, wired to rodio and commented out: there is no sound output to wire them to here either); the backdrop's tiled pattern of grey blocks (one glyph instead, see below); its zoom-tip emoji.

New gaps and bugs¶

Friction with the existing APIs¶

• A model that is not a signal. The game lives in an Rc<RefCell<Game>> that every handler mutates, then writes view.set(game.view()). That is the right shape (the timer needs to change it without redrawing on every frame), but it is hand-made glue: a Signal::update that returns whether the closure changed anything, or a store(model, view_fn) that derives a view and notifies only when it changes, would remove it.
• every exists only while building. Starting the tick when Space starts the game is not possible from a handler, so it ticks on the start screen too (and the model ignores it).
• The board as markup. Two hundred [color(n) on color(234)]██[/] runs are formatted and parsed again whenever the view changes; it works, and a 20x20 board is cheap, but a bigger grid (a map, Life) would want cells.
• A box without a title is .borders(Sides::ALL) (a panel without a title, by the guide's rule for non-panels), then .border(Border::Plain) and .border_style(..): three builders for ratatui's Block::bordered().
• Centring a fixed-size stage takes a column of a row with .justify(Justify::Center), or the 3x3 ring of fills once a backdrop is wanted (the opaque-layer gap). layers' .place(..) sizes the layer to its content's measure rather than to a size given.
• The test clock is good. Driver::advance(FRAME * 47) stepping to each due tick made gravity, the clear pause and the flash testable frame by frame with no seams beyond a seed and a prepared Game.

Components that would help¶

Comparable libraries: ratatui and crossterm games (tetris-io, tetris-tui, rata-tetris) all run their own loop with crossterm::event::poll and a fixed tick, handle DAS/ARR themselves, and use rodio for sound; Bubble Tea's tea.Tick and tea.Every return a command per tick (re-armed with a new duration at will), which is the changeable timer above; Textual's set_interval returns a Timer with pause(), resume() and reset(), and its Key events carry no release, the same limit as a terminal without the kitty protocol.

Round 2: rebuilt on round 6¶

examples/blocks.rs went from 919 lines to 959, tests/blocks.rs from 390 to 435 (15 tests to 18). The game model is unchanged but for the view (the piece no longer composited into the cells); the extra lines are the NES repeat rates, the sprite builder and comments, while the hand-built glue round the clock, the small-screen switch, the backdrop's ring and the state directory went. All 15 earlier tests pass unchanged.

Replaced by components¶

New tests: held → repeats at 16 then 6 frames and stops on the release (Driver::set_releases, Event::KeyUp); a loop stalled ten frames at level 29 drops the piece ten rows (Driver::update); the backdrop shows round the screen.

Still hand-built, and why¶

• The board is still twenty rows of [color(n) on color(234)]██[/] markup, now the stage's backdrop: there is no cell grid, and pixels cannot draw the ██/░░ glyphs and level palettes cell for cell.
• at(node, x, y, w, h), the original's absolute rectangles as .inset(..) from four sides: layers still has no .at(rect).
• The flash is counted in the model's frames (no blink/keyframes).
• The Rc<RefCell<Game>> + view.set(game.view()) glue, now also pausing the clock by the state after every change.
• The block lettering, the seeded generator and the backdrop's single glyph (no pattern fill), as in round 1.

New gaps¶

Bugs found¶

Fixed in 0.0.21 (2a36216): a node with a background clears its rectangle in a layers stack; the test is in tests/round7_bugs.rs, and the example's fill layer is gone.

• A styled layers node lets the layer below show through where its children leave room. The guide says a node with a background covers its whole rectangle; inside an inset (or between at() boxes) the backdrop's ▓ showed through the screen's .style("on color(234)"). The example puts a fill(" ", "on color(234)") first in the screen's layers. Minimal failing test:

let app = App::new(|| layers([
    fill("x", "red on blue"),
    layers([label("a").inset(0, 0, 0, 1)]).style("on green"),
]));
let mut driver = app.driver(5, 1);
driver.settle();
assert_eq!(driver.screen().plain()[0], " a   "); // is "xa   "

(row([..]).style(..) and label("").bg(..) over a fill do cover; the miss is a layers whose child is inset.)

Components that would help¶