Files
tidewall/CLAUDE.md
T
claudeandClaude Opus 5.5 9e653f213c N9: Server-side cheat and abuse protection
- A hostile test client crafts INPUT packets byte by byte and sends them
  through NetGame.take_input() into a real match: extreme axes, the same
  tick claimed repeatedly, the whole lead window at once, past, far-future
  and maximum ticks, fire toggled every tick with slot swaps, builds aimed
  anywhere with junk kinds and materials and no materials, and
  pickup/drop/select tricks. Speed stays within sprint speed per tick,
  shots within the weapon's rate, pieces within build reach and paid for,
  and every item is conserved.
- Fix: a command tick beyond the simulation's lead window no longer moves
  NetGame's dedupe marker, so one bogus far-future tick can't lock out a
  player's real commands.
- Connections are rate-limited per address (32 per 10 s, 8 handshakes in
  progress) with a new REASON_BUSY and a message for it.
- ParserFuzz mutates real messages from a bot match and random bytes and
  feeds them to every network decoder, the snapshot receiver and the list
  server. 20,000 per make check; make fuzz runs 1,000,000 (about 40 s):
  no errors, 2.9 KB of memory growth.
- ARCHITECTURE.md: "Trusting nothing from clients".

Closes #40

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

6.6 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 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 starts an offline match; 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. Menus (A10) will show 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 (captures/client_<stage>.png). Needs Docker. Look at them.
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.