This document will go over how to configure and publish your project to the web using the WebAssembly target platform.
What you need
Unreal Engine 5.9: the Launcher (installed) build from Preview 1 on, or a source build. Windows is the documented host.
A C++ project. A Blueprint-only project needs one C++ class added (Tools > New C++ Class) before it can be packaged for the web.
Visual Studio with the C++ workload, as for any C++ project.
Git, to download the Emscripten SDK.
The Emscripten SDK (emsdk), version 6.0.10 exactly. No other version is currently accepted.
Chrome or Edge on Windows to test. Chrome is the reference browser.
1. Install the Emscripten SDK
Emscripten is the compiler that turns C++ into WebAssembly. Install it once per computer:
Install Git if you don't have it, then open a command prompt.
Clone emsdk to a short path, for example:
Shellgit clone https://github.com/emscripten-core/emsdk C:\emsdkGo to that folder and install version 6.0.10:
Shellcd C:\emsdk emsdk install 6.0.10Type the version number. Don't use emsdk install latest: emsdk also offers newer versions (6.0.11 and later, and 7.0.0), and the engine accepts only 6.0.10.
Activate it for your user:
Shellemsdk activate 6.0.10 --permanent--permanent saves the EMSDK environment variable for your user, which is how the engine finds Emscripten. It also saves EMSDK_NODE and EMSDK_PYTHON, and adds C:\emsdk and C:\emsdk\upstream\emscripten to your user PATH. Without --permanent, the activation lasts only for that command prompt. (Setting WASM_EMSDK_ROOT to the folder manually also works, and takes precedence over EMSDK.)
The first time you activate, emsdk prints Failed to read environment variable EMSDK (and the same for EMSDK_NODE and EMSDK_PYTHON) before setting each one. These messages only mean the variables didn't exist yet.
Make Windows pass the new variables to the programs you start. Programs read environment variables only when they start, and they inherit them from the program that starts them, so restarting the editor alone isn't enough:
Sign out of Windows and sign back in. Alternatively, open System Properties > Environment Variables and click OK, which makes File Explorer reload the variables. (emsdk's own notification doesn't reach File Explorer, so a project you open by double-clicking still gets the old variables.)
If you start the editor from the Epic Games Launcher or Visual Studio, quit them completely first. For the Launcher, right-click its icon in the system tray and choose Exit.
Close any open command prompts, and open new ones.
Start the editor again.
Check the SDK:
In the editor, go to Platforms > SDK Management > Wasm. It shows the allowed and installed SDK versions: both should read 6.0.10.
From a command prompt in the engine folder (for a Launcher install, cd /d "C:\Epic Games\UE_5.9"), run:
ShellEngine\Build\BatchFiles\RunUAT.bat Turnkey -command=VerifySdk -platform=WasmThe result should be Status=Valid with Current_Sdk=6.0.10.
Common problem: an older emsdk activated for another project leaves the EMSDK variable pointing at it, and the build then fails SDK validation. WASM_EMSDK_ROOT takes precedence over EMSDK, so set it to the 6.0.10 folder, or clear EMSDK.
2. Make a project
In the editor, go to File > New Project > Games > Third Person, choose C++, then set the folder and name.
Don't copy a template folder by hand. The copy misses the template's shared content, and renaming breaks its Blueprints.
If you enable the AllToolsets plugin (editor AI tooling, off by default), keep it in the editor only by listing it in the .uproject file as:
{ "Name": "AllToolsets", "Enabled": true, "TargetAllowList": [ "Editor" ] }Enabling the editor's MCP server can add AllToolsets to the .uproject file for you, without the TargetAllowList line. Check the file and add the line if it's missing.
3. Set your project settings
Web settings are in Project Settings > Platforms > Wasm (Web). They're saved in Config/DefaultEngine.ini, in the section [/Script/WasmTargetPlatform.WasmTargetSettings].
The ones most projects change:
Page Title: the browser tab title and the loading screen heading. Empty uses the project name.
Start Mode: Auto starts as soon as the game is ready. Click waits for a click, which also lets sound start (browsers allow sound only after a click or key press).
Mobile Devices: what phones and tablets see: Warn (default), Block or Allow.
Required Texture Features: the texture formats your cook needs. The default (BC) runs on desktop GPUs but not on most phones.
Target Mobile Deferred Tier: on by default. Desktop-class GPUs get the mobile deferred renderer and phones get mobile forward. Turn it off to cook only the forward renderer (a smaller cook).
Page Args: engine arguments every load gets. Add to them, but keep the default ones: they keep the browser's thread limit from being hit.
Inject Isolation Headers (Data Cache section): turn it on only for a host that can't send headers, such as GitHub Pages.
Brotli Quality Release (Packaging section): how hard the staged .br copies are compressed. 11 (the default) is the smallest download and the slowest packaging.
Set Project Settings > Maps & Modes > Game Default Map. Shipping builds ignore a map given in the page's arguments and always start in this map.
4. Build and package
From the editor
Go to Platforms > Package Project and, under Package For, choose Wasm. The menu closes.
Open Platforms > Package Project again and, under Build Configuration, choose Shipping. The default is Use Project Setting (Development).
Open Platforms > Package Project again and click Package Project at the top of the menu.
Choose an output folder, then click Select Folder.
The editor shows Packaging project for Wasm… while it works. Click Show Output Log to follow the progress.
These choices are saved for your user, so later packages use them too.
To build and run in one step, choose a device from Platforms > SDK Management > Wasm: Local Browser or a specific browser (Chrome or Edge). The editor builds, cooks, starts a local server and opens the page.
From the Command Line
Run this command prompt in the engine folder:
Engine\Build\BatchFiles\RunUAT.bat BuildCookRun -project=<Path>\<Project>.uproject -platform=Wasm -clientconfig=Shipping -build -cook -stage -pak -iostore -package -archive -archivedirectory=<OutputFolder> -unattendedNotes
Use Shipping for anything you share: it's much smaller and uses less memory. Development builds contain source paths, so the deploy tools refuse them. The Launcher engine can't build the Test configuration.
The first build compiles the editor tools and your project, which can take a while. Linking the game takes a few minutes and a lot of memory. A first Shipping package of the Third Person template takes about 15 minutes.
Once the build is completed, you will get the following:
<OutputFolder>\Wasm is the whole website: index.html, the page scripts, the game's .wasm and data files, and .br compressed copies of some files.
Next to it, Wasm-Debug holds files that must never be uploaded, such as the symbol map. Keep it to read crash call stacks. The editor's Package Project doesn't stage the symbol map there. It stays at <Project>\Binaries\Wasm\<Project>-Wasm-Shipping.js.symbols, and the next build replaces it, so copy it if you need it.
The output folder also gets Play_<Project>.bat (and play-<project>.sh for macOS and Linux) and serve.py.
5. Run your project locally
Double-clicking index.html doesn't work. The game needs a web server that sends two security headers (cross-origin isolation), and the engine's own server does that.
Open it directly
Double-click Play_<Project>.bat in the output folder. It serves the Wasm folder on port 8950 and opens the game in your default browser. The server stops about 10 seconds after you close the game's tab. It needs Python 3.8 or newer (or an installed Unreal Engine, whose Python it uses).
Run a local server
Alternatively, you can run the local server yourself. Use this command prompt in the engine folder:
Engine\Binaries\ThirdParty\Python3\Win64\python.exe Engine\Platforms\Wasm\Build\Tools\web\serve.py --root <OutputFolder>\Wasm --port 8800Then open http://127.0.0.1:8800/index.html. Press Ctrl+C in the command prompt to stop the server.
Check that the game started
Press F12 to open the browser's developer tools, then click the Console tab. The engine prints UE_RUN READY when the game has started, and UE_RUN ERROR if something failed. Type UE_RUN in the filter box to show only these lines.
With Play_<Project>.bat, the console also shows a 404 (Not Found) error for __ue/log. You can ignore it.
Page URL options
?debug=1: an overlay with the frame rate, startup timings and cache use. Press Ctrl+Alt+D to show or hide it.
?compat=1: shows a compatibility report instead of starting the game: whether this browser and GPU pass each check and, if not, why. Useful when someone says the game won't start for them.
?tier=forward or ?tier=deferred: force a renderer.
?sw=0: skip the download cache.
Play_<Project>.bat opens index.html?ue-session=1. Keep ue-session=1 when you add options to that address, for example index.html?ue-session=1&debug=1: the server stops when no page with it is open.
To test on a phone or another PC, the page must be served over HTTPS: serve.py takes --bind 0.0.0.0 --tls-cert <cert.pem> --tls-key <key.pem>, and the device must trust the certificate.
Command-line arguments
Add ?args= to the page URL, followed by the engine arguments, URL-encoded. A space becomes %20, and &, # and ? inside an argument become %26, %23 and %3F. Example:
http://127.0.0.1:8800/index.html?args=/Game/Maps/MyMap%20-MyFlag=1A first argument without a leading - is the map to open. Combine args with other options using &, for example ?tier=forward&args=-MyFlag. Arguments that every player should get belong in the Page Args project setting.
Shipping builds ignore most command-line arguments, including the starting map. The page passes on only a map under /Game/, -culture=, -WebQualityPreset= and -WebScreenPercentage=, and the game ignores the map and always starts in the Game Default Map. To let ?args= choose the map in Shipping, define UE_ALLOW_MAP_OVERRIDE_IN_SHIPPING=1 in the game's target. Development builds accept any argument, so test command-line options there.
6. Host it on a web server
Upload the contents of the Wasm folder as-is (never Wasm-Debug). The server must:
Serve over HTTPS.
Send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp on index.html and sw.js, and Cross-Origin-Resource-Policy: same-origin on every file. Without them, the page stops with "not cross-origin isolated".
Send the right types: application/wasm for .wasm, text/javascript for .js, application/json for .json, application/octet-stream for .pak, .ucas and .utoc.
Answer byte-range requests with 206 and the raw bytes, and never compress files on the fly. A compressed range corrupts the game's data reads.
Send Cache-Control: no-cache. The page's download cache already tracks every file by its hash.
Optionally, serve <file>.br with Content-Encoding: br for whole-file requests. It cuts the download a lot: the Third Person template's 140 MB .wasm downloads as 26 MB.
Check the host's file size limit. The game's .wasm is larger than the limit of some hosts: for example, Cloudflare Pages accepts files up to 25 MiB.
Ready-made configurations for nginx, Apache, IIS, Netlify and Cloudflare-style hosts are in Engine/Platforms/Wasm/Build/Tools/deploy/templates. For a host that can't set headers, turn on Inject Isolation Headers.
The deploy tools are in Engine/Platforms/Wasm/Build/Tools/deploy. Run them with the engine's Python, from a command prompt in the engine folder:
To check a stage before upload, run check_stage.py:
ShellEngine\Binaries\ThirdParty\Python3\Win64\python.exe Engine\Platforms\Wasm\Build\Tools\deploy\check_stage.py <OutputFolder>\WasmAfter upload, run webdoctor.py with the game's URL. It also works on a local server, for example http://127.0.0.1:8800/.
deploy.py --stage <OutputFolder>\Wasm --host <host> --prefix <name> writes a deploy plan for a host type (static, pages, r2worker, s3cf, netlify or zip) and reports files that are over the host's limits. It never uploads anything.
For updates, upload each build to a new folder and switch to it, rather than overwriting the live build: open tabs still read the old files.
7. Host it on itch.io
itch.io limits for HTML games: 500 MB in total (extracted), 200 MB per file, 1,000 files, paths up to 240 characters, and file names are case-sensitive. itch.io raises the limits on request.
Package Shipping. If the build is still too large, delete .br files that have a plain copy next to them: they only make the first download faster. (deploy.py --host zip leaves them out for you.)
Create the project at itch.io/game/new: set Kind of project to HTML, and under Embed options, choose Embed in page (for example 1280 x 720), and turn on Fullscreen button, Click to play and SharedArrayBuffer support.
Save, then open Edit game again and check that SharedArrayBuffer support is still on. The new-project form has dropped it before, and without it the game stops with "not cross-origin isolated". The _headers file and Inject Isolation Headers don't help on itch.io, because the game runs in itch.io's frame.
Upload the contents of the Wasm folder: zip them so index.html is at the top of the zip, or use itch.io's butler tool (butler push <OutputFolder>\Wasm <user>/<game>:html). Then select This file will be played in the browser and save.
Check it: open the page in Chrome, press F12, switch the console's context from top to index.html, and check that crossOriginIsolated is true.
Keep preview builds in Draft and share the secret URL.
8. Good to know
Phones and tablets run the mobile forward renderer. iPhone runs single-threaded; use Shipping there. Preview 1 works best on iOS 27. On iOS 26, Development builds can run out of memory at startup; turning off Audio Thread (single-threaded) in the Wasm project settings (Threading and Sound > iOS) avoids it.
Most phones can't use BC textures (only recent iPhones can). To support them, package a second texture set: cook again with -cookflavor=ASTC into another folder, then package with -WasmAddTextureSet=<that folder>\Wasm_ASTC, or use the web-texture-sets LLM skill included in the engine (Engine/Platforms/Wasm/Skills). The page picks the set the device supports at start time.
Sound starts only after the first click or key press (a browser rule). Start Mode Click makes that click part of starting the game.
There are no raw network sockets in a browser. Multiplayer works through a WebSocket relay (ws_relay.py) to a native server. The browser can't host a game.
The page caches downloaded files, so later visits are fast. To reset it, load the page with ?sw=0, or in the developer tools, go to Application > Storage > Clear site data.
For a quick code-only change, rebuild the game and run Build/Tools/web/update_stage_binaries.py to copy the new .wasm into an existing stage, instead of packaging again.
The engine's own documentation for the web platform is in Engine/Platforms/Wasm/Docs.