bevy_ratatui#

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::{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)
        .run();
}

fn draw_system(mut context: ResMut<RatatuiContext>) -> 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 messages forwarded by this crate:

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

fn input_system(mut messages: MessageReader<KeyMessage>, mut exit: MessageWriter<AppExit>) {
    for message in messages.read() {
        if let KeyCode::Char('q') = message.code {
            exit.send_default();
        }
    }
}

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

demo#

See the demo example for the code and more information.

features#

• windowed: Render your ratatui application in a window instead of the terminal buffer. Reference the demo example for how to set up a Bevy project to handle either mode.
• serde: Passthrough feature for serializing crossterm types.

There are also a handful of features relating to running Bevy in no_std mode.

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#

license#

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

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.