make balance (tools/balance.sh, tools/balance.gd, BalanceReport) plays 200 bot-only matches in four processes under nice and reports match length, players standing over time, causes of death, eliminations by weapon and by difficulty, judged against the new BALANCE_* targets in Tuning and the GDD's Balance section. Before: median match 5.0 min, 3.4 of 24 standing at 2 min, the boathook 41% of eliminations. After, over seeds 1001-1200: median 13.1 min (p10 9.2, p90 14.6), top weapon the rivet repeater at 31.7%. Passes. Changes, each traced from single-match runs (docs/BALANCE.md): - Fix: bots leapt from the barge on a timer and landed hundreds of metres short of their spot; they now leap when it's in gliding reach or the barge starts drawing away from it. - Bots spread their landings, only brawl whoever hit them, pick out new opponents within 30 m, roam locally and hold ground, run from a gun when unarmed, and (normal and hard) break off when badly hurt. - Aim error widened; rivet repeater damage 17 to 15. - Tide: lower early levels, longer holds; every match ends within 17.75 min. Tests: BalanceReport, the new bot behaviours, the tide length. Tests that leaned on old bot luck now pin or set up what they check. make match moves to seed 29, where the scripted player still builds. Closes #56 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
13 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.
- docs/BALANCE.md: how the pacing and weapons were tuned from bot matches.
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 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 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.