Skip to content

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.

Check your browser build in CI optionally builds and tests the packaged page on each push and keeps an artifact, with publication left as a separate step.

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.

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.

  1. Check that Python runs. In the x64 Native Tools Command Prompt:

    Terminal window
    python --version

    If it prints Python 3.10 or a later version, such as Python 3.14.2, go on to step 2. emsdk refuses an older Python, such as Python 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, and python is Windows’ shortcut to the Microsoft Store. Typing python alone 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-interactivity

    Close the prompt, open a new x64 Native Tools Command Prompt, and run python --version again. With the install manager and no Python yet, Python’s documentation says the first python downloads and installs the latest Python before it answers, so it can take a while. If python still opens the Store, open Start, type Manage 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.

  2. Download emsdk. It is a ZIP of about 210 KB from GitHub, and Windows’ own curl and tar fetch and extract it, so you do not need Git or a browser:

    Terminal window
    if not exist C:\dev mkdir C:\dev
    cd /d C:\dev
    curl.exe --fail --location --output emsdk.zip https://github.com/emscripten-core/emsdk/archive/refs/tags/6.0.12.zip
    tar -xf emsdk.zip
    ren emsdk-6.0.12 emsdk
    del emsdk.zip
    dir /b emsdk\emsdk.bat

    curl shows a small table of progress and is done in a second; tar, ren and del print nothing when they work. The ZIP holds one folder, emsdk- and the version, which ren renames to C:\dev\emsdk. The last line checks it, and prints:

    Output
    emsdk.bat
  3. 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\emsdk
    emsdk install 6.0.12

    It 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 as 786432 [2.11%], and the Unpacking line 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 Bytes
    Unpacking '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 Bytes
    Unpacking '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 Bytes
    Unpacking '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.

  4. Make it the version emsdk uses:

    Terminal window
    emsdk activate 6.0.12

    It 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-64bit
    python-3.13.3-64bit
    releases-6e9f6885cb17a3d6c8fd488a5cff730f50aba61d-64bit
    Next steps:
    - Consider running `emsdk activate` with --permanent or --system
    to have emsdk settings available on startup.
    Adding directories to PATH:
    PATH += C:\dev\emsdk
    PATH += 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/emsdk
    EMSDK_NODE = C:\dev\emsdk\node\24.19.0_64bit\node.exe
    EMSDK_PYTHON = C:\dev\emsdk\python\3.13.3_64bit\python.exe
    Clearing existing environment variable: EMSDK_PY
    The 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.

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:

Terminal window
C:\dev\emsdk\emsdk_env.bat
cd /d C:\dev\mygame

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

Output
Setting up EMSDK environment (suppress these messages with EMSDK_QUIET=1)
Adding directories to PATH:
PATH += C:\dev\emsdk
PATH += 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/emsdk
EMSDK_NODE = C:\dev\emsdk\node\24.19.0_64bit\node.exe
EMSDK_PYTHON = C:\dev\emsdk\python\3.13.3_64bit\python.exe
Clearing existing environment variable: EMSDK_PY

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

Terminal window
echo %EMSDK%
emcc --version
Output
C:/dev/emsdk
shared: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.

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:

website/src/walkthrough/CMakePresets.json
"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" }

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:

website/src/walkthrough/game-CMakeLists.txt
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()
  • main_web.cpp replaces main.cpp. It starts the same first state. In a browser Application::run does not return, and everything on the stack below it is destroyed before the first frame, so the Application is a static rather 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 write MyGame.html, with MyGame.js and MyGame.wasm beside it.
  • --embed-file packs everything in game/content into the module, at the paths the Windows build copies it to, so load_manifest("./manifest.json") finds the same files.
  • --shell-file makes the page from web/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.
  1. Configure the browser build, in the prompt where you ran emsdk_env.bat, in C:\dev\mygame. This is needed once:

    Terminal window
    cmake --preset wasm-debug

    The 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 at Detecting 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 shared
    libraries. Use cmake < 4.2.0 or cmake > 4.3.3 if you need shared library
    support

    It ends:

    Output
    -- Configuring done (11.1s)
    -- Generating done (0.1s)
    -- Build files have been written to: C:/dev/mygame/out/build/wasm-debug

    The time on the Configuring done line is your own. If it stops with include could not find requested file:, emsdk_env.bat has not run in this prompt: see If something fails.

  2. Build it and run its test:

    Terminal window
    cmake --build --preset wasm-debug && ctest --preset wasm-debug

    The 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 Linking lines 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.html
    Test project C:/dev/mygame/out/build/wasm-debug
    Start 1: MyGameTests
    1/1 Test #1: MyGameTests ...................... Passed 0.15 sec
    100% tests passed, 0 tests failed out of 1
    Total Test time (real) = 0.17 sec

    The page is three files in out\build\wasm-debug\game: MyGame.html (2 KB), MyGame.js (270 KB) and MyGame.wasm (11 MB, a debug build; the release one below is under 400 KB). The folder out\build\wasm-debug takes about 60 MB.

    If the build ends ninja: build stopped: subcommand failed., find the first error: 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.

