Add a screen to your game
A game is made of screens: a title screen, the game itself, a pause menu, a “Really quit?” box.
On this engine each screen is a state, a class of your own that the engine keeps on a stack,
and the starter has two: HelloState, the circling greeting, and ConfirmState, the quit
question. This page adds a third, a title screen that shows the game’s name and waits for
Enter. It goes through every file that changes: the two new files for the state, the build
file that lists them, and the two files that choose the first state, one for Windows and one for
the browser. It takes about 15 minutes.
Before you start, do Make a first change, so that you know the edit, build and run loop and have a copy of your game to go back to. Make a fresh copy now with that page’s step 1 line. This page does not depend on the picture, animation or font pages, 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\mygame-
Make the state’s header. A class in C++ is usually two files: a header, ending
.h, that says what the class has, and a.cppfile with the code. First make the empty header, then open it:Terminal window if not exist game\states\title_state.h type nul > game\states\title_state.hnotepad game\states\title_state.hThe first line makes an empty file and prints nothing; it leaves the file alone if it is already there. Notepad opens the empty file. Paste all of this into it, then save and close Notepad:
game\states\title_state.h #pragma once#include "engine/app/application.h"#include "engine/core/state.h"#include "engine/scene/scene.h"#include <memory>// The title screen: the game's name, and how to start. Enter or A starts the// game by replacing this screen with HelloState; Escape or B quits.{public:void init() override;void update(float dt) override;private:labrador::Application* app_ = nullptr;// What is on screen: the title and the line under it.};class TitleState : public labrador::Statesays that aTitleStateis one of the engine’s states. The three functions afterpublic:are the ones every state has, and the engine calls them:initonce, when the screen starts, thenupdateanddrawon every frame. They must be spelt exactly as here, includingconstat the end ofdraw;overrideasks the compiler to check that they are. Underprivate:are the two things the state keeps: the application, which gives it the keyboard, the pads and the fonts, and a scene, which holds what it draws. -
Make the state’s code. Make the second file and open it:
Terminal window if not exist game\states\title_state.cpp type nul > game\states\title_state.cppnotepad game\states\title_state.cppPaste all of this into it, then save and close Notepad:
game\states\title_state.cpp #include "game/states/title_state.h"#include "engine/core/state_context.h"#include "engine/input/keyboard.h"#include "engine/math/rectanglef.h"#include "engine/math/vector2f.h"#include "engine/render/label.h"#include "game/states/hello_state.h"#include <memory>#include <string>using namespace labrador;namespace{// The fonts, as content/manifest.json names them, and how many times// bigger than its font the title is drawn.const std::string font_name = "jetbrains_mono_bold_16";const std::string title_font_name = "jetbrains_mono_bold_16";constexpr float title_scale = 3.0f;// Moves a label across so that its middle is at the middle of the// window, and down to y.{label.set_position(}}{}void TitleState::init(){const Vector2F resolution =this->app_->resolution_manager()->resolution_vec();Label* title = this->scene_->add(std::make_unique<Label>(centre_across(*title, resolution.x, resolution.y * 0.5f - 100.0f);Label* prompt = this->scene_->add(std::make_unique<Label>(L"Press Enter or A to start. Escape or B quits.", font_name,Vector2F::zero, resources, labrador::Colour::white));centre_across(*prompt, resolution.x, resolution.y * 0.5f + 40.0f);this->scene_->end_tick();}void TitleState::update(float dt){// Every pad slot, as in HelloState: the only pad need not be in slot 0.bool quit_requested = keyboard.pressed(Key::escape);{quit_requested |= pads.pressed(slot, GamepadButton::b);}if (start_requested){// Replaces this screen with the game. The title is destroyed once// this update() has returned.this->context()->transition_to(std::make_unique<HelloState>(this->app_));return;}if (quit_requested){this->app_->quit();return;}this->scene_->update(dt);this->scene_->end_tick();}{this->scene_->draw(renderer);}What each part does:
- The
#includelines bring in what the code uses. The first is the state’s own header. Your game’s files are written from the project’s folder,game/states/..., with forward slashes; the engine’s startengine/. initmakes the scene and adds twoLabels, lines of text, to it: the title in goldenrod at three times the font’s size, and the line under it in white. Each starts atVector2F::zero, the window’s top-left corner, andcentre_acrossthen moves it so that its middle is at the middle of the window, 100 pixels above the window’s middle for the title and 40 below it for the line. The window is 1280 pixels wide and 720 high. The last two lines ofinitare the same as inHelloState: they make what was added visible and give the scene one view, the whole window.updatereads the keyboard and every pad.pressedis true only on the frame a key goes down, so holding Enter starts the game once. Enter or A callstransition_towith a newHelloState: the title screen is replaced by the starter’s greeting. Escape or B quits the game at once, without asking, because there is nothing on a title screen to lose.drawdraws the scene.
The text uses the font the starter already has, so no content changes. Drawn three times its size, its letters are blocky; A smoother title below swaps in a 32-point font. To change the title, change
My gamebetween the quotation marks, keeping theLbefore them; it stays centred. - The
-
List the new file in the build, twice. Every
.cppfile is listed by name ingame\CMakeLists.txt, and the game’s are listed twice: once for the browser build, inside the part that startsif(EMSCRIPTEN), and once for Windows, below it. A file missing from either list breaks that build only, with the errors under If something fails. The header does not need listing. Open the build file:Terminal window notepad game\CMakeLists.txtSearch with Ctrl+F for
states/hello_state.cpp. The first match is in the browser’s list:add_executable(MyGamemain_web.cppstates/confirm_state.cppstates/hello_state.cpp)Click at the end of the
states/hello_state.cppline and press Enter. Notepad does not indent the new line, so type spaces up to the start of the line above, eight of them in this list, thenstates/title_state.cpp, so that the list reads:add_executable(MyGamemain_web.cppstates/confirm_state.cppstates/hello_state.cppstates/title_state.cpp)Press F3 to find the next
states/hello_state.cpp, in the Windows list further down:add_executable(MyGame WIN32main.cppstates/confirm_state.cppstates/hello_state.cppdpi_aware.manifest)Add the same name after it in the same way, with four spaces in this list, so that it reads:
add_executable(MyGame WIN32main.cppstates/confirm_state.cppstates/hello_state.cppstates/title_state.cppdpi_aware.manifest)The spaces at the start of the lines do not matter to CMake; matching the lines around them keeps the file readable. Save and close Notepad.
-
Start the Windows game on the title.
game\main.cppchooses the first state:Terminal window notepad game\main.cppSearch for
game/states/hello_state.h. The line reads:#include "game/states/hello_state.h"Change
hellototitle, so that it reads:#include "game/states/title_state.h"Once the next change is made too,
main.cppno longer namesHelloState;title_state.cppdoes, and includes its header itself. Now search forfirst_state =. These are the lines that start the game:samples/minimal/main.cpp if (smoke_test){first_state = std::make_unique<SmokeTest>(&app, std::move(first_state));}return app.run(std::move(first_state));samples/minimal/main.cpp, lines 138–143 at
0f4f503In the first of them, change
HelloStatetoTitleState, so that it reads:Leave the lines after it as they are. They are the start-up test: when the game is started with
--smoke-test, asctestdoes,SmokeTestwraps whichever state comes first, runs it in a hidden window for 30 frames and quits. The start-up test now checks the title screen; What the start-up test checks now says what that leaves out. Save and close Notepad. -
Start the browser game on the title too. The browser build starts from its own file,
game\main_web.cpp, which needs the same two changes, or the page would still open on the greeting:Terminal window notepad game\main_web.cppSearch for
game/states/hello_state.hand changehellototitleas before, so that it reads:#include "game/states/title_state.h"Then search for
make_unique<HelloState>. The line reads:samples/minimal/main_web.cpp return app.run(std::make_unique<HelloState>(&app));samples/minimal/main_web.cpp, line 55 at
0f4f503Change
HelloStatetoTitleState, so that it reads:return app.run(std::make_unique<TitleState>(&app));Save and close Notepad. The Windows build never compiles this file, so a slip here shows only when you build for the browser.
-
Build, test and run. Quit the game if it is open, then run the line from Make a first change’s step 5:
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. That prints[0/1] Re-running CMake...and about 30 lines from vcpkg and CMake, including a list of packages and lines such asfind_package(doctest CONFIG REQUIRED); they are expected, not errors. Then it compilestitle_state.cppandmain.cpp. On a fast desktop the whole line took between 9 and 17 seconds. It ends like this:Output -- Build files have been written to: C:/dev/mygame/out/build/x64-debug[1/6] Running utility command for game_content[2/6] Checking that no engine file includes a game header[3/6] Building CXX object game\CMakeFiles\MyGame.dir\states\title_state.cpp.obj[4/6] Building CXX object game\CMakeFiles\MyGame.dir\main.cpp.obj[5/6] Linking CXX executable game\MyGame.exeTest project C:/dev/mygame/out/build/x64-debugStart 1: MyGameTests1/2 Test #1: MyGameTests ...................... Passed 0.03 secStart 2: MyGameSmokeTests2/2 Test #2: MyGameSmokeTests ................. Passed 0.73 sec100% tests passed, 0 tests failed out of 2Then the game opens on the title:
My gamein large gold letters in the middle of the window, andPress Enter or A to start. Escape or B quits.under it. Click the window, so that the keys go to the game, and press Enter: the title is replaced by the circling greeting, which works as before. Escape there still asksReally quit?, and Enter says yes. Started again, Escape on the title quits at once.
Push or transition
Section titled “Push or transition”transition_to replaces the screen on top of the stack with a new one, and the old one is
destroyed: that is how the title gives way to the game. push puts a new screen on top and keeps
the one underneath, paused, until the new one closes with pop: that is how HelloState asks
its quit question and carries on afterwards. States and the stack
explains both, and how a pushed screen hands back an answer.
Going back to the title
Section titled “Going back to the title”As it stands, saying yes to the quit question closes the game. It can go back to the title
instead, with three changes in HelloState. Open its code:
notepad game\states\hello_state.cppSearch for game/states/confirm_state.h and add a line after it, so the two read:
#include "game/states/confirm_state.h"#include "game/states/title_state.h"Then search for Really quit?. You are in the part of update that asks the question:
this->context()->push<bool>( std::make_unique<ConfirmState>(this->app_, L"Really quit?"), [this](const bool& quit) { if (quit) { this->app_->quit(); } });return;samples/minimal/states/hello_state.cpp, lines 137–146 at 0f4f503
Change the question’s text, Really quit?, to Back to the title?, and the line
this->app_->quit(); to the two lines below, so that the part reads:
this->context()->push<bool>( std::make_unique<ConfirmState>(this->app_, L"Back to the title?"), [this](const bool& quit) { if (quit) { this->context()->transition_to( std::make_unique<TitleState>(this->app_)); } }); return;The lines between [this] and } run once, when the question closes, and quit is true when
it was answered yes. They now replace the greeting with a new title screen, just as the title
replaced itself with the greeting. Save and close Notepad, then build, test and run with the line
from step 6. This time it compiles hello_state.cpp as well. Escape in the game now asks
Back to the title?; Enter goes back to the title, and Escape there quits. No build list
changes, because no file was added. The hint along the bottom of the greeting still says
B or Escape asks to quit; it is in the same file, under this->hint_, if you want to change
its words.
A smoother title
Section titled “A smoother title”If you have done Fonts and text in your game, your manifest has a
32-point atlas, jetbrains_mono_bold_32, made for titles. To use it, open
game\states\title_state.cpp, search for title_font_name =, and change two lines so that they
read:
const std::string title_font_name = "jetbrains_mono_bold_32"; constexpr float title_scale = 1.5f;The title is then the same size, 48 pixels high, with smoother letters, because it is drawn from
a bigger picture of each letter. A scale of 1.0f draws it at its own 32 pixels. Without that
atlas in the manifest, the start-up test fails with startup failure: Font 'jetbrains_mono_bold_32' was never loaded.
What the start-up test checks now
Section titled “What the start-up test checks now”The start-up test runs only the first state, and nobody presses Enter in it, so it now checks the
title screen and not the greeting. A mistake that stops HelloState from starting, such as a
misspelt font name in hello_state.cpp, still passes ctest. It shows when you press Enter, as
the box titled Sample - startup failure, here saying Font 'jetbrains_mono_bold_61' was never loaded., and the game closes when you click OK. In one check, the same Enter press closed
the box at once, so the game simply closed with no message. After a change to HelloState, play
past the title before you rely on it.
To run the start-up test by itself, as ctest does:
start /wait out\build\x64-debug\game\MyGame.exe --smoke-testecho %ERRORLEVEL%It shows no window and prints 0 when the title screen starts and draws.
How errors show
Section titled “How errors show”A mistake in this page’s files shows in one of three places:
- The compiler stops with an
errorline naming one of your files and a line number: a slip in the C++ code. Read a build error shows how to find the line that matters. - The linker stops, with an error starting
LNKon Windows orwasm-ldin the browser build. Every file compiled, but one was not in the build: almost always a.cppmissing from one of the two lists in step 3. A name in a list that matches no file stops the build earlier still, with aCMake Errorbefore anything compiles. - Only one of the two builds fails. The Windows build reads only
main.cppand the Windows list; the browser build reads onlymain_web.cppand the browser list. Clang, the browser’s compiler, also warns about some things the Windows compiler does not. Build both before you rely on either.
Each message is below. The line numbers are those of the files as this page gives them.
If something fails
Section titled “If something fails”In the browser build
Section titled “In the browser build”Build the page as Build for the browser shows, in a prompt where you have
run emsdk_env.bat:
cmake --build --preset wasm-debug && ctest --preset wasm-debugIf you have not configured that preset before, run cmake --preset wasm-debug first. It
compiles title_state.cpp with clang and links the page; a missing entry in the browser’s list
gives the wasm-ld error above. The page opens on the title, and the keys are the same. The
browser page’s check from that guide, with --quit-keys Escape,Enter, still passes: Escape now
quits on the title, and the page calls Module.onQuit.
The line under the game in the page, set in game\web\shell.html, still describes the greeting.
To change it, open that file, search for Escape asks to quit; Enter says yes., and change the
words between the quotation marks on that line, for example to:
"Enter starts. Arrows, WASD or the left stick move the text. Escape quits from the title, and asks first during play; Enter says yes.";If you made the change in Going back to the title, say so instead,
for example Escape goes back to the title, and quits there; Enter says yes.
Where to go next
Section titled “Where to go next”- States and the stack explains
push,popandtransition_to, typed answers, and what a covered screen is told. - Menus builds a menu with several rows, which is what a title screen with Start, Options and Quit needs.
- Input lists the keys and buttons, and the difference between
pressedandheld. - Read a build error has more on compiler and linker messages.
What was checked
Section titled “What was checked”On 2026-10-30, in a starter project made from a starter ZIP of this tree at C:\dev\h1\mygame,
with Visual Studio 2026’s compiler 19.51 and Emscripten 6.0.12, every step above was made as
worded, by an agent editing the files with tools rather than Notepad, and the build and tests ran as shown, with C:\dev\h1\mygame in the quoted output
changed to C:\dev\mygame. The game was started and driven with key presses, and screenshots
showed the title, the greeting after Enter, the quit question, and the game closing on Enter there
and on Escape at the title; the --smoke-test line printed 0. The section going back to the
title was made the same way, and the screenshots showed Back to the title? and the title again.
The 32-point title was drawn with an atlas made by the command in Fonts and text. A misspelt font
name in hello_state.cpp passed ctest and gave the Sample - startup failure box after Enter;
in another run the same Enter closed the box and the game exited with code 1. Each message under
If something fails was made on purpose, one at a time: the file left out of
each list, the include not changed in main.cpp and in main_web.cpp, the class name misspelt in
main.cpp and in title_state.cpp, const removed from the header and from the .cpp, const
and override removed together, override alone removed, and a misspelt header name; removing
override alone built on Windows and failed only in wasm-debug. The wasm-debug page was
loaded in headless Chrome by the page runner from Build for the browser, with
--quit-keys Escape,Enter and with Enter, Escape, Enter, and called Module.onQuit with no
errors; a screenshot showed the title and, after Enter and Escape, the quit question. With the
changes from Going back to the title, Enter, Escape, Enter, Escape reached the title again and
quit there.
A second agent then followed the page as worded in another fresh starter, at
C:\dev\h1v\mygame. Its build output matched step 6 line for line, the screenshots matched what
the page says is on screen, and every message above matched. It found what the first version of
the page left out, and the page was corrected: a misspelt name in a build list gives the
CMake Error ... Cannot find source file entry, not a link error; the C2259 case prints a
C2511 and a C2671 first, and the .cpp-only C3668 case has a C2671 after its C2511;
after Going back to the title, the extra LNK2001, C3668 and C2259 lines under
hello_state.cpp and the C2065 at hello_state.cpp(144); the spaces to type in step 3; and the
shell.html line after Going back. Those messages were made in its starter, and the misspelt
name was made again in each list in the first starter, with Windows reporting
game/CMakeLists.txt:65 and wasm-debug reporting line 36; each build recovered once the name
was corrected. A gamepad was not used: A and B were read from the code, which reads them as
HelloState and ConfirmState do. The OK button on the error box was not clicked; that the game then closes is read from
main.cpp, which shows the box and then returns.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.