Add a rule and a test
In the game from Get the starter project, the arrow keys can steer
the greeting off the edge of the window, and it is lost until you steer it back. This page adds a
rule that stops that: a small piece of the game’s own arithmetic, in a file of its own, that
works out where the greeting is allowed to be. Then it adds a test of that rule, a file of
checks that run without opening the game, and shows what a passing and a failing test look like.
It goes through every file that changes: two new files for the rule, one for its test, two lines
in the build file and two edits in HelloState. It takes about 20 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 Put a picture in your game, Animate a sprite sheet or Fonts and text in your game, 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\mygameWhere rules and tests live
Section titled “Where rules and tests live”The starter’s game folder keeps two kinds of code apart:
- The states, in
game\states, talk to the engine: they read the keyboard and the pads, make the text and draw it.HelloStateis one. - The rules, in
game\rules, decide things: where the greeting goes, how fast it moves. They are handed plain numbers and hand plain numbers back.motion.handmotion.cppare the starter’s rules.
The build makes the rules into a library of their own, MyGameRules, that can use the engine’s
maths, such as Vector2F and RectangleF, and nothing else of the engine. That is what lets
MyGameTests, the program in game\tests, run the rules with no window, no graphics and no
keyboard. Test your game explains the
idea in more depth.
Rules and tests are each listed once in game\CMakeLists.txt: a rule’s .cpp file in
add_library(MyGameRules, a test’s .cpp file in add_executable(MyGameTests. The game’s
states are different: each of their .cpp files is listed twice, once for the browser build and
once for Windows. This page adds no state, so it changes neither of those two lists.
-
Make the rule’s header. A header, a
.hfile, says what functions a file of code offers, so that other files can call them. First make the empty file, then open it:Terminal window if not exist game\rules\bounds.h type nul > game\rules\bounds.hnotepad game\rules\bounds.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\rules\bounds.h #pragma once#include "engine/math/rectanglef.h"#include "engine/math/vector2f.h"// Keeping the greeting inside the window. Like motion.h, these work only on// values the state hands them, so a test can check them with no window.// Where the greeting's centre may be, so that a greeting of greeting_size,// circling the centre orbit_radius away, stays inside a window of// window_size. (0, 0) is the window's top-left corner.const labrador::Vector2F& greeting_size);// The point moved the shortest way into the area. A point already inside is// returned as it is.labrador::Vector2F keep_inside(const labrador::Vector2F& point,const labrador::RectangleF& area);It names two functions.
centre_areaworks out a rectangle: the part of the window the point the greeting circles can be in without any of the text going over an edge.keep_insidetakes a point and a rectangle and moves the point into the rectangle if it is outside. Each line that ends in;after its brackets is a declaration: it says the function exists, what it takes and what it gives back, but not what it does. The next step writes that. -
Write the rule. Make the second file, the code, and open it:
Terminal window if not exist game\rules\bounds.cpp type nul > game\rules\bounds.cppnotepad game\rules\bounds.cppPaste all of this into the empty file, then save and close Notepad:
game\rules\bounds.cpp #include "game/rules/bounds.h"#include "engine/math/scalar.h"#include "game/rules/motion.h"using namespace labrador;const Vector2F& greeting_size){// The greeting's top-left corner swings up to orbit_radius from the// centre on every side, and the text reaches greeting_size beyond it.return RectangleF(orbit_radius, orbit_radius,window_size.x - greeting_size.x - 2.0f * orbit_radius,window_size.y - greeting_size.y - 2.0f * orbit_radius);}Vector2F keep_inside(const Vector2F& point, const RectangleF& area){clamp(point.y, area.top(), area.bottom()));}The greeting circles a point,
motion_.centre, 24 pixels away from it: that isorbit_radius, frommotion.h. Its top-left corner can therefore be up to 24 pixels left, right, above or below the centre, and the text goes on to the right and down from that corner.centre_areamakes aRectangleF, which takes its left edge, top edge, width and height in that order: it starts 24 pixels in from the window’s left and top, and stops early enough on the right and at the bottom to leave room for the text and the 24 pixels.keep_insideuses the engine’sclamp, fromengine/math/scalar.h, which gives back a number moved inside a range: below the range it gives the low end, above it the high end, and otherwise the number itself. Doing that toxand toymoves the point into the rectangle.Everything this file uses is either the engine’s maths or the starter’s other rule,
motion.h, which is what a rule may use. -
List the rule in the build. Open the build file:
Terminal window notepad game\CMakeLists.txtSearch with Ctrl+F for
rules/motion.cpp. It is near the top, in the list of the rules’ files:add_library(MyGameRules STATICrules/motion.cpp)Click at the end of
rules/motion.cpp, press Enter, and type the new file’s name, with the same four spaces in front, so that the three lines read:add_library(MyGameRules STATICrules/motion.cpprules/bounds.cpp)The name is written from the
gamefolder, with a forward slash. This is the only place a rule is listed: the game and the tests both use this library. Leave Notepad open for the next change. -
Make the test file. A test calls a rule with numbers you chose and checks that what comes back is what you expected. Make the file and open it:
Terminal window if not exist game\tests\bounds_tests.cpp type nul > game\tests\bounds_tests.cppnotepad game\tests\bounds_tests.cppPaste all of this into the empty file, then save and close Notepad:
game\tests\bounds_tests.cpp // The tests of game/rules/bounds.h. doctest's main is in motion_tests.cpp,// and a program has only one, so this file includes doctest without it.#include <doctest/doctest.h>#include "game/rules/bounds.h"#include "game/rules/motion.h"using namespace labrador;TEST_CASE("a point inside the area stays where it is"){CHECK(inside.x == doctest::Approx(60.0f));CHECK(inside.y == doctest::Approx(40.0f));}TEST_CASE("a point outside the area moves to its nearest edge"){const RectangleF area(10.0f, 20.0f, 100.0f, 50.0f);// Far off the left: x moves to the left edge, and y stays.const Vector2F left = keep_inside(Vector2F(-500.0f, 40.0f), area);CHECK(left.x == doctest::Approx(10.0f));CHECK(left.y == doctest::Approx(40.0f));// Past the bottom-right corner: both move, to the corner.const Vector2F corner = keep_inside(Vector2F(900.0f, 900.0f), area);CHECK(corner.x == doctest::Approx(110.0f));CHECK(corner.y == doctest::Approx(70.0f));}TEST_CASE("a greeting circling the centre's area stays in the window"){const Vector2F window_size(1280.0f, 720.0f);const Vector2F greeting_size(200.0f, 20.0f);const RectangleF area = centre_area(window_size, greeting_size);// From the area's top-left corner, the greeting swings out to the// window's top and left edges and no further.CHECK(area.left() - orbit_radius == doctest::Approx(0.0f));CHECK(area.top() - orbit_radius == doctest::Approx(0.0f));// From its bottom-right corner, the text's far edges reach the window's.CHECK(area.right() + orbit_radius + greeting_size.x ==doctest::Approx(window_size.x));CHECK(area.bottom() + orbit_radius + greeting_size.y ==doctest::Approx(window_size.y));}The tests use doctest, a test library the starter already has. Each
TEST_CASE("...")is one test, named by the sentence in its quotation marks, which is what doctest prints when it fails. EachCHECK(...)inside it is one check: if what is between its brackets is not true, the test fails, and doctest says which line and what the values were.doctest::Approx(60.0f)means “60, give or take a tiny rounding error”, which is how to comparefloatnumbers.The rectangle in the first two tests starts at
10, 20and is 100 wide and 50 high, so its right edge is at 110 and its bottom at 70; those are the numbers the corner is checked against. The third test checkscentre_areaagainst the window’s edges usingorbit_radiusby name, so changing that number inmotion.hlater does not break the test.The file does not start with
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN, thoughmotion_tests.cppdoes. That line makes doctest writemain, the function a program starts in, and a program can have only one.motion_tests.cppalready has it, so every other test file leaves it out; copying it in gives a page ofLNK2005errors, which If something fails shows. -
List the test file in the build. In
game\CMakeLists.txt, which is still open, search fortests/motion_tests.cpp. It is a little lower, in the list of the tests’ files:add_executable(MyGameTeststests/motion_tests.cpp)Click at the end of
tests/motion_tests.cpp, press Enter, and type the new name, so that the three lines read:add_executable(MyGameTeststests/motion_tests.cpptests/bounds_tests.cpp)This, too, is the only place a test file is listed. Save and close Notepad.
-
Use the rule in
HelloState. Open the state’s code:Terminal window notepad game\states\hello_state.cppSearch for
game/states/confirm_state.hand add a line above it, so the two read:#include "game/rules/bounds.h"#include "game/states/confirm_state.h"That lets this file call the two new functions. Then search for
keyboard_direction(keyboard), dt);. It is the end of the lines, inupdate(), that move the greeting’s centre on every step of the game:samples/minimal/states/hello_state.cpp this->motion_ = step_motion(this->motion_,stick_direction,keyboard_direction(keyboard), dt);samples/minimal/states/hello_state.cpp, lines 143–145 at
f525bc6Click at the end of
keyboard_direction(keyboard), dt);, after the;, press Enter twice, and paste these lines:// Keep the greeting inside the window, however far it is steered.this->app_->resolution_manager()->resolution_vec();this->motion_.centre = keep_inside(this->motion_.centre,centre_area(window_size, this->greeting_->bounds().size()));The first line asks the engine for the window’s size, 1280 by 720 in the starter.
this->greeting_->bounds()is the rectangle the greeting’s text covers on screen, and.size()is its width and height. The last two lines move the centre back inside the area the rule works out, so the greeting is drawn there. This is the split the starter keeps: the state asks the engine for the numbers and hands them to the rule. Save and close Notepad. -
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; they are expected, not errors. Then it compiles the three files you made or changed. On a fast desktop the whole line took 6 to 7 seconds before the game opened. After the lines from vcpkg and CMake, it ends like this:Output -- Build files have been written to: C:/dev/mygame/out/build/x64-debug[1/9] Running utility command for game_content[2/9] Checking that no engine file includes a game header[3/9] Building CXX object game\CMakeFiles\MyGameRules.dir\rules\bounds.cpp.obj[4/9] Building CXX object game\CMakeFiles\MyGameTests.dir\tests\bounds_tests.cpp.obj[5/9] Linking CXX static library game\MyGameRules.lib[6/9] Linking CXX executable game\MyGameTests.exe[7/9] Building CXX object game\CMakeFiles\MyGame.dir\states\hello_state.cpp.obj[8/9] 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.69 sec100% tests passed, 0 tests failed out of 2Total Test time (real) = 0.76 secThen the game opens. Hold an arrow key, or W, A, S or D: the greeting moves to that edge of the window and stops there, still circling, instead of going off it. At the bottom it stops over the controls line; Changing the rule below moves that edge up.
ctest still says
out of 2: it counts test programs, andMyGameTestsis still one program. The new tests run inside it. The next step shows them. -
Run the tests on their own. The tests are a program you can run directly, which shows how many tests and checks it ran:
The
v0.3.0starter begins with two test cases and nine assertions. This page adds three cases and ten assertions in either version, so its successful release total is 5 cases and 19 assertions; the development example below has 6 and 27. Compare with your count before adding the file: it must increase by three cases and ten assertions.Terminal window out\build\x64-debug\game\MyGameTests.exeOutput [doctest] doctest version is "2.5.3"[doctest] run with "--help" for options===============================================================================[doctest] test cases: 6 | 6 passed | 0 failed | 0 skipped[doctest] assertions: 27 | 27 passed | 0 failed |[doctest] Status: SUCCESS!It takes well under a second.
test cases: 6is the starter’s three tests inmotion_tests.cppand your three;assertions: 27counts everyCHECKrun, the starter’s 17 and your 10. If the case count did not increase by three, your test file is not in the program: step 5’s line is missing or misspelt, and nothing warns about that, because a file that is not listed is simply not built. To see the tests’ names, add--list-test-cases:Terminal window out\build\x64-debug\game\MyGameTests.exe --list-test-casesOutput [doctest] listing all test case names===============================================================================a point inside the area stays where it isa point outside the area moves to its nearest edgea greeting circling the centre's area stays in the windowthe stick and the keys add up to at most one unita step moves the centre and turns the greetingthe only pad counts in whichever slot it is in===============================================================================[doctest] unskipped test cases passing the current filters: 6In
v0.3.0, the list omitsthe only pad counts in whichever slot it is inand ends with 5.
When a test fails
Section titled “When a test fails”A test is worth having because it fails when the rule stops doing what the test expects. To see what that looks like, break one check on purpose.
The failure output below uses the development starter’s totals. With v0.3.0, the same broken
check instead reports five cases and nineteen assertions, with one failure in each count.
Open the test file:
notepad game\tests\bounds_tests.cppSearch for Approx(110.0f). The line reads:
CHECK(corner.x == doctest::Approx(110.0f));Change 110.0f to 100.0f, save and close Notepad, and run the build line from step 7 again. The
build compiles the test file again, then ctest reports the failure, and the game does not start,
because && runs the next command only when the one before it worked:
[3/4] Building CXX object game\CMakeFiles\MyGameTests.dir\tests\bounds_tests.cpp.obj[4/4] Linking CXX executable game\MyGameTests.exeTest project C:/dev/mygame/out/build/x64-debug Start 1: MyGameTests1/2 Test #1: MyGameTests ......................***Failed 0.03 sec[doctest] doctest version is "2.5.3"[doctest] run with "--help" for options===============================================================================C:\dev\mygame\game\tests\bounds_tests.cpp(20):TEST CASE: a point outside the area moves to its nearest edge
C:\dev\mygame\game\tests\bounds_tests.cpp(31): ERROR: CHECK( corner.x == doctest::Approx(100.0f) ) is NOT correct! values: CHECK( 110 == Approx( 100 ) )
===============================================================================[doctest] test cases: 6 | 5 passed | 1 failed | 0 skipped[doctest] assertions: 27 | 26 passed | 1 failed |[doctest] Status: FAILURE!
Start 2: MyGameSmokeTests2/2 Test #2: MyGameSmokeTests ................. Passed 0.70 sec
50% tests passed, 1 tests failed out of 2
Total Test time (real) = 0.75 sec
The following tests FAILED: 1 - MyGameTests (Failed)Errors while running CTestHow to read it:
***Failednext toMyGameTestssays the rules’ tests failed. The lines under it are what the test program printed.bounds_tests.cpp(20)andTEST CASE:name the test that failed: the file, the line the test starts on in brackets, and its name.bounds_tests.cpp(31): ERROR:is the check that failed, at line 31, written out as it is in the file. To go there, open the file in Notepad, press Ctrl+G, type31and press Enter.values:is the same check with the numbers filled in: the rule gave back110, and the test expected100. That is the line to think about. Either the rule is wrong, or the test expects the wrong thing; here the test does.- The counts at the end say how many tests and checks failed, out of how many.
The starter’s test preset has "outputOnFailure": true, which is why ctest printed the test
program’s lines under ***Failed. ctest --preset x64-debug --output-on-failure asks for the
same thing by name, and printed the same lines here; use it in a project whose preset does not
have that setting. The test program run on its own, as in step 8, prints the same failure and
ends Status: FAILURE!.
Put the line back to 110.0f, save, and run the build line again: both tests pass and the game
opens.
To run only some tests, which helps once there are many, give the test program part of their name between asterisks. This runs only the one about the nearest edge:
out\build\x64-debug\game\MyGameTests.exe --test-case="*nearest edge*"Its counts say test cases: 1 | 1 passed | 0 failed | 5 skipped in the development example,
or 4 skipped with the v0.3.0 starter, and it ends
Status: SUCCESS!.
The wall around the rules
Section titled “The wall around the rules”A rule may use the engine’s maths and nothing else of it, and the build enforces that. Suppose you want holding Space to let the greeting leave the window, and you write the key check in the rule’s file. Open it:
notepad game\rules\bounds.cppSearch for engine/math/scalar.h and add a line above it, so the two read:
#include "engine/input/keyboard.h"#include "engine/math/scalar.h"Then click at the very end of the file, press Enter, and paste these lines:
// Holding Space lets the greeting leave the window.{}Save, close Notepad, and run the build line. Every file compiles, but the tests do not link:
[3/6] Building CXX object game\CMakeFiles\MyGameRules.dir\rules\bounds.cpp.obj[4/6] Linking CXX static library game\MyGameRules.lib[5/6] Linking CXX executable game\MyGameTests.exeFAILED: [code=4294967295] game/MyGameTests.exeMyGameRules.lib(bounds.cpp.obj) : error LNK2019: unresolved external symbol "public: bool __cdecl labrador::Keyboard::held(enum labrador::Key)const " (?held@Keyboard@labrador@@QEBA_NW4Key@2@@Z) referenced in function "bool __cdecl leaving_allowed(class labrador::Keyboard const &)" (?leaving_allowed@@YA_NAEBVKeyboard@labrador@@@Z)game\MyGameTests.exe : fatal error LNK1120: 1 unresolved externals[6/6] Linking CXX executable game\MyGame.exeninja: build stopped: subcommand failed.Two long lines after FAILED: have been left out here: the command that failed, and a line
saying that the linker failed. The error lines come after them. The game itself, MyGame.exe, linked, because it has the whole
engine. The tests have only the engine’s maths, so the linker finds nothing for
Keyboard::held, and says so with MyGameRules.lib(bounds.cpp.obj): a rule’s file asked for
something outside the wall. The #include line was not the problem. The engine’s headers can be
read from the rules; it is calling the engine’s code that fails.
The answer is to keep the rule free of the engine and do the engine’s part in the state, which
reads the keyboard already. Open game\rules\bounds.cpp again, delete the
#include "engine/input/keyboard.h" line and the lines you pasted at the end, save and close
Notepad. Then open the state:
notepad game\states\hello_state.cppSearch for // Keep the greeting inside the window. Select the five lines you added in step 6:
// Keep the greeting inside the window, however far it is steered. this->app_->resolution_manager()->resolution_vec(); this->motion_.centre = keep_inside(this->motion_.centre, centre_area(window_size, this->greeting_->bounds().size()));and paste these in their place:
// Keep the greeting inside the window, however far it is steered, // unless Space is held. this->app_->resolution_manager()->resolution_vec(); { this->motion_.centre = keep_inside(this->motion_.centre, centre_area(window_size, this->greeting_->bounds().size())); }keyboard is the state’s view of the keyboard, which update() already has a few lines higher.
! means “not”, so the greeting is kept inside unless Space is held. Save, close Notepad and
run the build line. Both tests pass. In the game, hold Space and an arrow key together and
the greeting goes past the edge; let go of Space and it jumps back to the edge. The rule did not
change, so its tests did not need to.
Changing the rule
Section titled “Changing the rule”Keep the greeting above the controls line. The text along the bottom of the window starts 40
pixels above its bottom edge. To stop the greeting before it, tell the rule the window is 48
pixels shorter than it is. In game\states\hello_state.cpp, search for
// Keep the greeting inside the window. Just below that comment are these two lines:
this->app_->resolution_manager()->resolution_vec();Change them to these three:
this->app_->resolution_manager()->resolution_vec() - Vector2F(0.0f, 48.0f);Build and run: held down, the greeting now stops just above the controls line. The tests still pass, because the rule works on whatever size it is given.
A rule of your own. The same five steps make any rule: a header in game\rules that declares
it, a .cpp beside it that writes it, its name in add_library(MyGameRules, a test file in
game\tests without the #define line, and its name in add_executable(MyGameTests. A rule
that needs something from the engine, such as a key, the window’s size or the time since the
last frame, is handed it by the state as a number, a flag or a Vector2F, the way
keep_inside is handed the window’s size and step_motion is handed dt.
A new state is listed twice. A .cpp file in game\states, such as a title screen, goes in
both add_executable(MyGame lists: the one inside if(EMSCRIPTEN) for the browser and the
add_executable(MyGame WIN32 one for Windows. Missing it from the Windows list gives
LNK2019, and missing it from the
browser list gives undefined symbol.
How errors show
Section titled “How errors show”A mistake in this page’s files shows in one of three places:
- The build stops at a compile error, an
error Cline naming a file and line: a slip in the C++ code. Read a build error shows how to find the line that matters. - The build stops at a link error, an
error LNKline: every file compiled, but a function has no code anywhere the program can see. A name afterFAILED:says which program:game/MyGameTests.exeis the tests,game/MyGame.exethe game. - A test fails. The build worked, and ctest shows
***Failednext toMyGameTests, with the check that failed under it, as in When a test fails.
Each message is below.
If something fails
Section titled “If something fails”The case count did not increase by three. A development starter still shows 3 instead of 6;
v0.3.0 still shows 2 instead of 5. The test file is not in the build: step 5’s line is
missing from add_executable(MyGameTests, or misspelt. The build and ctest both pass, since a
file that is not listed is simply not built, so the count is the only sign. Add the line, save
and build again.
ERROR: CHECK( ... ) is NOT correct! A test ran and one of its checks was false. When a test
fails reads the message.
In the browser build
Section titled “In the browser build”Nothing on this page needs a browser-only line. The rules library and the tests are listed once
and the browser build uses the same lists, so rules/bounds.cpp and tests/bounds_tests.cpp
are in it already. In the prompt where you ran emsdk_env.bat, as in Build for the
browser, run the line below. If you have not built for the browser in this
project yet, there is no out\build\wasm-debug folder and the line fails: run
cmake --preset wasm-debug first, as that page does.
cmake --build --preset wasm-debug && ctest --preset wasm-debugctest runs MyGameTests under Node and ends 100% tests passed, 0 tests failed out of 1. The
browser build has no start-up test, so it counts one. The page,
out\build\wasm-debug\game\MyGame.html, is built from the same hello_state.cpp and rules.
The browser build’s linker reports the same mistakes in its own words. With rules/bounds.cpp
missing from MyGameRules, both programs fail:
FAILED: [code=1] game/MyGameTests.jswasm-ld: error: game/CMakeFiles/MyGameTests.dir/tests/bounds_tests.cpp.o: undefined symbol: keep_inside(labrador::Vector2F const&, labrador::RectangleF const&)wasm-ld: error: game/CMakeFiles/MyGameTests.dir/tests/bounds_tests.cpp.o: undefined symbol: keep_inside(labrador::Vector2F const&, labrador::RectangleF const&)wasm-ld: error: game/CMakeFiles/MyGameTests.dir/tests/bounds_tests.cpp.o: undefined symbol: keep_inside(labrador::Vector2F const&, labrador::RectangleF const&)wasm-ld: error: game/CMakeFiles/MyGameTests.dir/tests/bounds_tests.cpp.o: undefined symbol: centre_area(labrador::Vector2F const&, labrador::Vector2F const&)FAILED: [code=1] game/MyGame.htmlwasm-ld: error: game/CMakeFiles/MyGame.dir/states/hello_state.cpp.o: undefined symbol: centre_area(labrador::Vector2F const&, labrador::Vector2F const&)wasm-ld: error: game/CMakeFiles/MyGame.dir/states/hello_state.cpp.o: undefined symbol: keep_inside(labrador::Vector2F const&, labrador::RectangleF const&)A name is listed once for each place that calls it, so keep_inside appears three times for the
tests. Each FAILED: line is followed by a long command line, and each program’s errors by a long
em++: error: line ending failed (returned 1); those are left out here.
With the #define line in a second test file, it prints wasm-ld: error: duplicate symbol:
followed by a doctest name, and >>> defined in both test files, then stops after 20 with
too many errors emitted. The fixes are the ones above.
One mistake shows only on Windows: the browser build linked the leaving_allowed function from
The wall around the rules without an error, because no test calls
it. Build for Windows too before trusting that a rule keeps to its wall.
Where to go next
Section titled “Where to go next”- Test your game covers the start-up test, tests that check what the game draws, and driving the game with pressed keys.
- Read a build error reads compile and link errors in more depth, and Troubleshooting lists them.
- LineSweeper, in Examples, is a whole game built the same way: its rules are a library with no engine in it, and its tests play whole games with no window.
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\h4\mygame,
with Visual Studio 2026’s compiler 19.51, every step above ran as shown, with C:\dev\h4\mygame
in the quoted output changed to C:\dev\mygame. The edits were made by an agent exactly as the
steps word them, with an editing tool rather than Notepad. Before the edits, the right arrow held
for three seconds took the greeting off the window; after them, each of the four arrows held for
three seconds left it at that edge, in screenshots of the window, and with the change under
Changing the rule it stopped above the controls line. Holding Space with
the right arrow took it past the edge and releasing Space brought it back. The test program and
ctest gave the output shown, passing and with the broken check, and --output-on-failure gave
the same lines. Each message under If something fails was made on purpose:
rules/bounds.cpp left out of MyGameRules, the Space check written in the rule, the #define
line copied into the second test file, the #include line left out and misspelt, and the test
file left out of MyGameTests, which still passed with two test cases. The wasm-debug build
compiled and passed with the new files, ran the tests under Node with five test cases, gave the
undefined symbol and duplicate symbol messages shown, and linked the rule with the Space check
in it without an error. On 2026-11-04 the starter gained a third test, of which pad slots count,
with 8 checks; the counts in the outputs above were raised by one test and 8 checks from that
change, not seen in a run of these steps.
A second agent then followed this page as worded in a fresh starter at C:\dev\h4v\mygame, with
keys sent to the game and screenshots of its window. Every edit target was found once, the code
compiled without warnings for Windows and the browser, and the outputs, the screenshots and every
message above matched. It found six smaller differences, which are corrected here: the wall’s
output numbering, which is [3/6] to [6/6] once the test file has been rebuilt after the broken
check (re-run and re-captured); a first link failure that can name the game as well as the tests;
the repeated undefined symbol lines and the em++: error: lines in the browser build; the
Total Test time line at the end of step 7, whose output is now that second run’s, with its folder changed the
same way; the last lines
of the one-test run; and the cmake --preset wasm-debug line for a project not yet built for the
browser.
Compiled example
Section titled “Compiled example”The three-guide pilot reads this page’s numbered main procedure into a copy of the current development starter and compiles and runs it with native null rendering and audio. It runs the guide’s rules tests and the game’s smoke check. This automation does not qualify the released v0.3.0 starter, browser pages, visual appearance, or the optional edits after the numbered procedure. The pilot procedure records its scope and measured cost.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.