1 unstable release

0.1.0 Jul 20, 2024

#170 in #ui-framework


Used in bevy_cobweb_ui

MIT/Apache

3KB

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

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

bevy bevy_cobweb_ui
0.14 0.1.0 - master

Dependencies

~235–670KB
~16K SLoC