A browser will not run a WebAssembly module from a file opened by double-clicking: opened that way the development page says The game could not be loaded.; the v0.3.0 starter 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:

Terminal window
start "MyGame server" "%EMSDK_PYTHON%" -m http.server 8000 --bind 127.0.0.1 --directory out\build\wasm-debug\game

A new window titled MyGame server opens and prints:

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

Output
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 found
127.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.

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:

Terminal window
cmake --build --preset wasm-debug && ctest --preset wasm-debug

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

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 .cpp file goes in both add_executable(MyGame lists in game\CMakeLists.txt, the one inside if(EMSCRIPTEN) and the Windows one. Without it the Windows build works and this one stops with wasm-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-file packs the whole game\content folder. It does need a line in the LINK_DEPENDS list inside if(EMSCRIPTEN), beside the .spritefont line. 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.json and the starter’s font are in that list already: a change to any of them rebuilds the page.

Start with the native debugger for a defect in portable rules or ordinary C++: Edit and debug in Visual Studio gives the breakpoint, step and variable workflow. Use the browser route when the problem only reproduces in the browser, such as page loading, input or a browser API boundary.

Open DevTools Console with Ctrl+Shift+J in Chrome. std::printf("message\n") reaches ordinary console output, and std::fprintf(stderr, "reason\n") reaches the error channel. Keep the newline: stdout is line buffered. The starter’s page does not override either channel. A C++ startup failure is also sent through Module.onError to the page’s status line.

A .wasm or loader script that cannot download fails before C++ runs. Read the failed URL and HTTP status in Console, then its request in Network; rebuilding the C++ does not repair a 404. The starter’s loader-failure line is intentionally simpler than the console’s reason. The page runner below treats console warnings/errors as failures, including deliberately printed stderr; ordinary stdout alone does not fail it.

One Windows route was verified with Emscripten 6.0.12, Chrome for Testing 151.0.7922.34 and the official C/C++ DevTools Support (DWARF) 0.2.5854.1 extension. The separate probe and exact setup recipe prepare an isolated testing-browser profile and an ignored build folder. They do not change your normal browser or the game’s Release build. Regular Chrome and Edge no longer accept the extension-loading command-line flags used by that recipe; use its testing browser.

The small probe deliberately adds where it should multiply:

tools/browser_debug/browser_fault.cpp
extern "C" EMSCRIPTEN_KEEPALIVE int browser_score(int player_count)
{
int points_per_player = 10;
int total_points = player_count + points_per_player;
std::printf("score: %d players produced %d points\n", player_count, total_points);
return total_points;
}

With its source and HTML copied into a separate folder, the verified Debug command is:

Terminal window
em++ browser_fault.cpp -g -O0 -fdebug-compilation-dir=. -sERROR_ON_WASM_CHANGES_AFTER_LINK=1 -sEXIT_RUNTIME=0 -o browser_fault.js

Serve that folder as the recipe describes. Full -g at compilation and linking retains DWARF, which describes C++ source lines, types and variables. The relative compilation directory lets the debugger fetch this probe’s source beside its wasm over loopback HTTP. -gsource-map alone maps locations and does not establish named C++ variable inspection.

In Sources, open browser_fault.cpp, set a gutter breakpoint on the total_points assignment, then click the page’s Calculate score for two players. The verified run paused in browser_score with player_count: 2 and points_per_player: 10 in Scope. Step over (F10 with DevTools focused) advances to printf and shows total_points: 12. The storage shown for that variable before its assignment is not an initialized C++ result. Resume, replace + with * in the copied source, rebuild and hard reload: the same step then shows 20. A wasm instruction listing alone means this source-debugging setup is incomplete.

The recipe links the recorded breakpoint, step and console evidence, with the tested tool versions and extension hash. It qualifies this pair, not every browser or extension version. Larger game sources use the same DWARF requirement; the existing wasm-debug configuration passes -g, while optimised variables can be unavailable or moved between source lines.

Keep the source, Debug wasm, extension and profile out of the normal distributable. Continue to package wasm-release; this exercise changes no Release flag or bundle target. Source maps or separate DWARF files are extra developer artifacts only when you explicitly choose them.

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:

Terminal window
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:

Terminal window
set "browser=C:\Program Files\Google\Chrome\Application\chrome.exe"

or Edge:

Terminal window
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:

Terminal window
"%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 60
echo %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:

Output
run_page: 60 animation frames
run_page: wasm heap after 60 frames: 17956864 bytes (17.13 MiB)
run_page: pressed Escape
run_page: pressed Enter
run_page: Module.onQuit was called
run_page: wasm heap at quit: 17956864 bytes (17.13 MiB)
run_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)
0

