R3: Player, server and contributor documentation
- docs/PLAY.md is now the player guide: install from the tarball or .deb, starting a match, controls, how a match goes, settings files and troubleshooting, ahead of the graphics and tested-configuration sections. - docs/SERVER.md: quick start, every option, ports, being found, logs, Docker and systemd, memory, and what was checked. - CONTRIBUTING.md (engine setup, rules, commits, licence of contributions) and CREDITS.md. - README: status and known limitations as they are. - GDD controls table matched to the real defaults (B, Tab, G, 1 to 6). Running the documented commands from an unpacked release found two bugs, fixed here: - `tidewall --connect=HOST` ignored the option unless it came after `--`. ClientConfig.game_args() now takes the game's own options from the engine's arguments when there is no `--`; tested. - A headless run with no mode printed a line and never exited; it quits now. The renderer option is given as the pair the capture tests use (`--rendering-method gl_compatibility --rendering-driver opengl3`) in the docs, the tarball README and the man page. The Join menu only searching the LAN is documented and filed as #82. Closes #62 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+128
@@ -0,0 +1,128 @@
|
||||
# Running a Tidewall server
|
||||
|
||||
A Tidewall server is the game itself running headless. It needs no display, GPU or
|
||||
sound card. It runs matches back to back, fills empty places with bots, and logs one
|
||||
JSON object per line on standard output. With 24 bots it uses about 200 MB of memory
|
||||
and well under one CPU core.
|
||||
|
||||
Container and systemd details are in [packaging/README.md](../packaging/README.md).
|
||||
For playing, see [PLAY.md](PLAY.md).
|
||||
|
||||
## Quick start
|
||||
|
||||
From the release tarball (see [PLAY.md](PLAY.md#install)):
|
||||
|
||||
cd tidewall-0.9.0-linux-x86_64
|
||||
./tidewall-server --config=server.cfg
|
||||
|
||||
From the Debian package, copy the example configuration first:
|
||||
|
||||
cp /usr/share/doc/tidewall/examples/server.cfg .
|
||||
tidewall-server --config=server.cfg
|
||||
|
||||
The example takes players over UDP port 24650, answers LAN discovery on 24651, fills
|
||||
empty places with bots and answers a health check on TCP 24650 on loopback. Ctrl+C or
|
||||
SIGTERM stops it cleanly: everyone connected is told the server shut down, and it exits
|
||||
with code 0.
|
||||
|
||||
Check it is up:
|
||||
|
||||
curl -s http://127.0.0.1:24650/health
|
||||
|
||||
which answers with something like
|
||||
`{"max_players":24,"phase":"lobby","players":0,"status":"ok","tick":189,"uptime_s":7}`.
|
||||
|
||||
Check that a game can see it, from the same machine or the LAN:
|
||||
|
||||
./tidewall --headless --browse --lan-target=127.0.0.1
|
||||
|
||||
## Options
|
||||
|
||||
Every option works on the command line (`--port=24700`) or in a `--config` file (one
|
||||
per line, without the dashes: `port = 24700`, or a bare `listen`). Options on the
|
||||
command line after `--config` win over the file. A misspelt or unknown option stops the
|
||||
server with exit code 2 instead of running the wrong match.
|
||||
|
||||
| Option | Default | What it does |
|
||||
|---|---|---|
|
||||
| `listen` | off | Take players over the network. Without it the server plays a bot-only match. |
|
||||
| `port=N` | 24650 | UDP port for players. LAN discovery uses this port plus one. |
|
||||
| `bots=N` | 0 | Any number above 0 fills each match's empty places with bots. |
|
||||
| `bot-difficulty=` | `mixed` | `easy`, `normal`, `hard` or `mixed`. |
|
||||
| `name=NAME` | `Tidewall server` | The name shown in server lists. |
|
||||
| `list=HOST[:PORT]` | none | Register with a list server, so people off your LAN can find you. Can be given more than once. |
|
||||
| `no-lan` | off | Don't answer LAN discovery. |
|
||||
| `seed=N` | random | The first island. Later islands follow from it, so a whole session can be replayed. |
|
||||
| `health-port=N` | 0 (none) | Answer `GET /health` on this TCP port. |
|
||||
| `health-bind=ADDRESS` | `127.0.0.1` | Where the health check listens. |
|
||||
| `log-every=N` | 0 | A progress line every N ticks (30 a second). |
|
||||
| `matches=N` | 0 | Stop after N matches. 0 runs until stopped. |
|
||||
| `ticks=N` | 0 | Stop after N ticks. 0 runs until stopped. |
|
||||
| `config=PATH` | none | Read options from a file. |
|
||||
|
||||
The full list, including options for tests, is in
|
||||
[`src/server/server_config.gd`](../src/server/server_config.gd).
|
||||
|
||||
## Ports and firewalls
|
||||
|
||||
| Port | Protocol | What | Open to players? |
|
||||
|---|---|---|---|
|
||||
| 24650 | UDP | Game traffic (`port`) | Yes |
|
||||
| 24651 | UDP | LAN discovery and list-server replies (`port` + 1) | On the LAN, if you want to be found |
|
||||
| 24650 | TCP | Health check (`health-port`), loopback only by default | No |
|
||||
| 24660 | UDP | A list server, if you run one | Yes, for that machine |
|
||||
|
||||
Players behind the same router as the server can join by its LAN address. Players on
|
||||
the internet need UDP 24650 forwarded to the server.
|
||||
|
||||
## Being found
|
||||
|
||||
- **On the LAN** the game's Join menu finds the server by broadcast, unless `no-lan` is
|
||||
set. Docker's default bridge network doesn't pass broadcasts; see
|
||||
[packaging/README.md](../packaging/README.md).
|
||||
- **Beyond the LAN**, run a list server somewhere reachable and register game servers
|
||||
with it:
|
||||
|
||||
./tidewall --headless --list-server --port=24660
|
||||
./tidewall-server --config=server.cfg --list=lists.example.org:24660 --name="Harbour"
|
||||
|
||||
Check it with `./tidewall --headless --browse --list=lists.example.org:24660`. In
|
||||
this release the game's Join menu only searches the LAN, so players outside it still
|
||||
join by address; the menu doesn't ask list servers yet.
|
||||
- **By address** always works: players type `host:port` in the Join menu, or start with
|
||||
`./tidewall --connect=host:24650`.
|
||||
|
||||
## Logs
|
||||
|
||||
Each line is one JSON object with an `event`, the `seed` and a timestamp `t_ms`. The
|
||||
first line, `start`, records every setting needed to reproduce the run. `stopping` and
|
||||
`stop` end it; `stop` carries the exit code and the number of errors. Pipe the log
|
||||
through `jq` to read it, or keep it as is for a log collector. Exit codes: 0 clean, 1 a
|
||||
script or engine error, 2 a bad command line.
|
||||
|
||||
## Docker, Compose and systemd
|
||||
|
||||
`packaging/docker/compose.yaml` runs the server as a read-only, unprivileged container
|
||||
with a health check:
|
||||
|
||||
cd packaging/docker
|
||||
docker compose up -d
|
||||
|
||||
`packaging/systemd/tidewall-server.service` runs it as a hardened systemd service.
|
||||
[packaging/README.md](../packaging/README.md) explains both, and `make
|
||||
server-package-check` tests the container from build to clean stop.
|
||||
|
||||
## Memory
|
||||
|
||||
The launchers set `MALLOC_ARENA_MAX=1` unless it is already set. Without it, memory
|
||||
grew about 28 MB a match for as long as the server ran. If you start the engine
|
||||
binary yourself instead of through `tidewall-server`, set it too.
|
||||
|
||||
## How this was checked
|
||||
|
||||
Each command on this page was run from an unpacked 0.9.0 release outside the source
|
||||
tree, with its own home directory, on 2026-11-14: the server from `server.cfg`, the
|
||||
health check, `--browse` on the LAN and through a list server, a headless game joining
|
||||
and playing through the drop, and a clean SIGTERM stop with exit code 0. The Debian
|
||||
package paths are checked by `make deb-check` and the container by `make
|
||||
server-package-check`.
|
||||
Reference in New Issue
Block a user