Files
eric a10b048968
build / Build Docker Image (push) Canceled after 0s
eom.dev customization
2026-10-24 18:49:03 -04:00

159 lines
7.1 KiB
Markdown

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](.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/lwproxy` build. Nginx forwards
`/proxy` WebSocket 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](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