Files
tidewall/docs/SERVER.md
T
claudeandClaude Opus 5.5 36d474695a 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>
2026-11-14 08:30:16 -05:00

129 lines
5.6 KiB
Markdown

# 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`.