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:
+16
-12
@@ -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
@@ -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
@@ -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