Text in 2D
Place text in a 2D scene with Text2d: fonts and sizes, colour, spans, justification, wrapping in a box, anchors and shadows.
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#
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#
| Component | What it does |
|---|---|
Text2d | The text. It derefs to a String, so **text = "new".into() changes it. |
TextFont | The font, font_size, weight, width, style and font_smoothing. |
TextColor | The colour. |
TextLayout | justify (Justify::Left, Center, Right, Justified, Start, End) and linebreak. |
TextBounds | The box text wraps inside. Unbounded by default. |
Anchor | Which point of the text block sits at the transform's position. The default is the centre. |
TextBackgroundColor | A colour behind the glyphs. |
Text2dShadow | A drop shadow: offset and color. |
Underline, Strikethrough | Decorations. |
Change text at runtime#
Query the component and assign to it:
#[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:
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:
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),
)],
));LineBreak | Wraps |
|---|---|
WordBoundary | Between words (the default). |
AnyCharacter | Anywhere, even mid-word. |
WordOrCharacter | Between words, falling back to mid-word for words that don't fit. |
NoWrap | Never; 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#
| Example | What it shows |
|---|---|
text2d | Moving, rotating and scaling text, wrapping, anchors, shadows and font smoothing. |
text | UI text, for comparison. |
Run it from the engine core's workspace: cargo run --example text2d.