Put your game on the web
This page puts the game from Get the starter project on the
internet as a web page, at an address such as https://your-name.github.io/mygame-web/, which
anyone can open and play in a current browser on a computer, with nothing to download or install.
It uses GitHub Pages, GitHub’s free hosting for static pages, from the same GitHub account
that Put your project on GitHub makes. The page goes in a repository
of its own, mygame-web, which holds only the five files the page needs, so your game’s own
repository can stay private. It takes about 30 minutes the first time, and 3 for each update
after.
You need:
- The browser build working: Build for the browser installs Emscripten,
and its
wasm-debugbuild and page should work in your project. This page buildswasm-release, the smaller and faster version, the same way. - A GitHub account, and Git signed in to it: steps 1 and 6 of Put your project on GitHub. Your game’s own repository does not have to be on GitHub.
Every command runs in an x64 Native Tools Command Prompt where Emscripten’s emsdk_env.bat has
run, in your project’s folder, as on the browser page:
C:\dev\emsdk\emsdk_env.batcd /d C:\dev\mygameGitHub Pages serves a repository’s files over HTTPS, as they are, with .wasm files marked as
WebAssembly, which is what Put your game on a web host asks of a host.
It is free for a public repository. A repository published with it must be public on a free
account, so anyone can read the five files; that is true of every web page anyway.
-
Link the notices from your page. The release carries a
NOTICE.txtwith the licences of the engine, the font and Emscripten’s libraries, and the page should link it. Open the page’s template:Terminal window notepad game\web\shell.htmlSearch with Ctrl+F for
<p id="status". Below that line, add:<p><a href="NOTICE.txt" style="color: #8cf">Third-party notices</a></p>so that the two lines read:
<p id="status" role="status">Loading...</p><p><a href="NOTICE.txt" style="color: #8cf">Third-party notices</a></p>role="status"is there so that a screen reader reads the line out when the page changes it. The line above it,<canvas id="canvas" tabindex="0" aria-label="Minimal sample"></canvas>, is the game’s picture, andaria-labelis the name a screen reader gives it.Minimal sampleis a placeholder, as the title is: change both to your game’s name. The<title>line is near the top,Labrador - minimal sample, and it is the browser tab’s title. Save and close Notepad.The
v0.3.0starter’s lines have noroleoraria-labelattributes yet. Addrole="status"to its<p id="status">andaria-label="Your game's name"to its<canvas>as above; these are page attributes and work with its existing engine. -
Configure the release build. This is needed once:
Terminal window cmake --preset wasm-releaseIt ends
-- Build files have been written to: C:/dev/mygame/out/build/wasm-release, after about 10 seconds, or about five minutes the first time, when vcpkg fetches its list of packages from GitHub: leave it running. It prints three warnings that this version of CMake does not support emscripten shared libraries; the game uses none, so they do not matter. If it stops withinclude could not find requested file:and a path starting/upstream/emscripten,emsdk_env.bathas not run in this prompt: run it, deleteout\build\wasm-releasewithrmdir /s /q out\build\wasm-release, and configure again. -
Save the release script. Building the page, gathering it with its notices and copying it to the folder you publish is a long command, so it goes in a file you run each time. First make the empty file, then open it:
Terminal window if not exist web-release.bat type nul > web-release.batnotepad web-release.batThe first line makes an empty file and prints nothing; it leaves the file alone if it is already there. Notepad opens the empty file. Paste this whole box into it, then save and close Notepad:
web-release.bat @echo offrem Builds the browser release of the game, gathers it with its notices inrem out\web-release, and copies it to C:\dev\mygame-web, the folder thatrem GitHub Pages publishes. Run it from the project's folder, in an x64 Nativerem Tools Command Prompt where C:\dev\emsdk\emsdk_env.bat has run.if not defined EMSDK (echo EMSDK is not set. Run C:\dev\emsdk\emsdk_env.bat in this prompt, then this again.exit /b 1)if not exist game\web\shell.html (echo Run this from your project's folder: cd /d C:\dev\mygameexit /b 1)cmake --build --preset wasm-release || exit /b 1ctest --preset wasm-release || exit /b 1if not exist game\web\Microsoft-LICENSE.txt copy external\labrador\tools\web_bundle\Microsoft-LICENSE.txt game\web\ >nulset "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 "index.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" || exit /b 1if not exist C:\dev\mygame-web mkdir C:\dev\mygame-webcopy /y out\web-release\* C:\dev\mygame-web >nul || exit /b 1type nul > C:\dev\mygame-web\.nojekyllecho The web release is in C:\dev\mygame-web:dir /b /a-d C:\dev\mygame-webWhat it does, in order: builds the
wasm-releasepage and runs its test; copies Microsoft’s licence for the engine’s timer code intogame\webthe first time; runs Labrador’s bundler, which puts the page, its script and its module inout\web-releasewithNOTICE.txtandBUILD.json, a record of what was built, naming the pageindex.html, the name a web server sends when an address ends in a folder; and copies the five files toC:\dev\mygame-web. The empty.nojekyllfile tells GitHub Pages to publish the files as they are, without running Jekyll, the site builder it otherwise runs over a repository. Renaming the page is safe: it loadsMyGame.jsandMyGame.wasmby name from its own folder. -
Run it:
Terminal window web-release.batThe first run builds the engine for the browser, about 90 steps, and took 13 seconds on the fast desktop where this page was checked; expect longer on a slower machine. Later runs rebuild only what changed, in a few seconds. The end of its output is the test, the bundler’s list of files with their sizes, and the folder:
Output 100% tests passed, 0 tests failed out of 1Total Test time (real) = 0.05 secMyGame.js 119887 bytes, 27539 under BrotliMyGame.wasm 388334 bytes, 120166 under BrotliNOTICE.txt 102282 bytes, 12468 under Brotliindex.html 1259 bytes, 568 under Brotlifrom 192d43d83b1ec128b1eca491f0bfd29939366a23 with uncommitted changesThe web release is in C:\dev\mygame-web:.nojekyllBUILD.jsonindex.htmlMyGame.jsMyGame.wasmNOTICE.txtThe two numbers are each file’s size and its size compressed, which is roughly what a player downloads, about 160 KB in all for the starter; the line after them names the commit of your game’s Git repository, or says
unknownif it is not one, andwith uncommitted changeswhen it has changes not yet committed, as it does here after step 1’s edit.BUILD.jsonrecords the same. If the script stops before this, its last lines say why: see If something fails.If your game’s project is a Git repository,
git statusin its folder now also lists two new files:Output ?? game/web/Microsoft-LICENSE.txt?? web-release.batThey are part of the game’s project: commit them with it, as in Sending the next change.
-
Check it on your own machine, as GitHub Pages will serve it. Pages serves the site under a folder named after the repository,
/mygame-web/, and sendsindex.htmlfor the folder itself. ServingC:\devdoes the same here, with the Python that came with Emscripten:Terminal window "%EMSDK_PYTHON%" -m http.server 8000 --bind 127.0.0.1 --directory C:\devIt prints
Serving HTTP on 127.0.0.1 port 8000 (http://127.0.0.1:8000/) ...and keeps the prompt. Openhttp://127.0.0.1:8000/mygame-web/in Chrome, Edge or Firefox, with the/at the end: the greeting draws, the keys work, and Third-party notices below the game opens the notices. The prompt prints a line for each file the browser asks for, ending200when it was sent:Output 127.0.0.1 - - [31/Oct/2026 00:09:40] "GET /mygame-web/ HTTP/1.1" 200 -127.0.0.1 - - [31/Oct/2026 00:09:40] "GET /mygame-web/MyGame.js HTTP/1.1" 200 -127.0.0.1 - - [31/Oct/2026 00:09:40] "GET /mygame-web/MyGame.wasm HTTP/1.1" 200 -127.0.0.1 - - [31/Oct/2026 00:09:41] code 404, message File not found127.0.0.1 - - [31/Oct/2026 00:09:41] "GET /favicon.ico HTTP/1.1" 404 -The
404for/favicon.icois the browser asking for a tab icon the page does not have, and is harmless. A404for one of the game’s own files means it is not inC:\dev\mygame-web: run step 4 again. When you have played it, click the prompt and press Ctrl+C to stop the server; it saysKeyboard interrupt received, exiting.Because of--bind 127.0.0.1, only this machine can reach the server while it runs. -
Make the site folder a Git repository and record the five files:
Terminal window cd /d C:\dev\mygame-webgit initgit add .git commit -m "Publish my game"git branch -M maingit add .warns thatLF will be replaced by CRLFforBUILD.json,MyGame.jsandNOTICE.txt, which is harmless: Git stores them as they are and GitHub serves them so.git commitprints:Output [master (root-commit) 8cd3822] Publish my game6 files changed, 2007 insertions(+)create mode 100644 .nojekyllcreate mode 100644 BUILD.jsoncreate mode 100644 MyGame.jscreate mode 100644 MyGame.wasmcreate mode 100644 NOTICE.txtcreate mode 100644 index.htmlwith your own seven characters after
root-commit.git branch -M mainprints nothing. -
Make the repository on GitHub. On github.com, click the + at the top right, then New repository. Name it
mygame-web; choose Public; leave it empty, with no README,.gitignoreor licence; and click Create repository, as in step 4 of Put your project on GitHub. The repository’s name is part of the page’s address. -
Send the files to it. Paste the first line, change
your-nameto your GitHub username before pressing Enter, then run the second:Terminal window git remote add origin https://github.com/your-name/mygame-web.gitgit push -u origin mainIf this is your first push from this machine, the Connect to GitHub window opens: click Sign in with your browser, as in step 6 of Put your project on GitHub, which also lists what each failure means. The push uploads about 195 KB and ends
* [new branch] main -> mainandbranch 'main' set up to track 'origin/main'. -
Turn on GitHub Pages. On the repository’s page on GitHub, click Settings, under the repository’s name; in the list on the left, under Code, planning, and automation, click Pages. Under Build and deployment, set Source to Deploy from a branch; under Branch, choose
mainand/ (root), and click Save.GitHub then publishes the site, which takes a minute or two and can take up to ten. The repository’s Actions tab shows it as a run called pages build and deployment, with a yellow dot while it works and a green tick when it is done. Reload the Pages settings page: it then says the site is live, gives its address, and has a Visit site button.
-
Play it on the web. The address is
https://your-name.github.io/mygame-web/, with your username, in lower case. Open it: the game loads as it did on your machine. Send the address to your friend.
Check what the browser received
Section titled “Check what the browser received”GitHub Pages sends the files the way the game needs, but checking takes a minute and shows where to look when something is wrong. On the game’s page, press F12 to open the browser’s developer tools:
- Console: nothing in red. A red line is a problem; If something fails has the common ones.
- Network: press F5 to reload with the tab open. The list shows
mygame-web/(the page),MyGame.jsandMyGame.wasm, each with status200. ClickMyGame.wasmand, under Headers, Response Headers,Content-Typeisapplication/wasm. With another type the game still starts, more slowly, and the console sayswasm streaming compile failed; Put your game on a web host explains.
Updating the game
Section titled “Updating the game”After changing the game, in the prompt where emsdk_env.bat has run:
cd /d C:\dev\mygameweb-release.batcd /d C:\dev\mygame-webgit add .git commit -m "Update my game"git pushGitHub publishes the new version a minute or two after the push. GitHub Pages tells browsers to
keep each file for up to ten minutes (Cache-Control: max-age=600), so a browser that opened the
page shortly before may show the old version, or for a moment a new page with the old module,
which may stop it with an error in the console. Wait ten minutes, or press Ctrl+F5 to reload
everything.
If something fails
Section titled “If something fails”A build error, a failing test or a Git message is the same as elsewhere: Read a build error, Build for the browser, and Put your project on GitHub. 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 game has been checked in desktop Chrome, Edge, Firefox and Safari, Safari on a hosted build machine rather than a Mac anyone plays on; phones, touchscreens and physical gamepads have not been checked. Platform support says how and when each browser was checked. Sound starts after the player’s first key press or click, which is a browser rule. GitHub Pages limits a site to 1 GB and about 100 GB of downloads a month, far more than a game of a few hundred kilobytes needs, and its terms do not allow it to run a business such as a shop.
Where to go next
Section titled “Where to go next”- Put your game on a web host says what any other host must send, for when you outgrow Pages or want your own domain.
- Send your game to a friend is the Windows download instead.
What was checked
Section titled “What was checked”On 2026-10-30 and 31, in a starter project made from a starter ZIP of this tree at
C:\dev\g8-author\exact\mygame, with Emscripten 6.0.12, Visual Studio 2026’s CMake 4.3.1 and Git
for Windows 2.52.0, steps 1 to 6 and 8 ran as shown, with C:\dev\g8-author\exact in place of
C:\dev in the script and the commands, and the output above is from those runs with the folder
changed back. Step 1’s line was added to shell.html as then worded, by a search for the status
line’s whole tag, which had no role yet, and web-release.bat saved with
Windows’ line ends, as Notepad saves it. The configure took 11 seconds; the first run of the
script 13, and a run after changing the page’s title 6, after which git add, git commit and
git push sent the two changed files, index.html and BUILD.json. On another configure the
same day vcpkg spent six minutes fetching its list of packages from GitHub, which is why step 2
allows for longer.
The local check of step 5 served the folder with Emscripten’s Python 3.13 at
http://127.0.0.1:8000/mygame-web/: /mygame-web without the slash answered 301 to the
address with it, index.html was sent for the folder, and MyGame.wasm as application/wasm.
Labrador’s page runner, pointed at that address, loaded the page in headless Chrome 156, saw 60
frames, pressed Escape and Enter and saw the page’s Module.onQuit; its only complaint was the
favicon.ico 404, and with an empty favicon.ico beside the folder it passed. A headless
screenshot showed the greeting and the Third-party notices link. With MyGame.js moved away,
the runner reported Failed to load resource: the server responded with a status of 404 (File not found) for it before the game started. The script’s two refusals, an unconfigured
wasm-release, and web-release.bat typed in a folder without it gave the messages quoted. Two
servers started on port 8000 both started, without an error, so the page does not quote one.
No GitHub repository was created, nothing was pushed to GitHub, and Pages was not turned on.
Step 8’s push went to an empty repository on the same machine, standing in for GitHub, with the
address line changed: it sent 8 objects, 194.47 KiB. Steps 7, 9 and 10, the pages build and
deployment run, the Visit site button and the visibility setting are written from GitHub’s
documentation as it stood on 2026-10-30: Creating a GitHub Pages site, Configuring a publishing
source for your GitHub Pages site, About GitHub Pages and GitHub Pages limits, which give the
public-repository rule, the branch and folder choices, .nojekyll, the ten minutes a publish can
take, and the 1 GB and 100 GB limits. What GitHub Pages sends was read from a public Pages site,
mdn.github.io/webassembly-examples, with curl: Content-Type: application/wasm for a .wasm
file, Cache-Control: max-age=600 on every file, a 301 from a repository’s address without the
slash to the address with it, and the two 404 pages quoted under If something
fails, There isn’t a GitHub Pages site here. for an unknown repository and
File not found for a missing file. The game itself has not been served from GitHub Pages.
On 2026-10-31 a second agent followed the page as worded in another fresh starter at
C:\dev\g8-follow\mygame, with C:\dev\g8-follow in place of C:\dev in the script and the
commands and the machine’s C:\Tools\emsdk in place of C:\dev\emsdk. The script’s three
refusals, the missing-emsdk_env configure and its recovery, the three shared-library warnings,
the first script run, 12 seconds and 92 steps, with the bundler’s sizes exactly as above, the
served check’s 301, 200s, application/wasm and favicon 404, a headless screenshot with the
greeting and the notices link, and step 6’s warnings and commit all matched; the push went to a
local stand-in, as before. Four points were corrected from that run. Its first wasm-release
configure took 283 seconds, so step 2 now says about five minutes the first time; step 8 now says
the Connect to GitHub window opens for a reader who has not pushed from this machine before;
step 4 now names the two files the script leaves for the game’s own repository, which git status
in the first starter listed as ?? game/web/Microsoft-LICENSE.txt and ?? web-release.bat; and
the follower stopped the server by ending its process, so it did not see step 5’s Ctrl+C line.
That line was then seen in the first starter: Emscripten’s Python server, started in a console of
its own and sent Ctrl+C there by GenerateConsoleCtrlEvent, printed
Keyboard interrupt received, exiting. and exited.
On 2026-10-31 a reviewer ran steps 1 to 6 again in a third fresh starter, with the script copied
from this page: 92 build steps, the bundler’s sizes exactly as above, the six files, the two new
files in git status, and step 6’s three warnings and six-file commit. Served at
/mygame-web/, the folder gave the 301, index.html and application/wasm, and Labrador’s page
runner, given the published index.html, saw the page quit through Module.onQuit in headless
Chrome.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.