make bench (tools/bench.sh, tools/bench_report.gd) measures the server's p50/p99/max tick with 24 bots on three seeds over a whole match, and the client's draw calls, primitives, objects, nodes and memory at six moments of a match rendered in the capture container. It fails on anything over the budgets now recorded in docs/ARCHITECTURE.md: p99 tick 12 ms, 2,000 draw calls and 2,000,000 primitives per frame (all passes), 1 GiB video and 512 MiB static memory. Every capture now reports its frame's render counts in a "render" field. The first run put the barge, with 24 figures together, at 2,197 draw calls. Each figure part had one surface per colour (about 43 per figure, drawn again for shadows). FigureRig now merges a part's surfaces into one per finish (coat, gilt, plain) and carries the Palette colours as vertex colours, with shared materials. The barge is down to 1,207 draw calls, with the same triangles and the same look. Frame rates on a real GPU are not measured here; that stays with R6. Closes #54 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
11 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 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 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 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 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 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.