Files
tidewall/docs/SERVER.md
T
claudeandClaude Opus 5.5 2167900e45 M7: Duos and revive
Two-player teams, enforced by the simulation:
- Match puts every player on a team (SimEntity.team); Weapons.damage_player
  refuses damage between teammates from every weapon, the boathook and blasts.
- A player whose health runs out with a teammate standing goes down instead of
  out: 60 health to bleed (one point every half second), crawling at 1 m/s, no
  firing, building, looting or items. Hits still take it; drowning too.
- A standing teammate within 2 m holding interact for 6 s revives them with 30
  health. Letting go or moving away starts it over.
- Downed players are out when their health runs out again or when no teammate
  is left standing, credited to whoever downed them. A team falls together and
  shares its place; the tie-break puts standing ahead of downed.
- Downs and revives go through Match events and the kill feed ("X knocked Y
  down"); the HUD says what to do while down.

Wire: FLAG_DOWNED in the player record and the own block (flags now u16),
so prediction crawls too. Protocol version 5.

Bots: never target a teammate, land with their teammate, regroup when they
stray past 30 m, crawl toward a standing teammate when down, go to revive a
downed teammate within 60 m when not in a fight, and turn from a downed target
to its standing teammate when it's in view.

Options: --team-size=2 on the server, --duos offline, and Solo/Duos under
Crew in the Practice menu. The figure has a downed crawl pose.

Tests: test_duos (downing, crawl, revive, interrupted revive, bleed-out,
finishing, team out, falling together, no friendly damage including kegs,
drowning while down, hash, match placement and tie-break), bots as teammates,
the downed flag on the wire, the feed, server and menu options. make
duo-matches plays 10 bot duos matches.

Closes #30

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 03:01:09 -05:00

5.8 KiB

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. For playing, see PLAY.md.

Quick start

From the release tarball (see PLAY.md):

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.
team-size=N 1 1 for solo, 2 for duos: players pair up in the order they join (bots fill in after), can't hurt their teammate, and go down instead of out while their teammate stands.
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.

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.

  • 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 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.