bevyengine / bevyengine/bevy

Use consistent best-practices in UI examples

Open
#22,695 3 comments 0 reactions 0 assignees View on GitHub
A-UI C-Docs C-Examples D-Straightforward S-Ready-For-Implementation X-Contentious
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 22h
Merged PRs (30d)
161

Description

## Background

I'm building a UI-heavy app after not having worked with `bevy_ui` for quite some time.
I now want to learn common patterns and best practices on how to build a UI with Bevy.

To my knowledge, there is no higher-level documentation available, so I turn to the `examples/ui` folder.
However, the patterns used there seem to be quite inconsistent, so I'm not sure what I should use when.

For example, compare [`grid.rs`](https://github.com/bevyengine/bevy/blob/main/examples/ui/grid.rs) and [`image_node.rs`](https://github.com/bevyengine/bevy/blob/main/examples/ui/image_node.rs).
The grid example makes heavy use of the `.with_children` syntax and uses shorthand functions like `px` and `percent`.
The image example instead uses the `children!` macro and the `Val::Px` constructor.
Then the [`standard_widgets.rs`](https://github.com/bevyengine/bevy/blob/main/examples/ui/standard_widgets.rs) example makes heavy use of the `impl Bundle` pattern, combined with `children!`, but also uses `Children::spawn`.

So I think after looking at these examples, I'm more confused than before.

## How can Bevy's documentation be improved?

I'd like us to:

1. Define (somewhere) some guidelines, on when to use which pattern (or maybe which patterns shouldn't be used at all anymore?)
2. Consistently apply these guidelines to the UI examples
3. Ideally also add more inline comments to better explain these things in the examples. There we need to find some balance between teaching important concepts and not repeating the same stuff in every example.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.