bevy_bitmap_text

Current Status: 🚧 Early Development (Initial version in progress)

bevy_bitmap_text — Glyph-as-Entity dynamic atlas text rendering for Bevy.

Introduction

bevy_bitmap_text is a text rendering backend for Bevy that spawns each character as an individual ECS entity with a Sprite component.
It solves the limitation of monolithic text meshes, allowing users to apply per-character ECS-driven animations such as shake, wave, and color changes.

With bevy_bitmap_text, you only need to add a TextBlock component and configure TextBlockStyling — the plugin handles rasterization, atlas packing, layout, and entity synchronization automatically.

Features

• Glyph-as-Entity architecture — each character is a separate Sprite entity, enabling per-character animation and styling via standard ECS
• Dynamic glyph atlas — on-demand rasterization with fontdue and rectangle packing via etagere
• Typewriter effect — built-in GlyphReveal component for progressive character reveal
• Per-character effects — ShakeEffect and WaveEffect components for jitter and sine-wave animations
• Color tags — inline {#RRGGBB:text} markup for per-segment coloring
• Text styling — configurable font, size, color, alignment, anchor, line height, character spacing, and word spacing
• Auto line-wrapping — optional max_width for automatic word wrap

How to Use

1. Add the dependency to your Cargo.toml:

   [dependencies]
   bevy_bitmap_text = { path = "crates/bevy_bitmap_text" }
   

2. Register the plugin:

   use bevy::prelude::*;
   use bevy_bitmap_text::{BitmapTextPlugin, FontDirectories};
   
   fn main() {
       App::new()
           .add_plugins(DefaultPlugins)
           .insert_resource(FontDirectories {
               directories: vec!["assets/fonts".to_string()],
           })
           .add_plugins(BitmapTextPlugin::default())
           .add_systems(Startup, setup)
           .run();
   }
   

3. Spawn a text block:

   use bevy_bitmap_text::*;
   
   fn setup(mut commands: Commands) {
       commands.spawn(Camera2d);
       commands.spawn((
           TextBlock::new("Hello, world!"),
           TextBlockStyling {
               font: FontId::from_name("my_font"),
               size_px: 32,
               world_scale: 32.0,
               ..default()
           },
       ));
   }
   

4. Typewriter effect:

   commands.spawn((
       TextBlock::new("Revealing text..."),
       TextBlockStyling { /* ... */ },
       GlyphReveal { visible_count: 0 },
   ));
   // Increment `visible_count` each frame to reveal characters one by one.
   

5. Color tags:

   use bevy_bitmap_text::parse_text_to_segments;
   let segments = parse_text_to_segments("{#FF0000:Red} and {#00FF00:Green}");
   commands.spawn((
       TextBlock::from_segments(segments),
       TextBlockStyling { /* ... */ },
   ));
   

How to Build

Prerequisites

• Rust 1.85 or later (edition 2024)
• Bevy 0.18

Build Steps

1. Build the crate:

   cargo build -p bevy_bitmap_text
   

2. Run tests:

   cargo test -p bevy_bitmap_text
   

3. Run the demo:

   cargo run -p bevy_bitmap_text --example demo
   

Dependencies

This project uses the following crates:

Contributing

Contributions are welcome! Whether you want to fix a bug, add a feature, or improve documentation:

• Submit an Issue or Pull Request.
• Share ideas and discuss design or architecture.

License

This project is 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.