Move a starter project to a newer Labrador
A project made from the starter ZIP holds the engine as a plain
folder, external\labrador, at the release it came with. Nothing moves it for you. To take a
newer release, you download that release’s starter ZIP, put your game folder and everything
else you added into it, and switch to it once it builds. Your old project stays as it is, under
another name, until you delete it, so a release that does not work for you costs nothing. It
takes about half an hour, most of it reading what changed, and downloads about 9 MB.
This is safer than replacing external\labrador by itself, because the project’s own files
(CMakeLists.txt, CMakePresets.json and above all vcpkg.json, which pins the engine’s
libraries) must match the engine, and the new ZIP has them matching.
If your project is in Git with the engine as a submodule, because you followed Start your own project or Put your project in Git, use Move your engine pin instead. A project in Git that keeps the engine as plain files, as Put your project on GitHub leaves it, moves by this page: step 5 carries its history across and step 10 commits the move.
The commands run in the x64 Native Tools Command Prompt. They assume your project is
C:\dev\mygame; if yours has another name, put it in place of mygame wherever a command has
C:\dev\mygame. Close Visual Studio, your game, and any File Explorer window showing the
project before you start.
-
See which release you have.
Terminal window type C:\dev\mygame\README.txtThe line
Labrador version:names it, for examplev0.3.0. -
Download the newest starter ZIP into
C:\dev.These pages are
v0.4.0's own documentation, so the ZIP below isv0.4.0's. If a newer release has come out since, follow this page in its documentation, from All documentation versions, instead.The starter ZIP for Labrador
v0.4.0islabrador-starter-v0.4.0.zip. This downloads it intoC:\dev, with thecurlprogram that comes with Windows:Terminal window cd /d C:\devcurl -fL -o labrador-starter-v0.4.0.zip https://github.com/matt439/Labrador/releases/download/v0.4.0/labrador-starter-v0.4.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.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.zipin its Assets list and click it. The other files there are not the project: a file whose name beginslabrador-docs-is a copy of this website, and GitHub's Source code links save the engine alone, asLabrador-and a version, with nomygamefolder (Not the starter ZIP). Your browser saves it in your Downloads folder. This moves it toC:\dev:Terminal window move "%USERPROFILE%\Downloads\labrador-starter-v0.4.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.Compare the version in the ZIP’s name, the part after
labrador-starter-such asv0.3.0, with theLabrador version:line from step 1. If they are the same, there is nothing newer: delete the ZIP withdel C:\dev\labrador-starter-*.zipand stop here. -
Extract it beside your project, into a new folder
C:\dev\new:Terminal window mkdir C:\dev\newtar -xf C:\dev\labrador-starter-v0.4.0.zip -C C:\dev\newThe new project is now
C:\dev\new\mygame. IfmkdirsaysA subdirectory or file C:\dev\new already exists., a folder is left from an earlier move: look in it, delete it withrmdir /s /q C:\dev\newif you no longer need it, and run the box again. -
Read what changed. Every change in the engine that a game can notice is an entry in CHANGES.md, under the heading of the release that made it, with what to do about it when there is something to do. Open the new release’s copy:
Terminal window notepad C:\dev\new\mygame\external\labrador\CHANGES.mdRead every heading above the one for your release, then close Notepad. The template your
gamefolder was copied from keeps its own list of changes, newest first and dated, of what a copy taken earlier would want:Terminal window notepad C:\dev\new\mygame\external\labrador\samples\minimal\README.mdIts list is under A copy is yours. Read the entries dated after your release, which is the date beside your release’s heading in CHANGES.md. Neither list needs anything from you unless an entry says so; note the ones that do for step 7. An entry marked Source break is one your code may need an edit for, and step 7’s page has it as a command. Numbers such as
SM-57orOCA-78in an entry are the owner’s references to other records, not things for you to do. -
Put your game into the new project. These lines delete the new project’s copy of the template and copy your
gamefolder in its place:Terminal window rmdir /s /q C:\dev\new\mygame\gamexcopy C:\dev\mygame\game C:\dev\new\mygame\game /E /ICheck the first line before you run it: it must name
C:\dev\new\mygame\game, the new copy, and not your own.xcopylists each file it copies and ends with a count such as15 File(s) copied.Your project can hold more than
game: a picture such ashero.pngfrom Put a picture in your game,web-release.batfrom Put your game on the web, and, if you put the project in Git, the hidden.gitfolder that holds its history. List the top folder of both projects:Terminal window dir /a /b C:\dev\mygamedir /a /b C:\dev\new\mygame/alists hidden names such as.gitas well. The second list is the starter’s own:Output .github.gitignoreCMakeLists.txtCMakePresets.jsonexternalgameREADME.txtvcpkg.jsonEvery name in the first list that the second lacks is yours, except
out, your build folder, and.vs, Visual Studio’s, which the new project makes again. Copy each one across, a file withcopyand a folder withxcopy. For the three examples above:Terminal window copy C:\dev\mygame\hero.png C:\dev\new\mygame\copy C:\dev\mygame\web-release.bat C:\dev\new\mygame\xcopy C:\dev\mygame\.git C:\dev\new\mygame\.git /E /I /HEach
copyprints1 file(s) copied.andxcopyends with its count;/Hcopies hidden files too. These copy rather than move, so your old project keeps its own until you delete it. Run the twodirlines again: now onlyoutand.vsmay be in the first list and not the second. -
Compare the project’s own files. Run these six lines. Each compares a file in your project with the new project’s:
Terminal window fc C:\dev\mygame\CMakeLists.txt C:\dev\new\mygame\CMakeLists.txtfc C:\dev\mygame\CMakePresets.json C:\dev\new\mygame\CMakePresets.jsonfc C:\dev\mygame\vcpkg.json C:\dev\new\mygame\vcpkg.jsonfc C:\dev\mygame\external\labrador\website\src\walkthrough\game-CMakeLists.txt C:\dev\new\mygame\external\labrador\website\src\walkthrough\game-CMakeLists.txtfc C:\dev\mygame\.gitignore C:\dev\new\mygame\.gitignorefc C:\dev\mygame\.github\workflows\ci.yml C:\dev\new\mygame\.github\workflows\ci.ymlFC: no differences encounteredmeans the file is the same in both. Otherwisefclists the lines that differ, as Reading fc below explains. What to do with each:-
CMakeLists.txtandCMakePresets.json: keep the new project’s, which matches the new engine, unless you changed yours yourself. Then open the new one with Notepad and make your change again in it. -
vcpkg.json: the new project’s names the libraries the new engine needs, so keep it, and add back any library you added to yours. A worked merge below does exactly that. -
The fourth compares the template’s
game\CMakeLists.txtat the two releases. If it differs, the release changed that file, and your owngame\CMakeLists.txt, which you just copied across, does not have the change yet.Find out whether you ever changed your
game\CMakeLists.txt, for example to add a source file or a library, by comparing it with the template it started from:Terminal window fc C:\dev\mygame\game\CMakeLists.txt C:\dev\mygame\external\labrador\website\src\walkthrough\game-CMakeLists.txtIf that prints
FC: no differences encountered, you never changed it, and the new release’s copy can simply replace it:Terminal window copy /y C:\dev\new\mygame\external\labrador\website\src\walkthrough\game-CMakeLists.txt C:\dev\new\mygame\game\CMakeLists.txtIt prints
1 file(s) copied.The new copy can list a file yourgamefolder does not have yet: Update your code for a newer Labrador says which, for each release, and step 9 names it if you miss one. If the comparison did list differences, those are your own changes: keep your file, open it withnotepad C:\dev\new\mygame\game\CMakeLists.txt, and make in it the changes the fourth comparison shows, using CHANGES.md and the template’s list from step 4 to see why each was made. -
.gitignoreand.github\workflows\ci.yml: keep the new project’s, and add back any line you added to yours. A.vs/line that Put your project on GitHub had you add to.gitignoreis in the new one already, so leave it out.
If you are not sure what you changed, keeping the new project’s file and adding back only the additions you remember making is safe: the build in step 9 tells you if one is missing, and your old project keeps every file until you delete it.
-
-
Update your code for the new release. If CHANGES.md or the template’s list in step 4 asked for an edit, make it now, in
C:\dev\new\mygame. Update your code for a newer Labrador gives the edits for each release as commands to copy: fromv0.2.0tov0.3.0, for example, one line renamesmattmath::tolabrador::andVector2F::ZEROtoVector2F::zeroin every file of yourgamefolder. Run them from the new project’s folder:Terminal window cd /d C:\dev\new\mygameIf an entry asks for something you cannot follow, stop here and keep using your old project, which this page has not changed: delete
C:\dev\newwithrmdir /s /q C:\dev\new, and ask in Labrador’s issues, naming the two releases and the entry. -
Swap the folders. This renames your project to
mygame-oldand moves the new one toC:\dev\mygame:Terminal window cd /d C:\devren C:\dev\mygame mygame-oldmove C:\dev\new\mygame C:\dev\mygamermdir C:\dev\newcd /d C:\dev\mygamemoveprints1 dir(s) moved.IfrensaysThe process cannot access the file because it is being used by another process., a window still has the project open, often another command prompt that is in it, Visual Studio, or Explorer: close it and run the box again. If it saysA duplicate file name exists, or the file cannot be found., amygame-oldis left from an earlier move; delete it withrmdir /s /q C:\dev\mygame-oldonce you are sure you do not need it, and run the box again. -
Configure, build, test and play, in the new project:
Terminal window cmake --preset x64-debugcmake --build --preset x64-debugctest --preset x64-debugout\build\x64-debug\game\MyGame.exeThe new project has no build folder yet, so this is a first build: configure installs whatever a changed
vcpkg.jsonneeds, which took 17 seconds when vcpkg had the packages already and can take a few minutes when it has to build one. The build compiles the engine and your game, about 100 steps, and both tests pass.The build applies the engine’s compiler settings to your code, warnings as errors among them, so a name the new engine renamed, or a warning a newer engine causes in your code, stops it; the message names the file and line. When it stops:
Cannot find source file:with a file name, from configure: the newgame\CMakeLists.txtlists a file yourgamefolder lacks. Update your code for a newer Labrador says where to copy it from.- An error naming something CHANGES.md renamed or removed, such as
'mattmath': is not a class or namespace name: step 7’s edits are missing. Make them, inC:\dev\mygamenow, and build again. - Anything else: Read a build error shows how to find the line that matters. If it does not match a CHANGES.md entry you understand, go back to your old project with the box under Going back, and report the first error in Labrador’s issues with the two releases.
-
Commit the move, if your project is in Git. Step 5 copied its history, so Git in the new project sees the move as changes to the files it already tracks:
Terminal window git status --shortgit add .git commit -m "Move to Labrador v0.4.0"Put the new release in place of
v0.4.0.git status --shortlists the changed and new files, andgit add .may print line-end warnings, which are harmless. Ifgit statussaysnot a git repository, the project was not in Git, or step 5 did not copy.git. If you keep the project on GitHub, push as Put your project on GitHub does.
Reading fc
Section titled “Reading fc”fc prints, for each place two files differ, a block of lines from the first file and then the
same place in the second, each headed by ***** and the file’s name, and a lone ***** ending
the pair. Around the lines that differ it prints one unchanged line before and one after, so you
can find the place. This is the third comparison of step 6 for a project that had added
lodepng to its vcpkg.json:
Comparing files C:\DEV\MYGAME\vcpkg.json and C:\DEV\NEW\MYGAME\VCPKG.JSON***** C:\DEV\MYGAME\vcpkg.json }, "doctest", "lodepng" ],***** C:\DEV\NEW\MYGAME\VCPKG.JSON }, "doctest" ],*****The first block is your file, the second the new project’s. }, and ], are the same in both
and only mark the place. In between, yours has "doctest", with a comma and a "lodepng" line,
and the new one "doctest" alone: the difference is your added library. fc writes the names in
capitals; the files are the same ones.
A change in the release looks the same, the other way round. The fourth comparison, from
v0.2.0 to v0.3.0, prints three pairs; this is the last:
***** C:\DEV\MYGAME\EXTERNAL\LABRADOR\WEBSITE\SRC\WALKTHROUGH\game-CMakeLists.txt states/hello_state.cpp)***** C:\DEV\NEW\MYGAME\EXTERNAL\LABRADOR\WEBSITE\SRC\WALKTHROUGH\GAME-CMAKELISTS.TXT states/hello_state.cpp dpi_aware.manifest)*****The new template lists one more file, dpi_aware.manifest, after states/hello_state.cpp. The
other two pairs change MattMath to LabradorMath and add two comment lines.
A worked merge
Section titled “A worked merge”You added lodepng to vcpkg.json in your old project, and the comparison above shows it. Open
the new project’s file:
notepad C:\dev\new\mygame\vcpkg.jsonFind "doctest", put a comma after it, and add your library on the next line, so that the end
of the list reads:
"doctest", "lodepng" ],Save and close Notepad, then run the third comparison again. It prints
FC: no differences encountered: the new file now has your library and everything else the new
engine wants. Every entry in a list but the last ends with a comma. A missing comma stops step
9’s configure with an error that names the file, its line and the place in it:
Failed to load manifest from directory C:\dev\mygameC:\dev\mygame\vcpkg.json:13:5: error: Unexpected character in middle of array on expression: "lodepng" ^-- Running vcpkg install - failedHere line 13, the "lodepng" line, follows "doctest" with no comma. Put the comma back, compare
the file with the box above again, and run the configure again.
Going back
Section titled “Going back”Until you delete mygame-old, your previous project is untouched. To use it again, rename the
new one aside and the old one back:
cd /d C:\devren C:\dev\mygame mygame-newren C:\dev\mygame-old mygameEach ren prints nothing. Your previous project is C:\dev\mygame again, and builds as it did,
and the new one is C:\dev\mygame-new. Keep it if you want to look at it or finish it later,
as long as you remember it is not the project you work in. Once you no longer need it, delete
it, and everything in it, without being asked:
rmdir /s /q C:\dev\mygame-newTo try the move again later, start again at step 2.
Deleting the old project
Section titled “Deleting the old project”When the new project builds, passes its tests and plays as you expect, delete the old one:
rmdir /s /q C:\dev\mygame-oldIt deletes the folder and everything in it without asking. Check first that the new project
has everything of yours: run step 5’s two dir lines with C:\dev\mygame-old in place of
C:\dev\mygame and C:\dev\mygame in place of C:\dev\new\mygame, and copy across anything
but out and .vs that only the old project has. Any change you made to the old project after
step 5 is in that folder only, so check you have none as well.
What was checked
Section titled “What was checked”On 30 October 2026 the commands on this page were run as written, in a command prompt, on two projects extracted from starter ZIPs of the same development revision, so the comparisons found nothing to change and the rebuilt project’s tests passed.
On 31 October 2026 a move between releases that differ was made. No two releases with starter
ZIPs exist yet, so the old project was extracted from a starter ZIP that starter_zip.py made of
a clean clone at v0.2.0, and the new one from a starter ZIP of this tree, whose README.txt
says it is a development build; both stood in C:\dev\g11-author\up in place of C:\dev, and the
quoted output has that folder changed back. The old project had its greeting changed and
lodepng added to its vcpkg.json, as a reader’s would. Steps 1, 3, 5, 6 and 8 ran as worded:
mkdir a second time printed the message step 3 quotes, xcopy copied 15 files, and the four
comparisons printed what Reading fc quotes, CMakeLists.txt differing in a
comment, CMakePresets.json in a Windows-only condition, vcpkg.json in the added library and
the template’s game\CMakeLists.txt in three places. The game’s own game\CMakeLists.txt had
never changed, so the new one was copied. The merge in A worked merge was made
with a tool rather than Notepad, after which fc found no differences, and the missing comma’s
error was made on purpose. Step 9 then stopped first at configure, on the missing
dpi_aware.manifest, then at the build, on mattmath, as
Update your code for a newer Labrador quotes; after that page’s edits the
project built, passed both tests and its smoke test exited 0. The first configure of the new
project took 17 seconds. Later configures on the machine sat at vcpkg’s
Detecting compiler hash line for up to 30 minutes while another project’s configure was also
running Visual Studio’s vcpkg; why was not found, and the builds after it were configured with
vcpkg’s install turned off, until a later configure with it, as step 9 gives it, finished in 3
seconds and the project built and passed both tests. Going back’s two ren lines brought the
v0.2.0 project back under its own name. Step 2’s download and step 4’s Notepad were not run in
this move; the step 2 comparison is of the names step 1 and the download print.
A second person then followed the page as worded with their own projects from the same two ZIPs,
at C:\dev\g11-follow\up. Steps 1, 3, 5, 6, 8 and 9, all four fc outputs, the missing comma’s
error, both ren messages of step 8 and Going back gave what is quoted. They found two gaps,
since filled: step 2, as this site shows it while no release has a starter ZIP, sent a reader who
already has a project to start again on the Git route, and now says there is nothing to move to
and how a project in Git can move instead; and Going back left C:\dev\mygame-new with nothing
said about it. On the same day at C:\dev\g11-fixer\up, an old project configured and built in
place, renamed to mygame-old with a new one moved into its name, came back with Going back’s
two lines, each printing nothing; its build then had nothing to compile and both tests passed,
and rmdir /s /q deleted mygame-new and printed nothing. Step 2’s text for a release that has
a starter ZIP was not shown, because no release had one then.
On 13 November 2026 the files outside game were checked. Two projects were extracted with
Windows’ tar from one starter ZIP of a development revision; the old one was put in Git, given
a hero.png, an empty web-release.bat, .vs and out folders and a second .vs/ line in
.gitignore, and committed. Step 5’s dir /a /b lines listed .git, .vs, hero.png, out
and web-release.bat in the old project beyond the starter’s eight names, which the new one
listed as quoted; the two copy lines each printed 1 file(s) copied. and xcopy copied the
hidden .git folder. Step 6’s two added comparisons found the extra .vs/ line and no
difference in ci.yml. After step 8’s swap, git status --short in the new project listed
.gitignore alone, since both projects came from one ZIP; step 10’s commit followed the old
project’s two in git log, the old project’s own history was unchanged, and rmdir /s /q
deleted mygame-old with its .git. Nothing was built in this check, and it was not a move
between two releases.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.