Crate bevy_aoui

source ·
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:

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

Modules

Structs

Enums