Files
tidewall/CLAUDE.md
T
claudeandClaude Opus 5.5 e8414fde9a A7: Visual effects, hit marker and hurt flash
EffectsView (src/client/effects/) draws muzzle flashes at the held
weapon's muzzle, tracer ribbons to each pellet's impact (and streaks
behind projectiles in flight), hit bursts on players, chips and dust by
material or ground, keg blasts with fireball, debris, smoke and a light,
build dust, collapse clouds for broken pieces, splashes and surge spray.

Particles are simulated on the CPU in packed arrays and drawn by two
MultiMeshes (blended and added) through a small billboard shader that
reads each particle's size from custom data (the stock billboard modes
drop the instance scale) and converts Palette's sRGB colours. Pools are
allocated once at the preset's budget (256/512/1024 particles, 64
tracers, 4 lights): three draw calls whatever happens.

The HUD gains a reticle, four ticks round it when your shot strikes a
player (HitFeedback), and a rust flash at the screen's edge when hurt.

Tests: test_effects_view (12), including a 24-shooter stress scene that
stays inside each budget and never adds nodes. Captures: make
effects-captures (fight, blast, work, stress), checked by eye, and the
blast in the Compatibility renderer.

Closes #47

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

108 lines
14 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.
- [docs/PLAY.md](docs/PLAY.md): the player guide (install, controls, rules), graphics presets, renderers and the tested configurations.
- [docs/SERVER.md](docs/SERVER.md): the server guide. [CONTRIBUTING.md](CONTRIBUTING.md) and [CREDITS.md](CREDITS.md).
- When a command, option or control changes, update PLAY.md, SERVER.md and the man pages in `packaging/deb/man/` with it.
- [docs/BALANCE.md](docs/BALANCE.md): how the pacing and weapons were tuned from bot matches.
## 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 balance` | H3: plays 200 bot-only matches in four processes under `nice` (about 15 min) and writes `build/balance/report.txt`: match length, players standing over time, causes of death, eliminations by weapon and by difficulty. Fails if the median match is outside 12 to 18 minutes or a weapon takes over 35% of eliminations (`BALANCE_*` in tuning). `BALANCE_MATCHES`, `BALANCE_FIRST`, `BALANCE_JOBS` scale it. See docs/BALANCE.md. |
| `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, 29, 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 poi-captures` | Renders each kind of point of interest (`captures/poi_*.png`, about 3 min). Needs Docker. Look at them. |
| `make build-captures` | Renders the fort and the wall test card: a row per material, a column per state (half built, intact, worn, battered), and a battered ramp (`captures/build_*.png`), and the barge and sea chests (`captures/vessels.png`), about 2 min. Needs Docker. Look at them. |
| `tools/capture.sh canopy captures/canopy.png` | H11: the shoulder camera on a player against a pine, with canopies in the way hidden (`canopy_before` puts them back). |
| `make style-captures` | Renders a hamlet and a dock with and without the woodcut print pass (`captures/style_*.png`). Needs Docker. |
| `make stability` | H4: one dedicated server plays 50 bot matches back to back, unthrottled, under `nice` (about 13 min), sampling its resident memory. Fails on a crash, hang, engine or script error, a match without a winner, or memory growing more than 256 KiB (static) or 1 MiB (resident) a match after the first five. `STABILITY_MATCHES`, `STABILITY_SEED`, `STABILITY_DIR` scale it. Report in `build/stability/report.txt`. |
| `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 bench` | H1: the server's p50/p99/max tick with 24 bots on three seeds, and the client's draw calls, triangles, objects and memory at six moments of a match (about 3 min, needs Docker). Fails on anything over the budgets in docs/ARCHITECTURE.md. Report in `build/bench/report.txt`. `BENCH_SEEDS`, `BENCH_TICKS`, `BENCH_CLIENT=0` scale it. |
| `make dist` | R1: exports the game with the official Godot templates (checked against `tools/engine.sha512`, installed into `.godot-home/`) to `build/dist/tidewall-<version>-linux-x86_64.tar.gz` with a `.sha256`. One binary and one pack: `tidewall.x86_64` is the game, `tidewall-server` runs it headless as the server. The version is `application/config/version` in project.godot; the commit goes in as `build_commit.txt` (`BuildInfo`). |
| `make dist-check` | R1: builds the package, unpacks it outside the repo with HOME and XDG dirs in a temp dir, and runs `SMOKE_DIST=<dir> tools/smoke.sh`, a whole bot match, and the exported game joining the exported server (about 2 min). |
| `make deb` | R2: builds `build/dist/tidewall_<version>-1_amd64.deb` from the `make dist` package with `dpkg-deb`: launchers in `/usr/games`, the game in `/usr/lib/tidewall`, a desktop entry, hicolor icons, and copyright with the engine's licences. Never install it on the host. |
| `make deb-check` | R2: builds the .deb and checks it in a throwaway `tidewall-deb-check-*` Debian 13 container: installs with only its Depends, `desktop-file-validate`, the server and the game headless as a user, lintian for information, and a purge that leaves nothing behind (about 3 min). |
| `make app-icon` | R2: renders `assets/icons/app/tidewall.svg` (written by hand) to `tidewall-<N>.png`. Commit what changes. |
| `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 effects-captures` | Renders the visual effects (A7): a shot striking a player over the shoulder with the HUD's hit marker, a keg blast beside a collapsing wall, build dust, chips and a splash, and 24 players firing with kegs going off at the largest particle budget (`captures/effects_*.png`, about 6 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, and
`CAPTURE_RENDERER=no_vulkan` hides the Vulkan driver to check the game falls back to OpenGL (H2).
The `quality_low`, `quality_medium` and `quality_high` scenarios draw a match moment with each preset. 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.