Weather.at(tide, tick) derives the weather from the tide's schedule alone, so every client sees the same sky with nothing new on the wire: the storm builds from calm at the first tide to a gale at sudden death, and the light runs from mid-afternoon to dusk at the time limit. WeatherView applies it each sync to the sky, sun, fog, ambient light, the sea's roughness and rain around the camera (CPUParticles3D, for both renderers). Under water the view closes into SEA_MURK, the rain stops and the surface is a rippled ceiling seen from below. The sea shader darkens open water and adds chop and whitecaps with the storm, and keeps a breathing foam band at the waterline with a fainter line beyond. In the Compatibility renderer, whose depth texture the shader can't read (the sea came out all foam), water depth comes from a texture of the terrain's heights instead. Sea colours move into Palette; the rain and wind beds follow the weather. Tests: test_weather (7). make check passes (611 tests). Captures: make sea-captures (every tide phase, calm beach, the last land in the gale, under water, and three in the Compatibility renderer). Closes #46 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
90 lines
10 KiB
Markdown
90 lines
10 KiB
Markdown
# 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](docs/DEVLOG.md) and the Gitea issues are the
|
|
continuity.
|
|
|
|
## Read these first
|
|
|
|
- [docs/DEVLOG.md](docs/DEVLOG.md): what happened, newest entries at the bottom.
|
|
- [docs/GDD.md](docs/GDD.md): the game design.
|
|
- [docs/ORIGINALITY.md](docs/ORIGINALITY.md): binding rules for everything we make.
|
|
- [docs/STYLE.md](docs/STYLE.md): the look and sound. Every client colour comes from `Palette`.
|
|
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): server-authoritative design and module map.
|
|
- [src/sim/tuning.gd](src/sim/tuning.gd): the one table of gameplay numbers.
|
|
|
|
## 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 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 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 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 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.
|