Skip to content

Start your own project

Starting a game on Labrador means copying the minimal sample and owning everything inside it. On this page your project is its own repository. Labrador sits inside it as a Git submodule, pinned to the commit you chose, and is built as part of your build.

This page calls the project mygame. Use your own name wherever that appears. The name in vcpkg.json takes only lowercase letters, digits and hyphens, so a project called MyGame is mygame there; vcpkg stops configure with "MyGame" is not a valid package name otherwise.

When you have finished, the project looks like this:

  • Directorymygame/
    • CMakeLists.txt your build, which builds Labrador first
    • CMakePresets.json
    • vcpkg.json the engine’s dependencies, at the engine’s versions
    • .gitignore
    • Directoryexternal/
      • Directorylabrador/ the engine, as a submodule
        • …
    • Directorygame/
      • CMakeLists.txt
      • dpi_aware.manifest keeps Windows from stretching the window on a scaled display
      • README.md the minimal sample’s, yours to rewrite or delete
      • main.cpp the Windows entry point
      • main_web.cpp the browser entry point, built only by a browser preset
      • Directorycontent/
        • …
      • Directoryrules/ the game’s rules, which its tests run without a window
        • …
      • Directorystates/
        • …
      • Directorytests/
        • …
      • Directoryweb/
        • shell.html the browser build’s page

main_web.cpp and web/shell.html are the browser build. The Windows build this page sets up does not compile them, and the wasm presets in step 6 do. Keep them if you might want your game in a browser, which Build for the browser adds to this project; if you never will, delete both, the if(EMSCRIPTEN) block in game/CMakeLists.txt and every wasm preset in CMakePresets.json with them.