with your own browser’s version and graphics card, and your own game’s heap size, which the runner prints but does not judge. 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:

Terminal window
del out\build\wasm-debug\game\MyGame.html
cmake --build --preset wasm-debug

The build ends [2/2] Linking CXX executable game\MyGame.html, and the check passes again.

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:

Terminal window
cmake --preset wasm-release
cmake --build --preset wasm-release && ctest --preset wasm-release

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

Terminal window
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:

Terminal window
curl.exe --fail --location https://raw.githubusercontent.com/microsoft/DirectXTK/a0a1ab67d9d8f1a41b76c0950eb37f27d6bf355d/LICENSE --output game\web\Microsoft-LICENSE.txt

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

Terminal window
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:

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

The 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, which is not in the folder you upload. lodepng, which decodes PNG textures, is compiled into the game’s .wasm; its zlib licence asks nothing of a program built from it.

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.

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, beside two of Emscripten’s own:

samples/minimal/web/shell.html
var Module = {
canvas: canvas,
onRuntimeInitialized: function () {
loading = false;
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;
},
onAbort: loadFailed,
};

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. A canvas has no text of its own, so the template names it with aria-label for a screen reader; Minimal sample is a placeholder to replace with your game’s name, as the <title> is. The status line has role="status", so a change to it is read out. What else the page or the game does for accessibility is the game’s choice.

The v0.3.0 template has neither attribute. Add aria-label="Your game's name" inside its opening <canvas> tag and role="status" inside its opening <p id="status"> tag if keeping that template. They are ordinary page attributes and need no engine update.

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 development template does it in the lines below Module:

samples/minimal/web/shell.html
// A download that fails never reaches the engine, so Module.onError cannot
// report it. Emscripten's loader calls Module.onAbort when the .wasm cannot
// be fetched or compiled; a preloaded .data file or the loader script
// fails as a rejected promise or an error event instead. The console still
// has the reason. This line is for the player, and only until the game has
// started.
var loading = true;
function loadFailed() {
if (!loading) { return; }
loading = false;
statusLine.className = "error";
statusLine.textContent =
"The game could not be loaded. Check your connection and reload the page.";
}
window.addEventListener("unhandledrejection", loadFailed);
window.addEventListener("error", function (event) {
// An uncaught exception arrives at the window, and a script that would
// not download at its own tag. A missing image is neither.
if (event.target === window || event.target.tagName === "SCRIPT") { loadFailed(); }
}, true);

onAbort and onRuntimeInitialized are Emscripten’s names, not the engine’s: its loader calls the first when it gives up on the .wasm, and the second when the module is ready and main is about to run, which is where the template stops listening. The two listeners catch what the loader does not report, a script that would not download and a promise nobody caught, such as a missing .data file’s. None of them hides anything: the browser’s console still shows the failure, and the page check still fails on it. The sentence is for a player, so it does not name a file; change its words as you change the others. Without these lines a page whose download failed would stay at Loading..., as the v0.3.0 template does. You can copy the handlers into that template too; they use the browser and Emscripten callbacks, rather than a newer engine API.

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.

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.

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.

A current Chrome, Edge, Firefox or Safari with WebGL2, on a computer. The browser build has been checked in desktop Chrome, Edge, Firefox and Safari: every sample’s page in headless Chrome, a starter’s page in Edge, every sample’s page in headless Firefox, and every sample’s page in Safari 26.6 on macOS 26, on a hosted build machine rather than a Mac anyone plays on. LineSweeper’s live demo has also been loaded and played briefly in Safari 27.0.1 on macOS 27.0.1. 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.

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 page’s own sentence for a failed download is later than these checks, and the page has not been opened from file:// since it was added.

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.

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

All documentation versions