The game now opens on a main menu when it has a window: practice against bots (count and skill), join a server (by address, or from a LAN search list), settings, and quit. In a match, Escape brings up a pause menu (the match goes on) with settings and leave; when a match the player was in ends, a results screen shows their place, eliminations and the last of the feed. - KeyBindings: every action rebindable to a key or mouse button. bind() refuses an input another action uses and names it; Escape is reserved. ClientInput reads keys through the bindings. - GameSettings: bindings, mouse, graphics (quality preset and the print pass), audio (master, music and effects buses), display (window mode, vsync, frame cap), name, last server and practice choices, saved in user://settings.cfg. Missing, unreadable or corrupt files and bad values fall back to defaults, value by value; hand-edited key clashes are repaired on load. - Menus (src/ui): paper-and-ink panels, brass focus edge, keyboard navigable; a drawn sea-and-tide-post backdrop, or an ink wash over a match. AppShell runs menus and the session. - LocalServer takes a bot difficulty. - make menu-captures renders every screen. Closes #50 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
82 lines
8.3 KiB
Markdown
82 lines
8.3 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 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 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.
|