Files
tidewall/CLAUDE.md
T
claudeandClaude Opus 5.5 05c7568ec1 N8: 24-client network soak, and the server fixes it found
make soak runs a real server and 24 headless clients in three processes for
two whole matches in real time. Each client reaches the server through its own
UdpRelay, which adds 60 ms, +/-20 ms jitter and 2% loss each way, so ENet runs
unchanged over a bad link. SoakPlayer drives each client from what a client
knows: it drops, glides, heads for high ground, harvests and tries to build.
tools/soak_report.gd checks world hashes against the server's, errors,
unreadable packets, every client playing every match with its connection
intact, memory between matches, and the p99 tick with the network's share.
make soak-selfcheck proves a drifted client world is caught.

Server changes: --matches=N, --world-hash-every=N, tick timing that includes
after_tick, and memory in match and progress lines.

What the soak found and fixed:
- Snapshot building for 24 clients took the p99 tick to 13.8 ms, over the
  12 ms budget, against a 2.8 ms simulation. Encoded records are now shared
  between clients for the tick, unchanged records skip the field diff, and
  clients are spread over the snapshot interval by handle. p99 is 7.3 ms.
- ENet peers had a timeout limit of 0, which gives up on a peer as soon as any
  reliable message has waited the minimum timeout. Now ENet's default, 32.

Not fixed: one or two clients still lose their connection about 15 s into the
second match's drop in each run (see the issue), so the soak still fails and
N8 stays open.

Refs #39

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 21:56:01 -05:00

77 lines
7.3 KiB
Markdown

