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.[^cfg] :

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

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.

[^cfg]: 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.