matrix-rain

The classic Matrix digital rain effect — glowing columns of characters falling from the top of the terminal — packaged as both a ratatui StatefulWidget and a standalone matrix binary.

• Smooth animation at 30–60 FPS, configurable density / speed / trail length.
• Five built-in themes (classic green, amber, cyan, red, rainbow) and five charsets (matrix, ascii, hex, binary, or a UTF-8 file you supply).
• Three rendering tiers — smooth RGB interpolation on truecolor terminals, quantized 5-stop ramp on 256-color, nearest-named collapse on 16-color — automatically detected and cached per state.
• Drop-in widget that respects area.x / area.y offsets and handles resize, suspend/resume, broken-pipe shutdown, and panic-during-raw-mode without stranding the terminal.

Install

cargo install matrix-rain

Or from a local checkout:

cargo install --path .

The package is matrix-rain; the installed binary is matrix.

Run

matrix                          # classic green, 30 fps
matrix --theme rainbow          # red → yellow → green → blue trails
matrix --charset binary         # 0s and 1s
matrix --fps 60 --density 0.8   # snappier and denser
matrix --seed 42                # deterministic output (handy for screenshots)
matrix --help                   # full reference

Quit with q, Esc, or Ctrl-C (or use --quit-on-any-key).

CLI options

Library usage

Add to Cargo.toml:

[dependencies]
matrix-rain = { version = "0.1", default-features = false }
ratatui = "0.26"

(Disabling default features drops clap, anyhow, and signal-hook, which are only used by the standalone binary.)

Embed the widget inside a larger ratatui layout:

use ratatui::prelude::*;
use ratatui::widgets::Block;
use matrix_rain::{MatrixRain, MatrixRainState, MatrixConfig};

let cfg = MatrixConfig::builder()
    .fps(30)
    .density(0.5)
    .build()?;
let mut state = MatrixRainState::new();

terminal.draw(|f| {
    let chunks = Layout::vertical([Constraint::Min(0), Constraint::Length(3)])
        .split(f.size());
    f.render_stateful_widget(MatrixRain::new(&cfg), chunks[0], &mut state);
    f.render_widget(Block::bordered().title("Demo"), chunks[1]);
})?;

Runnable examples in examples/:

• cargo run --example standalone — full-screen demo
• cargo run --example embedded — widget inside a larger layout
• cargo run --example custom_charset — CharSet::Custom with hand-picked glyphs

The widget is intentionally StatefulWidget-only. Animation needs state that persists across frames (MatrixRainState holds per-column streams, RNG, timing, and a cached color count); a stateless wrapper would either reset every frame or hide global mutable state behind the API.

Built-in character sets

Built-in themes

Determinism

Pass --seed <U64> (or use MatrixRainState::with_seed) to get a reproducible animation. The library's snapshot test suite drives frames purely via state.tick() so output is identical across runs given the same seed, area, and config.

MatrixRainState::set_color_count(count) overrides the cached terminal color count, letting you force a specific rendering tier (e.g. 16 for accessibility, u16::MAX to force smooth interpolation, or any value in tests where TERM/COLORTERM shouldn't matter).

Caveats

• Full-width and combining characters in custom charsets are not detected. Each glyph must occupy exactly one terminal cell or the column layout misaligns. CJK ideographs, emoji with variation selectors, and zero-width combiners are all single chars in Rust but multi-cell in the terminal. Display width can't reliably be detected across terminals; verifying single-cell-ness is the caller's responsibility.
• Mixing MatrixRainState::tick() with wall-clock rendering produces visible drift over time. Tick driving is exact (each call advances exactly one frame); wall-clock driving advances based on elapsed Instants. Pick one mode per session.
• Non-TTY refusal. The binary exits with code 2 when stdout isn't a terminal so it doesn't garble logs when accidentally run under a pipe, in a CI runner, or as a systemd service. --help and --version still work in non-TTY contexts (they run before the check).

License

MIT. See LICENSE (or Cargo.toml's license field) for details.