From 8c5457bc68da00892967e57992c8a4b3813f311e Mon Sep 17 00:00:00 2001 From: Bulat Fatykh <68301540+gitoutofthere@users.noreply.github.com> Date: Thu, 1 Oct 2026 17:07:23 +0300 Subject: [PATCH] docs: clarify master settings for players --- docs/MASTER.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/MASTER.md b/docs/MASTER.md index 8fd4b40..84c39a4 100644 --- a/docs/MASTER.md +++ b/docs/MASTER.md @@ -39,12 +39,45 @@ the honest description: it forwards packets and vouches for nobody. ## Hand out to players — this block plus `iw4l-ca.pem` -The host opens a match with `IW4L_MASTER_HOST_NAME='name' make map mp_boneyard`, -the rest join from `make menu`, 2..=18 (`IW4L_MASTER_MAX_PLAYERS`). Trust rests -entirely on pinning `ca.pem`, so hand it over a trusted channel. +Give every player these settings and the public CA file over a trusted channel. +Add the settings to their existing `.env`, replacing the address and CA path: ```dotenv IW4L_MASTER_ADDR=1.2.3.4:4433 IW4L_MASTER_SERVER_NAME=iw4l-prod IW4L_MASTER_CA_CERT=/path/to/iw4l-ca.pem ``` + +This example is for the default `prod` installation. With `--channel dev`, use +port `4434` and server name `iw4l-dev` instead. + +| Setting | What it changes and when to set it | +| --- | --- | +| `IW4L_MASTER_ADDR` | The master to contact: a hostname or IP **with a port**, such as `1.2.3.4:4433` or `[::1]:4433`. The game has no built-in address; if unset, master networking is disabled. Set it on hosts and joining players. | +| `IW4L_MASTER_SERVER_NAME` | The name to check in the server certificate, independently of its IP. Required whenever the address is set; there is no built-in name. Use `iw4l-prod` for the default installation, not the VPS hostname. | +| `IW4L_MASTER_CA_CERT` | Path to the PEM CA file that lets the client trust your master. Set it for the private CA created by `install`. If unset, the client uses the platform certificate verifier; if set, only certificates from this file are trusted. Relative paths use the process working directory, which on Windows is the folder containing `iw4l.exe`. | +| `IW4L_MASTER_HOST_NAME` | The room name other players see. To host via `map`, set a name that is not empty or only whitespace, and leave `IW4L_MASTER_JOIN` unset. Names can occupy at most 48 UTF-8 bytes. Hosting through the menu uses `iw4l host` if the name is unset. Joining through the menu needs no host name. | +| `IW4L_MASTER_MAX_PLAYERS` | The room capacity, **including the host**. Optional; defaults to `18`. Set an integer from `2` through `18` to limit the room size. It is read only when creating a room, via `map` or the menu; invalid values prevent room creation rather than being clamped. | + +The host can start a match with: + +```bash +make map mp_boneyard IW4L_MASTER_HOST_NAME='Friday match' IW4L_MASTER_MAX_PLAYERS=8 +``` + +Other players open `make menu` and select the room. Master networking needs +MW2 multiplayer data (`common_mp.ff`); it is disabled during demo replay. +The examples above describe syntax checked against the source, not a live run. + +When a setting appears in more than one place: + +* **Direct game launch:** existing environment values win. The game loads one + `.env`: next to its binary first, otherwise the first found from the working + directory upwards. It fills only unset variables; files are not merged. +* **GNU make recipes (without `-e`):** command-line assignments as above win + over the repository `.env`, which wins over inherited environment values + for keys it defines. The Makefile exports these values to the game. + See GNU make's [environment rules](https://www.gnu.org/software/make/manual/html_node/Environment.html). +* **Portable Windows launcher:** inherited environment values win over the + adjacent `.env`; after an explicit update, release-manifest values fill only + settings still unset. See [`WINDOWS.md`](WINDOWS.md) for the portable layout.