Crate bevy_aoui

Expand description

Bevy AoUI provides a light-weight rectangular anchor-offset based 2D sprite layout, UI layout and skeletal animation system.

Similar to the philosophy of Rust, AoUI provides low level control through the anchor-offset system and high level ergonomics through its layout system.

§The AoUI Pipeline

AoUI is not a full render pipeline system, but rather a Transform and GlobalTransform generator.

AoUI replaces bevy’s standard transform systems like propagate_transforms and sync_simple_transforms on structs marked with AoUI, while leveraging other parts of bevy’s standard library and ecosystem whenever possible.

AoUI provides 2 rendering methods:

BuildGlobal genetates GlobalTransform directly.
BuildTransform genetates Transform.

AoUI propagates translation, rotation, scale and font size down its tree.

In the default pipeline, the root node of the AoUI tree is the window. meaning orphaned sprites will be placed against the window’s rectangle.

§Getting Started

Before you start you should check out bevy_aoui_widgets’s examples if you like shapes or DSL.

First add the AoUI Plugin:

app.add_plugins(AoUIPlugin)

Create a sprite:

commands.spawn(AoUISpriteBundle {
    sprite: Sprite { 
        color: Color::RED,
        ..Default::default()
    },
    transform: Transform2D { 
        center: Some(Anchor::Center),
        anchor: Anchor::TopCenter,
        offset: Vec2::new(20.0, 0.0),
        rotation: 1.21,
        scale: Vec2::new(4.0, 1.0),
        ..Default::default()
    },
    dimension: Dimension::pixels(Vec2::new(50.0, 50.0)),
    texture: assets.load("sprite.png"),
    ..Default::default()
});

Create some text:

commands.spawn(AoUITextBundle {
    text: Text::from_section(
        "Hello, World!!", 
        style(Color::WHITE)
    ),
    font: assets.load::<Font>("OpenSans.ttf"),
    transform: Transform2D { 
        center: Some(Anchor::Center),
        anchor: Anchor::TopCenter,
        offset: Vec2::new(20.0, 0.0),
        rotation: 1.21,
        scale: Vec2::new(4.0, 1.0),
        ..Default::default()
    },
    dimension: Dimension::COPIED.with_em(SetEM::Pixels(24.0)),
    ..Default::default()
});

§Core Concepts

AoUI offers a refreshingly different paradigm from traditional CSS based UI layout.

AoUI Sprites contains these core components:

Each sprite is conceptualized as a rectangle with a dimension and 9 anchors: BottomLeft, CenterRight, Center, etc.

Custom anchors can be used but not in some layouts.

Sprites are connected to parent sprites via one of the parent’s anchors and can be offset by a Vec2. When the offset is set to (0, 0), the anchors of the parent and child sprites overlap.

In the case of parentless sprites, they are anchored to the window’s rectangle.

When applying rotation and scale, sprites can use a center that operates independently from the anchor.

§Container

Anchor-Offset is well-suited for isolated UI components, but when it comes to arranging multiple UI elements in a specific order, you’ll find the Container useful.

The Container is a layout system that only depands on insertion order and works with Bevy’s Children component.

Check out the book for more information.

§Advantages of AoUI

There are many awesome UI libraries in the bevy ecosystem that you should definitely use over AoUI in many use cases. However, AoUI offers some unique advantages:

Full ECS support with easy feature composition.

AoUI is built fully embracing bevy’s ecosystem. You can mix and match our modularized components and add, remove or edit any system you want to change.

Relative size system.

Full support for web like size units: em, rem, %, etc.

First class rotation and scaling support.

You are can rotate and scale any sprite from any position on it with ease.

Simple but versatile layout system.

Simple layouts that work out of the box with minimal configuration.

High level abstractions with low level control.

You can mix and match anchoring and layouts to best suit your needs.

Re-exports§

pub use schedule::AoUIPlugin;

Modules§

bundles
events
schedule

Structs§

Anchor
AoUI: Marker component for the default schedules.
AoUIREM: The root font size of the window.
BuildGlobal: Builds a GlobalTransform on a Anchor, by default Transform2d::anchor.
BuildTransform: Builds a Transform on a Anchor, by default center.
Container: A configurable container that lays out a sequence of AoUI Sprites.
Dimension: Controls the dimension of the sprite
Hitbox: Provides cursor detection on RotatedRect
Opacity
RotatedRect: A rotated 2D rectangle.
SceneLayout: Treat offset as a position in a coordinate system.
Size2: A context sensitive Vec2
Transform2D: The 2D transform component for AoUI

Enums§

Alignment: Where items are aligned to in a Container.
Cells: Cells in a Layout::Grid
Columns: Columns in a Layout::Table
DimensionSize: Size of the sprite.
FlexDir: Order items are laid out in a Container.
HitboxShape: Shape of a hitbox.
Layout: A layout that accepts a one dimensional sequence of widgets.
LayoutControl: Cause special behaviors when inserted into a Container.
SetEM: Set the font size of the widget.
SizeUnit: The unit of a Size px, em, rem, percent

Crate bevy_aouiCopy item path