Bump application/config/version, the install commands in PLAY.md and SERVER.md, and the README status for the v1.0.0 release (R5, #64). The README's limitations drop the effects item A7 already shipped and link the Later issues for keg-throwing bots and list servers in the menu. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
129 lines
5.6 KiB
Markdown
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-1.0.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`.
|