Also removes a stray probe .uid committed with M2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
332 lines
20 KiB
Markdown
332 lines
20 KiB
Markdown
# Tidewall development log
|
||
|
||
Newest entries at the bottom. Each entry records what was done, test results,
|
||
decisions, and what's next.
|
||
|
||
## 2026-11-09: first build run
|
||
|
||
**Done:** F1 skeleton and pinned engine, F2 GDD and originality rules, F3 architecture,
|
||
F4 test harness, F5 simulation core. Commits were made in the order F1, F4, F2, F3, F5,
|
||
because F2 and F3 add tests that need F4's runner.
|
||
|
||
**Tests:** `make check` passes: engine verified, 18 scripts parsed, 38 tests pass, and
|
||
all 8 self-check fixtures behave as expected. The determinism test replays a log of 24
|
||
players over 10,000 ticks.
|
||
|
||
**Decisions:**
|
||
- The test runner uses Godot's `Logger` API (`OS.add_logger`), so engine and script
|
||
errors during a test fail that test, without having to scrape output.
|
||
- The tuning table is `src/sim/tuning.gd`, as constants, because a misspelled name is a
|
||
parse error. The GDD refers to numbers by constant name, so it can't go stale.
|
||
- `tools/godot.sh` forces `--headless` and keeps engine data in `.godot-home/`. F7 can set
|
||
`TIDEWALL_GODOT_DISPLAY=1` inside its container only.
|
||
- Untyped declarations are errors, set in `project.godot`.
|
||
- `.gitattributes` can't filter by size, so `tools/check_binaries.sh` fails `make check`
|
||
on any tracked binary over 1 MB that isn't in LFS.
|
||
- Player movement in `Simulation` is a flat placeholder until v0.2 replaces it.
|
||
- Scanning for unseeded randomness uses a regex that tells `randf()` from a seeded
|
||
`stream.randf()`. Only `sim_rng.gd` may create a generator.
|
||
|
||
**Known gaps:** the LFS push path hasn't been exercised, as nothing is in LFS yet.
|
||
|
||
**Next:** F6 headless server and `make smoke`, then F7 capture harness.
|
||
|
||
## 2026-11-09 (evening): F6, F7, W1 and v0.1.0
|
||
|
||
**Done:**
|
||
- F6 (#6): headless dedicated server (`tools/godot.sh -- --server ...`), JSON-line logs
|
||
that all carry the seed, exit codes 0, 1 and 2, and `make smoke`, which is now part of
|
||
`make check`.
|
||
- F7 (#7): `tools/capture.sh`, which renders in a throwaway `tidewall-capture-*` container
|
||
(debian:13, Xvfb, Mesa) with no network, plus `make capture-test`.
|
||
- v0.1 Foundations milestone closed and tagged `v0.1.0`, on its due date.
|
||
- W1 (#8): `SimGround`, `Movement`, `CameraRig`, `InputSettings` and `PlayerCamera`.
|
||
- Opened #70 (H7), graceful shutdown on SIGTERM, as a low-priority hardening follow-up.
|
||
|
||
**Tests:** `make check` passes: 39 scripts parsed, 97 tests, 8 self-check fixtures,
|
||
and the smoke run. Smoke with 24 wander bots: p95 tick about 0.4 ms against the 12 ms
|
||
budget. `make capture-test` passes. Captures checked by eye: smoke, camera, camera_wall,
|
||
camera_aim.
|
||
|
||
**Decisions:**
|
||
- Captures default to Forward+ through Lavapipe, the game's renderer. Debian 13's ICD is
|
||
`lvp_icd.json`. Godot silently falls back to OpenGL when Vulkan fails, so `capture.sh`
|
||
fails when the renderer it got isn't the one it asked for. Compatibility renders
|
||
brighter than Forward+, so compare captures only within one renderer.
|
||
- `capture.sh` refreshes the class cache headless on the host before rendering, and
|
||
`captures/` has a `.gdignore`.
|
||
- **Look convention fixed:** right is forward x up, `(-cos yaw, 0, sin yaw)`, and turning
|
||
right decreases yaw. F5 had it mirrored. See ARCHITECTURE.md.
|
||
- Fall damage comes from landing speed, not drop height, so a capped slide down a steep
|
||
bank is harmless but a cliff fall isn't.
|
||
- The camera casts pivot to shoulder, then backward, then straight from the pivot, and
|
||
finishes with a clearance pull-in. The 24,480-view sweep found both a steep-slope
|
||
near-plane clip and over-the-wall occlusion before they shipped.
|
||
- The hash-sensitivity test now flips a high stick bit, because a 1/127 nudge to an
|
||
airborne player is below the hash's millimetre rounding.
|
||
- `WanderBot` is a placeholder until the bots in v0.4.
|
||
|
||
**Known gaps:** SIGTERM kills the server without a stop line (#70). Mouse feel and frame
|
||
rates can't be verified without a GPU playtest.
|
||
|
||
**Next:** W2, the procedural island generator (#9), then W3 chunked terrain (#10). v0.2 is
|
||
due at the end of 2026-11-10, with 6 issues left.
|
||
|
||
## 2026-11-10 (afternoon): W2, W3 and W4
|
||
|
||
**Done:**
|
||
- W2 (#9): `Island.generate(seed)`, a 513 × 513 heightfield at 2 m over the 1,024 m world,
|
||
with a warped coast, a shelf and interior dome, 2 to 4 summits on ridges, marsh, and
|
||
elevation bands. `Simulation` generates it; the server logs `world_hash`.
|
||
`tools/island_map.gd` draws top-down maps.
|
||
- W3 (#10): `TerrainView` and `TerrainChunkBuilder`, 64 m chunks at four detail levels,
|
||
built on worker threads, with skirts at the seams and a procedural splat shader.
|
||
`make terrain-capture` proves no cracks against a skirtless control.
|
||
- W4 (#11): `PoiSet` and `Poi`, six original POI kinds from modular parts, 10 to 16 per
|
||
island, with loot markers and walk routes. `PoiView` draws them as MultiMeshes.
|
||
`SimGround` now indexes solids in 8 m cells.
|
||
- Opened #71 (H8) to watch a one-off 238 ms streaming frame seen under host load.
|
||
|
||
**Tests:** `make check` passes: 120 tests, self-check and smoke (p95 tick 0.47 ms with
|
||
24 bots and about 300 POI solids). `make check` now takes about 2.5 minutes, mostly the
|
||
100-seed island sweep. `make terrain-capture` passes (control 437 crack pixels, real 0).
|
||
Captures checked by eye: island maps of seeds 1 to 4, terrain, terrain_lod,
|
||
terrain_cracks, and poi_* for all six kinds.
|
||
|
||
**Decisions:**
|
||
- The island is about 1 km across, not the 2 km in W2's text, because the world and the
|
||
snapshot position range are 1,024 m. Reasoning is on #9.
|
||
- Worldgen and POI placement each use their own `SimRng(seed)` copy, so generating them
|
||
on a client never shifts the match's gameplay streams.
|
||
- `Simulation.new(seed)` generates the island; tests that don't care pass
|
||
`SimGround.flat()` as the second argument to skip worldgen.
|
||
- Terrain seams use skirts, not edge stitching, so chunks never need to know their
|
||
neighbours' levels. Skirt depth is computed per chunk from the actual edge error.
|
||
- The streaming budget is measured as main-thread wall time in `TerrainView._process`,
|
||
headless. It can't see GPU upload cost.
|
||
- **Movement change:** step-up tests the body at the height it will step up to. The W4
|
||
traversal test showed the lighthouse stair was impassable without it. Treads must be
|
||
at least the player radius (0.4 m) deep; the POI stairs use 0.5 m.
|
||
- POI solids are axis-aligned boxes, rotated only in quarter turns.
|
||
- Summit stone was darkened after the shrine capture read as snow.
|
||
|
||
**Known gaps:** no water yet, so piers and coasts show bare sea floor (W6). POIs and
|
||
lowland are blockout visuals until W5 vegetation and the v0.6 art pass. Frame times
|
||
and feel still need a real GPU.
|
||
|
||
**Pace:** v0.2 is due at the end of today and W5, W6 and W7 remain, so it will finish
|
||
about a day late. Next by the work order is W5 (#12, no priority label), then W6 (#13,
|
||
water, core) and W7 (#14, the drop). If the next run finds v0.2 more than a day behind,
|
||
defer W5 per the pacing rule and do W6 and W7 first.
|
||
|
||
## 2026-11-11 (midday): W5, W6, W7 and v0.2.0
|
||
|
||
**Start of run:** the tree held an unfinished W5 from the previous run: the prop
|
||
simulation, `SimGround.remove_solid` and tests, but no view. Two of its tests had bugs.
|
||
`_first_open` always returned -1 because its clearance scan touched the trunk itself, and
|
||
the damage loop then spun forever, which hung the test run. Boulders on slopes were also
|
||
buried on their uphill side. I fixed both, finished the work and committed it rather than
|
||
stashing it. The Agents category held nothing for this task.
|
||
|
||
**Done:**
|
||
- W5 (#12): `PropSet`, about 3,000 pines, scrub, boulders, wrecks and crates per island,
|
||
each with one collision box and health. A destroyed prop's box is removed at once.
|
||
`PropView` draws one MultiMesh per kind per 128 m square, about 150 draws, with
|
||
per-kind visibility ranges and procedural flat-shaded meshes.
|
||
- W6 (#13): a global sea level, changeable at runtime; wading; swimming (float, sprint,
|
||
dive, kick out, stand up in the shallows); stamina, breath and drown damage, counted in
|
||
ticks; no fall damage into deep water. `WaterView` is a procedural sea shader with
|
||
depth tint, foam at the waterline and ripples that fade with distance.
|
||
- W7 (#14): `Drop`, a seeded route that always crosses land, riding, leaping,
|
||
freefall, the wing-sail (by hand or automatic at 40 m), steering, a safe handoff to
|
||
landing or swimming, and ejection at the route's end. Every server match starts with
|
||
the drop, and bots leap at a time fixed by their ID.
|
||
- Closed milestone v0.2 and tagged `v0.2.0`.
|
||
- Opened #72 (`needs-eric`, v0.6): the GDD's core loop describes the launch as a packet
|
||
ship, a lifeline mortar and a gull-kite, while W7 says sky barge and wing-sail. Only
|
||
names and visuals depend on it.
|
||
|
||
**Tests:** `make check` passes: 151 tests, self-check and smoke (p95 tick 0.53 ms with
|
||
24 bots, who now leap from the barge). Captures checked by eye: props_forest,
|
||
props_felled, props_overview, props_beach, props_crate, props_highland, water_shore
|
||
and water_flood.
|
||
|
||
**Decisions:**
|
||
- Vertex colours in generated meshes are sRGB (`vertex_color_is_srgb`). Without it the
|
||
palette came out washed out.
|
||
- Prop materials are matte, because a bright sky highlight on pine tips read as snow.
|
||
- Swimming starts at 1.35 m of water and ends below 1.2 m. The gap stops players
|
||
flickering between swimming and walking at the edge.
|
||
- An exhausted swimmer sinks until the head is under, so stamina feeds into drowning.
|
||
There's no separate "exhausted" damage.
|
||
- The drop's route passes near the island's middle, pulled onto land, so every route
|
||
crosses at least 250 m of dry land.
|
||
- Gameplay timers (breath, stamina, drowning) are whole ticks, for exact replay.
|
||
|
||
**Known gaps:** no client scene yet puts terrain, props, water and a player together.
|
||
That comes with the client and HUD work. There are no barge or sail visuals, pending #72.
|
||
A swimmer can't climb onto pier decks yet. GPU frame times are unverified.
|
||
|
||
**Pace:** v0.2 finished about half a day late. v0.3 (9 issues) is due at the end of
|
||
today, so the next run starts about a day behind. Next is B1 (#15, harvesting, which
|
||
can use `PropSet.damage` and `material_of`), then B2 and B3. If the next run is more
|
||
than a day behind, defer B4 (#18, priority/low) and then B8 (#22, no priority) as the
|
||
pacing rule says.
|
||
|
||
## 2026-11-11 (afternoon): B1, B2 and B3
|
||
|
||
**Start of run:** clean tree, nothing new in the Agents category for this task.
|
||
|
||
**Done:**
|
||
- B1 (#15): `Materials` and `Harvest`. Fire with the boathook (selection 0, outside build
|
||
mode) swings every 20 ticks. The server casts the swing from its own copy of the eye
|
||
and look, so range and rate can't be faked. Each hit does `HARVEST_DAMAGE` to the
|
||
nearest prop and gives `HARVEST_PER_HIT` of its material, capped at `MATERIAL_CAP`.
|
||
The simulation gained a per-tick `events` list and a shared `action_cooldown`.
|
||
- B2 (#16): `StructureSet` and `Building`, plus the client's `StructureView`,
|
||
`PieceMesher` and `BuildGhost` in `src/client/building/`. Pieces are wall, floor,
|
||
ramp, roof and breakwater, in three materials. The server validates range, world
|
||
bounds, occupancy, trapping a player, cost and support. Placement is limited to 10
|
||
pieces a second. The ghost runs the same `target()` and `check()` as the server.
|
||
- B3 (#17): health that builds up, boathook and tide damage, breakwater wear and
|
||
failure, and incremental integrity. The search starts from a removed piece's
|
||
neighbours and stops at the first grounded piece. `ground_changed()` handles
|
||
terrain changes.
|
||
|
||
**Tests:** `make check` passes: 193 tests, self-check and smoke (p95 tick 0.54 ms).
|
||
- 24 builders placing at 10 pieces a second: p95 6.6 ms.
|
||
- A 564-piece fort: removing one ground wall takes 57 µs, and the full 479-piece
|
||
cascade takes 4.7 ms.
|
||
- Captures `build_fort` and `build_fort_side`, checked by eye.
|
||
|
||
**Decisions:**
|
||
- **Half-level vertical snap.** Pieces are 4 m tall, but levels are 2 m apart
|
||
(`BUILD_LEVEL_METRES`). The first capture with a 4 m vertical grid showed a fort half
|
||
buried on a gentle slope. A slot is also taken when the same slot one level up or
|
||
down is used.
|
||
- Targeting snaps the look to a quarter turn. Walls go on the near edge of your own
|
||
cell; floors, ramps and roofs go in the next cell, or your own when looking down.
|
||
Looking up adds a whole cell.
|
||
- Ramps collide as 10 stairs of 0.4 m and are drawn as a sloped deck.
|
||
- Walls over lower ground get a skirt down to the terrain, at most one level deep.
|
||
- Grounded means touching the terrain or a fixed solid (POI). Props don't count.
|
||
- The boathook damages pieces (nothing back), so B3 has a real weapon before B6.
|
||
- `src/client/build/` would have been git-ignored by the `build/` rule, so the folder is
|
||
`src/client/building/`.
|
||
|
||
**Known gaps:** no visual for build-up or damage on pieces yet. Breakwaters don't hold
|
||
water back yet; that needs the tide's flood logic. The client doesn't send build
|
||
commands yet; that comes with the playable client and HUD. GPU frame times are
|
||
unverified.
|
||
|
||
**Pace:** v0.3 is due at the end of today, and B4 to B9 (6 issues) remain, so v0.3 will
|
||
finish about a day late. Next by the work order is B4 (#18, editing placed pieces). It
|
||
is priority/low, so if the next run is more than a day behind, defer it with a comment
|
||
and take B5 (#19, inventory), then B6 (#20) and B7 (#21).
|
||
|
||
## 2026-11-11 (evening): B5, B6 and B7
|
||
|
||
**Start of run:** clean tree. Nothing in the Agents category for this task. The newest
|
||
post there is a headless Luanti testing tip from another task, not relevant here.
|
||
|
||
**Deferred:** B4 (#18, priority/low) with a comment. v0.3 was due tonight with six
|
||
issues open and v0.4 is due tomorrow, so the build is effectively more than a day behind.
|
||
|
||
**Done:**
|
||
- B5 (#19): `ItemDef` resources built by `ItemCatalog` from `Tuning.WEAPONS`, `ITEMS`
|
||
and the new `AMMO` table. `Inventory`: five slots plus the boathook at selection 0,
|
||
ammunition outside the slots with caps, pickup entities, and pick up, drop and swap,
|
||
each once per press. The new `BUTTON_DROP` is bit 8. The simulation now marks
|
||
players eliminated at 0 health, emits `eliminated` with the last attacker, drops
|
||
everything they carried, and ignores their commands.
|
||
- B6 (#20): `Weapons`. Server-side fire rate, magazines and reloads, and seeded spread
|
||
with aim, bloom and movement terms. Hitscan traces in 16 m segments, and projectile
|
||
entities fall under gravity. Hits land on terrain, solids (pieces and props take
|
||
damage) or player boxes. Armor takes damage before health, and there are headshots
|
||
and linear falloff.
|
||
- B7 (#21): eight slot weapons, adding the rivet repeater and the harpoon gun. Four
|
||
tiers: rusted, seaworthy, brass_fitted and captains. The line thrower pulls the
|
||
shooter. `Consumables` adds the tar patch as a fourth consumable. Use is timed,
|
||
validated and interrupted by slot change, drop, sprint, swim or elimination.
|
||
|
||
**Tests:** `make check` passes: 247 tests, self-check and smoke (p95 tick 0.61 ms with
|
||
24 bots). New suites: `test_inventory` (18), `test_weapons` (22) and `test_roster` (14,
|
||
including data validation over every item).
|
||
|
||
**Decisions:**
|
||
- The issues ask for "resources", and CLAUDE.md says numbers live only in `tuning.gd`.
|
||
Both hold: `ItemDef` is a `Resource`, but `ItemCatalog` builds every definition from
|
||
the Tuning tables, so a new weapon is one table entry.
|
||
- Recoil on the server is bloom, extra spread that builds in sustained fire. It only
|
||
recovers on ticks the weapon is ready, otherwise automatics never bloomed. Camera
|
||
kick is presentation and comes with the client.
|
||
- Shots trace from the eye, not the third-person camera. That needs reconciling when
|
||
the client fires (noted on #20 for N4 and the client work).
|
||
- Taking damage doesn't interrupt a consumable. Sprinting does.
|
||
- Eliminated players skip their commands entirely. M3 decides what happens to them
|
||
next (spectating, removal).
|
||
|
||
**Known gaps:** nothing renders pickups, projectiles or shots yet, and no client sends
|
||
fire, interact or drop. The powder keg can be carried but not thrown until B8. Loot
|
||
doesn't spawn until B9.
|
||
|
||
**Pace:** v0.3 was due tonight and B8 and B9 are still open, so it will close about a
|
||
day late. Next is B9 (#23, priority/high, loot tables and containers). B8 (#22,
|
||
explosives) has no priority label. If the next run is more than a day behind, defer B8
|
||
with a comment and go on to v0.4, starting with M1 (#24). B4 stays deferred.
|
||
|
||
## 2026-11-11 (night): B9, M1 and M2
|
||
|
||
**Start of run:** clean tree, fast-forward pull was a no-op. Nothing in the Agents
|
||
category for this task: the newest posts are a headless Luanti testing tip and the CI
|
||
runner changes from `eom-cicd-roadmap`. This repo has no CI on the shared runner, so
|
||
nothing to act on.
|
||
|
||
**Deferred:** B8 (#22, explosives, no priority label) with a comment, under the pacing
|
||
rule. B4 (#18) stays deferred. Both stay open in v0.3, so the milestone and its tag wait.
|
||
|
||
**Done:**
|
||
- B9 (#23): `LootSet` rolls each match's loot once from the `"loot"` stream: a sea chest
|
||
or floor loot at every POI loot marker, by location table (`LOOT_SOURCES`) and tier
|
||
weights, plus one roll in every washed-up crate, spilled when it breaks. Interact
|
||
opens a chest in reach unless a pickup is nearer. If a match's rolls leave fewer than
|
||
24 weapons at POIs, extra weapon rolls top up floor spots.
|
||
- M1 (#24): `Match` and `MatchRules`: lobby, countdown, drop, play, results, then a new
|
||
island. Handles for participants, bots fill empty places, placements and winners,
|
||
leaving counts as elimination mid-match. `ServerLoop` now drives a `Match`.
|
||
- M2 (#25): `Tide` (schedule), `SafeGround` (per-island planned levels) and `Flood`
|
||
(water flows along a 4 m grid; breakwater stacks seal cell edges; cut-off ground fills
|
||
at the breach rate once overtopped or breached). Surges, sudden death, a time limit
|
||
and a tie-break, so every match has a winner.
|
||
|
||
**Tests:** `make check` passes: 285 tests, self-check and smoke (p95 0.73 ms with 24 bots,
|
||
still all hold). New: `test_loot` (12, with the 1,000-seed statistics run), `test_match`
|
||
(13), `test_tide` (18), and the safe-ground check in `test_island`'s 100-seed sweep. A
|
||
full real rise with 24 bots measured p99 1.5 ms, max 1.9 ms per tick. `make check` now
|
||
takes about 4.5 minutes, mostly the 100-island sweep and island-backed tests.
|
||
|
||
**Decisions:**
|
||
- Loot is rolled at match start, crates included, so contents never depend on order.
|
||
The 1,000-seed statistics share four generated islands, because one island takes
|
||
about 0.6 s; the shares and minimums are honest for those islands.
|
||
- The first match of a session uses the server's seed, so the smoke hash stayed the
|
||
same through the M1 refactor, which is how I checked it changed nothing.
|
||
- Planned tide levels: without them, 3 of 100 islands stranded the main landmass late
|
||
in the match. Lowering a phase to just under the main land's top fixed all 100. Most
|
||
islands get their 64 m phase lowered a little.
|
||
- Newly flooded ground fills from its lowest floor at the breach rate, even on the
|
||
coast. At real tide speeds that's a lag of well under a second.
|
||
- The tie-break is health, then height, then join order: deterministic and fits the
|
||
"highest ground wins" theme.
|
||
|
||
**Known gaps:** nothing renders chests, pickups or the flood grid yet. The client's
|
||
water (A6) has to follow `Flood`, not just `sea_level`. Snapshots (N2) will need the
|
||
flood state. No server CLI flags for match timers yet.
|
||
|
||
**Pace:** v0.3 was due tonight; its high-priority work is done and only the deferred
|
||
B4 and B8 remain. v0.4 is due tomorrow (2026-11-12) with M3 to M8 open (six issues),
|
||
then multiplayer, art and hardening. Still more than a day behind overall. Next by the
|
||
work order is M3 (#26, eliminations, spectating and results), then M4 (#27, bot
|
||
navigation) and M5 (#28). M6 and M7 have no priority label and should be deferred if
|
||
the next run is still behind.
|