Text rework (#15591)

**Ready for review. Examples migration progress: 100%.**

# Objective

- Implement #15014

## Solution

This implements [cart's
proposal](#15014 (comment))
faithfully except for one change. I separated `TextSpan` from
`TextSpan2d` because `TextSpan` needs to require the `GhostNode`
component, which is a `bevy_ui` component only usable by UI.

Extra changes:
- Added `EntityCommands::commands_mut` that returns a mutable reference.
This is a blocker for extension methods that return something other than
`self`. Note that `sickle_ui`'s `UiBuilder::commands` returns a mutable
reference for this reason.

## Testing

- [x] Text examples all work.

---

## Showcase

TODO: showcase-worthy

## Migration Guide

TODO: very breaking

### Accessing text spans by index

Text sections are now text sections on different entities in a
hierarchy, Use the new `TextReader` and `TextWriter` system parameters
to access spans by index.

Before:
```rust
fn refresh_text(mut query: Query<&mut Text, With<TimeText>>, time: Res<Time>) {
    let text = query.single_mut();
    text.sections[1].value = format_time(time.elapsed());
}
```

After:
```rust
fn refresh_text(
    query: Query<Entity, With<TimeText>>,
    mut writer: UiTextWriter,
    time: Res<Time>
) {
    let entity = query.single();
    *writer.text(entity, 1) = format_time(time.elapsed());
}
```

### Iterating text spans

Text spans are now entities in a hierarchy, so the new `UiTextReader`
and `UiTextWriter` system parameters provide ways to iterate that
hierarchy. The `UiTextReader::iter` method will give you a normal
iterator over spans, and `UiTextWriter::for_each` lets you visit each of
the spans.

---------

Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
Co-authored-by: Carter Anderson <mcanders1@gmail.com>

crates/bevy_dev_tools/src/fps_overlay.rs

@@ -7,15 +7,17 @@ use bevy_diagnostic::{DiagnosticsStore, FrameTimeDiagnosticsPlugin};
 use bevy_ecs::{
  change_detection::DetectChangesMut,
  component::Component,
+ entity::Entity,
  query::With,
  schedule::{common_conditions::resource_changed, IntoSystemConfigs},
  system::{Commands, Query, Res, Resource},
 };
 use bevy_hierarchy::{BuildChildren, ChildBuild};
 use bevy_render::view::Visibility;
-use bevy_text::{Font, Text, TextSection, TextStyle};
+use bevy_text::{Font, TextSpan, TextStyle};
 use bevy_ui::{
- node_bundles::{NodeBundle, TextBundle},
+ node_bundles::NodeBundle,
+ widget::{Text, UiTextWriter},
  GlobalZIndex, PositionType, Style,
 };
 use bevy_utils::default;
@@ -72,6 +74,7 @@ impl Default for FpsOverlayConfig {
  font: Handle::<Font>::default(),
  font_size: 32.0,
  color: Color::WHITE,
+ ..default()
  },
  enabled: true,
  }
@@ -95,35 +98,39 @@ fn setup(mut commands: Commands, overlay_config: Res<FpsOverlayConfig>) {
  },
  GlobalZIndex(FPS_OVERLAY_ZINDEX),
  ))
