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:
2026-11-14 08:30:16 -05:00
co-authored by Claude Opus 5.5
parent df367d691a
commit 36d474695a
13 changed files with 494 additions and 32 deletions
+16 -12
View File
@@ -212,7 +212,7 @@ sea wear each second: `TIDE_STRUCTURE_DPS` for most, and for breakwaters
`BREAKWATER_WEAR_PER_METRE` per metre of water over the base, failing at once past
`BREAKWATER_MAX_HEAD`.
**Placing.** Build mode (Q) shows a ghost of the selected piece where it would go:
**Placing.** Build mode (B) shows a ghost of the selected piece where it would go:
sea green if it can be placed, rust red if not. The look direction snaps to a quarter
turn. Walls and breakwaters go on the edge of your own cell in that direction; floors,
ramps and roofs go in the next cell, or in your own cell when you look well down. Ramps
@@ -312,25 +312,29 @@ keeps under `BALANCE_MEDIAN_MINUTES_MAX`. Findings and the changes they led to a
## Controls
Rebindable. Defaults for keyboard and mouse:
Rebindable in Settings → Controls (`src/client/key_bindings.gd` holds the defaults).
Keys are matched by position. Defaults for keyboard and mouse:
| Action | Default |
|---|---|
| Move | W A S D |
| Jump | Space |
| Crouch | Left Ctrl |
| Jump; leap from the barge; open the wing-sail | Space |
| Crouch; dive when swimming | Left Ctrl |
| Sprint | Left Shift |
| Fire / harvest / place | Left mouse |
| Use, fire, harvest or place | Left mouse |
| Aim | Right mouse |
| Reload | R |
| Interact | E |
| Build mode | Q |
| Next / previous piece | Mouse wheel |
| Cycle material | T |
| Inventory slots | 1 to 5 |
| Map | M |
| Pick up or open | E |
| Drop the held item | G |
| Boathook | 1 |
| Inventory slots | 2 to 6 |
| Build mode | B |
| In build mode: wall, floor, ramp, roof, breakwater | 1 to 5 |
| In build mode: next material | Tab |
| Chart | M |
| Pause menu (not rebindable) | Escape |
Gamepad support is planned with the accessibility work in v0.6.
Gamepad support is issue A13.
## Out of scope for v1.0
+126 -4
View File
@@ -1,7 +1,127 @@
# Playing Tidewall on Linux
This page covers graphics settings and the systems Tidewall has been tested on. R3
adds the rest of the player guide (controls, rules, servers).
Tidewall is a free and open-source build-and-survive battle royale. Up to 24 players
and bots leap from a sky barge onto a generated island, scavenge, fight and build,
while the sea rises in phases and swallows the low ground. The last one standing wins.
To run a server, see [SERVER.md](SERVER.md).
## Install
You need 64-bit Linux (x86_64) and a GPU with a Vulkan driver. Without Vulkan the game
falls back to OpenGL (see [Renderers](#renderers)).
**Any distribution: the tarball.** Download `tidewall-<version>-linux-x86_64.tar.gz` and
its `.sha256` from the [releases page](https://gitea.eom.dev/claude/tidewall/releases),
then:
sha256sum -c tidewall-0.9.0-linux-x86_64.tar.gz.sha256
tar xzf tidewall-0.9.0-linux-x86_64.tar.gz
cd tidewall-0.9.0-linux-x86_64
./tidewall
`./install-desktop-entry.sh` adds Tidewall to your application menu, for you alone, and
`./install-desktop-entry.sh --remove` takes it away again. Nothing is installed
system-wide. To uninstall, remove the entry and delete the folder.
**Debian 13 or Ubuntu: the .deb package.**
sudo apt install ./tidewall_0.9.0-1_amd64.deb
That puts `tidewall` and `tidewall-server` in `/usr/games` and the game in your
application menu. `sudo apt purge tidewall` removes it.
Replace `0.9.0` with the version you downloaded.
## Starting a match
The game opens on its main menu.
- **Practice** plays offline against bots on an island of its own. No network needed.
- **Join a server** lists the servers it finds on your local network. Pick one, or type
an address (`host` or `host:port`; the default port is 24650) for any other server.
- **Settings** has Controls, Mouse, Graphics, Display and Audio tabs.
You can also start straight into a match from a terminal:
./tidewall --offline # practice against 23 bots
./tidewall --offline --bots=5 --seed=42 # fewer bots, a chosen island
./tidewall --connect=192.0.2.7:24650 --name=Mara
./tidewall --headless --browse # print the LAN's servers, then quit
./tidewall --headless --browse --list=lists.example.org:24660 # and a list server's
On a server, matches run back to back: a short lobby, a countdown, the drop, the match
and the results, then a new island. If you join during a match you wait in the lobby
for the next one. Leaving during a match counts as being eliminated where you stood.
## Controls
Every key can be rebound in Settings → Controls. Mouse sensitivity and inversion are on
the Mouse tab. Escape opens the pause menu and can't be rebound. Keys are matched by
position, so they sit in the same place on any keyboard layout.
| Action | Default |
|---|---|
| Move | W A S D |
| Jump; on the barge, leap; in the air, open the wing-sail | Space |
| Crouch; in water, dive | Left Ctrl |
| Sprint | Left Shift |
| Use, fire, harvest or place | Left mouse |
| Aim | Right mouse |
| Reload | R |
| Pick up or open a chest | E |
| Drop the held item | G |
| Boathook | 1 |
| Inventory slots | 2 to 6 |
| Build mode on and off | B |
| In build mode: wall, floor, ramp, roof, breakwater | 1 to 5 |
| In build mode: next material | Tab |
| Chart (the full map) | M |
Gamepads aren't supported in this release.
## How a match goes
1. **The drop.** Everyone rides a sky barge across the island. Press jump to leap,
steer with the move keys while you fall, and press jump again to open the wing-sail.
It opens by itself near the ground. Anyone still aboard at the end of the route is
thrown off.
2. **Scavenge.** Fishing hamlets, docks, salt works, quarries, lighthouses and hilltop
shrines hold weapons, ammunition and supplies, on the floor and in sea chests (E opens one).
Washed-up crates on the beaches spill loot when broken.
3. **Harvest.** Hit trees, rocks and wrecks with the boathook (slot 1, left mouse) for
driftwood, stone and salvage iron.
4. **Read the tide.** The sea rises in phases. Between rises it holds still, and the
chart (M) and the minimap show where the next flood line will be. High ground is
safe ground, and the last land is the highest land.
5. **Build.** Walls, floors, ramps and roofs cost materials and snap to a grid. Iron is
strongest but slowest to set; driftwood is quickest. A ring of **breakwaters** keeps
the sea out of low ground for a while, until the water wears it down or someone
breaks it. Pieces with nothing holding them up collapse.
6. **Survive.** In shallow water you wade. In deep water you swim, which uses stamina,
and you can't fire or build. Underwater you run out of breath and start to drown.
After the last rise everyone left loses health until one remains.
Weapons come in four tiers: Rusted, Seaworthy, Brass-Fitted and Captain's. Bandages and
tonic restore health; tar patches and cork vests add armor, which takes damage first.
## Your files
Settings and key bindings are saved in
`~/.local/share/godot/app_userdata/Tidewall/settings.cfg` (under `$XDG_DATA_HOME` if
you set it). Delete that file to go back to the defaults.
## Troubleshooting
- **The menu says in red that it fell back to OpenGL.** Vulkan couldn't start. Install
your GPU's Vulkan driver (`mesa-vulkan-drivers` on Debian for AMD and Intel, or the
NVIDIA driver) to get the intended look. The game is fully playable either way.
- **It starts on the wrong GPU.** See [Display servers and GPUs](#display-servers-and-gpus).
- **No servers in the list.** LAN discovery uses UDP broadcasts on port 24651; some
networks and firewalls block them. Join by address instead.
- **A server is greyed out, marked "(another version)".** It runs a different release.
Use the same release as the server.
- **Run it from a terminal** to see its log: `./tidewall` prints engine messages there.
## Graphics presets
@@ -31,8 +151,10 @@ out paler under OpenGL than under Vulkan (issue #81).
To choose a renderer yourself:
./tidewall.x86_64 --rendering-method gl_compatibility # OpenGL
./tidewall.x86_64 --rendering-method forward_plus # Vulkan (the default)
./tidewall --rendering-method gl_compatibility --rendering-driver opengl3 # OpenGL
./tidewall --rendering-method forward_plus --rendering-driver vulkan # Vulkan (the default)
These are the same options the capture tests use for each renderer.
## Display servers and GPUs
+128
View File
@@ -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`.