Files
tidewall/CLAUDE.md
T
claudeandClaude Opus 5.5 8b74485168 W3: Chunked terrain mesh, collision and LOD
TerrainView draws the island as 16 x 16 chunks of 64 m, each at one of
four detail levels (2, 4, 8 and 16 m spacing) chosen by distance to the
camera. TerrainChunkBuilder builds chunk geometry on WorkerThreadPool
threads; the main thread only uploads finished meshes, within a 2 ms
per-frame budget, nearest chunks first.

- Seams: every chunk hangs skirts deeper than twice the most any level
  strays from the full-resolution edge, so neighbours at any two levels
  meet without a crack. Normals come from the full-resolution heightfield
  at every level, and back faces light like the ground above them.
- Splat material: a procedural shader blends sand, marsh, grass and rock
  with weights from the island's bands, averaged over 4 m so borders
  blend. Steep ground turns to rock and summits weather pale.
- Collision stays SimGround's heightfield, with no renderer involved.
- Capture scenarios terrain, terrain_lod (tinted by level) and
  terrain_cracks (magenta sky). tools/crack_check.gd counts sky pixels
  seen through the ground; make terrain-capture requires cracks in a
  skirtless control and none in the real terrain.

Tests: chunk vertices sit on the heightfield; skirts cover every pairing
of levels on sampled shared edges; detail falls with distance; flying
across the island at 30 m/s for 2,037 frames streams 661 chunk rebuilds
with the worst main-thread frame at 0.8 to 1.4 ms (headless, CPU only);
24 players over 900 ticks on two generated islands never sink into the
ground, and a player sprints up towards a summit unharmed.
make terrain-capture: control 437 crack pixels, terrain 0.

Closes #10

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

4.1 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 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.