Blazingly fast path based modular layout system built on top of Bevy ECS. It positions rectangles with user-defined positions to achieve a precise layout.
Note: Currently WIP development. Most of the features are already implemented, but we are giving ourselves some time to catch bugs and polish our systems. The deadline for the 0.1 release is the 0.12.0 release of Bevy.
^ A recreation of Cyberpunk 2077 UI in Bevy. It aligns Textures in 2D space to values calculated by the Bevy-Lunex layout engine. It achieves AAA-level layout capabilities and modularity. Source code here (Example).
For latest state-of-the-art example usage of Bevy-Lunex, take a look at the source code of this repository.
This project was developed as an alternative to all web-tech-inspired user interface libraries. I dislike HTML-CSS-inspired frameworks due to the confusion the underlying system causes. This project strives to be clean, simple and intuitive to the user. All underlying concepts used here were rediscovered from the ground up while developing this library.
Bevy-Lunex is a layout framework focused on defining and managing rectangles. The most prominent use case is to use it as a "building brick" for user interface.
The core of the library is purely math based and has limited relation to actual UI. However, we provide abstractions and functions to leverage the power of this layouting framework to create a very modular user interface.
Due to the nature of Rust, we had to come up with a unique way how to manage data. We decided to implement hierarchy tree structure, which is used in UNIX file system.
All data is stored in a master struct, called "UiTree", which manages all layout data. The "UiTree" is composed of "UiBranches", where each branch represents a rectangle and they can be nested inside each other. "Widgets" are custom smart pointers containing a "path" to the corresponding nested "UiBranch". "Widgets" are components and are spawned as entity.
When needed, the "Widget" can fetch "UiBranch" inside the "UiTree" and return a mutable borrow. From the borrow you can modify the layout data, thus changing the behaviour and the result of the rectangle calculations taking place. This is the way to get around the Rust's borrow checker. ```
|-> Mainmenu | |-> Background | |-> Board | | |-> Logo | | |-> Buttons | | | |-> Continue | | | |-> NewGame | | | |-> LoadGame | | | |-> Settings | | | |-> Credits | | | |-> AdditionalContent | | | |-> Quit_Game ``` ^ This is a "UiTree" structure printed out in a terminal. Each item displayed here is "UiBranch". Look for example at the "Board" branch, in which are nested "Logo" and "Buttons" branches.
First, create a "UiTree" struct that will hold all the layout data managed recursively.
rust
let mut tree = UiTree::new();
To create a new "Widget" in the root directory you pass in the "UiTree", specify widget properties and the function returns the smart pointer.
rust
let widget = Widget::create(&mut tree, "widget", RelativeLayout {
relative_1: Vec2::new(0.0, 0.0),
relative_2: Vec2::new(100.0, 100.0),
..default()
}.pack())?;
Once you have the "Widget" created, you can pass it to an entity as a component together with other components like "Image". Here we use "ImageElementBundle", which is the same as "SpriteBundle", but has extra fields for "Widget" and "Element". Element component is used when you need to attach a visual entity to a widget, like text or image.
rust
commands.spawn((
ImageElementBundle::new(
widget,
&ImageParams::default(),
asset_server.load("button.png"),
Vec2::new(1280.0, 250.0)),
ButtonHighlightEffect::new(Color::GOLD),
));
In this example, we also passed another component called "ButtonHighlightEffect", which we will define in the next section.
To add logic to your "Widgets", you use Bevy systems. In this example, we will create a system that will tint the sprite to a certain colour if a cursor hovers over the "Widget" First we define the component with color data. Then we define the system that will query "UiTree", "Cursor" and our components. Add the logic and we are done. ```rust
pub struct ButtonHighlightEffect (pub Color);
fn buttonhighlighteffectupdate( systems: Query<&UiTree>, cursors: Query<&Cursor>, mut query: Query<(&Widget, &mut Sprite, &ButtonHighlightEffect)> ) { for system in systems.iter() { for (widget, mut sprite, color) in &mut query { for cursor in cursors.iter() { if widget.iswithin(&system, "", &cursor.positionworld().aslunex(system.offset)).unwrap(){ sprite.color = color.0; } else { sprite.color = Color::WHITE; } } } } } ```
Don't forget to add the system to the app.
rust
.add_systems(Update, button_highlight_effect_update)
You need to spawn the "UiTree" we created in the first step as an entity so we can query for it.
rust
commands.spawn(tree);
There are 3 main layout options to pick from. With their combination, you can define any setup. They are: * RELATIVE || Defined from 2 points, as % of the parent container. * SOLID || Defined as a ratio of width and height. Will scale to fit or fill parent. * WINDOW || Defined as a point + width and height. Same as RELATIVE.
By nesting branches of these 3 types, you can precisely define the position and layout behaviour.
Any contribution submitted by you will be dual licensed as mentioned below, without any additional terms or conditions.
Released under both APACHE and MIT licenses, for the sake of compatibility with other projects. Pick one that suits you the most!