bevy_text

Text shaping, layout, and rendering. Built on cosmic-text for shaping plus a font-atlas approach to GPU rendering.

Purpose

bevy_text provides:

• Font asset (TTF/OTF).
• Text component for 2D and UI text rendering.
• TextLayout, TextFont, TextColor — layout and styling.
• Font atlas — glyph caching on a GPU texture.
• Bidi / shaping via cosmic-text.

Directory layout

crates/bevy_text/src/
├── lib.rs
├── font.rs
├── font_atlas.rs
├── font_atlas_set.rs
├── font_loader.rs
├── glyph.rs
├── pipeline.rs            # cosmic-text integration
├── text.rs                # Text component + spans
├── text2d.rs              # 2D-world text
├── bounds.rs, error.rs
└── prelude.rs

Key abstractions

Type	File	Description
TextPlugin	crates/bevy_text/src/lib.rs	Adds font asset, layout systems.
Font	crates/bevy_text/src/font.rs	Asset; parsed font face data.
Text	crates/bevy_text/src/text.rs	Component; sequence of TextSpans plus layout.
TextSpan	crates/bevy_text/src/text.rs	A run of text with one font/color/size.
TextLayout	crates/bevy_text/src/text.rs	Justification, line break behavior.
TextFont, TextColor	crates/bevy_text/src/text.rs	Per-span styling components.
FontAtlasSet	crates/bevy_text/src/font_atlas_set.rs	Per-font glyph atlas.
Text2d	crates/bevy_text/src/text2d.rs	Component for world-space 2D text.

How it works

1. A Text component is composed of TextSpan children, each with TextFont, TextColor, and optional TextLayout.
2. The text pipeline uses cosmic-text to shape each span and produce glyph runs.
3. Each glyph is rasterized once and stored in an atlas keyed by (Font, size).
4. Renderers (bevy_ui_render, bevy_sprite_render) extract the glyph runs and produce textured quads referencing the atlas.

Integration points

• Depends on: cosmic-text, bevy_app, bevy_ecs, bevy_asset, bevy_image, bevy_color, bevy_math.
• Depended on by: bevy_ui, bevy_ui_render, bevy_sprite_render (for Text2d), bevy_dev_tools.

Entry points for modification

• New text feature: edit text.rs and the layout in pipeline.rs.
• Font format: font_loader.rs. cosmic-text handles most of the parsing.
• Atlas tuning: font_atlas.rs. The atlas grows on demand; the heuristic for atlas size lives here.

See also

• bevy_ui — primary consumer.
• bevy_asset — font loading.