# 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/STYLE.md](docs/STYLE.md): the look and sound. Every client colour comes from `Palette`. - [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 ` | 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_.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 opens on its main menu (`AppShell`); 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. The join menu (A10) shows 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, the build ghost allowed and refused, and a breakwater basin kept dry by the tide (`captures/client_.png`, about 4 min). Needs Docker. Look at them. | | `make hud-captures` | Renders the HUD over a staged moment of play (three bots out, carried items, a wound) at 1280x720, in build mode, and at 3840x2160 (`captures/hud_*.png`, about 5 min). Needs Docker. Look at them. | | `make menu-captures` | Renders every menu screen: main, practice, join (with a made-up server list), settings (controls and mouse tabs), pause and results over a match (`captures/menu_*.png`, about 5 min). Needs Docker. Look at them. | | `make chart-captures` | Renders the chart and minimap of seed 2 with the first tide forecast, and again once it has risen (`captures/chart_*.png`, about 2 min). Needs Docker. Look at them. | | `make style-captures` | Renders a hamlet and a dock with and without the woodcut print pass (`captures/style_*.png`). Needs Docker. | | `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 server-package-check` | Builds the server image with `packaging/docker/compose.yaml`, waits for it to be healthy, checks it is non-root and read-only, joins it with a headless client and stops it with SIGTERM (N7, about 1.5 min). Needs Docker. See `packaging/README.md`. | | `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/.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 `, 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.