Crate bevy_image_font 

bevy_image_font

bevy_image_font enables rendering fonts stored as single images (e.g., PNG), with each letter at a predefined position. This crate focuses specifically on image-based fonts, often called “pixel fonts,” used in game development. The term “image font” was chosen for precision, as bitmap fonts in formats like OTB might also be referred to as “pixel fonts.”

Features

Supported

• Unicode (single codepoints)
• Defining character coordinates via strings (see example asset)
• Manual specification of rectangles (including non-uniform sizes)

Planned Enhancements

• Padding and offsets for texture layouts
• Inline newlines in strings

Out of Scope

• Rendering from traditional bitmap fonts
• Automatic line wrapping

Known Limitations

• Space characters require a blank texture region.
• Newlines are currently unsupported.

Getting Started

Add the following to your Cargo.toml:

[dependencies]
bevy = "0.17"
bevy_image_font = "0.10"

Usage

Add an ImageFontText component to an entity along with:

• A Sprite and a ImageFontPreRenderedText components to render the text onto the associated Sprite, or
• A ImageNode and ImageFontPreRenderedUiText components to render the text onto the associated ImageNode, or
• A ImageFontSpriteText component for atlas-based text rendering.

Minimal Example

Here’s a minimal example of using bevy_image_font to render text.¹ :

use bevy::prelude::*;
use bevy_image_font::{ImageFontPlugin, ImageFontText};
#[cfg(feature = "atlas_sprites")]
use bevy_image_font::atlas_sprites::ImageFontSpriteText;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, ImageFontPlugin))
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    let font_handle = asset_server.load("path/to/font_layout.image_font.ron");

    commands.spawn((
        #[cfg(feature = "atlas_sprites")]
        ImageFontSpriteText::default(),
        ImageFontText::default()
            .text("Hello, world!")
            .font(font_handle.clone()),
    ));
}

This example sets up a simple Bevy application with an ImageFontText component, rendering “Hello, world!” using a specified font image and layout.

See examples for more details:

• Rendered sprite example: Using pixel fonts for in-world text like damage numbers.
• Rendered UI example: Using bevy_asset_loader for texture and font handling.
• Atlased Sprite Example: Demonstrates rendering text with a texture atlas, including animations for dynamic text display and changing colors.

Note on Pixel Accuracy

Bevy anchors sprites at the center by default, which may cause odd-dimensioned sprites to appear blurry. To avoid this, use non-Center anchors like Anchor::TopLeft or adjust sprite translations. Refer to the rendered sprite example for details.

Optional Features

• You can disable the default atlas_sprites feature if you don’t use ImageFontSpriteText.
• You can disable the default rendered feature if you don’t use ImageFontPreRenderedText or ImageFontPreRenderedUiText. This removes the dependency on the image crate.
• You can disable the default ui feature if you don’t use ImageFontPreRenderedUiText to remove a dependency on the bevy/bevy_ui feature.
• If your project depends on this crate and you need support for non-PNG formats, add your own dependency on the same version of image and enable the relevant features.

Bevy Version Compatibility

Bevy Version	Crate Version
0.17	0.10
0.16	0.9
0.15	0.6, 0.7, 0.8
0.14	0.5

Changelog

For detailed changes across versions, see the Changelog. Each GitHub Release which is created each time the crate is published also includes the relevant section of the changelog in its release notes for easy reference.

Contributing

1. Configure Git hooks after cloning:

   git config --local core.hooksPath .githooks

2. Install required tools:

   cargo install cargo-hack --locked
   cargo install cargo-nextest --locked

PRs to support the latest Bevy releases are welcome!

Credits

• example_font by gnsh.
• example_variable_width_font by Clint Bellanger.

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.

---

1. Ignore the #[cfg(feature = "...")] lines in the example; they’re only there to satisfy the compiler when running it as a doc test for this README. ↩

Modules

atlas_spritesatlas_sprites

This module provides functionality for rendering text as individual sprites using the Bevy engine, utilizing custom image fonts.

loader

Code for parsing an ImageFont off of an on-disk representation.

renderedrendered

This module provides functionality for rendering text as images in the Bevy engine, utilizing custom image fonts. It includes components for pre-rendering text for both in-world and UI contexts, as well as systems to update and render the text when changes occur.

Structs

ImageFont

An image font as well as the mapping of characters to regions inside it.

ImageFontCharacter

Represents a character in an ImageFont, storing metadata required for rendering.

ImageFontPlugin

A Bevy plugin for rendering image-based fonts.

ImageFontSet

A system set containing all systems related to the ImageFontPlugin.

ImageFontText

Text rendered using an ImageFont.

Enums

ImageFontScalingMode

Determines how scaling is applied when calculating the dimensions of a character glyph. Scaling primarily affects width adjustments, while height remains proportional to the original glyph aspect ratio.

LetterSpacing

Specifies the spacing between characters in text rendering.

Functions

sync_texts_with_font_changes

Marks any text where the underlying ImageFont asset has changed as changed, which will cause it to be re-rendered.