Skill: Add text

Written for blit386 1.8.0. The rest of blit386.dev documents the newest engine, so an API you find there may be missing from a game pinned to 1.8.0.

Show text with the built-in font (no setup), or load a custom bitmap font.

When to use

Use for scores, labels, titles, dialog, or any on-screen words.

Built-in font (no file needed)

The order is position, color slot, text:

render() {
    BT.systemPrint(new Vector2i(8, 8), 4, `Score: ${this.score}`);
}

Center or right-align by measuring first:

const size = BT.systemPrintMeasure('Game Over'); // a Vector2i (width, height)
const x = Math.floor((BT.displaySize.x - size.x) / 2);
BT.systemPrint(new Vector2i(x, 100), 4, 'Game Over');

Custom bitmap font

Load a .btfont file in init() (async), then draw with printFont:

async init() {
    this.font = await BitmapFont.load('/fonts/pixel.btfont');
    return true;
}
render() {
    BT.printFont(this.font, new Vector2i(8, 8), 'HELLO');
}

Missing characters (engine 1.5.0+)

The built-in font covers plain ASCII plus dashes, arrows, media icons, uppercase Greek, and a few symbols. Any character it does not have draws as a fallback glyph, so you see a marker instead of the character quietly disappearing.

A custom .btfont only gets that safety net if it defines its own glyph keyed by U+FFFD (the Unicode replacement character). Without one, a missing character is skipped and the pen does not move - so the next character draws on top of the one before it, and the whole line looks scrambled rather than merely incomplete.

if (!this.font.hasGlyph('é')) {
  // This character has no glyph of its own in the font.
}

hasGlyph() answers whether a character has its own glyph, not whether the fallback would cover it. That is deliberate - use it to check what a font really contains.

You can ask the same question of the built-in font through BT.systemFont (a getter, engine 1.7.0+), which hands you the very font BT.systemPrint draws with:

BT.systemFont.hasGlyph('é'); // false - draws as the fallback marker
BT.systemFont.codePoints.length; // how many characters it covers in total

Read it after init() has started - it throws if the engine has not built the font yet. codePoints is a sorted array of Unicode code points, useful when you want to show the player which characters they can actually type.

Key calls

• BT.systemPrint(pos, slot, text) (method) - built-in 6x14 font.
• BT.systemPrintMeasure(text) (method) - returns a Vector2i size for centering.
• BitmapFont.load(url) (static, async) - load a .btfont file.
• BT.printFont(font, pos, text, paletteOffset?) (method) - draw with a loaded font; paletteOffset shifts the glyph colors.
• font.hasGlyph(char) (method) - true when the font has its own glyph for that character.
• BT.systemFont (getter, engine 1.7.0+) - the built-in font as a BitmapFont, so hasGlyph and codePoints work on it too. Pass it to BT.printFont to draw with the exact glyphs BT.systemPrint uses.
• font.codePoints (getter, engine 1.7.0+) - every Unicode code point the font covers, ascending.

Notes

• Positions are whole numbers (Vector2i).
• The color is a palette slot number (set up colors with the use-palette skill).
• await the font load - forgetting await is the most common beginner bug.

See docs/drawing.md.