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 project is exactly the one Start your own project makes by hand, so every later page applies to it in the same way. The only difference is that its 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: extracting another starter here would overwrite its files with the starter’s. Do step 2 to download the ZIP, then follow A second project below in place of steps 3 and 4. -
Download the starter ZIP.
The starter ZIP for Labrador
v0.3.0islabrador-starter-v0.3.0.zip. This downloads it intoC:\dev, with thecurlprogram that comes with Windows:Terminal window cd /d C:\devcurl -fL -o labrador-starter-v0.3.0.zip https://github.com/matt439/Labrador/releases/download/v0.3.0/labrador-starter-v0.3.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.3.0's release page and download it with your browser, as below.To download it with your browser instead, open Labrador v0.3.0's release page, find
labrador-starter-v0.3.0.zipin its Assets list and click it. Your browser saves it in your Downloads folder. This moves it toC:\dev:Terminal window move "%USERPROFILE%\Downloads\labrador-starter-v0.3.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:\devtar -xf C:\dev\labrador-starter-v0.3.0.ziptarcomes 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.jsonIf
tarsaysError 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.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:
Terminal window cmake --preset x64-debugA preset is a named configuration in the project’s
CMakePresets.json.x64-debugis a 64-bit debug build using the Direct3D 11 renderer, with its output inout\build\x64-debug.The first time, vcpkg downloads and builds the libraries the engine uses: DirectX Tool Kit and the DirectXMath library it uses, the XAudio2 redistributable, and the doctest test framework. It also downloads a CMake and a PowerShell of its own if it finds Visual Studio’s unsuitable. 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.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 andCould not find toolchain file. -
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.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. On a first build the usual ones are a folder too deep for the compiler and a 32-bit prompt. 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.
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
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.
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.
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.
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.3.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.
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.
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.3.0. Built from Labrador 0f4f503 of 2026-11-03.