- .with_children(|c| {
- c.spawn((
- TextBundle::from_sections([
- TextSection::new("FPS: ", overlay_config.text_config.clone()),
- TextSection::from_style(overlay_config.text_config.clone()),
- ]),
+ .with_children(|p| {
+ p.spawn((
+ Text::new("FPS: "),
+ overlay_config.text_config.clone(),
  FpsText,
- ));
+ ))
+ .with_child((TextSpan::default(), overlay_config.text_config.clone()));
  });
 }
 
-fn update_text(diagnostic: Res<DiagnosticsStore>, mut query: Query<&mut Text, With<FpsText>>) {
- for mut text in &mut query {
+fn update_text(
+ diagnostic: Res<DiagnosticsStore>,
+ query: Query<Entity, With<FpsText>>,
+ mut writer: UiTextWriter,
+) {
+ for entity in &query {
  if let Some(fps) = diagnostic.get(&FrameTimeDiagnosticsPlugin::FPS) {
  if let Some(value) = fps.smoothed() {
- text.sections[1].value = format!("{value:.2}");
+ *writer.text(entity, 1) = format!("{value:.2}");
  }
  }
  }
 }
 
 fn customize_text(
  overlay_config: Res<FpsOverlayConfig>,
- mut query: Query<&mut Text, With<FpsText>>,
+ query: Query<Entity, With<FpsText>>,
+ mut writer: UiTextWriter,
 ) {
- for mut text in &mut query {
- for section in text.sections.iter_mut() {
- section.style = overlay_config.text_config.clone();
- }
+ for entity in &query {
+ writer.for_each_style(entity, |mut style| {
+ *style = overlay_config.text_config.clone();
+ });
  }
 }
 

crates/bevy_ecs/src/system/commands/mod.rs

@@ -939,7 +939,7 @@ pub struct EntityCommands<'a> {
  pub(crate) commands: Commands<'a, 'a>,
 }
 
-impl EntityCommands<'_> {
+impl<'a> EntityCommands<'a> {
  /// Returns the [`Entity`] id of the entity.
  ///
  /// # Example
@@ -1533,6 +1533,11 @@ impl EntityCommands<'_> {
  self.commands.reborrow()
  }
 
+ /// Returns a mutable reference to the underlying [`Commands`].
+ pub fn commands_mut(&mut self) -> &mut Commands<'a, 'a> {
+ &mut self.commands
+ }
+
  /// Sends a [`Trigger`] targeting this entity. This will run any [`Observer`] of the `event` that
  /// watches this entity.
  ///

crates/bevy_text/Cargo.toml

@@ -18,6 +18,7 @@ bevy_asset = { path = "../bevy_asset", version = "0.15.0-dev" }
 bevy_color = { path = "../bevy_color", version = "0.15.0-dev" }
 bevy_derive = { path = "../bevy_derive", version = "0.15.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.15.0-dev" }
+bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.15.0-dev" }
 bevy_math = { path = "../bevy_math", version = "0.15.0-dev" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.15.0-dev", features = [
  "bevy",
@@ -36,6 +37,7 @@ derive_more = { version = "1", default-features = false, features = [
  "display",
 ] }
 serde = { version = "1", features = ["derive"] }
+smallvec = "1.13"
 unicode-bidi = "0.3.13"
 sys-locale = "0.3.0"
 

crates/bevy_text/src/font_atlas_set.rs

@@ -60,9 +60,9 @@ pub struct FontAtlasKey(pub u32, pub FontSmoothing);
 /// A `FontAtlasSet` is an [`Asset`].
 ///
 /// There is one `FontAtlasSet` for each font:
-/// - When a [`Font`] is loaded as an asset and then used in [`Text`](crate::Text),
+/// - When a [`Font`] is loaded as an asset and then used in [`TextStyle`](crate::TextStyle),
 /// a `FontAtlasSet` asset is created from a weak handle to the `Font`.
-/// - ~When a font is loaded as a system font, and then used in [`Text`](crate::Text),
+/// - ~When a font is loaded as a system font, and then used in [`TextStyle`](crate::TextStyle),
 /// a `FontAtlasSet` asset is created and stored with a strong handle to the `FontAtlasSet`.~
 /// (*Note that system fonts are not currently supported by the `TextPipeline`.*)
 ///

crates/bevy_text/src/glyph.rs

@@ -13,14 +13,14 @@ use bevy_sprite::TextureAtlasLayout;
 /// Used in [`TextPipeline::queue_text`](crate::TextPipeline::queue_text) and [`crate::TextLayoutInfo`] for rendering glyphs.
 #[derive(Debug, Clone, Reflect)]
 pub struct PositionedGlyph {
- /// The position of the glyph in the [`Text`](crate::Text)'s bounding box.
+ /// The position of the glyph in the text block's bounding box.
  pub position: Vec2,
  /// The width and height of the glyph in logical pixels.
  pub size: Vec2,
  /// Information about the glyph's atlas.
  pub atlas_info: GlyphAtlasInfo,
- /// The index of the glyph in the [`Text`](crate::Text)'s sections.
- pub section_index: usize,
+ /// The index of the glyph in the [`ComputedTextBlock`](crate::ComputedTextBlock)'s tracked spans.
+ pub span_index: usize,
  /// TODO: In order to do text editing, we need access to the size of glyphs and their index in the associated String.
  /// For example, to figure out where to place the cursor in an input box from the mouse's position.
  /// Without this, it's only possible in texts where each glyph is one byte. Cosmic text has methods for this
@@ -30,17 +30,12 @@ pub struct PositionedGlyph {
 
 impl PositionedGlyph {
  /// Creates a new [`PositionedGlyph`]
- pub fn new(
- position: Vec2,
- size: Vec2,
- atlas_info: GlyphAtlasInfo,
- section_index: usize,
- ) -> Self {
+ pub fn new(position: Vec2, size: Vec2, atlas_info: GlyphAtlasInfo, span_index: usize) -> Self {
  Self {
  position,
  size,
  atlas_info,
- section_index,
+ span_index,
  byte_index: 0,
  }
  }

crates/bevy_text/src/lib.rs

@@ -14,7 +14,7 @@
 //!
 //! The [`TextPipeline`] resource does all of the heavy lifting for rendering text.
 //!
-//! [`Text`] is first measured by creating a [`TextMeasureInfo`] in [`TextPipeline::create_text_measure`],
+//! UI `Text` is first measured by creating a [`TextMeasureInfo`] in [`TextPipeline::create_text_measure`],
 //! which is called by the `measure_text_system` system of `bevy_ui`.
 //!
 //! Note that text measurement is only relevant in a UI context.
@@ -23,7 +23,7 @@
 //! or [`text2d::update_text2d_layout`] system (in a 2d world space context)
 //! passes it into [`TextPipeline::queue_text`], which:
 //!
-//! 1. creates a [`Buffer`](cosmic_text::Buffer) from the [`TextSection`]s, generating new [`FontAtlasSet`]s if necessary.
+//! 1. updates a [`Buffer`](cosmic_text::Buffer) from the [`TextSpan`]s, generating new [`FontAtlasSet`]s if necessary.
 //! 2. iterates over each glyph in the [`Buffer`](cosmic_text::Buffer) to create a [`PositionedGlyph`],
 //! retrieving glyphs from the cache, or rasterizing to a [`FontAtlas`] if necessary.
 //! 3. [`PositionedGlyph`]s are stored in a [`TextLayoutInfo`],
@@ -43,6 +43,7 @@ mod glyph;
 mod pipeline;
 mod text;
 mod text2d;
+mod text_access;
 
 pub use cosmic_text;
 
@@ -56,13 +57,17 @@ pub use glyph::*;
 pub use pipeline::*;
 pub use text::*;
 pub use text2d::*;
+pub use text_access::*;
 
 /// The text prelude.
 ///
 /// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
  #[doc(hidden)]
- pub use crate::{Font, JustifyText, Text, Text2dBundle, TextError, TextSection, TextStyle};
+ pub use crate::{
+ Font, JustifyText, LineBreak, Text2d, TextBlock, TextError, TextReader2d, TextSpan,
+ TextStyle, TextWriter2d,
+ };
 }
 
 use bevy_app::prelude::*;
@@ -87,7 +92,7 @@ pub const DEFAULT_FONT_DATA: &[u8] = include_bytes!("FiraMono-subset.ttf");
 pub struct TextPlugin;
 
 /// Text is rendered for two different view projections;
-/// 2-dimensional text ([`Text2dBundle`]) is rendered in "world space" with a `BottomToTop` Y-axis,
+/// 2-dimensional text ([`Text2d`]) is rendered in "world space" with a `BottomToTop` Y-axis,
 /// while UI is rendered with a `TopToBottom` Y-axis.
 /// This matters for text because the glyph positioning is different in either layout.
 /// For `TopToBottom`, 0 is the top of the text, while for `BottomToTop` 0 is the bottom.
@@ -98,35 +103,37 @@ pub enum YAxisOrientation {
  BottomToTop,
 }
 
-/// A convenient alias for `With<Text>`, for use with
-/// [`bevy_render::view::VisibleEntities`].
-pub type WithText = With<Text>;
+/// System set in [`PostUpdate`] where all 2d text update systems are executed.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
+pub struct Update2dText;
 
 impl Plugin for TextPlugin {
  fn build(&self, app: &mut App) {
  app.init_asset::<Font>()
- .register_type::<Text>()
+ .register_type::<Text2d>()
+ .register_type::<TextSpan>()
  .register_type::<TextBounds>()
  .init_asset_loader::<FontLoader>()
  .init_resource::<FontAtlasSets>()
  .init_resource::<TextPipeline>()
  .init_resource::<CosmicFontSystem>()
  .init_resource::<SwashCache>()
+ .init_resource::<TextIterScratch>()
  .add_systems(
  PostUpdate,
  (
- calculate_bounds_text2d
- .in_set(VisibilitySystems::CalculateBounds)
- .after(update_text2d_layout),
+ remove_dropped_font_atlas_sets,
+ detect_text_needs_rerender::<Text2d>,
  update_text2d_layout
- .after(remove_dropped_font_atlas_sets)
  // Potential conflict: `Assets<Image>`
  // In practice, they run independently since `bevy_render::camera_update_system`
  // will only ever observe its own render target, and `update_text2d_layout`
  // will never modify a pre-existing `Image` asset.
  .ambiguous_with(CameraUpdateSystem),
- remove_dropped_font_atlas_sets,
- ),
+ calculate_bounds_text2d.in_set(VisibilitySystems::CalculateBounds),
+ )
+ .chain()
+ .in_set(Update2dText),
  )
  .add_systems(Last, trim_cosmic_cache);