Fonts and text in your game
The engine draws text from a font atlas: a .spritefont file holding a picture of every
letter the game can draw, at one size, made from a font installed on Windows. The starter has
one, JetBrains Mono Bold at 16 points, holding the 95 printable English letters, digits and
punctuation. This page makes two more from the same font: a 32-point one for a title, and a
16-point one that also has the letter é. Then it reads a line of text from a file of the
game’s own instead of writing it in the code. It takes about 20 minutes.
Before you start:
- Do Make a first change, and make a fresh copy of your game with its step 1 line.
- Install the content tools, which puts
MakeSpriteFont.exeinC:\dev\tools.
This page does not depend on Put a picture in your game or Animate a sprite sheet, and works whether or not you have done them. Every command runs in the x64 Native Tools Command Prompt, in your project’s folder:
cd /d C:\dev\mygameA bigger font for a title
Section titled “A bigger font for a title”-
Download the font. MakeSpriteFont reads a font installed on Windows, so the first job is to install JetBrains Mono, version 2.304, the version the starter’s atlas was made from. These lines download it, 5.4 MB, which
curlshows as5.36M, and take its Bold face out of the ZIP:Terminal window mkdir C:\dev\fontscurl -L --fail -o C:\dev\fonts\JetBrainsMono-2.304.zip https://github.com/JetBrains/JetBrainsMono/releases/download/v2.304/JetBrainsMono-2.304.ziptar -xf C:\dev\fonts\JetBrainsMono-2.304.zip -C C:\dev\fonts fonts/ttf/JetBrainsMono-Bold.ttfcurlshows its progress table and ends with a row starting100; it took a second here.tarprints nothing when it works, and leaves the font atC:\dev\fonts\fonts\ttf\JetBrainsMono-Bold.ttf. -
Install it. Open the folder it is in:
Terminal window explorer C:\dev\fonts\fonts\ttfIn the window that opens, right-click
JetBrainsMono-Bold.ttfand choose Install. Windows 11’s first, shorter menu may not list it; then choose Show more options, where the list has Install and Install for all users. Either works. To check that it worked, run the line for the one you chose in the prompt:Terminal window dir /b "%LOCALAPPDATA%\Microsoft\Windows\Fonts\JetBrains*"Terminal window dir /b C:\Windows\Fonts\JetBrains*The first is for Install, the second for Install for all users. The right one prints
JetBrainsMono-Bold.ttf;File Not Foundmeans the font is not installed that way yet. -
Make the 32-point atlas:
Terminal window C:\dev\tools\MakeSpriteFont.exe "JetBrains Mono" game\content\fonts\jetbrains_mono_bold_32.spritefont /FontSize:32 /FontStyle:BoldOutput Importing JetBrains MonoCaptured 95 glyphsCropping glyph bordersPacking glyphs into sprite sheetPacking efficiency 90.7144%Premultiplying alphaWriting game\content\fonts\jetbrains_mono_bold_32.spritefont (CompressedMono format)It took about a second.
"JetBrains Mono"is the font’s family name, not its file name and notJetBrains Mono Bold: the face is chosen by/FontStyle:Bold./FontSize:32is the size in points. One atlas holds one size; drawing an atlas bigger blurs or blocks its letters, so a new size needs a new atlas. The atlas goes in thefontsfolder, which the build already copies beside the game. -
Make a 16-point atlas with
éin it. The starter’s atlas has only English letters, and Text from a file below drawscafé. This makes one with the same letters as the starter’s plusé:Terminal window C:\dev\tools\MakeSpriteFont.exe "JetBrains Mono" game\content\fonts\menu_bold_16.spritefont /FontSize:16 /FontStyle:Bold /CharacterRegion:0x20-0x7e /CharacterRegion:0xe9Output Importing JetBrains MonoCaptured 96 glyphsCropping glyph bordersPacking glyphs into sprite sheetPacking efficiency 92.98238%Premultiplying alphaWriting game\content\fonts\menu_bold_16.spritefont (CompressedMono format)Captured 96 glyphsis the 95 English ones andé. Letters beyond English explains the two/CharacterRegionoptions. Nothing draws with this atlas until Text from a file. -
List both atlases in the manifest. Open it:
Terminal window notepad game\content\manifest.jsonPress Ctrl+A and paste the version below that matches the pages you have done in its place, then save and close Notepad. Each has the font group with the two new names, which are the files’ names without
.spritefont, and keeps the picture or sprite sheet from the other pages only if you have them. If you have done Play a sound in your game, none of these versions has itssound_bankgroup: after pasting, add the group back with that page’s second manifest tab, or the game stops withSoundBank 'tones' was never loaded.game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16","jetbrains_mono_bold_32","menu_bold_16"]}]}game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16","jetbrains_mono_bold_32","menu_bold_16"]},{"kind": "texture","directory": "./textures/","names": ["hero"]}]}game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16","jetbrains_mono_bold_32","menu_bold_16"]},{"kind": "texture","directory": "./textures/","names": ["hero"]},{"kind": "sprite_sheet","directory": "./textures/","names": ["lamp"]}]}game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16","jetbrains_mono_bold_32","menu_bold_16"]},{"kind": "sprite_sheet","directory": "./textures/","names": ["lamp"]}]} -
Draw a title with the 32-point atlas. Open the state’s code:
Terminal window notepad game\states\hello_state.cppSearch for
this->hint_ = this->scene_->add(, the line ininit()that adds the controls hint:samples/minimal/states/hello_state.cpp Click at the start of that line and paste these lines above it, with an empty line after them:
A
Labelis a line of text in the scene, the same kind as the greeting. Its arguments are the text, with theLbefore the quotation marks that every text in the engine needs, the atlas’s name from the manifest, where the top-left of the text goes, the table of loaded content, and the colour. Save and close Notepad. -
Build, test and run. Quit the game if it is open, then:
Terminal window cmake --build --preset x64-debug && ctest --preset x64-debug && out\build\x64-debug\game\MyGame.exeThe tests end with
100% tests passed, 0 tests failed out of 2, and the game opens withMy gamein large gold letters in its top-left corner.
Letters beyond English
Section titled “Letters beyond English”An atlas holds only the letters it was made with, and the starter’s holds U+0020 to U+007E:
the space, A to Z, a to z, the digits and the punctuation on an English keyboard. Any
other letter, such as é, draws as ?. To draw one, make an atlas that includes it, with
/CharacterRegion, as step 4 does. Each region is a range of Unicode numbers, written in
hexadecimal with 0x in front: 0x20-0x7e is the English range, and 0xe9 is the one number
for é. Windows’ Character Map (charmap) shows a letter’s number as U+00E9 when you click
it.
Give MakeSpriteFont every region the atlas needs, the English one included, because a command
with /CharacterRegion holds only the regions it names: /CharacterRegion:0xe9 alone captures
one glyph, and text drawn with that atlas stops the game with This font has no glyph for U+0057 and no stand-in to draw instead., because it has not even a ? to draw in place of a
W. The font must have the letters too. MakeSpriteFont does not say when it lacks one: it
stores the font’s shape for a missing letter, a box, in that letter’s place, and the game then
draws the box. Look at the letters on screen after drawing with a new atlas.
What the text path can draw at all, whatever the atlas holds, is in Which languages the text path can draw.
Text from a file
Section titled “Text from a file”Text written in the code needs a rebuild to change, and an é in C++ source is easy to get
wrong. A game can keep its text in a JSON file of its own instead, and read it when it starts.
This puts one line of text in a file and draws it with the menu_bold_16 atlas from
step 4 above, so do those steps first.
-
Make the file:
Terminal window mkdir game\content\stringsif not exist game\content\strings\en.json type nul > game\content\strings\en.jsonnotepad game\content\strings\en.jsonPaste this into the empty file:
game\content\strings\en.json {"title": "Welcome to the café"}Save and close Notepad. Notepad saves as UTF-8, which is what the game reads, unless Encoding in its Save as box is changed; UTF-8 with BOM works as well. Saved as ANSI, the
édraws as?. The file names one piece of text,title; a game adds more lines of the same form, with a comma after each but the last. -
Copy the strings folder beside the game. The game reads the file from the folder its
.exeis in, and the build copies only the folders it is told to. Open the build file:Terminal window notepad game\CMakeLists.txtSearch for
content/fonts"(with the quotation mark). You are in the block that copies the fonts. Click at the end of its last line,), press Enter, and paste this block below it:add_custom_command(TARGET game_content POST_BUILDCOMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different"${CMAKE_CURRENT_SOURCE_DIR}/content/strings""$<TARGET_FILE_DIR:MyGame>/strings"VERBATIM)Then search for
install(DIRECTORY content/fontsand add a line after it, so the two read:install(DIRECTORY content/fonts DESTINATION .)install(DIRECTORY content/strings DESTINATION .)That puts the file in a Windows release too. Save and close Notepad.
-
Read the file and draw its text. Open the state’s code:
Terminal window notepad game\states\hello_state.cppSearch for
engine/core/state_context.hand add two lines above it, so the three read:#include "engine/app/content_root.h"#include "engine/assets/json.h"#include "engine/core/state_context.h"Search for
engine/math/vector2f.hand add a line after it, so the two read:#include "engine/math/vector2f.h"#include "engine/render/text_encoding.h"If other
#includelines are already between them from another page, leave them; the order does not matter. Then search forthis->hint_ = this->scene_->add(again, click at the start of that line, and paste these lines above it, with an empty line after them:const std::string strings_path =The first line works out where the file is: in the
stringsfolder beside the game’s.exe, wherever the game was started from. The second reads the whole file. The last adds aLabelwhose text is the file’stitle. JSON text is UTF-8, and the engine draws wide text, sowidenconverts it. Save and close Notepad. -
Build, test and run:
Terminal window cmake --build --preset x64-debug && ctest --preset x64-debug && out\build\x64-debug\game\MyGame.exeThe build first runs CMake again, because
game\CMakeLists.txtchanged: it prints[0/1] Re-running CMake...and about 30 lines from vcpkg and CMake, including a list of packages, which are expected. The game opens withWelcome to the caféunder the title, with itsé. To change the text now, editen.json, save it and run the same line: the build copies the new file, and no C++ is compiled again.
A different font
Section titled “A different font”Any font installed on Windows can be made into an atlas. This changes the font of all the starter’s own text, the greeting, the hint and the quit question, to another one. The example uses Courier Prime, a free font under the SIL Open Font License; use the font you want.
-
Install the font as in step 2 above, from its
.ttffile. **Settings > PersonalizationFonts** lists the installed fonts by family name, the name the next step needs.
-
Make a 16-point atlas from it:
Terminal window C:\dev\tools\MakeSpriteFont.exe "Courier Prime" game\content\fonts\courier_prime_bold_16.spritefont /FontSize:16 /FontStyle:BoldIt prints the same kind of lines as step 3 above, ending with
Writingand the file’s name./FontStyle:Boldtakes the font’s bold face, which must be installed; leave it out for the regular face. Keep to 16 points for the starter’s text: at 32 the hint along the bottom is wider than the window. -
List it in the manifest. Open
game\content\manifest.jsonwith Notepad, and add the new name to the font group’snameslist, after the last name there, with a comma after the name before it:"names": ["jetbrains_mono_bold_16","jetbrains_mono_bold_32","menu_bold_16","courier_prime_bold_16"]Keep the starter’s own
jetbrains_mono_bold_16in the list unless you also take it out of every line of code that names it. Save and close Notepad. -
Use it for the starter’s text. Two files name the starter’s font, once each:
Terminal window notepad game\states\hello_state.cppSearch for
const std::string font_name. The line reads:const std::string font_name = "jetbrains_mono_bold_16";Change the name between the quotation marks, so that it reads:
const std::string font_name = "courier_prime_bold_16";Save and close Notepad, then make the same change in the quit question’s file:
Terminal window notepad game\states\confirm_state.cpp -
Build, test and run with the line from step 7 above. The greeting, the hint and, after Escape, the quit question are in the new font. The title and the café line keep the atlases their own lines name.
Read a font’s licence before you give a game with an atlas made from it to anyone else: the
atlas is a copy of the font’s letters. JetBrains Mono is under the SIL Open Font License 1.1,
which allows this, provided its licence travels with the atlas. That is why the starter’s
fonts folder has OFL.txt beside its atlas, and the atlases this page makes from the same
font are covered by it. A font that came with Windows is licensed to you as part of Windows;
check its terms before shipping an atlas made from it.
If something fails
Section titled “If something fails”The ways the build, the start-up test and the game report a problem are in Put a picture in your game, and its manifest messages apply here too.
A letter draws as ?. The atlas the text uses does not have that letter. Check which atlas
name the code passes, and make that atlas with a /CharacterRegion covering the letter. If the
letter comes from a file, the file may not be UTF-8: save it again with UTF-8 chosen as the
Encoding.
In the browser build
Section titled “In the browser build”Add each new file to the LINK_DEPENDS list near the top of game\CMakeLists.txt, after the
line ending
jetbrains_mono_bold_16.spritefont", so the page links again when one changes:
"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/jetbrains_mono_bold_16.spritefont" "${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/jetbrains_mono_bold_32.spritefont" "${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/menu_bold_16.spritefont" "${CMAKE_CURRENT_SOURCE_DIR}/content/strings/en.json"In the browser, the folder beside the game is the page’s own packed files, so the code above
finds strings/en.json there without a change.
What was checked
Section titled “What was checked”On 2026-10-30, on Windows 11 with the may2026 MakeSpriteFont, before JetBrains Mono was
installed, step 3’s command gave Can't find font 'JetBrains Mono'. The 2.304 ZIP and its Bold
file matched the checksums the
minimal sample’s README records. The font was then installed for the user only, as Install does, and the 16-point
command remade the starter’s atlas byte for byte, which shows the install and command are the
ones the starter’s atlas came from. A font installed for the user only, Courier Prime, also
worked. The commands above wrote the atlases shown. A region for U+4E00, which JetBrains Mono
does not have, still reported the glyph captured, and the atlas held the font’s missing-letter
box in its place. In the starter project from
Put a picture in your game the game drew the gold
title and Welcome to the café with its é. The é drew as ? with the 16-point starter atlas
and with the file saved as ANSI; a file saved with a byte-order mark worked. Each message under
If something fails was made on purpose, and the wasm-debug page loaded in
Chrome with the strings file. An agent then ran this page again in a fresh starter with neither
picture page done, making each edit as worded, and its output and captures matched; it remade
the starter’s own atlas from step 3’s command at 16 points byte for byte. The section on a
different font ran with Courier Prime, installed for the user only, and the greeting and hint
drew in it, and an x64-release build installed with cmake --install had the
three atlases and strings\en.json in its folder and drew the title. Explorer’s right-click menu was not driven: its Install and
Install for all users entries were read from Windows’ list of the file’s commands. The note in step 5 about Play a
sound in your game was checked in that page’s run: a manifest without the sound group, with that page’s
sound code in place, stopped the game with SoundBank 'tones' was never loaded., and that
page’s second manifest tab put the group back.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.