1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275#![expect(missing_docs, reason = "Not all docs are written yet, see #3492.")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(
html_logo_url = "https://bevy.org/assets/icon.png",
html_favicon_url = "https://bevy.org/assets/icon.png"
)]
//! This crate contains Bevy's UI system, which can be used to create UI for both 2D and 3D games
//! # Basic usage
//! Spawn UI elements with [`widget::Button`], [`ImageNode`](widget::ImageNode), [`Text`](prelude::Text) and [`Node`]
//! This UI is laid out with the Flexbox and CSS Grid layout models (see <https://cssreference.io/flexbox/>)
pub mod auto_directional_navigation;
pub mod interaction_states;
pub mod measurement;
pub mod update;
pub mod widget;
pub mod gradients;
#[cfg(feature = "bevy_picking")]
pub mod picking_backend;
pub mod ui_transform;
use bevy_derive::{Deref, DerefMut};
#[cfg(feature = "bevy_picking")]
use bevy_picking::PickingSystems;
use bevy_reflect::{std_traits::ReflectDefault, Reflect};
mod accessibility;
// This module is not re-exported, but is instead made public.
// This is intended to discourage accidental use of the experimental API.
pub mod experimental;
mod focus;
mod geometry;
mod layout;
mod stack;
mod ui_node;
pub use focus::*;
pub use geometry::*;
pub use gradients::*;
pub use interaction_states::{Checkable, Checked, InteractionDisabled, Pressed};
pub use layout::*;
pub use measurement::*;
pub use ui_node::*;
pub use ui_transform::*;
/// The UI prelude.
///
/// This includes the most common types in this crate, re-exported for your convenience.
pub mod prelude {
#[doc(hidden)]
#[cfg(feature = "bevy_picking")]
pub use crate::picking_backend::{UiPickingCamera, UiPickingPlugin, UiPickingSettings};
#[doc(hidden)]
pub use crate::widget::{Text, TextShadow, TextUiReader, TextUiWriter};
#[doc(hidden)]
pub use {
crate::{
geometry::*,
gradients::*,
ui_node::*,
ui_transform::*,
widget::{Button, ImageNode, Label, NodeImageMode, ViewportNode},
Interaction, UiScale,
},
// `bevy_sprite` re-exports for texture slicing
bevy_sprite::{BorderRect, SliceScaleMode, SpriteImageMode, TextureSlicer},
bevy_text::TextBackgroundColor,
};
}
use bevy_app::{prelude::*, AnimationSystems, HierarchyPropagatePlugin, PropagateSet};
use bevy_camera::CameraUpdateSystems;
use bevy_ecs::prelude::*;
use bevy_input::InputSystems;
use bevy_transform::TransformSystems;
use layout::ui_surface::UiSurface;
use stack::ui_stack_system;
pub use stack::UiStack;
use update::{propagate_ui_target_cameras, update_clipping_system};
/// The basic plugin for Bevy UI
#[derive(Default)]
pub struct UiPlugin;
/// The label enum labeling the types of systems in the Bevy UI
#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
pub enum UiSystems {
/// After this label, input interactions with UI entities have been updated for this frame.
///
/// Runs in [`PreUpdate`].
Focus,
/// All UI systems in [`PostUpdate`] will run in or after this label.
Prepare,
/// Propagate UI component values needed by layout.
Propagate,
/// Update content requirements before layout.
Content,
/// After this label, the ui layout state has been updated.
///
/// Runs in [`PostUpdate`].
Layout,
/// UI systems ordered after [`UiSystems::Layout`].
///
/// Runs in [`PostUpdate`].
PostLayout,
/// After this label, the [`UiStack`] resource has been updated.
///
/// Runs in [`PostUpdate`].
Stack,
}
/// The current scale of the UI.
///
/// A multiplier to fixed-sized ui values.
/// **Note:** This will only affect fixed ui values like [`Val::Px`]
#[derive(Debug, Reflect, Resource, Deref, DerefMut)]
#[reflect(Resource, Debug, Default)]
pub struct UiScale(pub f32);
impl Default for UiScale {
fn default() -> Self {
Self(1.0)
}
}
// Marks systems that can be ambiguous with [`widget::text_system`] if the `bevy_text` feature is enabled.
// See https://github.com/bevyengine/bevy/pull/11391 for more details.
#[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
struct AmbiguousWithText;
#[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
struct AmbiguousWithUpdateText2dLayout;
impl Plugin for UiPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<UiSurface>()
.init_resource::<UiScale>()
.init_resource::<UiStack>()
.configure_sets(
PostUpdate,
(
CameraUpdateSystems,
UiSystems::Prepare.after(AnimationSystems),
UiSystems::Propagate,
UiSystems::Content,
UiSystems::Layout,
UiSystems::PostLayout,
)
.chain(),
)
.configure_sets(
PostUpdate,
PropagateSet::<ComputedUiTargetCamera>::default().in_set(UiSystems::Propagate),
)
.add_plugins(HierarchyPropagatePlugin::<ComputedUiTargetCamera>::new(
PostUpdate,
))
.configure_sets(
PostUpdate,
PropagateSet::<ComputedUiRenderTargetInfo>::default().in_set(UiSystems::Propagate),
)
.add_plugins(HierarchyPropagatePlugin::<ComputedUiRenderTargetInfo>::new(
PostUpdate,
))
.add_systems(
PreUpdate,
ui_focus_system.in_set(UiSystems::Focus).after(InputSystems),
);
#[cfg(feature = "bevy_picking")]
app.add_plugins(picking_backend::UiPickingPlugin)
.add_systems(
First,
widget::viewport_picking.in_set(PickingSystems::PostInput),
);
let ui_layout_system_config = ui_layout_system
.in_set(UiSystems::Layout)
.before(TransformSystems::Propagate);
let ui_layout_system_config = ui_layout_system_config
// Text and Text2D operate on disjoint sets of entities
.ambiguous_with(bevy_sprite::update_text2d_layout)
.ambiguous_with(bevy_text::detect_text_needs_rerender::<bevy_sprite::Text2d>);
app.add_systems(
PostUpdate,
(
propagate_ui_target_cameras.in_set(UiSystems::Prepare),
ui_layout_system_config,
ui_stack_system
.in_set(UiSystems::Stack)
// These systems don't care about stack index
.ambiguous_with(widget::measure_text_system)
.ambiguous_with(update_clipping_system)
.ambiguous_with(ui_layout_system)
.ambiguous_with(widget::update_viewport_render_target_size)
.in_set(AmbiguousWithText),
update_clipping_system.after(TransformSystems::Propagate),
// Potential conflicts: `Assets<Image>`
// They run independently since `widget::image_node_system` will only ever observe
// its own ImageNode, and `widget::text_system` & `bevy_text::update_text2d_layout`
// will never modify a pre-existing `Image` asset.
widget::update_image_content_size_system
.in_set(UiSystems::Content)
.in_set(AmbiguousWithText)
.in_set(AmbiguousWithUpdateText2dLayout),
// Potential conflicts: `Assets<Image>`
// `widget::text_system` and `bevy_text::update_text2d_layout` run independently
// since this system will only ever update viewport images.
widget::update_viewport_render_target_size
.in_set(UiSystems::PostLayout)
.in_set(AmbiguousWithText)
.in_set(AmbiguousWithUpdateText2dLayout),
),
);
build_text_interop(app);
}
}
fn build_text_interop(app: &mut App) {
use widget::Text;
app.add_systems(
PostUpdate,
(
(
bevy_text::detect_text_needs_rerender::<Text>,
widget::measure_text_system,
)
.chain()
.after(bevy_text::load_font_assets_into_fontdb_system)
.in_set(UiSystems::Content)
// Text and Text2d are independent.
.ambiguous_with(bevy_text::detect_text_needs_rerender::<bevy_sprite::Text2d>)
// Potential conflict: `Assets<Image>`
// Since both systems will only ever insert new [`Image`] assets,
// they will never observe each other's effects.
.ambiguous_with(bevy_sprite::update_text2d_layout)
// We assume Text is on disjoint UI entities to ImageNode and UiTextureAtlasImage
// FIXME: Add an archetype invariant for this https://github.com/bevyengine/bevy/issues/1481.
.ambiguous_with(widget::update_image_content_size_system),
widget::text_system
.in_set(UiSystems::PostLayout)
.after(bevy_text::load_font_assets_into_fontdb_system)
.after(bevy_asset::AssetEventSystems)
// Text2d and bevy_ui text are entirely on separate entities
.ambiguous_with(bevy_text::detect_text_needs_rerender::<bevy_sprite::Text2d>)
.ambiguous_with(bevy_sprite::update_text2d_layout)
.ambiguous_with(bevy_sprite::calculate_bounds_text2d),
),
);
app.add_plugins(accessibility::AccessibilityPlugin);
app.add_observer(interaction_states::on_add_disabled)
.add_observer(interaction_states::on_remove_disabled)
.add_observer(interaction_states::on_add_checkable)
.add_observer(interaction_states::on_remove_checkable)
.add_observer(interaction_states::on_add_checked)
.add_observer(interaction_states::on_remove_checked);
app.configure_sets(
PostUpdate,
AmbiguousWithText.ambiguous_with(widget::text_system),
);
app.configure_sets(
PostUpdate,
AmbiguousWithUpdateText2dLayout.ambiguous_with(bevy_sprite::update_text2d_layout),
);
}