Skip to content

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.

  1. See which release you have.

    Terminal window
    type C:\dev\mygame\README.txt

    The line Labrador version: names it, for example v0.3.0.

  2. Download the newest starter ZIP into C:\dev.

    These pages are v0.4.0's own documentation, so the ZIP below is v0.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.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, 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.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.

    Compare the version in the ZIP’s name, the part after labrador-starter- such as v0.3.0, with the Labrador version: line from step 1. If they are the same, there is nothing newer: delete the ZIP with del C:\dev\labrador-starter-*.zip and stop here.

  3. Extract it beside your project, into a new folder C:\dev\new:

    Terminal window
    mkdir C:\dev\new
    tar -xf C:\dev\labrador-starter-v0.4.0.zip -C C:\dev\new

    The new project is now C:\dev\new\mygame. If mkdir says A subdirectory or file C:\dev\new already exists., a folder is left from an earlier move: look in it, delete it with rmdir /s /q C:\dev\new if you no longer need it, and run the box again.

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

    Read every heading above the one for your release, then close Notepad. The template your game folder 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.md

    Its 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-57 or OCA-78 in an entry are the owner’s references to other records, not things for you to do.

  5. Put your game into the new project. These lines delete the new project’s copy of the template and copy your game folder in its place:

    Terminal window
    rmdir /s /q C:\dev\new\mygame\game
    xcopy C:\dev\mygame\game C:\dev\new\mygame\game /E /I

    Check the first line before you run it: it must name C:\dev\new\mygame\game, the new copy, and not your own. xcopy lists each file it copies and ends with a count such as 15 File(s) copied.

    Your project can hold more than game: a picture such as hero.png from Put a picture in your game, web-release.bat from Put your game on the web, and, if you put the project in Git, the hidden .git folder that holds its history. List the top folder of both projects:

    Terminal window
    dir /a /b C:\dev\mygame
    dir /a /b C:\dev\new\mygame

    /a lists hidden names such as .git as well. The second list is the starter’s own:

    Output
    .github
    .gitignore
    CMakeLists.txt
    CMakePresets.json
    external
    game
    README.txt
    vcpkg.json

    Every 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 with copy and a folder with xcopy. 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 /H

    Each copy prints 1 file(s) copied. and xcopy ends with its count; /H copies hidden files too. These copy rather than move, so your old project keeps its own until you delete it. Run the two dir lines again: now only out and .vs may be in the first list and not the second.

  6. 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.txt
    fc C:\dev\mygame\CMakePresets.json C:\dev\new\mygame\CMakePresets.json
    fc C:\dev\mygame\vcpkg.json C:\dev\new\mygame\vcpkg.json
    fc C:\dev\mygame\external\labrador\website\src\walkthrough\game-CMakeLists.txt C:\dev\new\mygame\external\labrador\website\src\walkthrough\game-CMakeLists.txt
    fc C:\dev\mygame\.gitignore C:\dev\new\mygame\.gitignore
    fc C:\dev\mygame\.github\workflows\ci.yml C:\dev\new\mygame\.github\workflows\ci.yml

    FC: no differences encountered means the file is the same in both. Otherwise fc lists the lines that differ, as Reading fc below explains. What to do with each:

    • CMakeLists.txt and CMakePresets.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.txt at the two releases. If it differs, the release changed that file, and your own game\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.txt

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

      It prints 1 file(s) copied. The new copy can list a file your game folder 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 with notepad 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.

    • .gitignore and .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 .gitignore is 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.

  7. 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: from v0.2.0 to v0.3.0, for example, one line renames mattmath:: to labrador:: and Vector2F::ZERO to Vector2F::zero in every file of your game folder. Run them from the new project’s folder:

    Terminal window
    cd /d C:\dev\new\mygame

    If 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\new with rmdir /s /q C:\dev\new, and ask in Labrador’s issues, naming the two releases and the entry.

  8. Swap the folders. This renames your project to mygame-old and moves the new one to C:\dev\mygame:

    Terminal window
    cd /d C:\dev
    ren C:\dev\mygame mygame-old
    move C:\dev\new\mygame C:\dev\mygame
    rmdir C:\dev\new
    cd /d C:\dev\mygame

    move prints 1 dir(s) moved. If ren says The 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 says A duplicate file name exists, or the file cannot be found., a mygame-old is left from an earlier move; delete it with rmdir /s /q C:\dev\mygame-old once you are sure you do not need it, and run the box again.

  9. Configure, build, test and play, in the new project:

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

    The new project has no build folder yet, so this is a first build: configure installs whatever a changed vcpkg.json needs, 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 new game\CMakeLists.txt lists a file your game folder 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, in C:\dev\mygame now, 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.
  10. 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 --short
    git add .
    git commit -m "Move to Labrador v0.4.0"

    Put the new release in place of v0.4.0. git status --short lists the changed and new files, and git add . may print line-end warnings, which are harmless. If git status says not 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.

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:

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

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

You added lodepng to vcpkg.json in your old project, and the comparison above shows it. Open the new project’s file:

Terminal window
notepad C:\dev\new\mygame\vcpkg.json

Find "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:

Output
Failed to load manifest from directory C:\dev\mygame
C:\dev\mygame\vcpkg.json:13:5: error: Unexpected character in middle of array
on expression: "lodepng"
^
-- Running vcpkg install - failed

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

Until you delete mygame-old, your previous project is untouched. To use it again, rename the new one aside and the old one back:

Terminal window
cd /d C:\dev
ren C:\dev\mygame mygame-new
ren C:\dev\mygame-old mygame

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

Terminal window
rmdir /s /q C:\dev\mygame-new

To try the move again later, start again at step 2.

When the new project builds, passes its tests and plays as you expect, delete the old one:

Terminal window
rmdir /s /q C:\dev\mygame-old

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

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.

All documentation versions