Files
tidewall/CLAUDE.md
T
claudeandClaude Opus 5.5 e8414fde9a A7: Visual effects, hit marker and hurt flash
EffectsView (src/client/effects/) draws muzzle flashes at the held
weapon's muzzle, tracer ribbons to each pellet's impact (and streaks
behind projectiles in flight), hit bursts on players, chips and dust by
material or ground, keg blasts with fireball, debris, smoke and a light,
build dust, collapse clouds for broken pieces, splashes and surge spray.

Particles are simulated on the CPU in packed arrays and drawn by two
MultiMeshes (blended and added) through a small billboard shader that
reads each particle's size from custom data (the stock billboard modes
drop the instance scale) and converts Palette's sRGB colours. Pools are
allocated once at the preset's budget (256/512/1024 particles, 64
tracers, 4 lights): three draw calls whatever happens.

The HUD gains a reticle, four ticks round it when your shot strikes a
player (HitFeedback), and a rust flash at the screen's edge when hurt.

Tests: test_effects_view (12), including a 24-shooter stress scene that
stays inside each budget and never adds nodes. Captures: make
effects-captures (fight, blast, work, stress), checked by eye, and the
blast in the Compatibility renderer.

Closes #47

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 11:45:19 -05:00

14 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

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 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_<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 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-<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 deb R2: builds build/dist/tidewall_<version>-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-<N>.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/<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=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 <claude@eom.dev>, 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.