Crate bevy_egui

Source
Expand description

This crate provides an Egui integration for the Bevy game engine.

Trying out:

A basic WASM example is live at vladbat00.github.io/bevy_egui/ui.

Features:

  • Desktop and web platforms support
  • Clipboard
  • Opening URLs
  • Multiple windows support (see ./examples/two_windows.rs)
  • Paint callback support (see ./examples/paint_callback.rs)
  • Mobile web virtual keyboard (still rough around the edges and only works without prevent_default_event_handling set to false in the WindowPlugin settings)

§Dependencies

On Linux, this crate requires certain parts of XCB to be installed on your system. On Debian-based systems, these can be installed with the following command:

sudo apt install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

§Usage

Here’s a minimal usage example:

use bevy::prelude::*;
use bevy_egui::{egui, EguiContexts, EguiPlugin, EguiPrimaryContextPass};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(EguiPlugin::default())
        .add_systems(EguiPrimaryContextPass, ui_example_system)
        .run();
}

fn ui_example_system(mut contexts: EguiContexts) -> Result {
    egui::Window::new("Hello").show(contexts.ctx_mut()?, |ui| {
        ui.label("world");
    });
    Ok(())
}

Note that this example uses Egui in the multi-pass mode. If you don’t want to be limited to the EguiPrimaryContextPass schedule, you can use the single-pass mode, but it may get deprecated in the future.

For more advanced examples, see the examples section below.

§Note to developers of public plugins

If your plugin depends on bevy_egui, here are some hints on how to implement the support of both single-pass and multi-pass modes (with respect to the EguiPlugin::enable_multipass_for_primary_context flag):

  • Don’t initialize EguiPlugin for the user, i.e. DO NOT use add_plugins(EguiPlugin { ... }) in your code, users should be able to opt in or opt out of the multi-pass mode on their own.
  • If you add UI systems, make sure they go into the EguiPrimaryContextPass schedule - this will guarantee your plugin supports both the single-pass and multi-pass modes.

Your plugin code might look like this:


pub struct MyPlugin;

impl Plugin for MyPlugin {
    fn build(&self, app: &mut App) {
        // Don't add the plugin for users, let them chose the default mode themselves
        // and just make sure they initialize EguiPlugin before yours.
        assert!(app.is_plugin_added::<EguiPlugin>());

        app.add_systems(EguiPrimaryContextPass, ui_system);
    }
}

fn ui_system(contexts: EguiContexts) -> Result {
    // ...
    Ok(())
}

§Examples

To run an example, use the following command (you may replace ui with a name of another example):

cargo run --example ui

§ui (live page, source: examples/ui.rs)

Showcasing some more advanced UI, rendering images, hidpi scaling.

§absorb_input (live page, source: examples/absorb_input.rs)

Demonstrating the available options for absorbing input when Egui is using pointer or keyboard.

§color_test (live page, source: examples/color_test.rs)

