Build for the browser
The game you started from the starter project or
Start your own project builds for a browser as well as for
Windows. The same states, rules and content are compiled to WebAssembly by Emscripten, the
renderer draws through WebGL2, and the result is a web page you open in Chrome, Edge or Firefox.
Nothing in your game’s code changes: the browser build uses a second entry point,
main_web.cpp, and a page, web/shell.html, both of which came with your project.
This page installs Emscripten, builds the page, serves it from your own machine and opens it, then changes the game and sees the change. The first time takes about 20 minutes, most of it the download; you need about 2.2 GB of free disk, and no Git. To then put the page on the internet for a friend to play, Put your game on the web continues from here.
You need the project as Get the starter project leaves it, in
C:\dev\mygame, and the x64 Native Tools Command Prompt from
Install the tools. Every command on this page runs in that
prompt, one box at a time.
Install Emscripten
Section titled “Install Emscripten”Labrador’s browser build is built and tested with Emscripten 6.0.12, the version its
CI pins. Install that version rather than the latest: the engine compiles with warnings as errors,
and a newer compiler can warn about something the pinned one does not. Emscripten comes with its
own installer, emsdk, which needs Python the first time it runs and then brings its own.
-
Check that Python runs. In the x64 Native Tools Command Prompt:
Terminal window python --versionIf it prints
Python 3.10or a later version, such asPython 3.14.2, go on to step 2. emsdk refuses an older Python, such asPython 3.9.13: install a new one as below. Otherwise it prints one of these:'python' is not recognized as an internal or external command, operable program or batch file.: Python is not installed.Python was not found; run without arguments to install from the Microsoft Store, or disable this shortcut from Settings > Manage App Execution Aliases.: Python is not installed, andpythonis Windows’ shortcut to the Microsoft Store. Typingpythonalone opens the Store.
Then install the Python install manager, which is what python.org now gives Windows: open its page in the Microsoft Store and click Install, or run this in the prompt:
Terminal window winget install 9NQ7512CXL7T -e --accept-package-agreements --accept-source-agreements --disable-interactivityClose the prompt, open a new x64 Native Tools Command Prompt, and run
python --versionagain. With the install manager and no Python yet, Python’s documentation says the firstpythondownloads and installs the latest Python before it answers, so it can take a while. Ifpythonstill opens the Store, open Start, typeManage app execution aliases, open it, and turn the Python (default) entries off and on again, as Python’s documentation says. Python’s Using Python on Windows has the other ways to install it. -
Download emsdk. It is a ZIP of about 210 KB from GitHub, and Windows’ own
curlandtarfetch and extract it, so you do not need Git or a browser:Terminal window if not exist C:\dev mkdir C:\devcd /d C:\devcurl.exe --fail --location --output emsdk.zip https://github.com/emscripten-core/emsdk/archive/refs/tags/6.0.12.ziptar -xf emsdk.zipren emsdk-6.0.12 emsdkdel emsdk.zipdir /b emsdk\emsdk.batcurlshows a small table of progress and is done in a second;tar,renanddelprint nothing when they work. The ZIP holds one folder,emsdk-and the version, whichrenrenames toC:\dev\emsdk. The last line checks it, and prints:Output emsdk.bat -
Install Emscripten 6.0.12. This downloads the compiler, and the Node and Python it runs on, about 770 MB, and unpacks them to about 2.1 GB, all inside
C:\dev\emsdk:Terminal window cd /d C:\dev\emsdkemsdk install 6.0.12It took a minute on the fast connection where this page was checked. On a 25 Mbit/s connection the download alone takes about four minutes; leave it running. While each of the three downloads runs, a line under its
Downloading:line counts the bytes and the per cent, such as786432 [2.11%], and theUnpackingline then takes its place. It ends:Output Resolving SDK version '6.0.12' to 'sdk-releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit'Installing SDK 'sdk-releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit'..Installing tool 'node-24.19.0-64bit'..Downloading: C:/dev/emsdk/downloads/node-v24.19.0-win-x64.zip from https://storage.googleapis.com/webassembly/emscripten-releases-builds/deps/node-v24.19.0-win-x64.zip, 37304352 BytesUnpacking 'C:/dev/emsdk/downloads/node-v24.19.0-win-x64.zip' to 'C:/dev/emsdk/node/24.19.0_64bit'Done installing tool 'node-24.19.0-64bit'.Installing tool 'python-3.13.3-64bit'..Downloading: C:/dev/emsdk/downloads/python-3.13.3-0-win-amd64.zip from https://storage.googleapis.com/webassembly/emscripten-releases-builds/deps/python-3.13.3-0-win-amd64.zip, 29736374 BytesUnpacking 'C:/dev/emsdk/downloads/python-3.13.3-0-win-amd64.zip' to 'C:/dev/emsdk/python/3.13.3_64bit'Done installing tool 'python-3.13.3-64bit'.Installing tool 'releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit'..Downloading: C:/dev/emsdk/downloads/6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-wasm-binaries.zip from https://storage.googleapis.com/webassembly/emscripten-releases-builds/win/6e9f6885cb17a3d6c8fd488a5cff730f50aba61d/wasm-binaries.zip, 700727317 BytesUnpacking 'C:/dev/emsdk/downloads/6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-wasm-binaries.zip' to 'C:/dev/emsdk/upstream'Done installing tool 'releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit'.Done installing SDK 'sdk-releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit'.The long numbers are the release’s name inside Emscripten; they are the same on every machine. If it stops with
error:instead, see If something fails. -
Make it the version emsdk uses:
Terminal window emsdk activate 6.0.12It takes a second or two and prints this, with the very long
PATH =line shortened here:Output Resolving SDK version '6.0.12' to 'sdk-releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit'Setting the following tools as active:node-24.19.0-64bitpython-3.13.3-64bitreleases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bitNext steps:- Consider running `emsdk activate` with --permanent or --systemto have emsdk settings available on startup.Adding directories to PATH:PATH += C:\dev\emsdkPATH += C:\dev\emsdk\upstream\emscriptenSetting environment variables:PATH = C:\dev\emsdk;C:\dev\emsdk\upstream\emscripten;C:\Program Files\Microsoft Visual Studio\18\Communit...EMSDK = C:/dev/emsdkEMSDK_NODE = C:\dev\emsdk\node\24.19.0_64bit\node.exeEMSDK_PYTHON = C:\dev\emsdk\python\3.13.3_64bit\python.exeClearing existing environment variable: EMSDK_PYThe changes made to environment variables only apply to the currently running shell instance. Use the 'emsdk_env.bat' to re-enter this environment later, or if you'd like to register this environment permanently, rerun this command with the option --permanent.Do not add
--permanent. It would put Emscripten’s compiler, Node and Python in front of every prompt on the machine, the Windows build’s included. The next section sets them up in the one prompt that needs them instead.
Nothing is installed outside C:\dev\emsdk, and from now on emsdk runs on its own Python, not
the one from step 1. To uninstall Emscripten, delete the folder: rmdir /s /q C:\dev\emsdk.
Set EMSDK in your build prompt
Section titled “Set EMSDK in your build prompt”The browser build needs two set-ups in one prompt. The x64 Native Tools Command Prompt puts
CMake and Ninja on your PATH and sets VCPKG_ROOT, which the browser build still uses;
Emscripten’s emsdk_env.bat sets EMSDK and puts its compiler, emcc, on your PATH. Open the
Native Tools prompt as always, then run Emscripten’s script in it, and go to your project:
C:\dev\emsdk\emsdk_env.batcd /d C:\dev\mygameDo this in every new prompt you use for a browser build. The settings last until you close
the prompt, and do not change the Windows build. The script prints a screenful, which is normal;
the PATH = line is very long, and is shortened here:
Setting up EMSDK environment (suppress these messages with EMSDK_QUIET=1)Adding directories to PATH:PATH += C:\dev\emsdkPATH += C:\dev\emsdk\upstream\emscripten
Setting environment variables:PATH = C:\dev\emsdk;C:\dev\emsdk\upstream\emscripten;C:\Program Files\Microsoft Visual Studio\18\Communit...EMSDK = C:/dev/emsdkEMSDK_NODE = C:\dev\emsdk\node\24.19.0_64bit\node.exeEMSDK_PYTHON = C:\dev\emsdk\python\3.13.3_64bit\python.exeClearing existing environment variable: EMSDK_PYRun in the same prompt a second time, it prints only three lines: the first, Setting environment variables: and the last. It prints the same three lines the first time if you run it in the
prompt where you have just run emsdk activate, because activate has already set everything.
Check that it worked:
echo %EMSDK%emcc --versionC:/dev/emsdkshared:INFO: (Emscripten: Running sanity checks)emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 6.0.12 (5488e0871d46d19a3209988190fa6a653126256f)Copyright (C) 2026 the Emscripten authors (see AUTHORS.txt)This is free and open source software under the MIT license.There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.The sanity checks line appears only the first time emcc runs. If echo %EMSDK% prints
%EMSDK%, the script has not run in this prompt.
Build the game as a page
Section titled “Build the game as a page”Your CMakePresets.json already has two browser presets, wasm-debug and wasm-release, with
a build and a test preset for each. They are its three wasm entries in the configurePresets
array:
"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" }website/src/walkthrough/CMakePresets.json, lines 29–47 at 0f4f503
The toolchain is still vcpkg’s, so vcpkg still installs the game’s libraries.
VCPKG_CHAINLOAD_TOOLCHAIN_FILE tells vcpkg to hand over to Emscripten’s toolchain after it, and
VCPKG_TARGET_TRIPLET builds those libraries for WebAssembly instead of x64. The Windows-only
packages in your vcpkg.json, DirectXTK and XAudio2, are skipped for this triplet. In a browser
build Labrador chooses the only renderer, audio and input that work there: OpenGL drawing through
WebGL2, Web Audio, and the browser’s Gamepad API.
game/CMakeLists.txt has the browser half of the build too. It is the if(EMSCRIPTEN) block,
which a browser build reads in place of everything below it:
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()website/src/walkthrough/game-CMakeLists.txt, lines 32–60 at 0f4f503
main_web.cppreplacesmain.cpp. It starts the same first state. In a browserApplication::rundoes not return, and everything on the stack below it is destroyed before the first frame, so theApplicationis astaticrather than a local variable. A failure is written to the browser’s console and passed to the page, because a page has no message box.SUFFIX ".html"makes the build writeMyGame.html, withMyGame.jsandMyGame.wasmbeside it.--embed-filepacks everything ingame/contentinto the module, at the paths the Windows build copies it to, soload_manifest("./manifest.json")finds the same files.--shell-filemakes the page fromweb/shell.html. Emscripten puts the module’s script where the page says{{{ SCRIPT }}}.- The rules’ tests run under Node, which Emscripten’s toolchain gives ctest. The start-up check is not in this branch, because it needs a command line and a page has none.
-
Configure the browser build, in the prompt where you ran
emsdk_env.bat, inC:\dev\mygame. This is needed once:Terminal window cmake --preset wasm-debugThe first browser configure can take a quarter of an hour, sitting for minutes at
Fetching registry information from https://github.com/microsoft/vcpkg (HEAD)...or atDetecting compiler hash for triplet x64-windows...with nothing else happening; leave it running. Where this page was checked, the first configure took 860 seconds in one fresh project, 297 in another and 11 in a third; later configures take seconds. vcpkg builds doctest, the tests’ library, again for WebAssembly, and prints its usual lines. The configure also prints this warning three times, which does not matter, because the game uses no shared libraries:Output CMake Warning at C:/dev/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake:26 (message):This version of cmake (4.3.1-msvc1) does not support emscripten sharedlibraries. Use cmake < 4.2.0 or cmake > 4.3.3 if you need shared librarysupportIt ends:
Output -- Configuring done (11.1s)-- Generating done (0.1s)-- Build files have been written to: C:/dev/mygame/out/build/wasm-debugThe time on the
Configuring doneline is your own. If it stops withinclude could not find requested file:,emsdk_env.bathas not run in this prompt: see If something fails. -
Build it and run its test:
Terminal window cmake --build --preset wasm-debug && ctest --preset wasm-debugThe first build compiles the engine with Emscripten’s compiler, clang, in 92 steps, and took 9 seconds here; expect a minute or more on a slower machine. It ends as below, with the two
Linkinglines in either order:Output [90/92] Building CXX object game/CMakeFiles/MyGameTests.dir/tests/motion_tests.cpp.o[91/92] Linking CXX executable game\MyGameTests.js[92/92] Linking CXX executable game\MyGame.htmlTest project C:/dev/mygame/out/build/wasm-debugStart 1: MyGameTests1/1 Test #1: MyGameTests ...................... Passed 0.15 sec100% tests passed, 0 tests failed out of 1Total Test time (real) = 0.17 secThe page is three files in
out\build\wasm-debug\game:MyGame.html(2 KB),MyGame.js(270 KB) andMyGame.wasm(11 MB, a debug build; the release one below is under 400 KB). The folderout\build\wasm-debugtakes about 60 MB.If the build ends
ninja: build stopped: subcommand failed., find the firsterror:line above it. Clang’s errors look a little different from Visual Studio’s: In the browser build reads one. A test failure looks as on Windows.
Serve it and open it
Section titled “Serve it and open it”A browser will not run a WebAssembly module from a file opened by double-clicking: opened that
way the page stays at Loading.... It has to come from a web server, and the Python that came
with Emscripten has one. Start it in a window of its own, from the prompt in C:\dev\mygame:
start "MyGame server" "%EMSDK_PYTHON%" -m http.server 8000 --bind 127.0.0.1 --directory out\build\wasm-debug\gameA new window titled MyGame server opens and prints:
Serving HTTP on 127.0.0.1 port 8000 (http://127.0.0.1:8000/) ...and your prompt is free for the next command. Leave that window open: the server runs until you
close it. If the window closes at once, the server could not start; run the same command
without start "MyGame server" to read why in your prompt, as in If something
fails. Now open http://127.0.0.1:8000/MyGame.html in Chrome, Edge or Firefox. The page
shows the same greeting as the Windows build in a black box, with a line of help below it, and
the same keys work once you click the game. The server’s window prints a line for each file the
browser asks for: 200 when it was sent, and on a later visit 304 when the browser’s copy was
still current:
127.0.0.1 - - [31/Oct/2026 04:12:31] "GET /MyGame.html HTTP/1.1" 200 -127.0.0.1 - - [31/Oct/2026 04:12:31] "GET /MyGame.js HTTP/1.1" 200 -127.0.0.1 - - [31/Oct/2026 04:12:31] "GET /MyGame.wasm HTTP/1.1" 200 -127.0.0.1 - - [31/Oct/2026 04:12:31] code 404, message File not found127.0.0.1 - - [31/Oct/2026 04:12:31] "GET /favicon.ico HTTP/1.1" 404 -The 404 for favicon.ico is the browser asking for a tab icon the page does not have, and is
harmless. Opened without MyGame.html, http://127.0.0.1:8000/ shows Directory listing for
/, the build folder’s files; click MyGame.html there. Because of --bind 127.0.0.1, only this
machine can reach the server. If a browser is ended abruptly, the window can print a
Traceback ending ConnectionResetError: [WinError 10054] An existing connection was forcibly closed by the remote host; that is harmless, and the server goes on serving.
Sound starts after your first key press or click on the page, which is a browser rule. To stop
the server, close the MyGame server window, or click in it and press Ctrl+C, which prints
Keyboard interrupt received, exiting.
Change it, rebuild and refresh
Section titled “Change it, rebuild and refresh”With the server still running, change the game as in
Make a first change, for example the greeting in
game\states\hello_state.cpp. Then, in the prompt:
cmake --build --preset wasm-debug && ctest --preset wasm-debugA one-file change is three steps, compiling that file and linking the page, and took 8 seconds here. The server does not need restarting; it sends whatever is in the folder.
Then reload the page with Ctrl+F5, not F5. The server does not tell the browser how long it
may keep a file, so the browser guesses, and F5 asks the server again only for MyGame.html: it
keeps the old MyGame.js and MyGame.wasm and runs the old game. The server’s window shows it:
after F5 only GET /MyGame.html appears, and after Ctrl+F5 all three files. When this page was
checked, Chrome and Edge kept the old game through F5, a second F5 20 seconds later and opening the
address again, and Ctrl+F5 loaded the new one. Ctrl+F5 is the full reload in Edge and Firefox
too.
When you add a file
Section titled “When you add a file”The browser build has its own list of the game’s .cpp files and its own list of the content
files that make it link again:
- A new
.cppfile goes in bothadd_executable(MyGamelists ingame\CMakeLists.txt, the one insideif(EMSCRIPTEN)and the Windows one. Without it the Windows build works and this one stops withwasm-ld: error: ... undefined symbol. Add a screen to your game does it step by step. - A new content file, such as a picture, a sound or a font, needs no copy line, because
--embed-filepacks the wholegame\contentfolder. It does need a line in theLINK_DEPENDSlist insideif(EMSCRIPTEN), beside the.spritefontline. Without it, a change to that file alone does not rebuild the page, and the page keeps the old picture or sound. Put a picture in your game gives the line. web\shell.html,content\manifest.jsonand the starter’s font are in that list already: a change to any of them rebuilds the page.
Check the page loads and quits
Section titled “Check the page loads and quits”Labrador’s page runner opens your page in a hidden browser, lets it draw, presses keys and checks that it quits with nothing in the console. It is the check CI runs on the starter project’s page, and it takes about ten seconds. It needs the full path of Chrome or Edge; check that the one you have is there:
dir "C:\Program Files\Google\Chrome\Application\chrome.exe"dir "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"Each prints the file’s date and size if it is there, or File Not Found. Every Windows 11
machine has Edge. Set browser to one that is there, Chrome:
set "browser=C:\Program Files\Google\Chrome\Application\chrome.exe"or Edge:
set "browser=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"Then, in the prompt where you ran emsdk_env.bat, in C:\dev\mygame:
"%EMSDK_NODE%" "external\labrador\tests\render\web\run_page.mjs" ^ --browser "%browser%" ^ --page out\build\wasm-debug\game\MyGame.html ^ --quit-keys Escape,Enter --timeout 60echo %errorlevel%The runner starts its own web server and a browser with a temporary profile, and closes both
when it finishes; it does not need the MyGame server window. It waits for the game to
start, lets 60 frames draw, presses Escape and then Enter, and waits for the page’s
Module.onQuit callback. A pass, here with Edge, prints:
run_page: 60 animation framesrun_page: pressed Escaperun_page: pressed Enterrun_page: Module.onQuit was calledrun_page: browser: Edg/156.0.4314.50 (DevTools 1.3, revision @af2ba23ae0ecf7084d900446fc59d5119dd5fd5e)run_page: WebGL2 renderer: ANGLE (NVIDIA, NVIDIA GeForce RTX 5080 (0x00002C02) Direct3D11 vs_5_0 ps_5_0, D3D11)0with your own browser’s version and graphics card. A pass is the 0 at the end. A console
error or warning, a failed assertion, an uncaught exception, a browser warning or error, or a call
to Module.onError fails the run and prints the message, even if the page also quits; the last
line is then 1. A missing Module.onQuit fails, and a page that never starts or quits stops
after the 60 seconds. If you change the game’s quit keys, change --quit-keys to match: it
takes Escape, Enter, Space, the four Arrow directions, and KeyA to KeyZ. This checks
start-up and the quit path; it does not compare pictures or replace playing the game.
To see a failure, add console.error("deliberate page-check failure"); just after the opening
<script> tag in the built out\build\wasm-debug\game\MyGame.html and run the same command: it
prints that message and 1. A build with no source change does not replace the file: it prints
only [1/1] Checking that no engine file includes a game header, and the check fails again. To
put it right, delete the page and build again:
del out\build\wasm-debug\game\MyGame.htmlcmake --build --preset wasm-debugThe build ends [2/2] Linking CXX executable game\MyGame.html, and the check passes again.
The release page
Section titled “The release page”wasm-debug is for trying the game: its module is large and slow to start. wasm-release is
the one to give people. It builds the same way, into its own folder:
cmake --preset wasm-releasecmake --build --preset wasm-release && ctest --preset wasm-releaseHere the configure took 9 seconds and the build 10, again 92 steps, ending as in the debug build
with 100% tests passed, 0 tests failed out of 1. The page is in out\build\wasm-release\game:
MyGame.html (1 KB), MyGame.js (117 KB) and MyGame.wasm (379 KB). Serve it as above with
out\build\wasm-release\game in place of out\build\wasm-debug\game, after closing the first
server, or with 8001 in place of 8000 in the command and the address.
Put your game on the web builds, gathers and publishes the release with one script. The next section is what that script does, by hand. Put your game on a web host says what any host must send with the files.
Gather the browser release and its notices
Section titled “Gather the browser release and its notices”The template’s build writes the page, script and module; it does not gather their notices.
After building wasm-release, run this in C:\dev\mygame, in the prompt where you ran
emsdk_env.bat. It uses Labrador’s bundler and the Node that came with Emscripten; there is
nothing else to install.
First put Microsoft’s licence for the engine’s timer code in your game’s web folder. The
engine inside your project has a copy:
copy external\labrador\tools\web_bundle\Microsoft-LICENSE.txt game\web\It prints 1 file(s) copied. Keep the file with your game and reuse it for later releases. If
it prints The system cannot find the file specified., your engine is older than this file,
such as one pinned at v0.2.0; fetch the same text from this fixed upstream
revision instead:
curl.exe --fail --location https://raw.githubusercontent.com/microsoft/DirectXTK/a0a1ab67d9d8f1a41b76c0950eb37f27d6bf355d/LICENSE --output game\web\Microsoft-LICENSE.txtThe bundler empties out\web-release first. Keep that folder for generated release files
only; do not point --out at your project, source or build folder. Paste the whole box; each
line ending ^ continues on the next, so a missed line or a space after a ^ breaks it:
set "engine=external\labrador"set "emscripten=%EMSDK%\upstream\emscripten""%EMSDK_NODE%" "%engine%\tools\web_bundle\bundle.mjs" ^ --out out\web-release ^ --repository . ^ --emscripten "%emscripten%" ^ --build-type Release ^ --file "MyGame.html=out\build\wasm-release\game\MyGame.html" ^ --file "MyGame.js=out\build\wasm-release\game\MyGame.js" ^ --file "MyGame.wasm=out\build\wasm-release\game\MyGame.wasm" ^ --notice "%engine%\NOTICE" ^ --licence "Labrador=%engine%\LICENSE" ^ --licence "Microsoft sample code=game\web\Microsoft-LICENSE.txt" ^ --licence "RapidJSON=%engine%\external\rapidjson\license.txt" ^ --licence "JetBrains Mono=game\content\fonts\OFL.txt" ^ --licence "Emscripten=%emscripten%\LICENSE" ^ --licence "libc++=%emscripten%\system\lib\libcxx\LICENSE.TXT" ^ --licence "libc++abi=%emscripten%\system\lib\libcxxabi\LICENSE.TXT" ^ --licence "libunwind=%emscripten%\system\lib\libunwind\LICENSE.TXT" ^ --licence "compiler-rt=%emscripten%\system\lib\compiler-rt\LICENSE.TXT" ^ --licence "musl=%emscripten%\system\lib\libc\musl\COPYRIGHT"It takes under a second and prints each file’s size and its size compressed, roughly what a player downloads:
MyGame.html 1193 bytes, 525 under Brotli MyGame.js 119887 bytes, 27539 under Brotli MyGame.wasm 388334 bytes, 120166 under Brotli NOTICE.txt 102282 bytes, 12468 under Brotli from unknownThe last line names your project’s Git commit, or says unknown when it is not a Git
repository, as a starter project is not. If it prints a block starting node:fs instead, read
its Error: line: ENOENT: no such file or directory, copyfile and a path in
out\build\wasm-release means the release is not built, so build it as in The release
page; open and a path in game\web means the licence file is missing, so do
the copy above.
Upload all five files in out\web-release: MyGame.html, MyGame.js, MyGame.wasm,
NOTICE.txt and BUILD.json. Keep a link to NOTICE.txt on your hosting page so players can
read it. The notices cover the template’s default WebGL2/Web Audio build:
| Component | Where the notice comes from |
|---|---|
| Labrador, Microsoft’s shared timer code and the collision routines adapted from Real-Time Collision Detection | The engine’s NOTICE attribution record, its MIT LICENSE, and the preserved Microsoft MIT text |
| RapidJSON | The vendored license.txt |
| The template’s JetBrains Mono atlas | The game’s content/fonts/OFL.txt, in full even though it is also embedded with the atlas |
| Emscripten’s JavaScript runtime and system libraries | LICENSE in the same Emscripten install that built the module |
| libc++, libc++abi, libunwind and compiler-rt | Their licence texts in that install’s system/lib, including the LLVM Exceptions |
| The musl-derived C library and dlmalloc | musl’s COPYRIGHT; the engine’s NOTICE also records dlmalloc’s public-domain dedication |
The generated NOTICE.txt starts with Labrador’s third-party record and appends the full licence
texts. Identical texts are written once, with each later component pointing to the first.
BUILD.json records the project’s Git commit and tracked dirty state, the supplied build type,
the installed Emscripten version, and the files’ sizes and hashes. A failed Git lookup is
recorded as unknown; it still packages. Run this immediately after the release build:
the record describes the checkout when packaging, and does not prove which
sources or flags an older module used.
Windows DLLs, DirectXTK, DirectXMath, XAudio2Redist and the MSVC runtime are absent from this browser release. The rules-test framework, doctest, is used only by the test program, and lodepng only by the engine’s render tests. Neither test program is in the folder you upload.
Your game’s own code and content have their own terms. Add a --licence "Your game=LICENSE"
argument if you have a licence file to include, and add the notices of any libraries or content
you introduce. If you replace the font, change its licence argument too. If you change the
allocator or toolchain, recheck its notice inputs against that build. Read the licence texts
for their terms; the command assembles the template’s inputs and does not choose your game’s
licence. Rebuild and rerun it when the engine pin, toolchain or content changes.
The page, and what it owes the module
Section titled “The page, and what it owes the module”web/shell.html is yours to change. Its title, its status line and its styles are the minimal
sample’s, and you replace them with your own. Set Module before Emscripten’s generated script
starts the game. The template supplies a canvas and two of the four optional page callbacks:
var Module = { canvas: canvas, onRuntimeInitialized: function () { statusLine.textContent = "Arrows, WASD or the left stick move the text, and a finger on it shows its id. Escape asks to quit; Enter says yes."; canvas.focus(); }, onQuit: function () { statusLine.textContent = "Quit. Reload the page to play again."; }, onError: function (message) { statusLine.className = "error"; statusLine.textContent = message; }, };samples/minimal/web/shell.html, lines 43–57 at 0f4f503
Module.canvas must be the actual canvas element, present before the game starts. The page
owns its place in the DOM and its size in CSS; the engine follows that size and the device pixel
ratio when setting the drawing buffer. Keep tabindex="0" on the canvas so it can take keyboard
focus, and touch-action: none so a finger on it does not scroll the page. Call canvas.focus()
when the player starts playing, as the template does.
The four callbacks below are optional. Names are exact and case sensitive. A misspelled name
is silently ignored, with no warning; a value that is not a function is ignored too. The engine
reads each callback from Module when it is due.
| Callback | When it is called | What the page can show |
|---|---|---|
Module.onQuit() |
The game calls Application::quit() (or closes its Window), after the frame loop has been cancelled and the window’s input and page listeners have been removed. The Application releases its states and services on a later task. It has no arguments. |
The game has ended; offer a reload or another game. |
Module.onError(message) |
The template’s main_web.cpp forwards a startup exception, or the browser window catches an exception from a frame or input handler. message is a string, also written to the console. A caught frame or input failure stops the loop and window listeners before this call. |
The reason the game could not start or continue. |
Module.onContextLost() |
The renderer observes a lost WebGL2 context, once per loss, at the next begin_frame. It has no arguments. |
Graphics are unavailable and restoration is awaited. |
Module.onContextRestored() |
At begin_frame, after the renderer and the game’s device resources have been rebuilt. It has no arguments; that frame can now draw again. |
Remove the graphics-loss message. |
Keep the startup error forwarding in main_web.cpp when you change the entry point. A script,
fetch or WebAssembly compilation failure can happen before the engine runs, so the page must
handle loader failures separately; onError cannot report every failure to load the module.
The context callbacks run from a frame, rather than directly from the browser’s context events.
Loss is reported before restoration, even if both happen between two frames. Restoration has no
deadline: if the browser never restores the context, onContextRestored never arrives and the
canvas stays blank. Keep the loss message visible until restoration or a new page load.
Quit before removing the canvas
Section titled “Quit before removing the canvas”Keep the same canvas attached while the game is running. Removing it from the DOM does not
stop the frame loop, release the WebGL2 context or unregister the window’s listeners. It leaves
a hidden running game. Changing Module.canvas is not a way to stop or move that game either.
Before replacing or removing the canvas, arrange for the game to call Application::quit() and
wait for onQuit. The template’s Escape/Enter confirmation is one way to reach it. There is no
built-in JavaScript stop function; a host that needs a stop button must connect it to its own
game’s quit path.
Quit cancels the loop and removes the window’s listeners. On the next browser task the static
Application destroys its states and releases its services, the WebGL2 context and Web Audio
included, as its destructor would on Windows. Nothing may call into the game after onQuit.
Reload the template’s page to play again. An ES-module host such as LineSweeper’s creates a fresh
module instance and a fresh canvas for each game, then drops the old canvas after quit, so a
finished instance can be collected.
If something fails
Section titled “If something fails”Installing Emscripten
Section titled “Installing Emscripten”Building and serving
Section titled “Building and serving”A build error in your own code is the same as on Windows, in clang’s words: Read a build error. Troubleshooting lists this page’s messages too.
What players need
Section titled “What players need”A current Chrome, Edge, Firefox or Safari with WebGL2, on a computer. The browser build has been checked in desktop Chrome and Edge and, for LineSweeper’s page, Firefox. In Safari, only LineSweeper’s live demo has been loaded and played briefly, in Safari 27.0.1 on macOS. It has not been checked on a phone, with a real touchscreen or with a physical gamepad. Platform support says where each of those stands; say the same on your own page until you have checked them yourself.
What was checked
Section titled “What was checked”On 2026-10-31, in a starter project made from a starter ZIP of this tree at
C:\dev\g10-author\mygame, on Windows 11 with Visual Studio 2026’s CMake 4.3.1, every step on
this page was run as worded with C:\dev\g10-author in place of C:\dev, and the output above is
from those runs with the folder changed back. Every Git folder was removed from the prompt’s
PATH for the install and the builds, so where git found nothing. The machine already had
Python 3.14.2, through the Python install manager, so installing Python and Manage app
execution aliases are written from Python’s Using Python on Windows and were not followed,
and the Store shortcut’s Python was not found message, which Windows prints, was not reproduced
here. The emsdk ZIP was 212,350 bytes, and emsdk install fetched 767,768,043
bytes in three downloads and took 66 seconds on a fast connection; the four-minute figure is that
size at 25 Mbit/s, not a measurement. The folder then took 2.12 GB. Emscripten’s own page,
Download and install, says Git is needed only for development branches and that the ZIP from
GitHub works; git clone took 2 seconds and made a 4.3 MB folder.
The first wasm-debug configure ran with an empty vcpkg binary cache, so vcpkg built doctest for
WebAssembly; its sources and vcpkg’s list of packages were already on the machine, which is why
the page allows for a fetch of several minutes. The configure took 11 seconds, the build of 92
steps 9 and the test 0.2; wasm-release took 9 and 10. A rebuild after changing the greeting was
three steps. These are a fast desktop’s times, not the low tier’s.
The server was started with Emscripten’s Python 3.13.3 by the start line, which opened a
Windows Terminal window titled MyGame server; it served MyGame.wasm as application/wasm
and printed the request lines above when headless Chrome 156 loaded the page, which drew the
greeting. Closing it was done by ending its process, which closed the window; the Ctrl+C line was
seen by Put your game on the web. The refresh
behaviour was measured over Chrome’s DevTools protocol with a persistent profile, the server
running and the build changing the greeting between loads. Built and loaded at once, F5 kept the
old .js and .wasm for about a tenth of the time since the build, then fetched them; with the
build’s files dated a day earlier, as when you come back to a page built yesterday, F5, a second
F5 20 seconds later and opening the address again all showed the old greeting, the server’s log
showing only MyGame.html, and Ctrl+F5, sent as a reload that ignores the cache, showed the new
one. Edge 156 did the same in the same test. Firefox was not tried; Ctrl+F5 is its documented
full reload.
The failures were made on purpose: git clone with no Git, python hidden from PATH, a second
ren onto an existing folder, tar with no ZIP, a mistyped version, a download through a proxy
that was not there, activate before install, configuring without emsdk_env.bat, port 8000
held by another program, which gave WinError 10013, a second Python server on the same port,
which started without an error while the first went on answering, the server started from the
wrong folder, the page opened from file://, which stayed at Loading... with
Aborted(both async and sync fetching of the wasm failed) in the console, a misspelt browser
path and a misspelt page for the runner, and the bundler with no release build and with no
licence file. curl was given a host that does not exist, which printed curl: (6) Could not resolve host: and the host, and a tag that does not exist, which printed the 404; a machine
with no connection was not tried. The copy of the licence ran; its curl fallback for an
older engine did not. The page runner passed with Chrome 156 and Edge 156. Safari, a phone and a slow machine
were not used.
The same day the page was followed again as worded, in a second fresh starter at
C:\dev\g10-follow\mygame with Git hidden from PATH. There emsdk install took 78 seconds and
left 2,120,288,634 bytes, and the first wasm-debug configure took 297 seconds, with vcpkg’s
packages restored from its binary cache; the other outputs matched. That run found what this page
then corrected: the middle of emsdk activate’s output, captured with Python unbuffered so the
lines come in a console’s order; the three lines emsdk_env.bat prints after activate in the
same prompt; the first configure’s time and the Detecting compiler hash line; 304 and the
harmless ConnectionResetError in the server’s window, the second seen only when headless Chrome
was ended by force; the %EMSDK_PYTHON% message and its start dialog in a prompt without
emsdk_env.bat; and the deliberate page-check failure, which an ordinary build does not undo.
--accept-source-agreements was added to the winget line because --disable-interactivity
cannot answer msstore’s terms; it is in winget install --help, but no winget install ran.
Configuring again after emsdk_env.bat worked without deleting the build folder, in 5 seconds.
After the corrections, a third fresh starter at C:\dev\g10-fixer\mygame reran emsdk activate
and emsdk_env.bat in one prompt, the deliberate failure, the build that left it, and the delete
and build that removed it, the server and runner lines without emsdk_env.bat, and a request
that drew 304; each printed what this page shows. Its first configure took 8 seconds, and its
two Linking lines came in the other order. The start dialog was seen only in the second run.
A review the same day, in a fourth fresh starter at C:\dev\g10-reviewer\mygame, downloaded the
tag ZIP and ran emsdk install and emsdk activate with Git hidden from PATH; the install took
3 minutes 15 seconds on that connection, and printed what this page shows. Its first wasm-debug
configure took 860 seconds, nearly all of it at Fetching registry information, while vcpkg’s
fetch of its registry sat idle; nothing was pressed, and it finished on its own. The build, its
sizes, the no-change build’s one line, the wasm-release sizes, the bundler’s output, a page
runner pass with Chrome 156, WinError 10013 with the port held by another program, a second
server starting silently while the first answered, and configuring again after a configure
without emsdk_env.bat all matched the page. The review found that emsdk 6.0.12 refuses
Python older than 3.10, where the page had said 3.8; the refusal’s message is quoted from
emsdk.py, since no older Python was run.
Earlier, on 25 October 2026, this page’s procedure was followed with Emscripten installed by
git clone, the project configured, built under both presets, tested under Node and its page
loaded in headless Chrome; on 28 October the release command was followed from a fresh copy of
that project and its five files, licences and hashes checked, with no upload. CI’s
wasm-consumer job builds the starter project’s wasm-release page and loads it the same way on
every pull request to Labrador.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.