# 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. - [docs/PLAY.md](docs/PLAY.md): the player guide (install, controls, rules), graphics presets, renderers and the tested configurations. - [docs/SERVER.md](docs/SERVER.md): the server guide. [CONTRIBUTING.md](CONTRIBUTING.md) and [CREDITS.md](CREDITS.md). - When a command, option or control changes, update PLAY.md, SERVER.md and the man pages in `packaging/deb/man/` with it. - [docs/BALANCE.md](docs/BALANCE.md): how the pacing and weapons were tuned from bot matches. ## 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 balance` | H3: plays 200 bot-only matches in four processes under `nice` (about 15 min) and writes `build/balance/report.txt`: match length, players standing over time, causes of death, eliminations by weapon and by difficulty. Fails if the median match is outside 12 to 18 minutes or a weapon takes over 35% of eliminations (`BALANCE_*` in tuning). `BALANCE_MATCHES`, `BALANCE_FIRST`, `BALANCE_JOBS` scale it. See docs/BALANCE.md. | | `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, 29, 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 poi-captures` | Renders each kind of point of interest (`captures/poi_*.png`, about 3 min). Needs Docker. Look at them. | | `make build-captures` | Renders the fort and the wall test card: a row per material, a column per state (half built, intact, worn, battered), and a battered ramp (`captures/build_*.png`), and the barge and sea chests (`captures/vessels.png`), about 2 min. Needs Docker. Look at them. | | `tools/capture.sh canopy captures/canopy.png` | H11: the shoulder camera on a player against a pine, with canopies in the way hidden (`canopy_before` puts them back). | | `make style-captures` | Renders a hamlet and a dock with and without the woodcut print pass (`captures/style_*.png`). Needs Docker. | | `make stability` | H4: one dedicated server plays 50 bot matches back to back, unthrottled, under `nice` (about 13 min), sampling its resident memory. Fails on a crash, hang, engine or script error, a match without a winner, or memory growing more than 256 KiB (static) or 1 MiB (resident) a match after the first five. `STABILITY_MATCHES`, `STABILITY_SEED`, `STABILITY_DIR` scale it. Report in `build/stability/report.txt`. | | `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 bench` | H1: the server's p50/p99/max tick with 24 bots on three seeds, and the client's draw calls, triangles, objects and memory at six moments of a match (about 3 min, needs Docker). Fails on anything over the budgets in docs/ARCHITECTURE.md. Report in `build/bench/report.txt`. `BENCH_SEEDS`, `BENCH_TICKS`, `BENCH_CLIENT=0` scale it. | | `make dist` | R1: exports the game with the official Godot templates (checked against `tools/engine.sha512`, installed into `.godot-home/`) to `build/dist/tidewall--linux-x86_64.tar.gz` with a `.sha256`. One binary and one pack: `tidewall.x86_64` is the game, `tidewall-server` runs it headless as the server. The version is `application/config/version` in project.godot; the commit goes in as `build_commit.txt` (`BuildInfo`). | | `make dist-check` | R1: builds the package, unpacks it outside the repo with HOME and XDG dirs in a temp dir, and runs `SMOKE_DIST= tools/smoke.sh`, a whole bot match, and the exported game joining the exported server (about 2 min). | | `make deb` | R2: builds `build/dist/tidewall_-1_amd64.deb` from the `make dist` package with `dpkg-deb`: launchers in `/usr/games`, the game in `/usr/lib/tidewall`, a desktop entry, hicolor icons, and copyright with the engine's licences. Never install it on the host. | | `make deb-check` | R2: builds the .deb and checks it in a throwaway `tidewall-deb-check-*` Debian 13 container: installs with only its Depends, `desktop-file-validate`, the server and the game headless as a user, lintian for information, and a purge that leaves nothing behind (about 3 min). | | `make app-icon` | R2: renders `assets/icons/app/tidewall.svg` (written by hand) to `tidewall-.png`. Commit what changes. | | `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 models` | Rebuilds every item model (`assets/models/items/*.obj`, with grip data in `.json`) and icon (`assets/icons/items/*.png`) from `tools/models/items.py` in headless Blender on the CPU. Materials are named after `Palette` colours; `ItemModels` paints them. | | `make art` | Rebuilds every generated model: the player figure (`make figure`: `assets/models/figure/`, from `tools/models/figure.py`, about 3 s) and the items with their icons (`make models`). | | `make figure-captures` | Renders the player figure in every movement state, every action, and close up holding a carbine (`captures/figure_*.png`, about 1.5 min). Needs Docker. Look at them. | | `make sea-captures` | Renders the sea after every tide phase from out at sea, a calm beach, the last land in the gale and the view under water (`captures/sea_*.png`), and three of them in the Compatibility renderer (`*_compat.png`), about 6 min. Needs Docker. Look at them. | | `make item-captures` | Renders items held in a row, over the shoulder, lying on the ground and the four tiers (`captures/items_*.png`, about 3 min). Needs Docker. Look at them. | | `make effects-captures` | Renders the visual effects (A7): a shot striking a player over the shoulder with the HUD's hit marker, a keg blast beside a collapsing wall, build dust, chips and a splash, and 24 players firing with kegs going off at the largest particle budget (`captures/effects_*.png`, about 6 min). Needs Docker. Look at them. | | `make audio` | Regenerates every sound and the score's layers in `assets/audio/` from `tools/audio/` (about 6 s), with `manifest.json`. Commit the WAVs it changes. | | `make audio-check` | Checks each file in `assets/audio/` matches its manifest hash and its loudness target, and the mix order (tide loudest). Also run by `test_audio_assets`, which regenerates everything and compares. | | `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, and `CAPTURE_RENDERER=no_vulkan` hides the Vulkan driver to check the game falls back to OpenGL (H2). The `quality_low`, `quality_medium` and `quality_high` scenarios draw a match moment with each preset. 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.