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.
-
Make the repository. In the x64 Native Tools Command Prompt:
Terminal window cd /d C:\devmkdir mygamecd mygamegit initGit answers
Initialized empty Git repository in C:/dev/mygame/.git/, and the prompt endsC:\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 withcd /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.
-
Add Labrador as a submodule, and check out a release:
Terminal window git submodule add https://github.com/matt439/Labrador.git external/labradorgit -C external/labrador checkout v0.3.0The 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 experimentaland ends
HEAD is now atfollowed 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 aboutgit switch.v0.3.0was 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:refnameThese 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 whatmasterhas 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-submodulesto 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.gitA clone made without it has an empty
external\labradorfolder, and configure stops withdoes not contain a CMakeLists.txt file. Inside that clone, this fills the folder in:Terminal window git submodule update --init --recursive -
Copy the minimal sample into a folder called
game:Terminal window xcopy external\labrador\samples\minimal game /E /Ixcopylists each file it copies and ends with a count, such as15 File(s) copied, that depends on the release you checked out. -
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 undergame/. Change these lines:File Change this line To 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
Changedand 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 examplenotepad game\main.cpp, use Ctrl+H to replacesamples/minimal/withgame/, and save with Ctrl+S.main_web.cppis 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. -
Replace
game\CMakeLists.txtwith 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 STATICrules/motion.cpp)target_link_libraries(MyGameRules PUBLICLabradorMathlabrador_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(MyGameTeststests/motion_tests.cpp)target_link_libraries(MyGameTests PRIVATEMyGameRulesdoctest::doctestlabrador_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(MyGamemain_web.cppstates/confirm_state.cppstates/hello_state.cpp)target_link_libraries(MyGame PRIVATEMyGameRulesLabradorEnginelabrador_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 WIN32main.cppstates/confirm_state.cppstates/hello_state.cppdpi_aware.manifest)target_link_libraries(MyGame PRIVATEMyGameRulesLabradorEnginelabrador_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 PRIVATEGAME_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_BUILDCOMMAND "${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_BUILDCOMMAND "${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.0engine selected above. A newer development engine provideslabrador_find_package, which adds manifest advice when a dependency is missing; when that command is absent the file uses CMake’s ordinaryfind_package.To do that in Notepad, open the file:
Terminal window notepad game\CMakeLists.txtIn 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 libraryMyGameRules, the testsMyGameTestsandMyGameSmokeTests, and the content targetgame_content. Itsif(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_directoriesmakes the folder abovegamethe 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.
MyGameTestsruns the rules ingame\ruleswith no window and no graphics device.MyGameSmokeTestsstarts 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. -
Add the project’s own build files to the
mygamefolder. 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.txttype nul > vcpkg.jsontype nul > CMakePresets.jsontype nul > .gitignoreThen open them one at a time, after you have copied that file’s box:
Terminal window notepad CMakeLists.txtTerminal window notepad vcpkg.jsonTerminal window notepad CMakePresets.jsonTerminal window notepad .gitignoreMaking the file first keeps Notepad from adding
.txtto the name. Each name must match exactly, the leading dot of.gitignoreincluded.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; andlabrador_settings, which applies the engine’s compiler settings to your code too, warnings as errors included. Do not define your ownlabrador_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, anddoctest, the test framework your tests use. Thebuiltin-baselineis 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
x64presets are the Windows build this page uses. Neither setsLABRADOR_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. Thewasmpresets are the browser build, which needs Emscripten installed andEMSDKset, 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. -
Build, test and run it, from the
mygamefolder:Terminal window cmake --preset x64-debugcmake --build --preset x64-debugctest --preset x64-debugout\build\x64-debug\game\MyGame.exectest 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
Errorin 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-debugcmake --preset x64-debug -
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 saysAuthor identity unknowninstead, do Tell Git who you are and run thegit commitline again. Git may also print warnings thatLF 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.