Bevy Cobweb UI

A UI and asset-management framework for the bevy game engine.

Depends on bevy_ui, bevy_assets, and bevy_cobweb.

Features

• Custom scene format called COB
• Localization framework (text, fonts, images, audio)
• Font family API
• Built-in UI widgets and color palettes
• Asset management tools
• And many quality of life features.

Getting Started

1. (Optional) Install syntax highlighting for the COB asset format.

   • VSCode
   • vim
   • SublimeText

2. Add CobwebUiPlugin to your app.

app
    .add_plugins(bevy::prelude::DefaultPlugins)
    .add_plugins(CobwebUiPlugin);

3. Add a COB file to your assets directory. Use the .cob file extension.

#scenes
"hello"
    TextLine{ text: "Hello, World!" }

This hello world has a scene with one node (the root node "hello") and one loadable (TextLine). TextLine is an instruction that will insert a Text component to the scene node entity on spawn.

4. Load the COB file to your app in a plugin.

app.load("main.cob");

You can load other COB files recursively using #manifest sections (see the loading module docs).

5. Add a system for spawning a scene.

fn build_ui(mut commands: Commands, mut s: ResMut<SceneLoader>)
{
    commands
        // Converts Commands to UiBuilder<UiRoot>
        .ui_root()
        // Loads the scene "hello" from file "main.cob".
        // New entities will be spawned for the scene.
        .load_scene(("main.cob", "hello"), &mut s);
}

6. Add the system to your app.

app.add_systems(OnEnter(LoadState::Done), build_ui);

We put the system in OnEnter(LoadState::Done) so it runs after all COB files and assets loaded into this crate's asset managers have been loaded.

Check the loading module docs for how to write COB files. COB files can be hot reloaded with the hot_reload feature. Hot-reloaded changes will cause affected scene nodes to be refreshed (or cause commands to be re-applied). Hot-reloading is minimally destructive. Entities are only despawned when you delete scene nodes from a COB file.

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

Examples

NOTICE: Many examples are not yet migrated to use COB, which is still in development to reach feature parity with the previous JSON format.

• 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 (not migrated): Widget-ified counter that can be configured. Uses scene 'specs' to make the widget scene data parameterized, enabling customization within asset files.
• cursors: Set custom cursors that respond to interactions with UI elements.
• 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 (not migrated): A set of buttons where only one is selected at a time. Uses the built-in radio button widget.
• localization (not migrated): Showcases localized text and font.
• calculator: A minimalistic code-only calculator. Shows how to mix builder-pattern-based UI construction with bevy_cobweb_ui convenience tools for interactions.
• game_menu (not migrated): A simple game menu with settings page. Showcases multiple uses of built-in radio buttons, sliders, and drop-downs, localization, non-interactive animations, and how to manage localized image assets using COB files as asset manifests.

bevy compatability

bevy	bevy_cobweb_ui
0.15	0.5.0 - main
0.14	0.1.0 - 0.4.1