Text drawing belongs to the renderer. game.renderer.drawText() paints a string with the built-in font, or with a Font that you load through game.assets or scene.assets. A Font is one loaded font file. Import it from @bornengine/engine, or from @bornengine/engine/text.
Default font
The default font is built into the engine, so you do not load anything to use it.
import { Colors, Game } from '@bornengine/engine';
class ScoreScreen extends Game {
private score = 120;
constructor() {
super({ window: { title: 'Score', width: 640, height: 360 } });
}
protected override render(): void {
this.renderer.clear(Colors.BLACK);
this.renderer.drawText(`Score: ${this.score}`, { x: 24, y: 24 }, 24, Colors.WHITE);
}
}
new ScoreScreen().run();The full signature is drawText(text, position, size, color, font?, spacing = 0).
positionis the top-left corner of the text. It uses the same coordinates as shapes: pixels from the top-left of the window, or world units inside a 2D camera pass.sizeis the font size in pixels. You can pass a different size on every call.fontis optional. Leave it out to use the default font.spacingadds extra pixels between letters. It only applies when you pass a customfont; the default font ignores it.- The method returns
trueafter it draws. It returnsfalsewhen theGameis not ready, or when thefontyou pass is not usable.
Custom fonts
Load a font file with assets.loadFont(path, size). The result is a Font, or null when the path is empty, the size is not a positive number, or the asset scope is already disposed. A font file that cannot be read still gives you a Font, with isLoaded set to false and a message in error.
import { Colors, Game } from '@bornengine/engine';
import type { Font } from '@bornengine/engine';
class TitleScreen extends Game {
private heading: Font | null = null;
constructor() {
super({ window: { title: 'Title', width: 640, height: 360 } });
}
protected override onStart(): void {
const font = this.assets.loadFont('assets/fonts/heading.ttf', 48);
if (font === null || !font.isLoaded) {
console.error(font?.error ?? 'Could not load the heading font.');
return;
}
this.heading = font;
}
protected override render(): void {
this.renderer.clear(Colors.DARKBLUE);
const font = this.heading ?? undefined;
this.renderer.drawText('My Game', { x: 40, y: 40 }, 48, Colors.WHITE, font);
}
}
new TitleScreen().run();If the font failed to load, font is undefined and the text falls back to the default font.
Things to know about custom fonts:
game.assetskeeps a font until theGameshuts down.scene.assetsreleases it when the scene unloads, so usescene.assets.loadFont(...)for a font that only one level needs. Assets explains the ownership rules.- The cache key is the path plus the size. Calling
loadFontagain with the same arguments returns the sameFont, and a different size creates a secondFont. A failed load stays in the cache, so callassets.release(font)before you retry. - The
sizeyou pass toloadFontis stored asfont.size. It is the default size forfont.measureText(). EachdrawTextcall still takes its own size. - A
Fontonly works with theGamethat loaded it. - The engine reads TrueType (
.ttf) and OpenType (.otf) fonts. Keep font files with your other assets, as described in Assets.
Measurement
Measure text before you draw it when you need to center it or fit it into a box. Use the same size, font, and spacing for measuring and for drawing.
import { Colors, Game } from '@bornengine/engine';
import type { Font } from '@bornengine/engine';
const WINDOW_WIDTH = 640;
const TITLE = 'Settings';
class SettingsScreen extends Game {
private heading: Font | null = null;
constructor() {
super({ window: { title: 'Settings', width: WINDOW_WIDTH, height: 360 } });
}
protected override onStart(): void {
this.heading = this.assets.loadFont('assets/fonts/heading.ttf', 32);
}
protected override render(): void {
this.renderer.clear(Colors.BLACK);
const font = this.heading !== null && this.heading.isLoaded ? this.heading : undefined;
const width = this.renderer.measureText(TITLE, 32, font);
const position = { x: (WINDOW_WIDTH - width) / 2, y: 40 };
this.renderer.drawText(TITLE, position, 32, Colors.WHITE, font);
if (font !== undefined) {
const bounds = font.measureText(TITLE, 32);
const box = { x: position.x, y: position.y, width: bounds.x, height: bounds.y };
this.renderer.drawRectangleOutline(box, Colors.GRAY);
}
}
}
new SettingsScreen().run();There are two ways to measure:
renderer.measureText(text, size, font?, spacing = 0)returns the width in pixels as a number. It returns0when the renderer is not ready or thefontis not usable. The default font ignoresspacing, as it does when drawing.font.measureText(text, size = font.size, spacing = 0)returns aVector2D. Itsxis the width. Itsyis thesizeyou asked for, not the exact height of the letters, so treat it as a line height.
Next steps
- Shapes draws the boxes and panels that text usually sits on.
- Assets explains how
game.assetsandscene.assetscache and release fonts. - GUI controls provides ready-made text, button, and menu controls.
- Audio and UI builds a heads-up display.