Bevy Cobweb UI

Provides a framework for building UI and managing assets in a Bevy app. Built on bevy_cobweb, sickle_ui, and standard bevy_ui/bevy_assets/etc.

Features

• Custom asset format for specifying scenes and loading commands to be applied on startup, with seamless fine-grained hot reloading and thorough error handling.

• Integration with sickle_ui so widgets and themes can be specified in cobweb asset files then easily overridden/customized. Also includes various reactivity extensions for UiBuilder, including UI interactions (e.g. .on_pressed(your_system)).

• Standardized API for accessing fonts with families, weights, styles, and widths (e.g. Fira Sans + Bold + Italic + Condensed).

• Robust localization support for text, fonts, images, and audio, with extensibility to other assets.

• Asset manager resources that keep track of asset handles, take care of localization automatically, and are easily populated using asset manifests specified in cobweb asset files.

• Wrappers around bevy_ui for loading UI into scenes via cobweb asset files.

• Built-in UI widgets, color palettes, and assets (e.g. fonts). Note that the widgets, colors, and assets features are enabled by default.

Getting Started

This is an asset-oriented UI framework revolving around cobweb asset files (.caf.json files). You spawn CAF scenes in-code, and then you can edit those scenes to add code-side behavior like on_pressed/on_hover/etc. or to insert components, or to spawn child scenes within a scene.

To get started, you need three things.

1. Add CobwebUiPlugin.
2. Load a CAF file if you have one. Usually these are stored in your assets directory.
3. Wait until in state LoadState::Done before loading UI. This avoids jank while loading CAF files and other assets. You can build UI in-code before then without a problem, as long as you don't reference not-yet-loaded assets.

app
    .add_plugins(bevy::DefaultPlugins)
    .add_plugins(CobwebUiPlugin)
    .load("main.caf.json")
    .add_systems(OnEnter(LoadState::Done), build_ui);

Check the loading module for how to write CAF files.

Check the repository examples for how to build different kinds of UI.

Examples

• hello_world: Bare-bones hello world.

• counter: Simple counter button. Shows how ControlRoot and ControlLabel can be used to transfer interactions within a widget. Also demonstrates updating text dynamically on the code side.

• counter_widget: Widget-ified counter that can be configured. Uses scene 'specs' to make the widget scene data parameterized, enabling customization within asset files.

• help_text: Help text that appears on hover. Showcases PropagateOpacity, which allows controlling (and animating) the opacity of entire node trees, and even layering multiple PropagateOpacity within a single tree.

• radio_buttons: A set of buttons where only one is selected at a time. Uses the built-in radio button widget.

• localization: Showcases localized text and font.

• calculator: A minimalistic code-only calculator. Shows how to mix normal sickle_ui UI construction with bevy_cobweb_ui convenience tools for interactions.

• game_menu: A simple game menu with settings page. Showcases multiple uses of built-in radio buttons, localization, non-interactive animations, integration with sickle_ui built-in widgets (a slider and drop-down), and how to manage localized image assets using CAF files as manifests.

NOTICE

You may encounter a compiler diagnostic bug when using LoadedScene with nested closures/functions. Check out the game_menu example for how to manage the lifetimes properly. The bug is fixed on nightly so if you compile with +nightly or add nightly to your build toolchain then it will error properly instead of panicking.

bevy compatability