Files
tidewall/CLAUDE.md
T
claudeandClaude Opus 5.5 1d6a24ab64 M8: Complete offline match
`make match` plays one whole match from the lobby to the results and back to the
lobby: one scripted player and 23 bots on a local server, with no script errors.

- CommandLog records the seed, the rules and every command the server is given.
  MatchReplay plays a log again with nobody thinking and ends on the same state
  hash; `make match` saves the log, reads it back and checks that.
- ServerLoop.submit() is now the one way commands reach the simulation, so a
  recording server sees them all.
- ScriptedPlayer plays a human seat: it drops, loots, fights and flees as a bot
  does, and also cuts driftwood and builds a breakwater and a wall.
- Bots draw randomness from their own per-bot generators, not the simulation's
  streams. A bot thinking no longer changes the simulation's state, which a
  replay without bots needs.
- MatchView and EntityView draw a match from one Simulation: terrain, sea,
  points of interest, props, pieces, players, the barge, items and chests, with
  stand-in shapes for the art pass to replace.
- `make match-captures` renders eight stages of the recorded match.

Closes #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 05:35:32 -05:00

4.9 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 ... 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 (several minutes, under nice) and checks every one has a winner, under a tenth of deaths are drownings, easy bots place worst and hard bots take the most eliminations. BOT_MATCH_SEEDS=5 BOT_MATCH_FIRST=40 changes the seeds.
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.
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. 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.