Presets now tune shadows, cascades, render scale and anti-aliasing: Low (no shadows, 75%, FXAA), Medium (200 m, 2 cascades, FXAA), High (400 m, 4 cascades, MSAA 2x). GameSettings.apply_to_viewport sets the viewport; MatchView.apply_settings sets the sun's cascades. No preset changes how far props or pieces are drawn, so a lower one never shows a player through cover; a test guards it. When Vulkan can't start, Godot falls back to OpenGL (fallback_to_opengl3) and RendererCheck has the main menu say so. tools/capture.sh gains CAPTURE_RENDERER=no_vulkan, which hides the Vulkan driver and expects the fallback. New scenarios quality_low/medium/high draw a match moment with each preset, reviewed in both renderers. docs/PLAY.md lists the presets, renderers, Wayland and hybrid-GPU notes, and the tested configurations, marking each as software-rendered only or not tested. Closes #55 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
12 KiB
12 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.
- docs/PLAY.md: graphics presets, renderers and the tested configurations.
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 dist |
R1: exports the game with the official Godot templates (checked against tools/engine.sha512, installed into .godot-home/) to build/dist/tidewall-<version>-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=<dir> tools/smoke.sh, a whole bot match, and the exported game joining the exported server (about 2 min). |
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, andCAPTURE_RENDERER=no_vulkanhides the Vulkan driver to check the game falls back to OpenGL (H2). Thequality_low,quality_mediumandquality_highscenarios 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 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.