# Tidewall: working notes
Tidewall is a free and open-source third-person build-and-survive battle royale for
Linux, made with Godot 4.7.2 and GDScript. Each development session starts with no
memory, so this file, [docs/DEVLOG.md](docs/DEVLOG.md) and the Gitea issues are the
continuity.
## Read these first
- [docs/DEVLOG.md](docs/DEVLOG.md): what happened, newest entries at the bottom.
- [docs/GDD.md](docs/GDD.md): the game design.
- [docs/ORIGINALITY.md](docs/ORIGINALITY.md): binding rules for everything we make.
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): server-authoritative design and module map.
- [src/sim/tuning.gd](src/sim/tuning.gd): the one table of gameplay numbers.
## Commands
| Command | What it does |
|---|---|
| `make check` | Verifies the engine, checks binaries, parses all scripts, runs all tests. Must pass before every push. |
| `make test` | Runs `test/**/test_*.gd` headless. |
| `make test-selfcheck` | Proves the runner catches each kind of failure, using `test/fixtures/`. |
| `make smoke` | Boots the headless server for 1,000 ticks with 24 bots, prints tick timing, and checks exit codes and logs. Part of `make check`. |
| `tools/godot.sh -- --server --seed=N --bots=N --ticks=N` | Runs a headless dedicated server. See `src/server/server_config.gd` for every option. Logs are JSON lines carrying the seed. Exit codes: 0 clean, 1 script error, 2 bad command line. |
| `tools/godot.sh -- --server --listen --port=N --bots=1` | Runs a server people can join over UDP (default port 24650). It waits in the lobby for the first of them and fills each match's empty places with bots. |
| `tools/godot.sh ...` | Runs the pinned engine. Headless by default. |
| `tools/capture.sh <scene-or-scenario> <out.png>` | Renders the real client offscreen in a throwaway `tidewall-capture-*` Docker container (Xvfb, Mesa software rendering) and saves a PNG. Fails on a blank frame or a renderer fallback. |
| `tools/godot.sh --script res://tools/island_map.gd -- --seed=N --out=res://captures/island.png` | Draws a top-down map of a seed's island, with a contour at each tide level. |
| `make bot-matches` | Plays 20 bot-only matches (about ten minutes, under `nice`) and checks every one has a winner, under a tenth of deaths are drownings, and easy bots win less than an even share and take the fewest eliminations. `BOT_MATCH_SEEDS=5 BOT_MATCH_FIRST=40` changes the seeds; under 20 matches the difficulty checks are skipped. |
| `make match` | Plays one whole offline match, lobby to results: a scripted player and 23 bots on a local server (about 25 s). Saves the command log to `build/match/match.tclog`, replays it and checks the replay ends on the same state hash. `MATCH_SEED=N` changes the seed; the default, 2, is one where the scripted player also builds. |
| `make match-captures` | Renders eight stages of that match from its command log (`captures/match_<stage>.png`), about 3 minutes. Needs Docker. Look at them. |
| `make terrain-capture` | Renders the terrain crack check and a skirtless control in the capture container. The control must crack and the real terrain must not. Needs Docker. |
| `tools/godot.sh -- --connect=HOST:PORT --autoplay --client-seconds=N` | Runs the client headless against a server for N seconds, played by its script, and prints one JSON line saying how far it got. `--offline` plays a server in the same process instead. On a real display, with no options, the game starts an offline match; see `src/app/client_config.gd`. |
| `make client-check` | Starts a server and a client as two processes, joins them over loopback UDP and checks the client plays (about a minute, real time). |
| `tools/godot.sh -- --list-server [--port=N]` | Runs a list server (default UDP port 24660). Game servers started with `--listen --list=HOST[:PORT] --name=NAME` register with it; see `src/server/list_server.gd`. |
| `tools/godot.sh -- --browse [--list=HOST[:PORT]] [--lan-target=IP] [--lan-port=N]` | Looks for servers on the LAN and in list servers and prints them as one JSON line. Menus (A10) will show the same list. |
| `make discovery-check` | Starts a list server and a game server as processes and checks `--browse` finds the game both on the LAN (loopback) and through the list (about 15 s). |
| `make fuzz` | Feeds 1,000,000 malformed messages (`FUZZ_MESSAGES=N`, `FUZZ_SEED=N`) to every network parser and fails on any engine error or memory growth (about 40 s). |
| `make client-captures` | Renders what a network client sees on the barge, gliding and landed (`captures/client_<stage>.png`). Needs Docker. Look at them. |
| `make soak` | The 24-client network soak (N8): a real server and 24 headless `SoakPlayer` clients in three processes, each behind a `UdpRelay` adding 60 ms, +/-20 ms jitter and 2% loss each way, for two whole matches in real time (about 30 min, under `nice`). Fails on a world-hash mismatch, errors, unreadable packets, a client that didn't play every match, memory growth between matches, or a p99 tick over budget. `SOAK_MATCHES`, `SOAK_CLIENTS`, `SOAK_PROCS`, `SOAK_LATENCY`, `SOAK_JITTER`, `SOAK_LOSS` scale it. Results in `build/soak/report.txt`. |
| `make soak-selfcheck` | About a minute: tampers with one client's world and checks the soak's comparison catches it and only it. |
| `make capture-test` | Proves the capture harness works and rejects a blank frame. Needs Docker, so it isn't part of `make check`. |
Run one group of tests with `tools/run_tests.sh --root=res://test/sim` or
`tools/run_tests.sh --filter=name`.
## Visual work
- Every issue that changes what the game looks like attaches or describes a capture from
`tools/capture.sh`, made after the change. Scenarios live in `test/capture/<name>.tscn`.
- **Open every capture and look at it** (the Read tool shows images). The harness only
catches blank frames. A broken, ugly or misleading capture means the issue isn't done.
- The default renderer is Forward+ through Mesa's Lavapipe, which matches the game.
`CAPTURE_RENDERER=compatibility` uses OpenGL through llvmpipe. Colours differ between
the two, so compare captures made with the same renderer.
- Software rendering shows what is drawn, not how fast. Never report frame rates from it.
## Rules
- The engine lives in `tools/godot/`, is git-ignored, and is pinned by
`tools/engine.version` and `tools/engine.sha512`. Never download or replace it casually.
- Never open a window on the host desktop. `tools/godot.sh` forces `--headless`.
Don't use the host's display, GPU, webcams or audio devices.
- GDScript is typed everywhere practical. Untyped declarations are errors.
- Simulation code in `src/sim/` must not depend on rendering, audio or UI. A test enforces this.
- Gameplay numbers go in `src/sim/tuning.gd`, nowhere else.
- All randomness in the simulation comes from the seeded streams described in the
architecture document.
- Tests: extend `TestCase` in a file named `test_*.gd` under `test/`. Any engine or
script error during a test fails it, unless the test calls `expect_error()`.
- The repo is public. Never commit secrets, internal hostnames, private network details
or personal data.
- Commit as `Claude <claude@eom.dev>`, one commit per issue, with `Closes #N`. Scheduled
runs use `git -c commit.gpgsign=false commit`.
- Software rendering can't show real GPU frame rates or how the game feels. Never claim
those were verified. Say what was actually tested.