Bevy Lunex is a high-performance retained layout engine designed for Bevy entities. Unlike traditional UI frameworks, it is built directly around vanilla Bevy ECS, allowing you to create custom UI using regular ECS patterns just like any other part of your application.

Key Characteristics

• Positioning Focus: Lunex primarily provides the capability to position entities. It does not currently include flexbox-like layout capabilities.
• ECS-Native: Everything is handled via Bevy ECS, making it highly customizable and suitable for low-level interactivity.

Use Case Suitability

Recommended for:

• Worldspace 3D UI
• Sprite-based 2D UI
• Custom rendering hooks
• Scenarios requiring high customizability and low-level control

Not recommended for:

• Rapid development and high iteration speed
• Using prebuilt input components
• Building standard desktop application UIs

Lunex automates the scaling of 2D text to fit UI bounds through the following lifecycle:

1. Text Computation: Lunex waits for Bevy to compute the text bounds (glyph size, font size, etc.).
2. Boundary Assignment: Once computed, Lunex takes these values and applies them to the UiLayout::boundary::size property, scaled by the value provided in UiTextSize.
3. Layout Computation: The UI layout is computed for the current frame.
4. Transform Scaling: Lunex scales the entity's Transform so that the text fits precisely within the computed node bounds.

Interactivity in bevy_lunex is implemented using Observers. An observer is a one-shot system that executes only when a specific event is triggered on a specific entity.

To use interactivity, you define an observer that takes a Trigger<E> (where E is the event type) and attach it to a spawned entity. This creates a local observer that listens for that event on that specific entity.

// Example of attaching a local observer to an entity
ui.spawn((/* components */))
    .observe(|trigger: Trigger<Pointer<Click>>, /* other resources */| {
        // Logic executed when the entity is clicked
    });

When UiLunexDebugPlugin is active, it prints a tree representation of your UI layout to the terminal whenever changes occur. The output format follows this pattern:

[ID] ⇒ [w: Width, h: Height, d: Depth] ➜ [Type]

• ID: The unique identifier of the node (e.g., 11v1).
• Dimensions: Width (w) and Height (h).
• Depth: The nesting depth (d).
• Type: The UI element type (e.g., Solid, Window).

▶ 11v1 ⇒ [w: 1920, h: 1080]
  ├─ Background ⇒ [w: 1920, h: 1080, d: 1] ➜ Solid
  └─ 13v1 ⇒ [w: 595, h: 1080, d: 1] ➜ Solid
  ┆  ├─ Panel ⇒ [w: 624, h: 1134, d: 2] ➜ Window

The UiLunexDebugPlugin<R_2D, R_3D> uses two generic constants to determine which RenderLayers the debug gizmos should be drawn on:

• R_2D: The render layer for 2D gizmos.
• R_3D: The render layer for 3D gizmos.

To see the debug outlines, your cameras must include these layers in their RenderLayers component.

If you use UiLunexDebugPlugin::<1, 2>, configure your cameras as follows:

// For Camera2d
// Must include layer 0 and the 2D debug layer (e.g., 1)
RenderLayers::from_layers(&[0, 1])

// For Camera3d
// Must include layer 0 and the 3D debug layer (e.g., 2)
RenderLayers::from_layers(&[0, 2])

To debug UI behavior, you can enable the UiLunexDebugPlugin. This plugin provides two main features:

1. Gizmo Outlines: Draws outlines around all UI nodes to visualize their positions and sizes.
2. Layout Logging: Prints the UI layout hierarchy to the terminal whenever a change is detected.

To enable gizmo outlines, you must add the plugin to your Bevy application and configure the RenderLayers on your cameras to match the layers specified in the plugin's generic parameters.

// Example: Adding the plugin with default render layers
app.add_plugins(UiLunexDebugPlugin::<1, 2>);

To start a 2D UI, spawn a UiLayoutRoot using UiLayoutRoot::new_2d(). To ensure the UI viewport size stays synchronized with your camera, add the UiFetchFromCamera::<N> component, where N is the index of your camera's UiSourceCamera::<N> component. This maintains the Camera -> Dimension -> UiLayout pipeline automatically.

// Create UI
commands.spawn((
    // Initialize the UI root for 2D
    UiLayoutRoot::new_2d(),

    // Make the UI synchronized with camera viewport size
    UiFetchFromCamera::<0>,
)).with_children(|ui| {

    // ... Here we will spawn our UI

});

To use the library, you must add the UiLunexPlugins to your Bevy App instance alongside DefaultPlugins.

fn main() -> AppExit {
    App::new()
        // Add necessary plugins
        .add_plugins((DefaultPlugins, UiLunexPlugins))
        .run()
}

To add bevy_lunex to your Rust project, add it to your Cargo.toml dependencies. You can use the standard versioning or pull directly from the Git repository for the latest features.

[dependencies]
  bevy_lunex = { version = "*" }

Or for the bleeding edge version:

[dependencies]
  bevy_lunex = { git = "https://github.com/bytestring-net/bevy_lunex" }