terminal_graphics_interactive

Make art, animations, games and drawing tools in your terminal, with the mouse and keyboard, in a few lines of Rust. It works in Windows PowerShell, Linux, macOS and over SSH. Its only dependency is terminal_graphics (re-exported), and almost nothing in it is unsafe.

A formula becomes an animation	A physics world in five lines
move the mouse to make ripples	the mouse pulls the balls, the right button pushes them, a click adds one

These are recordings of the real examples below, run against the real library, with a scripted mouse arrow drawn on top (cargo run --release --example make_gifs rebuilds them).

Try it in your browser

Write some Rust in the page, press run, and watch it in a terminal. Nothing to install.

Install

cargo add terminal_graphics_interactive

Make art in a few lines

Write the interesting part and nothing else. The library starts the terminal, runs the frame loop, tracks the mouse, quits on q and puts everything back.

A formula becomes an animation. The closure runs for every cell every frame and returns a number from -1 to 1, which is what sin and cos give:

use terminal_graphics_interactive::prelude::*;

fn main() -> std::io::Result<()> {
    // Move the mouse to send ripples across it. Press q to quit.
    sketch_with(Palette::fire(), |cell| {
        let ripple = cell.dist_to_mouse() * 0.25 - cell.t * 3.0;
        ((cell.x * 0.15 + cell.t).sin() + (cell.y * 0.2 - cell.t * 0.7).sin() + ripple.sin()) / 3.0
    })
}

cell has x, y, t (seconds), the mouse position and button, and the window size. y is stretched so a circle looks round. A terminal has only 16 colours, so numbers between two colours are drawn with shade blocks (░▒▓█) for about four times as many steps. Pick a Palette (ocean, fire, rainbow, mono) or make your own with Palette::new(&[...]).

A physics world in a few settings. Balls bounce off the walls and each other, and a click adds one:

use terminal_graphics_interactive::prelude::*;

fn main() -> std::io::Result<()> {
    // The mouse pulls the balls in, the right button pushes them away, a click
    // adds a ball. Press q to quit.
    World::new()
        .balls(5)
        .size(3.5)
        .gravity(0.02)
        .mouse_pulls()
        .trails()
        .run()
}

Terminal Games

Make games in your terminal. A game is a set of screens (a title, a play screen, a pause, a game over). Each one is a Game that updates 60 times a second, reads held keys and the mouse, and draws on a Screen. The crate also brings random numbers, timers, object pools and collision shapes, and Headless runs a game with no terminal, so tests can play it.

Play the examples. sail is the flagship: a sailboat on the open sea, under a sky that turns from dawn to night. Steer left and right to dodge the fireballs that fall from the sky; the farther you sail, the rougher the sea and the more fireballs come.

cargo run --example sail        # the flagship: a sailboat on the sea; steer to dodge the fireballs
cargo run --example glow        # a light drifts through a plasma sky; touch the motes
cargo run --example quickgame   # steer a @ and collect the * stars for 20 seconds
cargo run --example sail_together -- host 2        # sail with a friend: one hosts (waits for 1 more) ...
cargo run --example sail_together -- join HOST:7777   # ... and the other joins

It makes multiplayer games too. This is sail_together: two players, two boats, one sea. Each machine runs the whole game and they share only their key presses, so it needs almost no bandwidth.

A recording of the real game, from the first player's screen. The two players here are two games joined by an in-process link, so the recording is the same every time; the example itself plays over TCP between computers (cargo run --release --example make_gifs rebuilds it).

This is the shape of quickgame: a title that switches to the play screen on Enter. The rest is in examples/quickgame.rs:

use terminal_graphics_interactive::game::*;

fn main() -> std::io::Result<()> {
    run(Title { score: None })
}

impl Game for Title {
    fn update(&mut self, ctx: &mut Context<'_>) -> Next {
        if ctx.keys.pressed(KeyCode::Enter) {
            Next::switch(Play::new(ctx.seed))
        } else {
            Next::stay()
        }
    }
}

What is and is not verified. Held keys need key release events, which only some terminals send: kitty, WezTerm, Ghostty, foot, Alacritty, iTerm2 and recent Windows Terminal support the kitty keyboard protocol. Where a terminal does not, a held key is timed instead, so a key stays held for a moment after its last repeat. The glow game runs in a pseudo terminal in our tests on Linux, and quickgame is tested headless. Both games are not yet run by a person on Windows or macOS, and the games also run on the website (/games/, the real games as WebAssembly), which a headless browser check loads but no person has looked at yet. Multiplayer: Sim, Lockstep and the Local and Tcp transports are built and tested (including two machines playing sail_together over real TCP on loopback, and lossy, reordered and dropped messages over a fake link). The game's numbers are checked to be bit-identical across machines only by a recorded state hash that CI runs on Linux, macOS and Windows; a person has played sail_together between two Windows PowerShell windows on one laptop over localhost, and it worked well. It has not yet been played across a real network (a LAN or the internet), or in macOS or Linux terminals, and there is no WebSocket transport for the browser yet. The host listens on all addresses with no password or encryption, so play on a trusted network.

