Get the starter project
Each Labrador release comes with a starter ZIP: a game project of your own, made from the engine’s minimal sample, with the engine inside it. You download it, extract it, build it and play it. You do not need Git, and you do not build Labrador on its own first.
The game code and build are the ones Start your own project makes by hand, so later code-editing pages apply to both. The engine folder is a plain copy rather than a Git submodule; Put your project in Git changes that whenever you want to.
Before you start, do Install the tools. Every command on this page runs in the x64 Native Tools Command Prompt, one box at a time, in order.
-
Go to your projects folder. Open the x64 Native Tools Command Prompt and run:
Terminal window if not exist C:\dev mkdir C:\devcd /d C:\devdir /bThe first line makes the folder
C:\devif it is not there yet, and prints nothing either way. The prompt now endsC:\dev>, anddir /blists what is already in the folder, which may be nothing, orFile Not Found. If the list hasmygamein it, you already have a project calledmygame, and step 3 refuses to extract over it, since that would put the starter’s files back over your changes. Do step 2 to download the ZIP, then follow A second project below in place of steps 3 and 4.Every box on this page uses
C:\devas written, even if you gave a deep folder a drive letter in Keeping a deep folder. -
Download the starter ZIP.
The starter ZIP for Labrador
v0.4.0islabrador-starter-v0.4.0.zip. This downloads it intoC:\dev, with thecurlprogram that comes with Windows:Terminal window cd /d C:\devcurl -fL -o labrador-starter-v0.4.0.zip https://github.com/matt439/Labrador/releases/download/v0.4.0/labrador-starter-v0.4.0.zipcurldraws a small table while it downloads, about 9 MB, and the prompt comes back when it has finished. If it ends withcurl: (22) The requested URL returned error: 404instead, there is no file of that name at that address: open Labrador v0.4.0's release page and download it with your browser, as below.To download it with your browser instead, open Labrador v0.4.0's release page, find
labrador-starter-v0.4.0.zipin its Assets list and click it. The other files there are not the project: a file whose name beginslabrador-docs-is a copy of this website, and GitHub's Source code links save the engine alone, asLabrador-and a version, with nomygamefolder (Not the starter ZIP). Your browser saves it in your Downloads folder. This moves it toC:\dev:Terminal window move "%USERPROFILE%\Downloads\labrador-starter-v0.4.0.zip" C:\dev\moveprints1 file(s) moved.If it saysThe system cannot find the file specified., your browser saved the file somewhere else: press Ctrl+J in the browser to see where. -
Extract it, still in
C:\dev:Terminal window cd /d C:\devif exist C:\dev\mygame (echo C:\dev\mygame already exists. Nothing was extracted.) else (tar -xf C:\dev\labrador-starter-v0.4.0.zip)tarcomes with Windows 10 and later, and extracts ZIP files as well as its own kind. It prints nothing when it works. The ZIP holds one folder,mygame, so you now haveC:\dev\mygame. Check it:Terminal window dir /b mygameOutput .github.gitignoreCMakeLists.txtCMakePresets.jsonexternalgameREADME.txtvcpkg.jsonThis is the released
v0.3.0ZIP’s listing. Development starter ZIPs also includelabrador.vsconfig, an optional Visual Studio setup file described in Install the tools. It changes none of the commands below.If the box prints
C:\dev\mygame already exists. Nothing was extracted., you already have a project calledmygame, and the box left it as it was: follow A second project in place of this step and the next. IftarsaysError opening archive: Failed to open, the ZIP is not inC:\dev, or has another name:dir /b C:\dev\*.ziplists the ZIP files that are there. If one is calledLabrador-and a version, or beginslabrador-docs-, it is not the starter ZIP: Not the starter ZIP. If it printsCan't create '\\?\P:\mygame\...'for every file, with your drive letter in place ofP:, the ZIP was extracted at the root of a drive made withsubst, where Windows’tarcannot create files. Run the box above as written, which extracts inC:\dev.To extract it with File Explorer instead, right-click the ZIP and choose Extract All…. In the box under Files will be extracted to this folder, replace the folder shown with
C:\dev, then click Extract. If you kept the folder Explorer suggested, named after the ZIP, the project is in amygamefolder inside that one and its path is longer than it should be: The project is in a folder named after the ZIP has the box that moves it toC:\dev\mygame. -
Go into the project:
Terminal window cd /d C:\dev\mygameThe prompt ends
C:\dev\mygame>. Every later command runs in this folder. -
Configure the build:
Configure prepares the build: it checks the tools, obtains the libraries the project needs and writes the build instructions. It does not yet make the game executable.
Terminal window cmake --preset x64-debugA preset is a named configuration in the project’s
CMakePresets.json.x64-debugis a 64-bit debug build, prepared for finding problems while developing, using the Direct3D 11 renderer, the part that turns drawing requests into an image. Its output is inout\build\x64-debug. Setup words explains these terms.The first time, vcpkg downloads and builds the libraries the engine uses: DirectX Tool Kit and the DirectXMath library it uses, the XAudio2 redistributable, the lodepng image library and the doctest test framework. If Git is not installed, it prints
A suitable version of git was not foundand downloads a private copy of Git, about 60 MB, which it uses only to read its list of package versions. That is expected, and you never run Git yourself. With nothing cached, on a fast desktop, this configure took 2 minutes 8 seconds, a minute of it building DirectX Tool Kit, and downloaded about 400 MB. A slower machine can take much longer; leave the window alone until the prompt comes back. vcpkg keeps what it downloaded and built, so later configures are quick.Before building those libraries, vcpkg checks the tools it uses. It may download its own CMake and PowerShell 7 even though
cmake --versionworked: its package cache depends on specific tool versions, and Visual Studio does not install PowerShell 7. Lines like these announce normal tool downloads, rather than a failure to configure the build:Example output, 13 November 2026 A suitable version of cmake was not found (required v4.3.2).A suitable version of powershell-core was not found (required v7.5.4).Those examples came from Visual Studio 2026's bundled vcpkg on 13 November 2026. That run downloaded about 53 MB of CMake and 117 MB of PowerShell. Other Visual Studio or vcpkg versions can select different tools and print different versions or an order unlike this example. A clean Windows Sandbox run that day fetched CMake 4.4.3, PowerShell 7.6.6 and 7-Zip 26.03; a tool's downloaded version can exceed the minimum the message names.
Keep vcpkg's default tool selection. You do not need to install PowerShell 7 separately or change a setting to force system tools. Let the downloads finish and check for the final
Configuring doneandGenerating donelines below. Later configures reuse the downloaded tools and built libraries while their caches remain available.It has worked when the last lines are these:
Output -- Configuring done-- Generating done-- Build files have been written to: C:/dev/mygame/out/build/x64-debugCMake also prints a time in brackets after each
done. If it ends withConfiguring incomplete, errors occurred!instead, find the first line that saysErrorand look it up in Troubleshooting. The usual ones are the wrong command prompt,Could not find toolchain file, a download that failed, and a project folder too deep, which configure warns about withCMAKE_OBJECT_PATH_MAX. -
Build it:
Terminal window cmake --build --preset x64-debugThis compiles the engine and your game, which took 7 seconds on the same desktop. Ninja numbers each step as it goes, such as
[57/97], and a build that worked stops at the last number with no line sayingFAILED. Warnings are errors in this project, so a successful build has none. A compiler warning flags suspicious code; here it must be fixed before the new game can be made.If a line says
FAILED, the build stopped there. The lines under it name the reason: skip the long line that starts with the compiler’s path, find the first line witherrorin it, and look up its message in Troubleshooting. A project folder deep enough to have warned in step 5 can stop the build with C1083. Hundreds ofunresolved external symbollines at once, with awarning LNK4272among them, mean the wrong command prompt, not a fault in the code:LNK4272says what to do. A build that prints no numbered lines at all means the configure in step 5 did not finish: its entry lists what it prints instead. Do not go on to the next step until the build works: the tests and the game need the program it makes. -
Run the tests:
Terminal window ctest --preset x64-debugctest lists the two tests as it runs them, each ending
Passed, and then reports100% tests passed, 0 tests failed out of 2.MyGameTestschecks the game’s rules with no window.MyGameSmokeTestsstarts the game hidden, lets it draw a few frames and quits, so it also tells you the game can start on your machine. Test your game explains both.A test that fails says
***Failedin place ofPassed, and the summary counts it. The lines under the failed test say why. A game that cannot load a file, for example, ends:Output 2/2 Test #2: MyGameSmokeTests .................***Failed 0.21 secstartup failure: No file at C:\dev\mygame\out\build\x64-debug\game\.\./fonts/jetbrains_mono_bold_16.spritefont.50% tests passed, 1 tests failed out of 2Total Test time (real) = 0.24 secThe following tests FAILED:2 - MyGameSmokeTests (Failed)Errors while running CTestMyGameSmokeTestsfailing means the game cannot start on this machine, and the line startingstartup failure:is the reason: look it up in Troubleshooting’s Running section. On a fresh starter project the usual cause is a build in step 6 that did not finish, so run step 6 again and read its last lines first.MyGameTestsfailing on a project you have not changed would be a fault in the starter; report it as the top of Troubleshooting says. -
Play it:
Terminal window out\build\x64-debug\game\MyGame.exeA 1280×720 window opens with the line Hello from the engine. circling a point, and a hint along the bottom. Move the point with the left stick of a gamepad, the arrow keys or WASD. Press B or Escape and the game asks whether you really want to quit; A or Enter quits, and B or Escape goes back. The prompt is ready for the next command as soon as the window opens, but quit the game before you build again: a program that is running cannot be replaced, and the build stops with
LNK1168.If the prompt answers
'out\build\x64-debug\game\MyGame.exe' is not recognized as an internal or external command, operable program or batch file.orThe system cannot find the path specified., the build in step 6 did not finish: run it again and read its last lines.This
MyGame.exeis a debug build, which runs only on a PC with Visual Studio. To give the game to someone, follow Send your game to a friend.
That is your game. Make a first change changes what it says
and how it moves. Run the minimal sample
explains which code makes each thing on the screen; your game folder is a copy of that
sample.
What is in the folder
Section titled “What is in the folder”Directorymygame/
- README.txt which Labrador release this is, and where these pages are
- CMakeLists.txt your build, which builds Labrador first
- CMakePresets.json
- vcpkg.json the engine’s dependencies, at the engine’s versions
- .gitignore for when you put the project in Git
Directory.github/
Directoryworkflows/
- ci.yml a GitHub Actions workflow for when it is on GitHub
Directoryexternal/
Directorylabrador/ the engine, which you do not edit
- …
Directorygame/ yours: the code and content of your game
- CMakeLists.txt the game’s build: its source files, tests, content and release
- README.md how the template is arranged, and what changed in it
- main.cpp starts the game on Windows
- main_web.cpp starts it in a browser
- dpi_aware.manifest tells Windows not to stretch the window on a scaled display
- game_icon.rc optional native icon recipe in the development template; absent in v0.3.0
Directorystates/
- hello_state.h the screen with the circling greeting
- hello_state.cpp
- confirm_state.h the “Really quit?” question
- confirm_state.cpp
Directoryrules/
- motion.h how the greeting moves, with no window or device
- motion.cpp
Directorycontent/
- manifest.json every file the game loads, by name
Directoryfonts/
- jetbrains_mono_bold_16.spritefont the font the text is drawn with
- OFL.txt the font’s licence
Directorytests/
- motion_tests.cpp the rules’ tests
Directoryweb/
- shell.html the page around the game in a browser
The guides that add a source file to the game say to list it in game\CMakeLists.txt, the one
under game, not the one beside CMakePresets.json.
There is also a look-alike external\labrador\samples\minimal\ inside the complete engine
source. Follow game guides in game\, for example game\states\hello_state.cpp.
The v0.3.0 ZIP’s game\README.md is the original template README shown above. New starter
assemblies from the development engine give that file a concise map of your game’s files
and targets and adapt copy-specific comments to MyGame names. Their root README.txt
explains the distinction too. The full original template README and its change list stay at
external\labrador\samples\minimal\README.md in both arrangements.
Start your own project explains each of these files, since
it makes them one at a time. Everything you change is in game. Leave external\labrador as
it is: moving to a newer Labrador replaces it, and
Move a starter project to a newer Labrador says how.
Coming back later
Section titled “Coming back later”A new command prompt starts in its own folder. Each time you open the x64 Native Tools Command Prompt to carry on, go back to the project first:
cd /d C:\dev\mygameThe build only recompiles what changed, so running the build, test and play lines again is always safe. Open the x64 prompt, not the plain Developer Command Prompt: a build in that one fails after your first edit, with hundreds of unresolved externals.
Starting the build again from nothing
Section titled “Starting the build again from nothing”The build folder remembers how it was configured. After a configure failed, or after you change
something it depends on, such as VCPKG_ROOT, the folder the project is in, or which prompt you
use, delete the build folder and configure again. From the mygame folder:
rmdir /s /q out\build\x64-debugcmake --preset x64-debugcmake --build --preset x64-debugrmdir /s /q deletes the folder and everything in it without asking, so check that the prompt
ends mygame> before you run it. It deletes only what the build made. After moving or renaming
the project’s folder, configure and build fail with
The current CMakeCache.txt directory ... is different,
and that entry’s box is the one to run.
A second project
Section titled “A second project”Every starter ZIP holds a folder called mygame, so a second project is extracted somewhere
else first and then moved to a name of its own. Download the ZIP into C:\dev first, as in
step 2, if you have not already.
Then choose the project’s name. Paste this line, but before you press Enter, change
secondgame to the name you want, short and without spaces, as
Typing the commands shows:
set "NAME=secondgame"It prints nothing. Then run this box. It extracts the ZIP into a new folder, C:\dev\unpack,
moves the project to the name you chose, deletes what is left of unpack, and goes into the
new project:
mkdir C:\dev\unpacktar -xf C:\dev\labrador-starter-v0.4.0.zip -C C:\dev\unpackif exist "C:\dev\%NAME%" (echo C:\dev\%NAME% already exists. Choose another name.) else (move C:\dev\unpack\mygame "C:\dev\%NAME%")rmdir /s /q C:\dev\unpackcd /d "C:\dev\%NAME%"move prints 1 dir(s) moved., and the prompt ends with the new project’s folder. If it says
already exists. Choose another name. instead, a folder of that name is there already and
nothing was moved, and the prompt is now in that other folder: run the name line again with
another name, then this box again. Then build the new project from step 5. The program in it is still called MyGame.exe; the names inside
the project are explained on Start your own project, and
Rename your game changes them to your game’s name.
Optional commands from an ordinary prompt
Section titled “Optional commands from an ordinary prompt”These helpers belong to the development starter after v0.3.0; that release’s
ZIP uses the manual steps above. Move a starter project to a newer Labrador
explains how to take a release that carries new starter files.
If your project has build.cmd, test.cmd and play.cmd, you can use them
from an ordinary Command Prompt. Open Start, type cmd, and open
Command Prompt. Go to the project folder, using your folder’s name if
you chose another:
cd /d C:\dev\mygameRun one command at a time:
build.cmdtest.cmdplay.cmdbuild.cmd configures and builds. test.cmd does both and then runs the game’s
tests. play.cmd does both and then opens the game. The three share the
tools\starter_commands.ps1 file, find Visual Studio’s x64 tools, and print
each manual command before running it. Keep all four files in the project.
They install nothing and keep the command’s output and failure code. If a
step fails, later steps stop; read its output and use the matching repair in
Build problems.
They choose x64-debug unless you ask for Release:
test.cmd -Preset x64-releaseplay.cmd -SmokeTest runs the hidden startup check and returns to the prompt.
For browser builds, follow Build for the browser.
The x64 Native Tools prompt and manual commands above remain available.
The ordinary-prompt route still needs the tools from
Install the tools.
What was checked
Section titled “What was checked”On 30 October 2026, a starter ZIP made by the same tool from the change that added this page
was extracted with Windows’ tar into a new folder, then configured, built and tested in the
x64 Native Tools Command Prompt of Visual Studio 2026, with Git hidden from vcpkg and vcpkg’s
download, package and registry caches empty. vcpkg downloaded its own Git and everything else,
and the configure, build and tests all passed, with the times above. In Windows Sandbox, where
Git has never been installed, Visual Studio’s vcpkg also downloaded its own Git and read its
package list. The same ZIP was extracted by Windows’ own ZIP handling, the one Extract All
uses, into the same single mygame folder. The boxes that move a ZIP from Downloads,
extract it by the start of its name, make a second project, and move a project out of the
folder Extract All suggests were run as written in a command prompt, with a drive letter
standing in for C:\dev, the ZIP renamed as a release’s would be, and the command prompt’s
USERPROFILE pointed at a stand-in for the Downloads folder’s parent.
On 31 October 2026 the failed test in step 7 was made in a fresh starter by moving the build’s
fonts folder away, and the file tree’s sixteen files in game were listed from it; a second
agent did both again in another fresh starter, and the output and the files matched.
On 13 November 2026 step 3’s box was run with a stand-in ZIP, its if line passed to cmd /c
so that %f is read as at the prompt: into an empty folder it extracted mygame, and run
again after a line had been added to mygame\game\main.cpp it printed
already exists. Nothing was extracted. and the added line was still there. Its form that
finds the ZIP by the start of its name did both the same way.
No release had carried a starter ZIP when this was checked, so the download step was not run
against a real release, and the Extract All dialog itself was not clicked through. CI makes a starter ZIP
from every change, extracts it with tar, and builds and tests the project in it.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.