#tui #ratatui #bevy #terminal

bevy_ratatui

A Bevy plugin for building terminal user interfaces with Ratatui

25 releases

9.3.2 Apr 29, 2024
0.7.1 Mar 26, 2025
0.7.0 Dec 2, 2024
0.6.4 Oct 22, 2024
0.2.2 Mar 28, 2024

#242 in Command-line interface

Download history 127/week @ 2024-12-04 43/week @ 2024-12-11 117/week @ 2024-12-18 34/week @ 2024-12-25 35/week @ 2025-01-01 19/week @ 2025-01-08 11/week @ 2025-01-15 10/week @ 2025-01-22 9/week @ 2025-01-29 35/week @ 2025-02-05 43/week @ 2025-02-12 20/week @ 2025-02-19 253/week @ 2025-02-26 58/week @ 2025-03-05 42/week @ 2025-03-12 136/week @ 2025-03-19

491 downloads per month
Used in 4 crates

MIT/Apache

60KB
1K SLoC

bevy_ratatui

Crate Badge Docs Badge Downloads Badge License Badge

Set up a Ratatui application, using bevy to manage the update loop, handle input events, draw to the buffer, etcetera.

getting started

cargo add bevy_ratatui ratatui crossterm

use bevy::prelude::*;
use bevy::app::ScheduleRunnerPlugin;
use bevy_ratatui::{terminal::RatatuiContext, RatatuiPlugins};

fn main() {
    let frame_time = std::time::Duration::from_secs_f32(1. / 60.);

    App::new()
        .add_plugins((
            MinimalPlugins.set(ScheduleRunnerPlugin::run_loop(frame_time)),
            RatatuiPlugins::default(),
        ))
        .add_systems(Update, draw_system.map(bevy::utils::error))
        .run();
}

fn draw_system(mut context: ResMut<RatatuiContext>) -> std::io::Result<()> {
    context.draw(|frame| {
        let text = ratatui::text::Text::raw("hello world");
        frame.render_widget(text, frame.area());
    })?;

    Ok(())
}

To read user input, you can listen for the crossterm input events forwarded by this crate:

use bevy::app::AppExit;
use bevy_ratatui::event::KeyEvent;
use crossterm::event::KeyCode;

fn input_system(mut events: EventReader<KeyEvent>, mut exit: EventWriter<AppExit>) {
    for event in events.read() {
        if let KeyCode::Char('q') = event.code {
            exit.send_default();
        }
    }
}

...or use the enable_input_forwarding option in RatatuiPlugins which will map crossterm input events to normal bevy input events.

demo

Made with VHS

See the demo example for the code and more information.

see also

integrates with

  • bevy: A refreshingly simple data-driven game engine built in Rust.
  • ratatui: A Rust crate for cooking up terminal user interfaces (TUIs).

more tools

  • egui_ratatui: A ratatui backend that is also an egui widget. Deploy on web with WASM or ship natively with bevy, macroquad, or eframe. Demo at https://gold-silver-copper.github.io/.
  • bevy_ratatui_camera: Print a bevy scene to the terminal. Provides a ratatui widget that converts a bevy camera's rendered image to text and draws it to the terminal with ratatui.

alternatives

  • widgetui: A wrapper for ratatui that reduces boilerplate and handles the update loop. Uses an approach similar to bevy systems.
  • bevyterm: A bevy crossterm integration that uses bevy systems to set up a terminal application.

compatibility

bevy bevy_ratatui
0.15 0.7
0.14 0.6
0.13 0.5

license

Copyright (c) Josh McKinney Copyright (c) Cooper Jax Reiff

This project is licensed under either of

at your option.

contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~32–46MB
~799K SLoC