Play between machines is lockstep: every machine runs the same deterministic Sim and they share only each player's input, so a match needs almost no bandwidth and a game that drifts apart is reported with the step it happened at. See examples/sail_together.rs.

To test a game without a terminal, use Headless. It runs the same updates as run: you press keys, step time and read back what was drawn, as tests/game_api.rs and the tests in examples/quickgame.rs do.

Add the mouse and keyboard to anything

Under the art API is Terminal: a full-screen session that gives you key presses, mouse clicks, drags, scrolling and pastes as events, and a window to draw a Display in. poll doubles as the frame timer, and mouse.cell_in(&display) turns a mouse position into a cell:

use std::time::Duration;
use terminal_graphics_interactive::{Colour, Display, Event, MouseKind, Terminal};

fn main() -> std::io::Result<()> {
    let mut terminal = Terminal::start()?;

    // `draw` needs a display at most one row shorter than the window
    let (width, height) = terminal.size();
    let mut display = Display::new(width, height.saturating_sub(1));

    loop {
        terminal.draw(&display)?;

        // wait up to 50 ms for input; `None` means a frame passed with no input
        match terminal.poll(Duration::from_millis(50))? {
            Some(Event::Key(key)) if key.is_char('q') || key.is_ctrl('c') => return Ok(()),
            Some(Event::Mouse(mouse)) if matches!(mouse.kind, MouseKind::Down(_)) => {
                if let Some((x, y)) = mouse.cell_in(&display) {
                    display.set_pixel(x, y, 'X', Colour::BrightYellow, Colour::Blue);
                }
            }
            _ => {}
        }
    }
}

Ctrl+C arrives as a key (key.is_ctrl('c')) while a Terminal exists, so check for it and leave your loop. Pasted text arrives as one Event::Paste, so pasting a command can never trigger your key bindings.

More examples

cargo run --example plasma        # the formula above
cargo run --example balls         # the physics world above
cargo run --example paint         # drag to paint, right-drag to erase, 1-8 or scroll for colour, c clears
cargo run --example screensaver   # bouncing dots with fading trails; click to add one, any key quits
cargo run --example events        # prints every key and mouse event

For AI coding agents

llms.txt is a short page written for you: what this crate is, when to use it and when not to, the whole API, the mistakes that are easy to make (Ctrl+C is an event, the display must be one row shorter than the window, use \r\n in raw mode) and complete examples that are checked against the code.

Platforms

Over SSH it works when a terminal is allocated (ssh -t host ...). The tests prove that raw mode, key and mouse sequences, pastes and quitting work on each system. They cannot prove that a physical mouse click becomes an escape sequence: that is your terminal emulator's job.

Under the hood

• Almost no unsafe. Raw mode cannot be done in safe Rust, so the only unsafe is a few libc calls on Unix and a few kernel32 calls on Windows (src/raw_mode/), each with a // SAFETY: comment. tests/unsafe_audit.rs fails the build if unsafe appears anywhere else.
• Fast. cargo bench runs benchmarks that use only std. A 200 by 60 plasma costs about 0.8 ms of a 33 ms frame, and parsing input takes tens of nanoseconds per event.
• Tested. Unit tests for the parser, the palette and the simulation, and end-to-end tests that run every example in a real pseudo terminal on all three systems.

Rendering cost

Terminal::draw sends only the cells that changed since the last frame (Renderer, also public for any Write). The first frame draws everything. cargo bench --bench render compares it with redrawing the whole frame each time, on the same frames, with std timing:

Machine: Intel Xeon at 2.10 GHz, 4 threads, Linux x86_64. Each time is a median of 15 samples. The ranges are the lowest and highest of the runs made: five for the full redraw (two of them from before the renderer existed) and three for the changed cells only. The byte counts are exact and do not vary between runs. The first full frame is left out of the changed-cells bytes.

• Still and moving pictures send far fewer bytes, which is what matters over a slow SSH link: none at all for a still picture, and under 100 bytes for a small moving block instead of several kilobytes. They also take less time, at 200 by 60 about 19 us against about 31 us for the moving block, and far less for the still picture.
• Plasma, where every cell changes, saves only 2 to 3 per cent of the bytes. Its time is not better: the changed-cells runs were slower than the full redraw in both runs at both sizes, but at 80 by 24 the spread between runs is as large as the difference, so these runs do not show whether it is a real cost.
• At 60 frames a second a frame has about 16.7 ms, and both ways fit easily at these sizes. The gain is in the bytes, not the CPU.

Contributing

Small, friendly pull requests are welcome. CONTRIBUTING.md has short recipes for adding a palette, a World setting or an example, and CLAUDE.md explains the principles and process.

Links

• Website with a live editor and playable games: https://calum.github.io/terminal_graphics_interactive/ (art at /art/, games at /games/)
• crates.io: https://crates.io/crates/terminal_graphics_interactive
• API documentation: https://docs.rs/terminal_graphics_interactive
• The graphics crate it builds on: https://github.com/calum/terminal_graphics_api

Licence

Licensed under either of MIT or Apache-2.0 at your option.