bevy_inspector_egui/lib.rs
1#![warn(
2 clippy::undocumented_unsafe_blocks,
3 clippy::missing_safety_doc,
4 unsafe_op_in_unsafe_fn
5)]
6#![allow(
7 clippy::needless_lifetimes, // can be good for clarity
8 clippy::needless_doctest_main, // sometimes a full copy-pasteable standalone example is better
9 clippy::too_many_arguments,
10 clippy::type_complexity,
11)]
12
13//! This crate contains
14//! - general purpose machinery for displaying [`Reflect`](bevy_reflect::Reflect) values in [`reflect_inspector`],
15//! - a way of associating arbitrary options with fields and enum variants in [`inspector_options`]
16//! - utility functions for displaying bevy resource, entities and assets in [`bevy_inspector`]
17//! - some drop-in plugins in [`quick`] to get you started without any code necessary.
18//!
19//! # Use case 1: Quick plugins
20//! These plugins can be easily added to your app, but don't allow for customization of the presentation and content.
21//!
22//! ## WorldInspectorPlugin
23//! Displays the world's entities, resources and assets.
24//!
25//! 
26//!
27//! ```no_run
28//! use bevy::prelude::*;
29//! use bevy_inspector_egui::quick::WorldInspectorPlugin;
30//!
31//! fn main() {
32//! App::new()
33//! .add_plugins(DefaultPlugins)
34//! .add_plugins(WorldInspectorPlugin::new())
35//! .run();
36//! }
37//!
38//! ```
39//! ## ResourceInspectorPlugin
40//! Display a single resource in a window.
41//!
42//! 
43//!
44//! ```no_run
45//! use bevy::prelude::*;
46//! use bevy_inspector_egui::prelude::*;
47//! use bevy_inspector_egui::quick::ResourceInspectorPlugin;
48//!
49//! // `InspectorOptions` are completely optional
50//! #[derive(Reflect, Resource, Default, InspectorOptions)]
51//! #[reflect(Resource, InspectorOptions)]
52//! struct Configuration {
53//! name: String,
54//! #[inspector(min = 0.0, max = 1.0)]
55//! option: f32,
56//! }
57//!
58//! fn main() {
59//! App::new()
60//! .add_plugins(DefaultPlugins)
61//! .init_resource::<Configuration>() // `ResourceInspectorPlugin` won't initialize the resource
62//! .register_type::<Configuration>() // you need to register your type to display it
63//! .add_plugins(ResourceInspectorPlugin::<Configuration>::default())
64//! // also works with built-in resources, as long as they implement `Reflect`
65//! .add_plugins(ResourceInspectorPlugin::<Time>::default())
66//! .run();
67//! }
68//! ```
69//!
70//! <hr>
71//!
72//! There is also the [`StateInspectorPlugin`](quick::StateInspectorPlugin) and the [`AssetInspectorPlugin`](quick::AssetInspectorPlugin).
73//!
74//! # Use case 2: Manual UI
75//! The [`quick`] plugins don't allow customization of the egui window or its content, but you can easily build your own UI:
76//!
77//! ```no_run
78//! use bevy::prelude::*;
79//! use bevy_egui::{EguiPlugin, EguiContext, EguiPrimaryContextPass};
80//! use bevy_inspector_egui::prelude::*;
81//! use bevy_inspector_egui::bevy_inspector;
82//! use bevy_window::PrimaryWindow;
83//! use std::any::TypeId;
84//!
85//! fn main() {
86//! App::new()
87//! .add_plugins(DefaultPlugins)
88//! .add_plugins(EguiPlugin::default())
89//! .add_plugins(bevy_inspector_egui::DefaultInspectorConfigPlugin) // adds default options and `InspectorEguiImpl`s
90//! .add_systems(EguiPrimaryContextPass, inspector_ui)
91//! .run();
92//! }
93//!
94//! fn inspector_ui(world: &mut World) {
95//! let mut egui_context = world
96//! .query_filtered::<&mut EguiContext, With<bevy_egui::PrimaryEguiContext>>()
97//! .single(world)
98//! .expect("EguiContext not found")
99//! .clone();
100//!
101//! egui::Window::new("UI").show(egui_context.get_mut(), |ui| {
102//! egui::ScrollArea::both().show(ui, |ui| {
103//! // equivalent to `WorldInspectorPlugin`
104//! bevy_inspector::ui_for_world(world, ui);
105//!
106//! // works with any `Reflect` value, including `Handle`s
107//! let mut any_reflect_value: i32 = 5;
108//! bevy_inspector::ui_for_value(&mut any_reflect_value, ui, world);
109//!
110//! egui::CollapsingHeader::new("Materials").show(ui, |ui| {
111//! bevy_inspector::ui_for_assets::<StandardMaterial>(world, ui);
112//! });
113//!
114//! ui.heading("Entities");
115//! bevy_inspector::ui_for_entities(world, ui);
116//! });
117//! });
118//! }
119//! ```
120//!
121//! Pair this with a crate like [`egui_dock`](https://docs.rs/egui_dock/latest/egui_dock/) and you have your own editor in less than 100 lines: [`examples/egui_dock.rs`](https://github.com/jakobhellermann/bevy-inspector-egui/blob/main/crates/bevy-inspector-egui/examples/integrations/egui_dock.rs).
122//! 
123//!
124//! # FAQ
125//!
126//! **Q: How do I change the names of the entities in the world inspector?**
127//!
128//! **A:** You can insert the [`Name`](bevy_core::Name) component.
129//!
130//! **Q: What if I just want to display a single value without passing in the whole `&mut World`?**
131//!
132//! **A:** You can use [`ui_for_value`](crate::reflect_inspector::ui_for_value). Note that displaying things like `Handle<StandardMaterial>` won't be able to display the asset's value.
133//!
134//! **Q:** Can I change how exactly my type is displayed?
135//!
136//! **A:** Implement [`InspectorPrimitive`](crate::inspector_egui_impls::InspectorPrimitive) and call `app.register_type_data::<T, InspectorEguiImpl>`.
137
138pub mod bevy_inspector;
139pub mod inspector_egui_impls;
140pub mod inspector_options;
141#[cfg(feature = "bevy_render")]
142pub mod quick;
143pub mod reflect_inspector;
144pub mod restricted_world_view;
145
146pub mod dropdown;
147pub mod egui_utils;
148mod utils;
149
150use std::any::TypeId;
151
152#[cfg(feature = "bevy_render")]
153pub use bevy_egui;
154pub use egui;
155
156/// [`bevy_app::Plugin`] used to register default [`struct@InspectorOptions`] and [`InspectorEguiImpl`](crate::inspector_egui_impls::InspectorEguiImpl)s
157pub struct DefaultInspectorConfigPlugin;
158impl bevy_app::Plugin for DefaultInspectorConfigPlugin {
159 fn build(&self, app: &mut bevy_app::App) {
160 if app.is_plugin_added::<Self>() {
161 return;
162 }
163
164 // Defensively register stuff since bevy only registers glam, color types used by other structs internally
165 app.register_type::<bevy_math::IVec2>()
166 .register_type::<bevy_math::IVec3>()
167 .register_type::<bevy_math::IVec4>()
168 .register_type::<bevy_math::UVec2>()
169 .register_type::<bevy_math::UVec3>()
170 .register_type::<bevy_math::UVec4>()
171 .register_type::<bevy_math::DVec2>()
172 .register_type::<bevy_math::DVec3>()
173 .register_type::<bevy_math::DVec4>()
174 .register_type::<bevy_math::BVec2>()
175 .register_type::<bevy_math::BVec3>()
176 .register_type::<bevy_math::BVec3A>()
177 .register_type::<bevy_math::BVec4>()
178 .register_type::<bevy_math::BVec4A>()
179 .register_type::<bevy_math::Vec2>()
180 .register_type::<bevy_math::Vec3>()
181 .register_type::<bevy_math::Vec3A>()
182 .register_type::<bevy_math::Vec4>()
183 .register_type::<bevy_math::DAffine2>()
184 .register_type::<bevy_math::DAffine3>()
185 .register_type::<bevy_math::Affine2>()
186 .register_type::<bevy_math::Affine3A>()
187 .register_type::<bevy_math::DMat2>()
188 .register_type::<bevy_math::DMat3>()
189 .register_type::<bevy_math::DMat4>()
190 .register_type::<bevy_math::Mat2>()
191 .register_type::<bevy_math::Mat3>()
192 .register_type::<bevy_math::Mat3A>()
193 .register_type::<bevy_math::Mat4>()
194 .register_type::<bevy_math::DQuat>()
195 .register_type::<bevy_math::Quat>()
196 .register_type::<bevy_math::Rect>()
197 .register_type::<bevy_color::Color>()
198 .register_type::<core::ops::Range<f32>>()
199 .register_type::<TypeId>();
200
201 let type_registry = app.world().resource::<bevy_ecs::prelude::AppTypeRegistry>();
202 let mut type_registry = type_registry.write();
203
204 inspector_options::default_options::register_default_options(&mut type_registry);
205 inspector_egui_impls::register_std_impls(&mut type_registry);
206 inspector_egui_impls::register_glam_impls(&mut type_registry);
207 inspector_egui_impls::register_bevy_impls(&mut type_registry);
208 }
209}
210
211#[doc(inline)]
212pub use inspector_options::InspectorOptions;
213
214#[doc(hidden)]
215pub mod __macro_exports {
216 pub use bevy_reflect;
217}
218
219/// Reexports of commonly used types
220pub mod prelude {
221 // for `#[derive(Reflect)] #[reflect(InspectorOptions)]
222 pub use crate::inspector_options::InspectorOptions;
223 pub use crate::inspector_options::ReflectInspectorOptions;
224}