Luanti-wasm
This is an experimental port of Luanti to the web using emscripten/WebAssembly.
System Requirements
This has only been tested on Ubuntu 20.04.
- Ubuntu: apt-get install -y build-essential cmake tclsh
Building
cd luanti-wasm
./build_all.sh
Single-server menu
The in-game main menu uses Catppuccin Mocha and only offers username, password, and Connect. Server browsing, editable destinations, local worlds, hosting, and content installation are not exposed. Connection errors return to this menu. Passwords are not saved by the menu.
The build-time environment variables LUANTI_SERVER_ADDRESS and
LUANTI_SERVER_PORT select the destination (defaults: luanti.eom.dev, 30000).
The packer writes them beside the builtin menu, outside player settings. Set them
before running the build. To change just the destination or menu after a build,
rerun build_fsroot.sh and build_www.sh with the same environment; recompiling
the WASM binary is not necessary.
The launch page also uses Mocha. It does not accept destination, auto-connect,
invite, or hosting query parameters, and uses a same-origin /proxy WebSocket
endpoint instead of a public proxy selector.
Docker Compose
Copy .env.example to .env if you want to change the defaults,
then run docker compose up --build -d. Open http://localhost:8080 in a browser
with WebAssembly JSPI support. The initial build compiles Luanti, Emscripten
dependencies, and the proxy, so it can take a long time and needs substantial RAM
and disk space.
The two services are:
- web: the compiled browser client served by unprivileged Nginx, including the COOP/COEP headers needed for WebAssembly threads.
- proxy: a pinned, protocol-compatible
paradust7/lwproxybuild. Nginx forwards/proxyWebSocket upgrades to it on the private Compose network. No proxy or UDP port is published on the host.
This runs the web client and networking proxy, not a dedicated Luanti game
server. The proxy must be able to reach luanti.eom.dev:30000/UDP (or your chosen
server). In particular, localhost as a game destination means the proxy
container, not the Docker host.
LUANTI_SERVER_ADDRESS and LUANTI_SERVER_PORT are build arguments, not
runtime container settings: after changing them, run docker compose up --build -d
again. WEB_BIND_ADDRESS defaults to 127.0.0.1 and WEB_PORT to 8080.
The original Dockerfile artifact image remains the default build target; Compose
explicitly uses the smaller web runtime target.
If Docker reports that its automatic address pools are exhausted, use the optional
docker/compose.network.yaml override:
docker compose -f compose.yaml -f docker/compose.network.yaml up --build -d.
It uses 10.231.73.0/24; set LUANTI_SUBNET to another unused subnet if that
conflicts with your LAN or VPN. No existing Docker networks need to be removed.
For remote players, put an HTTPS reverse proxy in front of the web service,
forward WebSocket upgrades for /proxy, and preserve the COOP/COEP headers.
The launcher automatically uses wss:// on HTTPS pages. Non-localhost plain HTTP
does not provide the secure browser context required by the client. Only change
WEB_BIND_ADDRESS if necessary for your ingress setup.
Security boundary: the fixed destination is a UI restriction, not a network allowlist. A modified browser client can bypass it, and upstream lwproxy can relay UDP to other destinations. Keep this stack private for testing; before public deployment, add proxy authentication/access controls and egress firewall rules. The proxy's HTTP host allowlist does not restrict UDP game traffic. This setup does not expose browser-hosted games or native-client invite ports.
Checks (without a full WASM build)
From the repository root, run lua tests/menu.lua, node tests/launcher.cjs, and
bash tests/fsroot.sh (the last requires Bash, tar, zstd, and the system CA bundle).
Use docker compose config --quiet to check deployment configuration.
Alternatively, docker build --target checks -f docker/tests.Dockerfile . runs
all three regression suites in Linux without local Lua/Node installations.
Installation
If the build completes successfully, the www/ directory will contain the entire application. This
includes an .htaccess file which sets headers that are required (by browsers) to load the app.
If your webserver does not recognize .htaccess files, you may need to set the headers in
another way.
Persistent Storage
If the browser provides an origin private file system (OPFS), the whole /luanti tree is kept
there instead of in memory. A data pack is only downloaded and unpacked when its contents change.
What is mounted is the OPFS directory luanti, not the OPFS root. WasmFS has no way to root a
backend at a subdirectory, so emsdk_wasmfs_opfs_subdir.patch makes the OPFS backend do this.
Each pack records the URL it was installed from (luanti/.packs/<name>.ver) along with the list
of files it wrote (luanti/.packs/<name>.files). Since pack URLs contain the release id and are
served immutable, a new release invalidates the packs: the files the old version wrote are removed
and the new ones unpacked, leaving worlds and installed content alone.
Values passed to setConf() are applied as defaults, so a setting the player later changes in-game
is not overwritten on the next launch.
launch() calls navigator.storage.persist(). The browser may still evict the saved worlds under
storage pressure. Chrome and Safari decide whether to honor this silently, Firefox asks the user.
The storage URL parameter overrides this feature:
?storage=auto use OPFS when available (default)
?storage=memory never use OPFS
The CA certificate bundle installs to /etc/ssl/certs, outside of OPFS, so are unpacked (from
certs.pack) on every run.
Network Play
The supplied launch page uses the same-origin /proxy endpoint, provided by the
Compose stack. If hosting the generated files elsewhere, configure your webserver
to forward this endpoint to lwproxy, including WebSocket upgrades. A proxy is
necessary because websites cannot open normal TCP/UDP sockets.
The reusable LuantiLauncher API still defaults to wss://luanti.dustlabs.io/proxy
unless a page calls setProxy(). Public regional alternatives include:
North America (Dallas) - wss://na1.dustlabs.io/mtproxy South America (Sao Paulo) - wss://sa1.dustlabs.io/mtproxy Europe (Frankfurt) - wss://eu1.dustlabs.io/mtproxy Asia (Singapore) - wss://ap1.dustlabs.io/mtproxy Australia (Melbourne) - wss://ap2.dustlabs.io/mtproxy
The compatible proxy server is https://github.com/paradust7/lwproxy. The browser networking shim is here:
https://github.com/paradust7/webshims/blob/main/src/emsocket/proxy.js
Custom Emscripten
The Emscripten SDK (emsdk) will be downloaded and installed the first time you build. To provide
your own instead, set $EMSDK before building (e.g. using emsdk_env.sh). An external Emscripten
may need to be patched by running this exactly once:
./apply_patches.sh /path/to/emsdk