Crate bevy_egui

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, EguiContextPass};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(EguiPlugin { enable_multipass_for_primary_context: true })
        .add_systems(EguiContextPass, ui_example_system)
        .run();
}

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

Note that this example uses Egui in the multi-pass mode. If you don’t want to be limited to the EguiContextPass 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 EguiContextPass 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(EguiContextPass, ui_system);
    }
}

fn ui_system(contexts: EguiContexts) {
    // ...
}

§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_2d (live page, source: examples/side_panel_2d.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.

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

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

§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

bevy-inspector-egui

Re-exports§

pub use egui;

Modules§

egui_node: Egui render node.
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.
render_systems: Plugin systems for the render app.

Structs§

EguiClipboard: A resource for accessing clipboard.
EguiContext: A component for storing bevy_egui context.
EguiContextPass: Use this schedule to run your UI systems with the primary Egui context. (Mandatory if the context is running in the multi-pass mode.)
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.
EguiRenderOutput: Is used for storing Egui shapes and textures delta.
EguiRenderToImage: Contexts with this component will render UI to a specified image.
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.
RenderTargetSize: Stores physical size and scale factor, is used as a helper to calculate logical size.
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.

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 EguiContextPass schedule once independently.
setup_new_windows_system: Adds bevy_egui components to newly created windows.
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.

Crate bevy_eguiCopy item path