Crate raster_font 

Raster Font is a declarative format for authoring and using image-backed fonts.

Design

General-purpose text engines are designed to solve many problems at once: shaping, font fallback, layout, rasterization, editing, and platform integration across many scripts and font formats. In game development, working with vector fonts can be burdensome. If all you want is an authored set of glyphs, explicit ligatures, and pixel-perfect rendering, adopting standard font formats and text engines can be a tall order. You may find yourself fighting the shaping model of a text engine, or trying to shoehorn your assets into a format that prioritizes other use cases.

Raster Font takes a narrower approach. Instead of deriving glyphs from codepoints through a runtime text pipeline, glyph resolution is baked into the font itself. A font declares the exact input sequences it accepts and the glyph each sequence resolves to. Input patterns are precompiled into efficient matching structures that can be used in a variety of game engines and rendering systems.

raster_font is not a general-purpose text engine, and it does not attempt to provide the shaping and script support of a full typography stack. It is designed for fonts whose glyph set, ligatures, spacing, and visual behavior are authored explicitly ahead of time. In return, “raster fonts” stay simple to define, predictable to resolve, and easy to render with crisp scaling and exact control over glyph mapping.

Authoring

The Raster Font format supports multi-character sequences, unions of sequences bound to shared glyphs, per-glyph overrides, and manual glyph extraction.

Creating a pixel-perfect font is a simple as opening your favorite image editor, drawing some glyphs, and writing a simple TOML file to describe your font’s layout and behavior.

See the meta documentation details on the font format and authoring process.

Resolution

A RasterFont maps input text to valid glyphs using the InputResolver API. valid produces an iterator of leftmost-longest matches, silently skipping unmatched input.

use raster_font::{backend::prelude::*, tree::InputResolver};

fn resolve<B: Backend<Resources: SpriteSheet>>(font: &RasterFont<B>) {
    let glyphs = font.valid("Hello -> world :)").collect::<Vec<_>>();
    // use glyphs...
}

---

First-party backends

The following crates have a stable/familiar release cycle and are considered reasonable for raster_font to maintain first-party backends for:

Backend	Feature	Description
Bevy game engine	bevy	Enables integration with Bevy’s asset system by providing Asset implementations for RasterFont and the RasterFontAssetLoaderPlugin.

Example backends

The following examples are available in the crate repository.

Example	Description
bevy_asset	Demonstrates using the first-party bevy backend to load raster fonts as assets.
macroquad	Demonstrates implementing a custom backend for Macroquad and loading a font using the builder API.

Open an issue if you’d like to see an integration example for a specific engine or framework.

---

Bevy integration

Enable the bevy feature to use the built-in Bevy backend.

use bevy::prelude::*;
use raster_font::prelude::*;

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

fn load_font(asset_server: Res<AssetServer>, mut commands: Commands) {
    let font: Handle<RasterFont> =
        asset_server.load("font.toml");
     
    commands.insert_resource(MyFont(font));
}

fn render_text(
    mut commands: Commands,
    font: Res<MyFont>,
    layouts: Res<Assets<TextureAtlasLayout>>,
) {
    let Some(font) = font_assets.get(font) else {
        warn!("Font {font:?} not loaded yet");
        return;
    };
    for glyph in font
        .upgrade(&*texture_atlas_layout_assets)
        .expect("Texture atlas must be loaded if font is loaded")
        .valid("Hello, Bevy world!")
        .map(Option::unwrap)
    {
        // Draw glyph using region and offset data...
    }
}

---

Common modules

• Use prelude for common types and traits for consuming fonts.
• Use backend if implementing your own integration.
• Use core for core types like Sequence, Token, and AtlasIndex.

Feature flags

Feature	Description
bevy	Enables Bevy asset loading and integration
font_sequence_map	Enables direct sequence lookup via RasterFont::get

Modules

backend

Backend-agnostic abstractions for raster font data.

builder

Builder pattern for constructing a RasterFont in multiple stages.

collections

Provides HashMap and HashSet type aliases that switch between std and bevy collections based on feature flags.

core

layout

Parsable representation of ordered glyph tokens for raster font atlases.

meta

Serialization types for the raster font asset format.

prelude

Common imports for using Raster Font.

token

Primitive token and sequence types for defining raster fonts.

tree

Efficient multi-character sequence resolution via Aho-Corasick matching.