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. Allow time to rebuild the project and try the parts of the game you changed. The v0.4.0 starter download is about 13 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. Note one route through your game that you can repeat afterwards. For example, collect an item, finish a level and restart. Keep any expected score, custom controls and content you need to check.

  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. If you replaced the starter’s README, open external\labrador\vcpkg.json and read the engine’s version-string. The top-level vcpkg.json identifies your game.

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

    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, 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, your project already has this release. Stop here.

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

    Terminal window
    if exist C:\dev\new (echo C:\dev\new already exists. Nothing was extracted.) else (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 the command prints C:\dev\new already exists. Nothing was extracted., inspect the existing folder, rename it to an unused name to keep it, then 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 can require an edit where your game uses that API. Step 7 shows examples. 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 /H

    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 includes hidden names such as .git. A v0.4.0 starter also has build.cmd, test.cmd, play.cmd, labrador.vsconfig and a tools folder. Copy the project files you added. Leave behind out and .vs, which the tools regenerate. 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. A top-level comparison can miss a game script inside a folder that both projects have. This read-only command lists old files missing from the new tree, including files inside tools and .github. It skips the engine, Git’s own files and the two build folders.

    Terminal window
    robocopy C:\dev\mygame C:\dev\new\mygame /L /S /XJ /XX /XC /XN /XO /FP /NDL /NJH /NJS /XD C:\dev\mygame\external\labrador C:\dev\mygame\.git C:\dev\mygame\out C:\dev\mygame\.vs

    Copy each missing file your game owns into the same relative folder, then run the command again. If you customized a file that now exists at the same path in both projects, compare the two copies with fc and merge your edits. The missing-file list checks names only.

  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 unsure which differences are yours, compare the old project’s file with the unmodified copy in the old release ZIP. If you committed that starter to Git before editing it, git diff --name-status STARTER -- . in your old project lists tracked files you changed. Replace STARTER with the commit that imported the starter. Reapply your changes to the new release’s version. Check custom assets, scripts and tests even if the executable builds.

  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. For v0.4.0, for example, check positional application options and any direct collision or sprite-sheet calls. Run that page’s commands 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

    If you renamed the game, use its executable name in the last command. 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. Check that CTest still lists your game’s tests and that each passes. Repeat the play route you chose at the start, including a restart. If you ship a browser build, run its build and play that route in the browser too. This catches missing content or controls that a successful native build can leave unnoticed.

    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. The surrounding lines help you locate the edit. A v0.3.0 game added fmt to format its timer. The dependency block from the third comparison in step 6 shows that the new starter adds lodepng:

Output
***** C:\DEV\MYGAME\vcpkg.json
"doctest",
"fmt"
],
***** C:\DEV\NEW\MYGAME\VCPKG.JSON
"doctest",
"lodepng"
],
*****

The first block is your file, the second the new project’s. The final manifest needs both fmt for the game and lodepng for the engine. Your own project name and version may also show up in this comparison.

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.

To carry the timer’s fmt dependency forward, open the new project’s file:

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

Find "lodepng", put a comma after it, and add your library on the next line, so that the end of the list reads:

"doctest",
"lodepng",
"fmt"
],

Keep the new starter’s builtin-baseline and reapply your game’s name and version if you changed them. Save, then run the third comparison again. In this example the new manifest still differs from the old one by the addition of lodepng. Every entry in the dependency list except the last ends with a comma. If configure reports Unexpected character in middle of array, check the comma on the preceding line and 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. Before running it, repeat step 5’s file comparison, using C:\dev\mygame-old as the source and C:\dev\mygame as the destination. Update the excluded paths to use mygame-old too. Check any edits you made in the old folder after step 5, including edits to files that both projects have.

On 20 November 2026, a two-room courier game named Night Dispatch was moved between the published v0.3.0 and v0.4.0 starter ZIPs. Its timer needed the game’s fmt dependency alongside the engine’s new lodepng. Its postal cart used the renamed collision call. The first browser playthrough command failed because its script had been missed inside tools, a folder the new starter also supplies. Step 5 now checks for missing files inside shared folders. The migration record identifies the archives, game revisions and results.

On 30 October 2026 the original procedure was run 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. At that date there were no two releases with starter ZIPs, 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. In the procedure at the time, mkdir a second time reported that the destination already existed, and xcopy copied 15 files. The four comparisons showed 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. After the game dependency was restored in the new manifest with a text-editing tool, 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 reproduced the first run. They found two gaps, since filled. Before a release had a starter ZIP, step 2 sent a reader who already had a project to start again on the Git route. The fallback now explains when a project can move. Going back also left C:\dev\mygame-new unexplained. 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 that starter’s eight names. 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.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions