The game now opens on a main menu when it has a window: practice against bots (count and skill), join a server (by address, or from a LAN search list), settings, and quit. In a match, Escape brings up a pause menu (the match goes on) with settings and leave; when a match the player was in ends, a results screen shows their place, eliminations and the last of the feed. - KeyBindings: every action rebindable to a key or mouse button. bind() refuses an input another action uses and names it; Escape is reserved. ClientInput reads keys through the bindings. - GameSettings: bindings, mouse, graphics (quality preset and the print pass), audio (master, music and effects buses), display (window mode, vsync, frame cap), name, last server and practice choices, saved in user://settings.cfg. Missing, unreadable or corrupt files and bad values fall back to defaults, value by value; hand-edited key clashes are repaired on load. - Menus (src/ui): paper-and-ink panels, brass focus edge, keyboard navigable; a drawn sea-and-tide-post backdrop, or an ink wash over a match. AppShell runs menus and the session. - LocalServer takes a bot difficulty. - make menu-captures renders every screen. Closes #50 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.3 KiB
8.3 KiB
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 and the Gitea issues are the continuity.
Read these first
- docs/DEVLOG.md: what happened, newest entries at the bottom.
- docs/GDD.md: the game design.
- docs/ORIGINALITY.md: binding rules for everything we make.
- docs/STYLE.md: the look and sound. Every client colour comes from
Palette. - docs/ARCHITECTURE.md: server-authoritative design and module map.
- 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 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_<stage>.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 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 intest/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=compatibilityuses 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 bytools/engine.versionandtools/engine.sha512. Never download or replace it casually. - Never open a window on the host desktop.
tools/godot.shforces--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
TestCasein a file namedtest_*.gdundertest/. Any engine or script error during a test fails it, unless the test callsexpect_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, withCloses #N. Scheduled runs usegit -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.