Work in game/, for example game/states/hello_state.cpp. The look-alike external/labrador/samples/minimal/ remains the engine’s original template. This page’s manual copy keeps its template README and comments until you change them. New starter assemblies from the development engine provide a concise project README and adapt copy-specific comments to MyGame targets; the executable game code is the same. The original template’s full README and change list stay in external/labrador/samples/minimal/README.md.

  1. Make the repository. In the x64 Native Tools Command Prompt:

    Terminal window
    cd /d C:\dev
    mkdir mygame
    cd mygame
    git init

    Git answers Initialized empty Git repository in C:/dev/mygame/.git/, and the prompt ends C:\dev\mygame>. Every later command on this page runs in this folder. If you open a new prompt part way through, go back to it first with cd /d C:\dev\mygame.

    Step 8 makes a commit, which needs Git to know your name and email address. If you skipped Tell Git who you are, do it now.

  2. Add Labrador as a submodule, and check out a release:

    Terminal window
    git submodule add https://github.com/matt439/Labrador.git external/labrador
    git -C external/labrador checkout v0.3.0

    The first line downloads Labrador into external\labrador, as the clone did on Build Labrador. The second prints a long note that begins:

    Output
    Note: switching to 'v0.3.0'.
    You are in 'detached HEAD' state. You can look around, make experimental

    and ends HEAD is now at followed by a commit. That is expected, and nothing needs fixing. Detached HEAD means the engine’s folder is on one fixed release rather than on a branch that moves, which is what you want for an engine you build against. Ignore the note’s advice about git switch.

    v0.3.0 was the newest release when this page was written. To see whether there is a newer one, list the releases, newest first:

    Terminal window
    git -C external/labrador tag --list "v*" --sort=-v:refname

    These pages describe v0.4.0, and the files they give you to copy are that release's. For a newer release, follow this page in that release's own documentation, from All documentation versions, instead.

    Your repository now records exactly which commit of Labrador it builds against, and moving to a newer tag is a change you make deliberately and commit, after reading what CHANGES.md says changed between the two; Move your engine pin is the procedure. The development documentation describes master, which can be ahead of the newest tag, and CHANGES.md’s Unreleased heading, when it has one, lists what master has that the tag does not; a release’s own documentation, named at the foot of each page, describes that release.

    Anyone cloning your project, you included on another machine, needs --recurse-submodules to get the engine too. With your repository’s address in place of the one shown:

    Terminal window
    git clone --recurse-submodules https://github.com/you/mygame.git

    A clone made without it has an empty external\labrador folder, and configure stops with does not contain a CMakeLists.txt file. Inside that clone, this fills the folder in:

    Terminal window
    git submodule update --init --recursive
  3. Copy the minimal sample into a folder called game:

    Terminal window
    xcopy external\labrador\samples\minimal game /E /I

    xcopy lists each file it copies and ends with a count, such as 15 File(s) copied, that depends on the release you checked out.

  4. Point its includes at the new folder. Includes in Labrador are written from the root of the repository, so the sample names its own headers as samples/minimal/.... In your project they are under game/. Change these lines:

    FileChange this lineTo this
    game/main.cpp#include "samples/minimal/states/hello_state.h"#include "game/states/hello_state.h"
    game/main.cpp#include "samples/minimal/native_process_report.h"#include "game/native_process_report.h"
    game/main_web.cpp#include "samples/minimal/states/hello_state.h"#include "game/states/hello_state.h"
    game/rules/motion.cpp#include "samples/minimal/rules/motion.h"#include "game/rules/motion.h"
    game/states/confirm_state.cpp#include "samples/minimal/states/confirm_state.h"#include "game/states/confirm_state.h"
    game/states/hello_state.cpp#include "samples/minimal/states/hello_state.h"#include "game/states/hello_state.h"
    game/states/hello_state.cpp#include "samples/minimal/states/confirm_state.h"#include "game/states/confirm_state.h"
    game/states/hello_state.h#include "samples/minimal/rules/motion.h"#include "game/rules/motion.h"
    game/tests/motion_tests.cpp#include "samples/minimal/rules/motion.h"#include "game/rules/motion.h"

    This one command makes every change in the table for you. Paste it as a single line:

    Terminal window
    powershell -NoProfile -Command "$q = [char]34; Get-ChildItem game -Recurse -Include *.h,*.cpp | ForEach-Object { $t = [IO.File]::ReadAllText($_.FullName); $n = $t.Replace('#include ' + $q + 'samples/minimal/', '#include ' + $q + 'game/'); if ($n -ne $t) { [IO.File]::WriteAllText($_.FullName, $n); 'Changed ' + $_.FullName } }"

    It prints Changed and the path of each file it edited, one line per file in the table. To make the changes by hand instead, open each file in the table with Notepad, for example notepad game\main.cpp, use Ctrl+H to replace samples/minimal/ with game/, and save with Ctrl+S.

    main_web.cpp is only compiled by a browser build, so a mistake in its line shows only there. Change it with the rest unless you have deleted the file.

  5. Replace game\CMakeLists.txt with this:

    game/CMakeLists.txt
    set(GAME_ICON_FILE "" CACHE FILEPATH
    "Optional absolute path to an .ico file embedded in the native game")
    # The game's rules, in a library that links the engine's maths and nothing else
    # of it, so the tests below run them with no window and no device.
    add_library(MyGameRules STATIC
    rules/motion.cpp
    )
    target_link_libraries(MyGameRules PUBLIC
    LabradorMath
    labrador_settings
    )
    # Includes are written from the project root - "game/states/hello_state.h" -
    # so the directory above game/ is the include root, for the rules and for
    # everything that links them.
    target_include_directories(MyGameRules PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/..")
    # The rules' tests, with doctest from vcpkg. A new test file is listed here.
    if(COMMAND labrador_find_package)
    labrador_find_package(doctest)
    else()
    find_package(doctest CONFIG REQUIRED)
    endif()
    add_executable(MyGameTests
    tests/motion_tests.cpp
    )
    target_link_libraries(MyGameTests PRIVATE
    MyGameRules
    doctest::doctest
    labrador_settings
    )
    add_test(NAME MyGameTests COMMAND MyGameTests)
    # The browser build: main_web.cpp in place of main.cpp, a page made from
    # web/shell.html, and the content packed into the module at the paths the
    # Windows build copies it to. Under a wasm preset this is the whole build, and
    # the Windows half below is never read.
    if(EMSCRIPTEN)
    # The rules' tests run under Node, which ctest starts for them.
    target_link_options(MyGameTests PRIVATE -sENVIRONMENT=node)
    add_executable(MyGame
    main_web.cpp
    states/confirm_state.cpp
    states/hello_state.cpp
    )
    target_link_libraries(MyGame PRIVATE
    MyGameRules
    LabradorEngine
    labrador_settings
    )
    set_target_properties(MyGame PROPERTIES SUFFIX ".html")
    # Neither the page nor the content is a source, so name them here, or a
    # change to either does not relink.
    set_property(TARGET MyGame APPEND PROPERTY LINK_DEPENDS
    "${CMAKE_CURRENT_SOURCE_DIR}/web/shell.html"
    "${CMAKE_CURRENT_SOURCE_DIR}/content/manifest.json"
    "${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/jetbrains_mono_bold_16.spritefont"
    )
    target_link_options(MyGame PRIVATE
    "SHELL:--embed-file ${CMAKE_CURRENT_SOURCE_DIR}/content@/"
    "SHELL:--shell-file ${CMAKE_CURRENT_SOURCE_DIR}/web/shell.html"
    -sENVIRONMENT=web
    )
    return()
    endif()
    # dpi_aware.manifest declares per-monitor DPI awareness, so Windows does not
    # stretch the frame on a scaled display; the file says what that means.
    add_executable(MyGame WIN32
    main.cpp
    states/confirm_state.cpp
    states/hello_state.cpp
    dpi_aware.manifest
    )
    target_link_libraries(MyGame PRIVATE
    MyGameRules
    LabradorEngine
    labrador_settings
    )
    if(NOT "${GAME_ICON_FILE}" STREQUAL "")
    if(GAME_ICON_FILE MATCHES ";")
    message(FATAL_ERROR "GAME_ICON_FILE cannot contain a semicolon: ${GAME_ICON_FILE}")
    endif()
    if(NOT IS_ABSOLUTE "${GAME_ICON_FILE}")
    message(FATAL_ERROR
    "GAME_ICON_FILE must be an absolute path to your .ico file: ${GAME_ICON_FILE}")
    endif()
    if(NOT EXISTS "${GAME_ICON_FILE}" OR IS_DIRECTORY "${GAME_ICON_FILE}")
    message(FATAL_ERROR
    "GAME_ICON_FILE does not name an existing .ico file: ${GAME_ICON_FILE}. "
    "Supply your icon or clear the option with -DGAME_ICON_FILE=.")
    endif()
    get_filename_component(game_icon_extension "${GAME_ICON_FILE}" LAST_EXT)
    string(TOLOWER "${game_icon_extension}" game_icon_extension)
    if(NOT game_icon_extension STREQUAL ".ico")
    message(FATAL_ERROR "GAME_ICON_FILE must name an .ico file: ${GAME_ICON_FILE}")
    endif()
    file(TO_CMAKE_PATH "${GAME_ICON_FILE}" game_icon_path)
    enable_language(RC)
    target_sources(MyGame PRIVATE game_icon.rc)
    target_compile_definitions(MyGame PRIVATE
    GAME_HAS_ICON_RESOURCE=1
    "GAME_ICON_FILE=\"${game_icon_path}\""
    )
    set_property(SOURCE game_icon.rc APPEND PROPERTY OBJECT_DEPENDS "${game_icon_path}")
    endif()
    # The start-up check: the game hidden, a few frames drawn, and out. It needs a
    # graphics device, and a missing content file fails it naming the file.
    add_test(NAME MyGameSmokeTests COMMAND MyGame --smoke-test)
    set_tests_properties(MyGameSmokeTests PROPERTIES TIMEOUT 60)
    # Content is found beside the executable, so copy it there on every build.
    add_custom_target(game_content ALL)
    add_custom_command(TARGET game_content POST_BUILD
    COMMAND "${CMAKE_COMMAND}" -E copy_if_different
    "${CMAKE_CURRENT_SOURCE_DIR}/content/manifest.json"
    "$<TARGET_FILE_DIR:MyGame>/manifest.json"
    VERBATIM
    )
    add_custom_command(TARGET game_content POST_BUILD
    COMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different
    "${CMAKE_CURRENT_SOURCE_DIR}/content/fonts"
    "$<TARGET_FILE_DIR:MyGame>/fonts"
    VERBATIM
    )
    add_dependencies(MyGame game_content)
    # The release folder a player gets, from the x64-release build:
    # cmake --install out/build/x64-release --prefix <folder>
    # The program, the DLLs it loads, its content and the notices of what it
    # carries. A debug build loads the debug runtime, which may not be given away.
    if(NOT CMAKE_BUILD_TYPE STREQUAL "Release")
    install(CODE [[message(FATAL_ERROR "Install the x64-release build.")]])
    endif()
    install(TARGETS MyGame RUNTIME DESTINATION .)
    # DirectXTK and the XAudio2 redistributable, which vcpkg built as DLLs.
    install(FILES $<TARGET_RUNTIME_DLLS:MyGame> DESTINATION .)
    # The MSVC runtime, copied beside the program from Visual Studio's redist
    # folder, so a player needs no installer: CMake's list of its DLLs, which
    # leaves out vcruntime140_threads.dll and vccorlib140.dll.
    set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP TRUE)
    include(InstallRequiredSystemLibraries)
    install(PROGRAMS ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS} DESTINATION .)
    install(FILES content/manifest.json DESTINATION .)
    install(DIRECTORY content/fonts DESTINATION .)
    # The licences of what the program carries: the engine, the libraries
    # compiled into it and the DLLs beside it. The font's is fonts/OFL.txt.
    get_target_property(labrador_engine_dir LabradorEngine SOURCE_DIR)
    set(vcpkg_share "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/share")
    install(FILES "${labrador_engine_dir}/../LICENSE"
    DESTINATION notices RENAME Labrador.txt)
    # NOTICE: the code in the engine that is not Labrador's to license.
    install(FILES "${labrador_engine_dir}/../NOTICE"
    DESTINATION notices RENAME Labrador-NOTICE.txt)
    install(FILES "${labrador_engine_dir}/../external/rapidjson/license.txt"
    DESTINATION notices RENAME rapidjson.txt)
    install(FILES "${vcpkg_share}/directxtk/copyright"
    DESTINATION notices RENAME DirectXTK.txt)
    install(FILES "${vcpkg_share}/directxmath/copyright"
    DESTINATION notices RENAME DirectXMath.txt)
    install(FILES "${vcpkg_share}/xaudio2redist/copyright"
    DESTINATION notices RENAME XAudio2Redist.txt)

    Its doctest lookup works with the v0.3.0 engine selected above. A newer development engine provides labrador_find_package, which adds manifest advice when a dependency is missing; when that command is absent the file uses CMake’s ordinary find_package.

    To do that in Notepad, open the file:

    Terminal window
    notepad game\CMakeLists.txt

    In Notepad, press Ctrl+A to select everything in the file, then paste the block above over it with Ctrl+V (copy it with its copy button first), save with Ctrl+S and close Notepad. Any text editor does as well; what matters is that the file holds exactly the block.

    It is the sample’s build file with its names changed: the program is MyGame, the rules library MyGameRules, the tests MyGameTests and MyGameSmokeTests, and the content target game_content. Its if(EMSCRIPTEN) block is the browser build, which a Windows build skips; Build for the browser explains it. The install rules at the end of the Windows half make the folder you give players, as Ship a Windows release explains. One line is new. target_include_directories makes the folder above game the place your includes start from, for the rules and for everything that links them, which the sample did not need because Labrador’s root already was.

    Two tests come with it. MyGameTests runs the rules in game\rules with no window and no graphics device. MyGameSmokeTests starts the game hidden with --smoke-test, lets it draw a few frames and quits, so a change that stops the game starting fails a test rather than your next launch. Test your game says how both work and how to add your own.

  6. Add the project’s own build files to the mygame folder. There are four, each shown below in a box with its file name at the top. Make each file empty first, then open it in Notepad, paste its box into it with the box’s copy button and Ctrl+V, save with Ctrl+S and close Notepad before the next. These lines make the four empty files:

    Terminal window
    type nul > CMakeLists.txt
    type nul > vcpkg.json
    type nul > CMakePresets.json
    type nul > .gitignore

    Then open them one at a time, after you have copied that file’s box:

    Terminal window
    notepad CMakeLists.txt
    Terminal window
    notepad vcpkg.json
    Terminal window
    notepad CMakePresets.json
    Terminal window
    notepad .gitignore

    Making the file first keeps Notepad from adding .txt to the name. Each name must match exactly, the leading dot of .gitignore included.

    CMakeLists.txt
    cmake_minimum_required(VERSION 3.26)
    project(MyGame LANGUAGES CXX)
    # ctest runs this project's tests: the game's own, which game/CMakeLists.txt
    # registers.
    enable_testing()
    # Defines LabradorEngine, LabradorMath and labrador_settings. Labrador is not the
    # top-level project here, so its tests, benchmarks and samples are not built,
    # and none of its tests is in this project's ctest.
    add_subdirectory(external/labrador)
    add_subdirectory(game)

    enable_testing() makes your tests ctest’s. add_subdirectory(external/labrador) builds the engine library and defines the targets your build links: LabradorEngine; LabradorMath, the engine’s maths on its own, which the rules library links instead of the whole engine; and labrador_settings, which applies the engine’s compiler settings to your code too, warnings as errors included. Do not define your own labrador_settings; CMake stops at a second target with the same name.

    vcpkg.json
    {
    "name": "mygame",
    "version-string": "0.1.0",
    "dependencies": [
    {
    "name": "directxtk",
    "features": [
    "xaudio2redist"
    ],
    "platform": "windows"
    },
    "doctest",
    "lodepng"
    ],
    "builtin-baseline": "d92484ed3c5020c6679d095ad3e5add907887b62"
    }

    vcpkg reads only the top-level project’s manifest, so your project names the engine’s dependencies itself, among them lodepng, which reads PNG pictures, and doctest, the test framework your tests use. The builtin-baseline is Labrador’s own, which pins them to the versions the engine is built and tested with.

    CMakePresets.json
    {
    "version": 6,
    "cmakeMinimumRequired": { "major": 3, "minor": 26, "patch": 0 },
    "configurePresets": [
    {
    "name": "base",
    "hidden": true,
    "condition": {
    "type": "equals",
    "lhs": "${hostSystemName}",
    "rhs": "Windows"
    },
    "generator": "Ninja",
    "binaryDir": "${sourceDir}/out/build/${presetName}",
    "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
    "architecture": { "value": "x64", "strategy": "external" }
    },
    {
    "name": "x64-debug",
    "inherits": "base",
    "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" }
    },
    {
    "name": "x64-release",
    "inherits": "base",
    "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
    },
    {
    "name": "wasm-base",
    "hidden": true,
    "generator": "Ninja",
    "binaryDir": "${sourceDir}/out/build/${presetName}",
    "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
    "cacheVariables": {
    "VCPKG_CHAINLOAD_TOOLCHAIN_FILE": "$env{EMSDK}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake",
    "VCPKG_TARGET_TRIPLET": "wasm32-emscripten"
    }
    },
    {
    "name": "wasm-debug",
    "inherits": "wasm-base",
    "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" }
    },
    {
    "name": "wasm-release",
    "inherits": "wasm-base",
    "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
    }
    ],
    "buildPresets": [
    { "name": "x64-debug", "configurePreset": "x64-debug" },
    { "name": "x64-release", "configurePreset": "x64-release" },
    { "name": "wasm-debug", "configurePreset": "wasm-debug" },
    { "name": "wasm-release", "configurePreset": "wasm-release" }
    ],
    "testPresets": [
    {
    "name": "x64-debug",
    "configurePreset": "x64-debug",
    "output": { "outputOnFailure": true }
    },
    {
    "name": "x64-release",
    "configurePreset": "x64-release",
    "output": { "outputOnFailure": true }
    },
    {
    "name": "wasm-debug",
    "configurePreset": "wasm-debug",
    "output": { "outputOnFailure": true }
    },
    {
    "name": "wasm-release",
    "configurePreset": "wasm-release",
    "output": { "outputOnFailure": true }
    }
    ]
    }

    The x64 presets are the Windows build this page uses. Neither sets LABRADOR_RENDER_BACKEND, so both build the engine’s default renderer, Direct3D 11, which is the one to ship; Which renderer to ship says why, and how a preset of yours chooses another. The wasm presets are the browser build, which needs Emscripten installed and EMSDK set, as Build for the browser describes; until then, leave them unused.

    .gitignore
    out/
    .vs/

    It keeps two folders out of Git: out, the build, and .vs, which Visual Studio makes when it opens the project and keeps open while it runs.

  7. Build, test and run it, from the mygame folder:

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

    ctest runs your two tests and reports 100% tests passed, 0 tests failed out of 2. The window is the minimal sample’s, because so far the game is the minimal sample. The configure step installs the dependencies for this project; vcpkg reuses what it built for Labrador, so it is quicker than the first time.

    If configure stops, the first line with Error in it says why, and Troubleshooting lists the usual ones. A mistake in one of the files from step 5 or 6 usually shows as an error naming that file and a line number: open it again, select everything, paste its box again and save. Then delete the half-made build and configure again:

    Terminal window
    rmdir /s /q out\build\x64-debug
    cmake --preset x64-debug
  8. Commit it:

    Terminal window
    git add .
    git commit -m "Start from Labrador's minimal sample"

    Git prints a line beginning [master (root-commit) or [main (root-commit) and a list of the files it recorded. If it says Author identity unknown instead, do Tell Git who you are and run the git commit line again. Git may also print warnings that LF will be replaced by CRLF; they are harmless. Save and undo changes with Git is what to do with the repository from here: record each working version and go back to any of them.

Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.

All documentation versions