Skip to content

Get the starter project

Since v0.3.0, Labrador releases include 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.

  1. Go to your projects folder. Open the x64 Native Tools Command Prompt and run:

    Terminal window
    if not exist C:\dev mkdir C:\dev
    cd /d C:\dev
    dir /b

    The first line makes the folder C:\dev if it is not there yet, and prints nothing either way. The prompt now ends C:\dev>, and dir /b lists what is already in the folder, which may be nothing, or File Not Found. If the list has mygame in it, you already have a project called mygame, 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:\dev as written, even if you gave a deep folder a drive letter in Keeping a deep folder.

  2. Download the starter ZIP.

    The starter ZIP for Labrador v0.4.0 is labrador-starter-v0.4.0.zip. This downloads it into C:\dev, with the curl program that comes with Windows:

    Terminal window
    cd /d C:\dev
    curl -fL -o labrador-starter-v0.4.0.zip https://github.com/matt439/Labrador/releases/download/v0.4.0/labrador-starter-v0.4.0.zip

    curl draws a small table while it downloads, and the prompt comes back when it has finished. If it ends with curl: (22) The requested URL returned error: 404 instead, 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.zip in its Assets list and click it. The other files there are not the project: a file whose name begins labrador-docs- is a copy of this website, and GitHub's Source code links save the engine alone, as Labrador- and a version, with no mygame folder (Not the starter ZIP). Your browser saves it in your Downloads folder. This moves it to C:\dev:

    Terminal window
    move "%USERPROFILE%\Downloads\labrador-starter-v0.4.0.zip" C:\dev\

    move prints 1 file(s) moved. If it says The system cannot find the file specified., your browser saved the file somewhere else: press Ctrl+J in the browser to see where.

  3. Extract it, still in C:\dev:

    Terminal window
    cd /d C:\dev
    if exist C:\dev\mygame (echo C:\dev\mygame already exists. Nothing was extracted.) else (tar -xf C:\dev\labrador-starter-v0.4.0.zip)

    tar comes 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 have C:\dev\mygame. Check it:

    Terminal window
    dir /b mygame
    Output
    .github
    .gitignore
    build.cmd
    CMakeLists.txt
    CMakePresets.json
    external
    game
    labrador.vsconfig
    play.cmd
    README.txt
    test.cmd
    tools
    vcpkg.json

    This is the released v0.4.0 ZIP’s listing. It includes the optional command helpers and labrador.vsconfig, the optional Visual Studio setup file described in Install the tools. The v0.3.0 ZIP has neither addition and uses the manual commands below.

    If the box prints C:\dev\mygame already exists. Nothing was extracted., you already have a project called mygame, and the box left it as it was: follow A second project in place of this step and the next. If tar says Error opening archive: Failed to open, the ZIP is not in C:\dev, or has another name: dir /b C:\dev\*.zip lists the ZIP files that are there. If one is called Labrador- and a version, or begins labrador-docs-, it is not the starter ZIP: Not the starter ZIP. If it prints Can't create '\\?\P:\mygame\...' for every file, with your drive letter in place of P:, the ZIP was extracted at the root of a drive made with subst, where Windows’ tar cannot create files. Run the box above as written, which extracts in C:\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 a mygame folder 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 to C:\dev\mygame.

  4. Go into the project:

    Terminal window
    cd /d C:\dev\mygame

    The prompt ends C:\dev\mygame>. Every later command runs in this folder.

  5. 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-debug

    A preset is a named configuration in the project’s CMakePresets.json. x64-debug is 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 in out\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 found and 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 --version worked: 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 finalConfiguring done and Generating done lines 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-debug

    CMake also prints a time in brackets after each done. If it ends with Configuring incomplete, errors occurred! instead, find the first line that says Error and 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 with CMAKE_OBJECT_PATH_MAX.

  6. Build it:

    Terminal window
    cmake --build --preset x64-debug

    This 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 saying FAILED. 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 with error in 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 of unresolved external symbol lines at once, with a warning LNK4272 among them, mean the wrong command prompt, not a fault in the code: LNK4272 says 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.

  7. Run the tests:

    Terminal window
    ctest --preset x64-debug

    ctest lists the two tests as it runs them, each ending Passed, and then reports 100% tests passed, 0 tests failed out of 2. MyGameTests checks the game’s rules with no window. MyGameSmokeTests starts 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 ***Failed in place of Passed, 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 sec
    startup 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 2
    Total Test time (real) = 0.24 sec
    The following tests FAILED:
    2 - MyGameSmokeTests (Failed)
    Errors while running CTest

    MyGameSmokeTests failing means the game cannot start on this machine, and the line starting startup 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. MyGameTests failing on a project you have not changed would be a fault in the starter; report it as the top of Troubleshooting says.

  8. Play it:

    Terminal window
    out\build\x64-debug\game\MyGame.exe

    A 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. or The system cannot find the path specified., the build in step 6 did not finish: run it again and read its last lines.

    This MyGame.exe is 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.

  • 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.

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:

Terminal window
cd /d C:\dev\mygame

The 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.

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:

Terminal window
rmdir /s /q out\build\x64-debug
cmake --preset x64-debug
cmake --build --preset x64-debug

rmdir /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.

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:

Terminal window
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:

Terminal window
mkdir C:\dev\unpack
tar -xf C:\dev\labrador-starter-v0.4.0.zip -C C:\dev\unpack
if 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\unpack
cd /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.

The helpers first shipped in v0.4.0. Use the manual steps above with the v0.3.0 ZIP. 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:

Terminal window
cd /d C:\dev\mygame

Run one command at a time:

Terminal window
build.cmd
test.cmd
play.cmd

build.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:

Terminal window
test.cmd -Preset x64-release

play.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.

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.

On 17 November 2026, the published v0.4.0 starter ZIP was checked against its release digest. Windows tar extracted the archive into a new short path, and x64 Debug configure, build and both starter tests passed without Git metadata in the extracted project. The release record has the result and archive digest. CI makes a starter ZIP for build changes, extracts it with tar, and builds and tests the project in it.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions