Skip to content

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.

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

  2. Download the starter ZIP.

    The starter ZIP for Labrador v0.3.0 is labrador-starter-v0.3.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.3.0.zip https://github.com/matt439/Labrador/releases/download/v0.3.0/labrador-starter-v0.3.0.zip

    curl draws a small table while it downloads, about 9 MB, 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.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.zip in its Assets list and click it. Your browser saves it in your Downloads folder. This moves it to C:\dev:

    Terminal window
    move "%USERPROFILE%\Downloads\labrador-starter-v0.3.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
    tar -xf C:\dev\labrador-starter-v0.3.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
    CMakeLists.txt
    CMakePresets.json
    external
    game
    README.txt
    vcpkg.json

    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.

    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:

    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 using the Direct3D 11 renderer, with its output in out\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 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.

    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 and Could not find toolchain file.

  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.

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

  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.

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

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.

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.

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

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.

All documentation versions