Byte Engine Docs

Build a user interface

Build retained, asynchronous interfaces that run in the Byte Engine render loop.

Use the early UI module to build retained, asynchronous interfaces inside the Byte Engine render loop.

An asynchronous component function receives a layout Context. It creates elements in stable keyed slots, waits for events, and can mount child components that return values. The runtime keeps state between evaluations, so your application doesn't rebuild each interaction from the beginning.

engine.mount(async |ctx| {
    let mut panel = ctx
        .element("panel")
        .container(|c| card(c).width(240.into()).flow(flow::column))
        .await;
    panel.element("title").text("Settings", |t| t.font_size(20.0)).await;
    panel.element("clock").component(clock).await;
});

Pass components as async closures or async functions that take &mut EvaluationContext, such as async fn clock(ctx: &mut EvaluationContext).

Choose the main API

  • layout::engine::Engine evaluates retained UI and produces render data.
  • Context and ContainerContext are the component-facing construction and event APIs.
  • Container, Text, Image, Curve, and Path are the current built-in primitives. Declare a text field with text_field: it's a Text that receives text edits while focused.
  • UiRenderPass turns evaluated UI render data into GPU draw work.
  • ConcreteStyle, ConcreteLayer, and Transform hold styling and animation-oriented transforms; set opacity with the opacity property.

The layout layer stays small by design. Containers own sizing, positioning, flow, clipping, style, and visual data. Flow functions such as row, column, grid, and centered variants place children. Transforms are best treated as animation and presentation state, while position and sizing describe stable layout. A transform applies to the whole subtree: a scaled container scales its descendants' rectangles, hit bounds, clipping, curve points, stroke widths, and font sizes together, so one transform on a content layer zooms a canvas.

Handle events and focus

UI events are futures that your component can await. A component can wait for pointer-style events, keys, text edits, timers, or render ticks. Text input is app-owned: a text field emits edit deltas such as inserted and deleted characters, and application state decides how to apply them. Write the result back with update_text.

Components request and release focus explicitly. Send key and text-edit events to the focused element.

Read and change engine state

A component never holds the engine. Every change it makes is a future: declaring an element, update_container, remove, reparent, focus requests, and starting a component. Await it, and it writes straight into the engine while your component runs, in the order you awaited them. The next layout sees the change, and so do components that run after yours in the same evaluation.

Declarations and edits take a setup function that sets properties in place, such as |c| c.width(240.into()).clip(false). The setters write into the element where the engine stores it, so nothing is built, copied, or sent on the way. Setup runs only when the declaration creates the element. An element that already exists keeps its properties until you edit it. A plain function over Properties holds a reusable look for both declarations and edits:

fn card(card: Properties<'_, Container>) -> Properties<'_, Container> {
    card.corner_radius(8.0).style([fill, border])
}

let mut panel = ctx.element("panel").container(|c| card(c).width(240.into())).await;
panel.update_container(|c| card(c).opacity(0.5)).await;

To keep steady screens free of allocations, pass text as a &str, a number, or format_args!("{name} {score}") instead of a formatted String, and style layers as an array, such as .style([fill, border]). The engine reuses the storage of removed elements, render entries, and ended components, so a screen that opens again allocates only one box for each component or mount it starts.

To animate, pass animate an element, a driver such as emphasized_out or spring, and an async closure that writes one frame's value. The closure can edit other elements it borrows, so one animation can move a card and fade its content together:

animate(&mut card, emphasized_out(0.3), async |card, t| {
    card.update_container(|c| c.opacity(t)).await;
    label.update_text(|l| l.opacity(t)).await;
})
.await;

Reads are futures that complete at once. Await them in the component:

let bounds = card.geometry().await;
let pointer = ctx.pointer().await;
let held = ctx.drag().await;
let score = ctx.with(|app: &App| app.score.get()).await;

Context::with lends the application context you passed to Engine::with_context. The host reaches the same value between evaluations through Engine::ctx and Engine::ctx_mut.

Understand component lifetime

A component started with component runs until its future returns or until the removal of the scope that started it, whichever comes first. A scope is the one a mount created: when the mounted future completes or is dropped, its elements are removed and every component started inside it ends, including components those components started. Components started outside any mount live until they return or the engine is dropped.

EvaluationContext::remove removes one element together with everything declared under it: its descendants and the components started there. The context it was called on stays valid only to declare the same key again, which gets the same id. A mounted component awaited from outside the removed element keeps running until its own future ends. Its elements are gone, so its updates change nothing.

Build content at runtime

Context::element takes an ElementKey. An element's id is computed from its parent's path and its key, so the same key under the same parent always resolves the same retained element. A static name identifies a fixed part of a component. A name made from data, such as one node of a graph, is keyed by its content. Pass it as format_args!, which is hashed while it's formatted without allocating. An owned String with the same content gives the same key:

let mut node = canvas.element(format_args!("node-{id}")).container(|c| node_frame(c, position)).await;
let mut wire = canvas.element(format_args!("wire-{from}-{to}")).curve(|c| wire_between(c, a, b)).await;

Siblings under one parent need distinct keys. For a list, pair a name with the item's index:

for (index, row) in rows.iter().enumerate() {
    list.element(("row", index)).container(|c| row_frame(c, row)).await;
}

Declaring the same key twice under the same parent in one frame is an error: the engine logs it, ignores the second declaration, and fails a debug assertion.

Keep the element contexts as the handles to that content. Re-route a wire while its ends move with EvaluationContext::update_curve, editing the path in place so its segment buffer is reused. Changing only the segments repaints the curve without replaying layout. Remove a node or a wire with EvaluationContext::remove:

wire.update_curve(|c| c.clear_segments().cubic(from, from + tangent, to - tangent, to)).await;
node.remove().await;

Drag a UI item onto an application target

The engine owns one pointer drag. Create a position action with ActionBindingDescription::new("Mouse.Position").dragged_by("Mouse.LeftButton") in your UI's input sink and forward its phases to the engine in normalized window coordinates. Engine::press grabs the surface under the pointer from the last evaluated frame and returns whether it found one. In this example, accept_drop maps the released source to your data and validates the application target before changing application state:

match phase {
    ActionPhase::Started => {
        engine.press(window_position);
    }
    ActionPhase::Updated => {
        engine.drag_to(window_position);
    }
    ActionPhase::Ended => {
        if let Some(drop) = engine.release(window_position) {
            accept_drop(drop);
        }
    }
    ActionPhase::Cancelled => {
        engine.cancel();
    }
}

Capture the gesture in your UI's sink before gameplay processes the same input, and continue forwarding motion and release outside the source. Engine::hit answers what's under a point when a sink needs that for its own capture decisions, such as refusing a drop over UI.

The grabbed surface receives the gesture as events, so it can react on its own. It gets Events::Grabbed on press. Once the pointer travels past the drag threshold, it gets Events::Dragged at the start of each Engine::evaluate in which the pointer moved, with UiEvent::delta set to the offset from the press point in layout units. When the grab ends by release or cancellation it gets Events::DragEnded, with UiEvent::source set to the surface the drag was dropped on, if any. Await all three in one loop, because an event with no component waiting for it's discarded, and a press and release can arrive in the same frame:

let mut origin = None;
loop {
    let event = select! {
        event = card.on(Events::Grabbed) => event,
        event = card.on(Events::Dragged) => event,
        event = card.on(Events::DragEnded) => event,
    };
    match event.kind {
        Events::Grabbed => {
            origin = card.geometry().await;
            card.update_container(|c| c.depth(Depth::absolute(1))).await;
        }
        Events::Dragged => {
            if let (Some(origin), Some(delta)) = (origin, event.delta) {
                card.update_container(|c| c.transform(placed_at(origin.x() + delta.x, origin.y() + delta.y))).await;
            }
        }
        _ => {
            origin = None;
            card.update_container(|c| c.depth(Depth::relative(1)).transform(Transform::identity())).await;
        }
    }
}

Depth::absolute lifts the card out of its parent's flow and places it from the viewport, so a translation by the drag offset from its grabbed geometry follows the pointer. When scaling a preview, use Transform::origin(UiPoint::zero()) to keep its top-left corner anchored.

The surface under the release point, and then each of its ancestors, gets Events::Dropped with UiEvent::source set to the released source. The source itself is skipped when finding that surface. The engine resolves the target at the start of the next Engine::evaluate from the previous frame's hit geometry, before components run, and queues the source's DragEnded after it, so a target claims the source before the source settles. A target takes a dropped element into its own layout with EvaluationContext::adopt, which makes it the target's last flow child while keeping its id and properties:

loop {
    let event = stack.on(Events::Dropped).await;
    if let Some(card) = event.source {
        stack.adopt(card).await;
    }
}

While a source is held, the surface under the pointer other than the source is available as DragCapture::over, so the source can preview where a release would land.

Engine::release still returns the DragDrop for applications that apply drops outside the UI, so either side can act on it. An element can also move itself under another parent with EvaluationContext::reparent.

Engine::cancel ends the interaction in progress: it restores the held source and discards queued clicks, scrolls, key presses, and text edits. Call it when the window loses focus or the user cancels. A changed viewport size cancels from Engine::evaluate, because layout distances and the source's place move with it. The UI supplies the gesture and geometry. Your application decides which targets accept the item and how to apply it.

React to the pointer passing over a surface

Each Engine::evaluate compares the surface under the pointer with the previous frame's. When it changes, the old surface gets Events::PointerExited and the new one Events::PointerEntered, each followed by the ancestors that stopped or started containing the pointer. An ancestor containing both surfaces hears nothing, so a panel keeps its hover state while the pointer moves between its children. A held drag source is skipped, so a drop target under a dragged item still receives PointerEntered. Engine::hovered answers the same question at the application level, for a cursor shape for example.

Curves take part once given a hit width: hit_width(width) in a curve's setup lets the pointer find the curve within width layout units of its stroke, along its whole length even where it runs beyond its declared size. A wire can then be hovered, clicked, and dropped on like a container. The width follows the inherited transform scale.

A container with an absolute position may sit partly outside its parent, including at negative coordinates, so a canvas can be panned past its edge without snapping its content. Flow-placed children are still kept inside the viewport.

Work within the current limits

Primitive UI layer

The module isn't a complete widget toolkit yet. Treat it as a retained primitive layer with an asynchronous interaction model.

Build higher-level widgets through small composed components before you add runtime machinery.

The UI renderer has fixed per-frame limits on clip masks, images, primitives, and glyphs. The UI reference lists them, and defines how depth orders elements and what text rendering guarantees.

Publish only changed renders

Applications should publish a render only when Render::revision changes. The render source deduplicates repeated revisions anyway, so a republished unchanged render never makes a sink rebuild.

Anything that must change pixels has to go through the tree: mutate elements through the evaluation context rather than by keeping visual state outside the engine. Placement, style, opacity, clipping, and transforms all live on retained elements, so the revision covers them. Changing the viewport size is the one input outside the tree, and both evaluation and rendering key on it.

Rust API

On this page