Crate bevy_rich_text3d

Expand description

§bevy_rich_text3d

Mesh based raster rich text implementation for bevy.

§Overview

This crate is similar to bevy_text but aims to be more user friendly and powerful.

Unlike bevy_text, this crate renders text as a Mesh and an Image atlas. This not only works with StandardMaterial but also can be empowered by user defined shaders.

We render each glyph as a separate quad, meaning in shaders, we can easily manipulate individual glyphs for different effects. Additionally we support exporting specific values like glyph count, glyph position or user defined magic numbers via either uv1 or custom mesh attributes.

§Getting Started

Add plugins:

app.add_plugins(Text3dPlugin{
    default_atlas_dimension: (1024, 1024),
    load_system_fonts: true,
    ..Default::default()
});

// Add fonts via the `LoadFonts` resource.
app.insert_resource(LoadFonts {
    font_paths: vec!["assets/roboto.ttf".to_owned()],
    font_directories: vec!["assets/fonts".to_owned()],
    ..Default::default()
});

Spawn a Text3d.

commands.spawn(
    Text3d::new("Hello, World!"),
    // Mesh2d also works
    Mesh3d::default(),
    MeshMaterial3d(materials.add(
        StandardMaterial {
            base_color_texture: Some(TextAtlas::DEFAULT_IMAGE.clone()),
            alpha_mode: AlphaMode::Blend,
            ..Default::default()
        }
    ))
)

§Rich Text

Rich text can be created from a string using the Text3d::parse function. We support a straightforward syntax:

{style:value}: equivalent to <style>value</style> in html.
{value} (without :): parse as a dynamic value that can be fetched from the world.

See documentation on Text3d::parse for up-to-date syntax.

§Dependencies

cosmic_text

A minimal subset of Cosmic text is used for layout.

tiny_skia

Used for tesselation.

bevy

Bevy’s asset system functions as an alternative to swash.

§Glyph Atlas

We store rendered glyphs inside a texture atlas in the component TextAtlasHandle. If you did not create a new one, all glyphs will be cached inside the same default texture, and you can use the convenient TextAtlas::DEFAULT_IMAGE as the image in your materials.

However, if you need more control over where your glyphs are stored, you can manually create a TextAtlas and Image alongside your Text3d, they can be managed the same way as other assets.

§FAQ

How do I add fonts?

Add them to the LoadFonts resource before the app starts.

Some characters are missing when text changes

You must add TouchTextMaterial*dPlugin to get around a change detection issue in bevy. This is a band-aid solution intended to be removed later as we wait for a fix upstream.

§Showcase

§Versions

bevy	bevy_rich_text3d
0.15	0.1-0.2
0.16	0.3-0.4
0.17	0.5
0.18	0.6
0.19	0.7-latest

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs§

DrawStyle: Style that only concerns drawing but not layout.
FetchedTextSegment: A string segment on a component, as opposed to in a Text3d.
FontSystemGuard: Mutex guard over a FontSystem.
LoadFonts: A Resource that contains paths of fonts to be loaded.
MeshExportEntry
SegmentStyle: Text style of a segment.
SharedTextSegment: If alongside a FetchedTextSegment, prevent Text3d from despawning it on remove.
Text3d: A rich text component.
Text3dBounds: Determines the maximum width of rendered text, by default infinite.
Text3dDimensionOut: Size of the output mesh’s Aabb.
Text3dPlugin: Text3d Plugin.
Text3dSet: SystemSet of text3d rendering in PostUpdate before transforms.
Text3dStyling: Default text style of a rich text component.
TextAnchor: Anchor of a text block, usually in (-0.5, -0.5)..=(0.5, 0.5).
TextAtlas: Backing image handle and atlas of Text3d.
TextAtlasHandle: Component of a Handle<TextAtlas>, if left as default, will use the shared TextAtlas::DEFAULT_IMAGE as the underlying image.
TextFetch: A component that fetches data as a string from the world.
TextRenderer: An Arc<Mutex> around cosmic_text::FontSystem, rendering fonts require exclusive access.
TouchTextMaterial2dPlugin: This plugin must be added if you want text changes to affect the material, this works by mutably dereferencing the material to signal a change.
TouchTextMaterial3dPlugin: This plugin must be added if you want text changes to affect the material, this works by mutably dereferencing the material to signal a change.
Weight: Specifies the weight of glyphs in the font, their degree of blackness or stroke thickness.

Enums§

GlyphMeta: Determines what kind of data each field in MeshExport carry.
MeshExport: Determines what data to export as a part of the mesh.
ParseError: Error emitted when parsing rich text.
SegmentSize: Size of a segment.
StrokeJoin: Specifies how corners are drawn when a shape is stroked.
Style: Allows italic or oblique faces to be selected.
Text3dSegment: A string segment in Text3d.
TextAlign: Horizontal align of text.

Traits§

TextProgressReportCallback: A callback function that helps a loading screen keep track of progress.