Files
tidewall/docs/PLAY.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

194 lines
9.3 KiB
Markdown

# Playing Tidewall on Linux
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
Settings → Graphics → Quality.
| Preset | Sun shadows | Shadow cascades | 3D resolution | Anti-aliasing |
|---|---|---|---|---|
| Low | Off | n/a | 75% of the window | FXAA |
| Medium | Up to 200 m | 2 | 100% | FXAA |
| High (default) | Up to 400 m | 4 | 100% | MSAA 2x |
No preset changes how far trees, rocks, wrecks or built pieces are drawn. A lower
preset never lets anyone see a player through cover that a higher one would still
draw. The woodcut ink lines are a separate switch on the same tab.
`make bench` counts what a frame asks of the GPU, with High's shadows. The measured numbers are in
[ARCHITECTURE.md](ARCHITECTURE.md#performance-budgets) and the DEVLOG.
## Renderers
Tidewall is made for Godot's **Forward+** renderer on **Vulkan**. If Vulkan can't start
(no Vulkan driver, or a GPU too old for it), the game falls back to **OpenGL**
(Godot's Compatibility renderer) rather than crashing. The main menu then says so in
red under the motto. Everything works there, but the light, fog and sea look a little
different. Known difference: with shadows on (Medium, High) the ground and rocks come
out paler under OpenGL than under Vulkan (issue #81).
To choose a renderer yourself:
./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
- **X11:** the default.
- **Wayland:** by default the game runs through XWayland, which every Wayland desktop
provides. To try Godot's native Wayland support, start it with
`--display-driver wayland`.
- **Hybrid graphics (a laptop or desktop with an integrated and a discrete GPU):**
Godot's Vulkan renderer prefers the discrete GPU on its own. If the game still starts
on the integrated one, run it with the driver's offload variables, for example
`__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia ./tidewall.x86_64` on
NVIDIA, or `DRI_PRIME=1 ./tidewall.x86_64` on Mesa. `--gpu-index N` picks a Vulkan
device by number.
## Tested configurations
Be careful reading this table. The automated tests run in a container with **software
rendering only**. They show that the game starts, draws the right picture and falls back
correctly. They say nothing about frame rates or how it feels on real hardware. That
is checked in the hands-on playtest (R6), and this table will be updated from it.
| Configuration | Renderer | How it was tested | Result |
|---|---|---|---|
| Debian 13, Xvfb (X11), Mesa Lavapipe | Forward+ / Vulkan | Software only: every capture, all three presets (`quality_*` captures) | Draws correctly |
| Debian 13, Xvfb (X11), Mesa llvmpipe | Compatibility / OpenGL | Software only: all three presets | Draws correctly. Paler ground with shadows on (see above) |
| Debian 13, Xvfb (X11), no Vulkan driver | Falls back to OpenGL | Software only: `CAPTURE_RENDERER=no_vulkan` capture of the main menu | Falls back and shows the notice |
| Release package outside the repo, headless | None (server and autoplay client) | `make dist-check` | Plays a full match; the game joins its server |
| Wayland (native or XWayland) | Any | **Not tested** | Unknown |
| Real NVIDIA, AMD or Intel GPU | Forward+ / Vulkan | **Not tested yet** (R6) | Unknown |
| Hybrid NVIDIA and Intel desktop | Any | **Not tested yet** (R6) | Unknown |
To reproduce the software-rendered rows:
CAPTURE_RENDERER=forward_plus tools/capture.sh quality_high captures/q.png
CAPTURE_RENDERER=compatibility tools/capture.sh quality_low captures/q.png
CAPTURE_RENDERER=no_vulkan tools/capture.sh menu_main captures/m.png