Hey! I'm the author of the crate, and I was born in Mariupol, Ukraine. When russians started the war in 2014, I moved to Kyiv. My parents, who had been staying in Mariupol till the start of the full-scale invasion, barely escaped the city alive. By the moment of writing (November 5th, 2023), we had 874 air raid alerts in Kyiv, and russians managed to bomb the city 132 times.

If you are using this crate, please consider donating to any of the listed funds (see the banner above), that will mean a lot to me.

bevy_egui

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:

# Cargo.toml
[dependencies]
bevy = "0.16.0"
bevy_egui = "0.34.1"

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:

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

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

• jakobhellermann/bevy-inspector-egui

Bevy support table

Note: if you're looking for a bevy_egui version that supports main branch of Bevy, check out open PRs, there's a great chance we've already started working on the future Bevy release support.