Rendering test from egui.rs. We don’t fully pass it, help is wanted (#291).

§side_panel (live page, source: examples/side_panel.rs)

Showing how to display an Egui side panel and transform a camera with a perspective projection to make rendering centered relative to the remaining screen area.

§split_screen (live page, source: examples/split_screen.rs)

Demonstrating how to render multiple Egui contexts, attaching them to several cameras that target the same window.

§render_egui_to_image (live page, source: examples/render_egui_to_image.rs)

Rendering UI to an image (texture) and then using it as a mesh material texture.

§render_to_image_widget (live page, source: examples/render_to_image_widget.rs)

Rendering to a texture with Bevy and showing it as an Egui image widget.

§two_windows (source: examples/two_windows.rs)

Setting up two windows with an Egui context for each.

§paint_callback (live page, source: examples/paint_callback.rs)

Using Egui paint callbacks.

§simple (live page, source: examples/simple.rs)

The minimal usage example from this readme.

§run_manually (live page, source: examples/run_manually.rs)

The same minimal example demonstrating running Egui passes manually.

§See also

Re-exports§

pub use egui;

Modules§

helpers
Helpers for converting Bevy types into Egui ones and vice versa.
input
Systems for translating Bevy input events into Egui input.
node
The names of bevy_egui nodes.
output
Systems for handling Egui output.
picking
bevy_picking integration for Egui.
render
Rendering Egui with bevy_render.

Structs§

EguiClipboard
A resource for accessing clipboard.
EguiContext
A component for storing bevy_egui context.
EguiContextSettings
A component for storing Egui context settings.
EguiContexts
A helper SystemParam that provides a way to get EguiContext with less boilerplate and combines a proxy interface to the EguiUserTextures resource.
EguiFullOutput
Intermediate output buffer generated on an Egui pass end and consumed by the process_output_system system.
EguiGlobalSettings
A resource for storing global plugin settings.
EguiInput
Is used for storing Egui context input.
EguiInputSystemSettings
All the systems are enabled by default. These settings exist within both EguiGlobalSettings and EguiContextSettings.
EguiManagedTexture
Represents a texture allocated and painted by Egui.
EguiManagedTextures
Contains textures allocated and painted by Egui.
EguiMultipassSchedule
Add this component to your additional Egui contexts (e.g. when rendering to a new window or an image), to enable multi-pass support. Note that each Egui context running in the multi-pass mode must use a unique schedule.
EguiOutput
Stores last Egui output.
EguiPlugin
Adds all Egui resources and render graph nodes.
EguiPrimaryContextPass
Use this schedule to run your UI systems with the primary Egui context. (Mandatory if the context is running in the multi-pass mode.)
EguiRenderOutput
Is used for storing Egui shapes and textures delta.
EguiUserTextures
A resource for storing bevy_egui user textures.
EnableMultipassForPrimaryContext
This resource is created if EguiPlugin is initialized with EguiPlugin::enable_multipass_for_primary_context set to true.
MultiPassEguiQuery
MultiPassEguiQueryItem
Automatically generated WorldQuery item type for MultiPassEguiQuery, returned when iterating over query results.
MultiPassEguiQueryReadOnly
Automatically generated WorldQuery type for a read-only variant of MultiPassEguiQuery.
MultiPassEguiQueryReadOnlyItem
Automatically generated WorldQuery item type for MultiPassEguiQueryReadOnly, returned when iterating over query results.
PrimaryEguiContext
A marker component for a primary Egui context.
RenderComputedScaleFactor
Stores physical size and scale factor, is used as a helper to calculate logical size. The component lives only in the Render world.
UpdateUiSizeAndScaleQuery
UpdateUiSizeAndScaleQueryItem
Automatically generated WorldQuery item type for UpdateUiSizeAndScaleQuery, returned when iterating over query results.
UpdateUiSizeAndScaleQueryReadOnly
Automatically generated WorldQuery type for a read-only variant of UpdateUiSizeAndScaleQuery.
UpdateUiSizeAndScaleQueryReadOnlyItem
Automatically generated WorldQuery item type for UpdateUiSizeAndScaleQueryReadOnly, returned when iterating over query results.

Enums§

EguiInputSet
Subsets of the EguiPreUpdateSet::ProcessInput set.
EguiPostUpdateSet
System sets that run during the PostUpdate schedule.
EguiPreUpdateSet
System sets that run during the PreUpdate schedule.
EguiStartupSet
The bevy_egui plugin startup system sets.

Constants§

PICKING_ORDER
The ordering value used for bevy_picking.

Traits§

BevyEguiEntityCommandsExt
Extension for the EntityCommands trait.

Functions§

begin_pass_system
Marks a pass start for Egui.
capture_pointer_input_system
Captures pointers on Egui windows for bevy_picking.
end_pass_system
Marks a pass end for Egui.
free_egui_textures_system
This system is responsible for deleting image assets of freed Egui-managed textures and deleting Egui user textures of removed Bevy image assets.
run_egui_context_pass_loop_system
Runs Egui contexts with the EguiMultipassSchedule component. If there are no contexts with this component, runs the EguiPrimaryContextPass schedule once independently.
setup_primary_egui_context_system
Adds bevy_egui components to a first found camera assuming it’s a primary one.
update_egui_textures_system
Updates textures painted by Egui.
update_ui_size_and_scale_system
Updates UI egui::RawInput::screen_rect and calls egui::Context::set_pixels_per_point.