bevy_ratatui

The bevy_ratatui integration follows a specific flow through the Bevy schedules to handle terminal input and rendering. This pattern is applicable to games, dashboards, and editors:

1. Initialization: RatatuiPlugins initializes the terminal context and emits terminal events (e.g., KeyMessage).
2. Input Translation: A PreUpdate system translates terminal-specific messages (like KeyMessage) into your application's domain-specific messages (e.g., GameCommand). This decouples terminal key codes from your core logic.
3. State Update: Chained Update systems synchronize terminal-dependent resources, read your application commands, and advance the application state in a deliberate order.
4. Rendering: A PostUpdate system borrows RatatuiContext and calls draw. This ensures rendering sees the state produced by the current update cycle without the rendering system owning or mutating the application rules.

To use bevy_ratatui, add RatatuiPlugins to your Bevy App. You can then access the RatatuiContext resource in a system to perform drawing operations using the standard Ratatui API.

Note: In the example below, MinimalPlugins is configured with a ScheduleRunnerPlugin to define the frame rate.

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<(), Box<dyn std::error::Error>> {
    context.draw(|frame| {
        let text = ratatui::text::Text::raw("hello world");
        frame.render_widget(text, frame.area());
    })?;

    Ok(())
}

Some terminals do not emit key release events or independent modifier events. You can control how bevy_ratatui emulates these missing capabilities using the EmulationPolicy resource.

• EmulationPolicy::Automatic: The default policy. It emulates any capability (key release or modifiers) that has not been explicitly detected from the terminal.
• EmulationPolicy::Manual(Capability): Allows you to specify exactly which capabilities to emulate using the Capability bitflags.

To use emulation, you must also insert the Emulate marker resource into your Bevy app.

use bevy::prelude::*;
use bevy_ratatui::crossterm_context::translation::keyboard_translation::{EmulationPolicy, Emulate, Capability};

// Example: Manually emulating only key releases
fn setup_emulation(mut commands: Commands) {
    commands.insert_resource(Emulate);
    commands.insert_resource(EmulationPolicy::Manual(Capability::KEY_RELEASE));
}

The EventPlugin uses a specific set of system sets to order input processing within the PreUpdate schedule. If you need to ensure your input handling systems run at a specific stage relative to the terminal event emission, use the InputSet enum with .in_set().

To ensure the ordering applies correctly, systems using these extension points must be added to PreUpdate.

The execution order is:

1. InputSet::Pre: Before any input messages are emitted.
2. InputSet::EmitCrossterm: When crossterm messages are emitted.
3. InputSet::CheckEmulation: For checking emulation.
4. InputSet::EmitBevy: When Bevy-native messages are emitted (requires TranslationPlugin).
5. InputSet::Post: After all input messages are emitted.

# use bevy::prelude::*;
# use bevy_ratatui::event::{InputSet, KeyMessage};
# fn handle_keys(_: MessageReader<KeyMessage>) {}

fn handle_keys(_: MessageReader<KeyMessage>) {}

// In your app setup:
// app.add_systems(PreUpdate, handle_keys.in_set(InputSet::Post));

To use bevy_ratatui, add RatatuiPlugins to your Bevy App. You can then access the RatatuiContext resource in your systems to draw Ratatui widgets. For handling input, you can use the MessageReader to listen for events like KeyMessage (when the crossterm feature is enabled).

use std::time::Duration;

use bevy::{
    app::{AppExit, ScheduleRunnerPlugin},
    prelude::*,
};
use bevy_ratatui::{event::KeyMessage, RatatuiContext, RatatuiPlugins};
use ratatui::crossterm::event::KeyCode;
use ratatui::text::Text;

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

    App::new()
        .add_plugins((
            MinimalPlugins.set(ScheduleRunnerPlugin::run_loop(frame_time)),
            RatatuiPlugins::default(),
        ))
        .add_systems(PreUpdate, input_system)
        .add_systems(Update, draw_system)
        .run();
}

fn draw_system(mut context: ResMut<RatatuiContext>) -> Result<(), Box<dyn std::error::Error>> {
    context.draw(|frame| {
        let text = Text::raw("hello world\npress 'q' to quit");
        frame.render_widget(text, frame.area());
    })?;

    Ok(())
}

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