Vienna-WebGPU-Engine

Shipping to the Web (emdawnwebgpu)

How to build the engine for the browser and put it on an actual webpage. The web backend is emdawnwebgpu (Dawn’s Emscripten port, vendored in external/webgpu/emdawnwebgpu/pkg/); the implementation at runtime is the browser’s own WebGPU. Requires emsdk >= 4.0.10 (the vendored pkg is tested against 5.0.6):

git clone https://github.com/emscripten-core/emsdk %USERPROFILE%\emsdk
%USERPROFILE%\emsdk\emsdk install 5.0.6 && %USERPROFILE%\emsdk\emsdk activate 5.0.6

Build

From a shell where emsdk_env has run (and cmake/ninja are on PATH):

scripts\build-example.bat main_demo Release EMDAWN

Output in examples/build/main_demo/Emscripten/Release/:

File	Size (main_demo)	What it is
MainDemo.html	~6 KB	the page (from src/shell_web.html)
MainDemo.js	~250 KB	emscripten loader + emdawnwebgpu JS glue
MainDemo.wasm	~4.4 MB	the engine
MainDemo.data	~58 MB	resources/ + the example’s assets/, preloaded into MEMFS

src/shell_web.html is the default shell (loading bar, WebGPU-support check, engine log panel, fullscreen button); pass SHELL_FILE to add_engine_executable for a custom one. src/shell_minimal.html is the bare emscripten reference. The shell and the demo landing page (src/web_index.html) share their styling via src/web_theme.css. The shell’s log panel is batched: engine output is buffered and flushed to the DOM once per second (2000-line cap), so per-frame logging can never stall the page - wasm builds also raise the spdlog level to info so trace/debug spam never crosses the JS boundary in the first place.

Test locally

python -m http.server 8080 --directory examples\build\main_demo\Emscripten\Release

then open http://localhost:8080/MainDemo.html. WebGPU works on localhost without TLS; any other host needs HTTPS.

Hosting on a real webpage

Any static host works (GitHub Pages, Netlify, nginx, S3+CDN). Upload the four files. This repo automates it: .github/workflows/web-demo.yml builds every example (matrix, minus runtime_player which ships no assets) on tagged commits or manual dispatch and publishes them to GitHub Pages behind src/web_index.html.

• HTTPS is mandatory - browsers expose WebGPU only in secure contexts.
• MIME types: .wasm must be served as application/wasm; .data as application/octet-stream. Most hosts do this out of the box.
• Compression matters: the 58 MB .data compresses well (textures/models); enable gzip or brotli on the host. For long-term hosting, add far-future cache headers to .wasm/.data and version the filenames when updating.
• No special isolation headers needed: the build is single-threaded (no -pthread), so COOP/COEP / SharedArrayBuffer requirements do not apply.
• Embedding in an existing page: simplest is an <iframe src=".../MainDemo.html">. For native embedding, copy the <canvas id="canvas">, the Module script block from shell_web.html, and a <script src="MainDemo.js"> tag into your page.
• Browser support: Chrome/Edge (stable), Firefox 141+, Safari 26+; see caniuse.com/webgpu.

Web-platform constraints baked into the engine

Found while porting; all are guarded with __EMSCRIPTEN__ (or generic guards):

• PathProvider roots at MEMFS /; --preload-file maps engine resources/ to /resources and the example’s assets/ to /assets (see add_engine_executable).
• No threads without -pthread (which would force COOP/COEP hosting): SceneManager scene init runs inline (its std::async was awaited immediately anyway) and the physics thread is disabled with a warning in wasm builds.
• No encoder.writeTimestamp in the browser API (only pass-level timestampWrites): the FrameProfiler’s GPU timing is disabled in wasm builds.
• No explicit present: the browser presents at the end of the rAF callback; Renderer skips surface.present() under emscripten.
• Zero-size window events (canvas before CSS layout; also native minimize) are ignored in GameEngine::onWindowResize - WebGPU forbids 0x0 textures.
• -sASYNCIFY is required (the wrapper’s blocking requestAdapter/requestDevice helpers); -sASSERTIONS is Debug-only.
• The legacy WEBGPU_BACKEND=EMSCRIPTEN flavor (-sUSE_WEBGPU) predates the v29 header generation and no longer compiles against this engine - use EMDAWN.

Scene editor in the browser

The scene editor ships as a web demo too, with browser replacements for every native file dialog (tinyfiledialogs has no wasm backend - calling it aborts with null function):

• Open Project uses the browser’s directory picker (webkitdirectory): the whole project folder is copied into MEMFS under /projects/<name>/ and opened from there. A second menu entry, Open Project Zip…, accepts a .zip of the project folder instead (unpacked with the vendored miniz).
• Save / export goes the other way: the project directory is zipped in MEMFS and handed to the browser as a download. Nothing is ever written to a server - open and save are entirely client-side.
• Single-file pickers (import asset, open scene) use <input type="file">; message boxes and text prompts map to confirm()/prompt() with graceful fallbacks where the embedding context blocks them.
• All of this lives in examples/scene_editor/SceneEditorUI.cpp behind __EMSCRIPTEN__ guards (EM_ASYNC_JS/EM_JS interop).

This site is open source. Improve this page.