159 lines
7.1 KiB
Markdown
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
|