Plurimus

Provides a set of components and systems to make it easier to build terminal UIs with bevy_ratatui.

Overview

Plurimus adds a layer of abstraction on top of bevy_ratatui, allowing you to define renderable ratatui widget using components with queryable traits. This makes it easier to manage the state and behavior of your UI components using bevy's ECS, while still leveraging the power of ratatui for rendering.

The core functionality of Plurimus is to provide queryable traits that enable bevy entities to reflect renderable ratatui widgets. The traits can be implemented on any bevy component, allowing you to create custom widgets and manage their state using bevy's ECS.

It's important to note that once Plurimus is enabled as a plugin, RatatuiContext draw function will be exclusively managed by Plurimus. Attempting to use RatatuiContext's draw function directly will result in flickering renders, as Plurimus will override the draw calls. To avoid this, you should use the provided traits and components to define your widgets and their rendering behavior.

The main traits are:

• DrawArea: Implement on any component to define the area of the terminal frame where the widget should be drawn.
• DrawOrder: Implement on any component to define the order in which widgets are drawn, allowing layering of widgets.
• DrawFn: Implement on any component to define a custom draw function for the widget. This widget is required in order for rendering.

Features

Plurimus provides default Widget components that implement the above traits, but you can also create your own custom widgets by implementing the traits on your own components. There are also optional ui and tachyon features which provide additional components and systems for managing UI state and input events.

Core Widget Components

• Widget: Represents a ratatui widget that can be drawn on the screen, either as widget, stateful widget, or a render function.
• WidgetOrder: Component state that determines the draw order of widgets, allowing you to control which widgets are drawn on top of others.
• WidgetRect: Component state that holds the position and size of a widget on the screen.
• WidgetLayout: Component state that recalculates WidgetRect based on the current terminal frame size.

Optional Ui Components & Functions

To enable the UI features, add the ui feature to your Cargo.toml.

• UiFocusable: Marks a widget as focusable, allowing it to receive input events and be navigated to using keyboard/mouse controls.
• UiHoverable: Marks a widget as hoverable, allowing it to respond to mouse hover events.
• UiPressable: Marks a widget as pressable, allowing it to respond to mouse click events.
• UiDisabled: Marks a widget as disabled, preventing it from receiving input events and applying a disabled style.
• UiFocused: Indicates that a widget is currently focused, which can be used to apply different styles or behaviors when the widget is active.
• UiHovered: Indicates that a widget is currently being hovered over by the mouse, which can be used to apply different styles or behaviors when the widget is hovered.
• UiPressed: Indicates that a widget is currently being pressed (clicked) by the mouse, which can be used to apply different styles or behaviors when the widget is pressed.
• UiActions: A component that holds a list of actions that can be triggered by input events, allowing you to define input handlers.
• UiFocusMessage: A message that can be sent to request focus on a specific Focusable entity. Sets the UiFocused component.
• UiBuilder: A helper struct for building UI widgets with a fluent interface, allowing you to easily configure the various UI components.

Optional Tachyon Components & Functions

To enable the Tachyon features, add the tachyonfx feature to your Cargo.toml.

Since Tachyon effects are no send/sync, effects are stored in a non-send resource. In order to enable an effect on a frame area, you can attach a TachyonEffect component to an entity with a DrawArea and DrawFn. The TachyonEffect just marks the entity as having a tachyon effect, and the actual effect(s) are stored in the TachyonRegistry resource.

To remove the effect from the registry, simply remove the TachyonEffect component from the entity. Plurimus will automatically clean up any effects associated with that entity.

• TachyonEffect: Marks an entity as having a tachyon effect, allowing it to be registered in the TachyonRegistry and rendered.
• enable_fx: Helper function to add the TachyonEffect component and register the effect in the TachyonRegistry.
• add_fx: Helper function to add an effect to the TachyonRegistry for an entity that already has a TachyonEffect component.

Usage

See the examples folder for more complete examples, but here is a simple example of how to use Plurimus a simple "Hello, world!" widget:

use bevy::MinimalPlugins;
use bevy::prelude::*;
use bevy_ratatui::RatatuiPlugins;
use plurimus::{PlurimusPlugin, Widget, WidgetLayout};

fn main() {
    let mut app = App::new();

    app.add_plugins((
        PlurimusPlugin,
        MinimalPlugins,
        RatatuiPlugins {
            enable_kitty_protocol: true,
            enable_input_forwarding: true,
            enable_mouse_capture: true,
        },
    ));

    app.add_systems(Startup, startup);
  
    app.run();
}

fn startup(mut commands: Commands) -> Result {
    use ratatui::prelude::Rect;
    use ratatui::widgets::Paragraph;

    commands.spawn((
        Widget::from_widget(Paragraph::new("! Hello, world !")),
        WidgetLayout::new(|area| {
            let width = area.width / 2;
            let height = area.height / 2;
            let x = (area.width - width) / 2;
            let y = (area.height - height) / 2;
            Rect::new(x, y, width, height)
        }),
    ));

    Ok(())
}