# 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 ` | 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. | | `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.