NEOLearn

Text in 2D

Place text in a 2D scene with Text2d: fonts and sizes, colour, spans, justification, wrapping in a box, anchors and shadows.

Updated October 20, 2026

On this page

Text2d draws text in the world: damage numbers, name tags, signs, labels that move with a sprite. It sits at its entity's Transform, so it moves, rotates, scales and sorts by Z like a sprite.

For text that belongs to the interface, such as menus, scores and dialogue boxes, use UI Text instead. Both share the same font and style components; see UI text.

Show some text#

src/main.rs
use neo::prelude::*;

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    commands.spawn((
        Text2d::new("Level 1"),
        TextFont {
            font: asset_server.load("fonts/FiraSans-Bold.ttf").into(),
            font_size: FontSize::Px(50.0),
            ..default()
        },
        TextColor(Color::WHITE),
        TextLayout::justify(Justify::Center),
        Transform::from_xyz(0.0, 200.0, 1.0),
    ));
}

Without a TextFont, text uses the built-in default font, which only has ASCII characters. Load a .ttf or .otf font for anything else. NEO's builds can also use fonts installed on the device by family name; see Fonts.

Components#

ComponentWhat it does
Text2dThe text. It derefs to a String, so **text = "new".into() changes it.
TextFontThe font, font_size, weight, width, style and font_smoothing.
TextColorThe colour.
TextLayoutjustify (Justify::Left, Center, Right, Justified, Start, End) and linebreak.
TextBoundsThe box text wraps inside. Unbounded by default.
AnchorWhich point of the text block sits at the transform's position. The default is the centre.
TextBackgroundColorA colour behind the glyphs.
Text2dShadowA drop shadow: offset and color.
Underline, StrikethroughDecorations.

Change text at runtime#

Query the component and assign to it:

Rust
#[derive(Component)]
struct ScoreLabel;

fn update_label(score: Res<Score>, mut labels: Query<&mut Text2d, With<ScoreLabel>>) {
    for mut text in &mut labels {
        **text = format!("Score: {}", score.0);
    }
}

Every distinct font size makes the engine rasterise the glyphs again, so to animate the size of text, change its Transform scale rather than font_size.

Spans#

A text entity can have TextSpan children, each with its own font and colour. They're laid out as one block, after the parent's own text:

Rust
commands.spawn(Text2d::new("Health: ")).with_children(|parent| {
    parent.spawn((TextSpan::new("100"), TextColor(Color::srgb(0.2, 0.9, 0.3))));
});

To edit spans by position, use the Text2dWriter system parameter: *writer.text(entity, 1) = "75".into() changes the first span.

Wrap text in a box#

Give the text a TextBounds and a line-break rule:

Rust
let size = Vec2::new(300.0, 200.0);
commands.spawn((
    Sprite::from_color(Color::srgb(0.25, 0.25, 0.55), size),
    children![(
        Text2d::new("This text wraps inside the box."),
        TextLayout::new(Justify::Left, LineBreak::WordBoundary),
        TextBounds::from(size),
        // draw on top of the box
        Transform::from_translation(Vec3::Z),
    )],
));
LineBreakWraps
WordBoundaryBetween words (the default).
AnyCharacterAnywhere, even mid-word.
WordOrCharacterBetween words, falling back to mid-word for words that don't fit.
NoWrapNever; only at explicit \n.

Crisp pixel fonts#

For bitmap-style fonts, turn off antialiasing: TextFont { font_smoothing: FontSmoothing::None, .. } (import FontSmoothing from neo::text). Also render the scene at the pixel art's resolution; see Pixel-perfect rendering.

Examples#

ExampleWhat it shows
text2dMoving, rotating and scaling text, wrapping, anchors, shadows and font smoothing.
textUI text, for comparison.

Run it from the engine core's workspace: cargo run --example text2d.

Next steps#