Nodes and layout
Lay out UI with Node: sizes and Val units, flexbox direction, alignment and gaps, absolute positioning, display and visibility, z-order, UI scale and which camera UI draws on.
On this page
Every UI element is an entity with a Node. A Node is a box: it says how big the box is, where it goes, how much space surrounds it and how its children are arranged. The engine computes the layout every frame, after your Update systems, so you change a node's fields and the screen follows.
A node with no Node parent is a root node and is laid out against the whole viewport. UI coordinates start at the top-left corner and grow right and down.
Sizes and units#
Lengths are Vals. Helper functions make them short to write:
| Helper | Val | Meaning |
|---|---|---|
px(10) | Val::Px(10.0) | Logical pixels, multiplied by UiScale and the window's scale factor. |
percent(50) | Val::Percent(50.0) | Percent of the parent: its width for widths, margins and padding, its height for heights. |
vw(10), vh(10) | Val::Vw, Val::Vh | Percent of the viewport's width or height. |
vmin(10), vmax(10) | Val::VMin, Val::VMax | Percent of the viewport's smaller or larger side. |
em(2), rem(2) | Val::Em, Val::Rem | Multiples of the node's font size, or the root font size. |
auto() | Val::Auto | Let the layout decide. |
UiRect holds four sides, for margin, padding and border. UiRect::all(px(8)), UiRect::axes(horizontal, vertical), UiRect::horizontal(v), UiRect::top(v) and so on build them, and px(8).all() is shorthand for UiRect::all(px(8)).
The fields you'll use most#
| Field | What it does |
|---|---|
width, height, min_*, max_* | The box's size and limits. |
aspect_ratio | Some(width / height) keeps the box's shape. |
margin, padding, border | Space outside, inside and the border's thickness. Colour the border with BorderColor. |
border_radius | Rounded corners: BorderRadius::all(px(6)), BorderRadius::MAX for pills and circles. |
display | Display::Flex (the default), Grid, Block or None (removed from layout). |
position_type | Relative (the default) or Absolute. |
left, right, top, bottom | Offsets; with Absolute, the position inside the parent. |
overflow | What happens to children that don't fit; see Scrolling and overflow. |
Flexbox#
By default a node lays its children out in a row, one after another. These fields control how:
| Field | Values | What it does |
|---|---|---|
flex_direction | Row, Column, RowReverse, ColumnReverse | The main axis. |
justify_content | Start, End, Center, SpaceBetween, SpaceAround, SpaceEvenly, ... | Where children go along the main axis. |
align_items | Start, End, Center, Stretch, Baseline, ... | Where children go across it. |
align_self | as align_items | Overrides align_items for one child. |
flex_wrap | NoWrap, Wrap, WrapReverse | Whether children wrap onto new lines. |
row_gap, column_gap | a Val | Space between children. |
flex_grow, flex_shrink, flex_basis | numbers, a Val | How children share leftover space. |
commands.spawn((
Node {
position_type: PositionType::Absolute,
bottom: px(0),
width: percent(100),
height: px(80),
flex_direction: FlexDirection::Row,
justify_content: JustifyContent::SpaceEvenly,
align_items: AlignItems::Center,
..default()
},
BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.6)),
children![slot(), slot(), slot()],
));
fn slot() -> impl Bundle {
(
Node { width: px(64), height: px(64), border: px(2).all(), border_radius: BorderRadius::all(px(8)), ..default() },
BorderColor::all(Color::WHITE),
)
}Building the tree#
Nest nodes with children![...] when you spawn, or with with_children when you need a loop:
commands
.spawn(Node { flex_direction: FlexDirection::Column, row_gap: px(8), ..default() })
.with_children(|menu| {
for label in ["Play", "Options", "Quit"] {
menu.spawn(Text::new(label));
}
});Hierarchy in general is covered in Relationships and hierarchy.
Absolute positioning and anchoring#
With position_type: PositionType::Absolute, a node is taken out of its parent's flow and placed by left, right, top and bottom. Use it for HUD corners, badges and overlays:
commands.spawn((
Text::new("Score: 0"),
Node { position_type: PositionType::Absolute, top: px(12), right: px(12), ..default() },
));A node with FixedNode is positioned against the viewport even when it has a UI parent, and doesn't inherit its parent's clipping or transform. Use it for tooltips and pop-ups that belong to a widget but must escape its box.
Hiding nodes#
| Set | Effect |
|---|---|
Node { display: Display::None, .. } | Removed from layout: the space it took closes up. Its children are hidden too. |
Visibility::Hidden | Not drawn, but still takes up its space. |
Draw order#
Siblings draw in the order they appear, later ones on top. ZIndex(n) changes the order among siblings. GlobalZIndex(n) lifts a node above (or below) everything else in the UI, whatever its parent, which is what modal dialogs need.
Transforms#
UI nodes don't use Transform. UiTransform moves, scales and rotates a node after layout, without disturbing its neighbours. Use it for animation: a button that grows on hover, a spinning icon.
UiTransform::from_rotation(Rot2::degrees(15.0))UI scale#
The UiScale resource multiplies every pixel size in the UI. Set it from a settings menu to make the interface bigger or smaller: ui_scale.0 = 1.5;.
Which camera UI draws on#
Root nodes draw on the default UI camera: the camera with IsDefaultUiCamera, or else the highest-order camera that renders to the primary window. To put UI on another camera, such as one per split-screen player, add UiTargetCamera(camera_entity) to the root node. The UI is then laid out in that camera's viewport.
Examples#
| Example | What it shows |
|---|---|
flex_layout | Every combination of align_items and justify_content. |
size_constraints | min_* and max_*. |
anchor_layout | Pinning nodes to edges and corners. |
fixed_node | FixedNode. |
display_and_visibility | Display::None against Visibility::Hidden. Needs --features neo_feathers. |
z_index | ZIndex and GlobalZIndex. |
ui_transform | UiTransform. |
ui_scaling | UiScale. |
ui_target_camera | UiTargetCamera and camera order. |
Run one from the engine core's workspace: cargo run --example flex_layout.