Web Deployment Guide

Torque2D can be compiled to WebAssembly with Emscripten, so a game (or the in-engine editor) runs in any browser with WebGL — no plugin, no install. This page covers building the Web target, running it locally, deploying it, and the current limitations.

For the overall build system and the other platforms, see Building from Source.

Status: the Web target is part of the single CMake build and is runtime-verified — the Project Manager and toys render in-browser (text, sprites, and blended/lit draws). Verified with emsdk 6.0.1. The old hand-maintained engine/compilers/emscripten scripts predate the CMake migration and are no longer the build path.

How it works (the short version)

Emscripten compiles the engine's C/C++ through LLVM to a .wasm module plus a .js loader. The browser owns the event loop, so instead of a blocking while loop the engine is driven once per animation frame (emscripten_set_main_loop → Game->mainLoop()), the same model as iOS/Android. Rendering goes through WebGL 1.0 via Emscripten's LEGACY_GL_EMULATION. The game's scripts and assets are packed at build time into a single .data image that is mounted as an in-memory filesystem — there is no live disk in the browser.

A finished build is four files:

File	What it is
Torque2D_DEBUG.html	the page shell (canvas + the JS that boots the module)
Torque2D_DEBUG.js	the loader / runtime glue
Torque2D_DEBUG.wasm	the compiled engine
Torque2D_DEBUG.data	the packed script + asset tree (main.cs, editor/, library/, toybox/)

Prerequisites

• The Emscripten SDK (emsdk). Install it once:

  git clone https://github.com/emscripten-core/emsdk
  cd emsdk && ./emsdk install latest && ./emsdk activate latest
  

  Then activate it in the shell you'll build from:

  source ./emsdk_env.sh        # emsdk_env.bat on Windows cmd
  

• A make program on your PATH (the Web build uses the "Unix Makefiles" generator). On Windows, mingw32-make, MSYS make, or the Chocolatey make package all work.
• CMake 3.21+ and Python 3 (only for the tiny local web server below).

Windows / Git-Bash gotcha. emsdk_env.sh shells out to python, which on Windows often hits the Microsoft-Store python stub and silently fails to export EMSDK/PATH. If emcc isn't found afterward, drive the tools directly instead: set export EM_CONFIG=/c/Users/<you>/emsdk/.emscripten and prepend …/emsdk/upstream/emscripten and …/emsdk/node/<version>/bin to your PATH. Then emcc and emcmake work.

Building

From the repository root, with emsdk active:

./generate-emscripten.sh            # configures build/emscripten via emcmake
cmake --build build/emscripten -j   # compiles + links + packages the .data

generate-emscripten.sh is just a wrapper for emcmake cmake -S . -B build/emscripten -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug. emcmake points CMake at the Emscripten toolchain and defines EMSCRIPTEN=1, which selects the platformEmscripten back-end. Pass Release or Shipping to the script for an optimized build.

The output lands in build/emscripten/ (not at the repo root — it's a web bundle, not run from the working directory like the desktop builds).

Changing scripts or assets? You must repackage. The --preload-file asset trees are not tracked as CMake dependencies, so editing a .cs file or an asset does not trigger a rebuild of the .data on its own. After a script/asset edit, force it:

rm build/emscripten/Torque2D_DEBUG.{html,js,wasm,data}
cmake --build build/emscripten -j

Running locally

A browser will not load a wasm app from a file:// URL — you must serve it over HTTP. The simplest way:

cd build/emscripten
python -m http.server 8000

Then open http://localhost:8000/Torque2D_DEBUG.html. The Project Manager appears; pick the Toy Box (or your project) to run it. Bring up the in-engine console any time with **Ctrl + ~** (tilde).

Deploying to a web server

Upload the four Torque2D_DEBUG.* files (keep them together) to any static host. Two things to get right:

• MIME type for .wasm. The server should send application/wasm for the .wasm file so the browser can stream-compile it. Most modern hosts do this already; if the page fails to start, this is the first thing to check.
• The .data file is large. The full editor bundle is on the order of ~186 MB (it ships the editor's prebaked fonts and all the toys). A game-only build — your module plus library/, without the editor — is far smaller. Trim what you preload to keep the download reasonable.

For your own game you'll typically boot straight into a module instead of the Project Manager; see main.cs for the ModuleDatabase scan/load lines, and rebuild so the .data reflects your content.

Current limitations

• Scrollers don't render. The Scroller object clips with OpenGL clip planes, which WebGL 1.0 doesn't have. A WebGL-friendly clipping path would be needed; until then scroller layers won't draw on the web.
• No networking. Browsers can't open raw TCP/UDP sockets, so the engine's platformNet is stubbed on the Web target — the TorqueScript networking APIs are present but non-functional.
• Content is baked in. As noted above, scripts and assets live in the packed .data image, so changing them means a recompile/repackage, not a live reload.

Fonts on the web

The Web build has no system font service, so text is handled two ways, automatically: the engine's self-contained .uft glyph caches (shipped with the editor) render directly, and anything not in that cache is rasterized at runtime by FreeType (compiled to wasm) from a bundled Roboto face. The net effect is that web text behaves like the desktop — see the FontAsset Guide for the font system in general.

Browser support

Runs on any WebGL-capable browser. Chrome and Firefox have historically given the best performance.

---

Maintainer reference: the authoritative build recipe, the runtime fixes behind this round, and the known-issue list live in the engine repo at cmake/BUILD-PLATFORM-NOTES.md (the "Emscripten / Web round" section).