claude
050b8251a7
ci / verify (push) Successful in 48s
Four always-on-screen slots, items as data, and loot tables on enemies and bosses. Health potions drop rarely from trash and always from the Warden; the Warden also drops a Warden's Ration, one per living player, which does nothing at all. The ration is not filler. Player-instanced loot is a separate code path from shared loot -- a distinct entity per owner, filtered per peer in the snapshot encoder -- and the cheapest way to keep that path honest is to have something in the game that exercises it on every boss kill. Item actions ride the input frame rather than becoming new client messages. InputFrame gained BTN_USE, BTN_DROP and a slot byte, which buys the packet-loss redundancy, the replay guard on last_input_tick, ordering against movement on the same tick, and a rate limit of one action per tick -- all of which a separate RPC would have needed bolted back on. The cost is that anything in the frame which must not repeat has to be edge-triggered, since frames are resent and a starved server coasts on the last one it holds. Instanced loot is enforced in NetCodec.encode_snapshot, beside the actor interest radius: a peer is never told another player's copy exists. Hiding it client-side would have been the same mistake as relying on fog to hide enemies. Inventories live on the character and are written to the store on every transaction, so a crash between "picked it up" and "wrote it down" cannot lose or duplicate an item. Anything dropped becomes world-shared whatever it was before, and a potion used at full health is refused rather than spent. tools/diag_loot.tscn covers drop -> snapshot -> pick up -> persist -> use -> drop plus both visibilities on the wire, for the same reason diag_progression exists: bots are poor shots and almost never produce a drop. It asserts each input frame was actually consumed, after an early version silently dropped its first press and every later check passed for the wrong reason. check.sh clean, 266 tests, SMOKE PASS, all three diagnostics green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
208 lines
12 KiB
Markdown
208 lines
12 KiB
Markdown
# Transcience
|
|
|
|
Top-down twin-stick bullet-hell with a dedicated, server-authoritative backend.
|
|
Godot 4.7, GDScript only. One executable is both server and client.
|
|
|
|
**Starting a new session?** [docs/ROADMAP.md](docs/ROADMAP.md) says what is
|
|
built, what is next, and which file implements each feature.
|
|
[docs/DECISIONS.md](docs/DECISIONS.md) records what the user has already decided
|
|
and why — read it before asking a design question, several answers there are not
|
|
the obvious default.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
tools/check.sh # parse-check every script (~5s) -- run after every edit
|
|
tools/test.sh # GUT suite, headless (~3s)
|
|
tools/smoke.sh # real server + 4 bot clients over ENet (~40s)
|
|
tools/server.sh # dedicated server
|
|
tools/client.sh --listen # host and play, no menu
|
|
```
|
|
|
|
Diagnostics. Each runs as a *scene* (they need the `Net` autoload) and exits
|
|
non-zero on failure, so they gate like tests:
|
|
|
|
```bash
|
|
godot --headless --path . res://tools/diag_prediction.tscn # prediction gap; injects clock drift
|
|
godot --headless --path . res://tools/diag_progression.tscn # kill -> xp -> level -> death -> roster
|
|
godot --headless --path . res://tools/diag_loot.tscn # drop -> pick up -> persist -> use -> drop
|
|
godot --headless --path . --script tools/bench.gd # sim cost per tick
|
|
python3 tools/build_local_assets.py # rebuild the local-only bullet atlas
|
|
```
|
|
|
|
`diag_progression` and `diag_loot` exist because the bot smoke test cannot cover
|
|
either: bots are poor shots, so they rarely kill anything, which means they
|
|
neither earn levels nor produce drops.
|
|
|
|
Everything after `--` goes to `GameOpts.parse()`:
|
|
|
|
| Flag | Effect |
|
|
| --- | --- |
|
|
| `--server` | Dedicated server, no view. |
|
|
| `--join` | Skip the menu and connect. |
|
|
| `--listen` | Skip the menu and host a listen server with a local player. |
|
|
| `--bot` | Scripted input instead of the keyboard. Implies `--join`. |
|
|
| `--host`, `--port`, `--name` | Connection details. |
|
|
| `--autoquit N` | Quit after N physics ticks. |
|
|
| `--boss-rush` | Server-side: dungeons spawn the boss and no trash. |
|
|
| `--depth N` | Server-side: depth of new dungeons, which drives map size. |
|
|
| `--account N` | Client-side: override the local account, so several clients can coexist on one machine. |
|
|
| `--store PATH` | Server-side: character store location. Use a scratch path in tests. |
|
|
| `--verbose` / `--quiet` | Log level. |
|
|
|
|
A change is done when `check.sh`, `test.sh` and — if it touched networking,
|
|
instances or the simulation — `smoke.sh` all pass. Say so explicitly; do not
|
|
report a networking change as working on the strength of unit tests alone.
|
|
|
|
## Hooks
|
|
|
|
`tools/install-hooks.sh` once per clone (points `core.hooksPath` at
|
|
`.githooks/`, committed in the repo — plain bash, no `pre-commit` framework, so
|
|
cloning costs nothing extra to run tools/*.sh). Own `.gd` files (not vendored
|
|
`addons/`) trigger `check.sh` + `test.sh` on commit (~7s); `smoke.sh` runs on
|
|
push (~35s, skip deliberately with `SKIP_SMOKE_HOOK=1 git push`).
|
|
|
|
## The one rule
|
|
|
|
**The server decides everything; the client only sends intent.**
|
|
|
|
A client can send exactly two things: an [InputFrame] (move vector, aim angle,
|
|
five button bits, an inventory slot) and a handshake — plus the two low-rate
|
|
character-roster requests, which are also pure intent. There is no message for
|
|
"I moved here", "I hit that", "I took damage", "my escape finished" or "I now
|
|
own this item". Adding one would collapse the whole security model, so don't —
|
|
validate-after-the-fact is strictly weaker than having no code path at all.
|
|
|
|
When a new player action needs a message, look at whether it fits in the input
|
|
frame first. Item use and drop did, and got the redundancy, the replay guard and
|
|
the per-tick rate limit for free. The cost was one rule: anything in the input
|
|
frame that must not repeat has to be **edge-triggered** (see `prev_buttons`),
|
|
because frames are resent and a starved server coasts on the last one it holds.
|
|
|
|
`SimWorld.authoritative` is `true` on the server and `false` on the client. In
|
|
replica mode the world runs no AI, fires no emitters and resolves no hits; it
|
|
only integrates bullets it was told about. `tests/unit/test_server_authority.gd`
|
|
and `tests/integration/test_replica_parity.gd` pin this down.
|
|
|
|
## Layout
|
|
|
|
| Path | What lives there |
|
|
| --- | --- |
|
|
| `src/sim/` | The whole game as plain RefCounted objects. No nodes, no physics server, no rendering. |
|
|
| `src/actors/` | Data-only `Resource` definitions: `EnemyDef`, `BossDef`, `ItemDef`, `LootDrop`. Shapes, not instances. |
|
|
| `src/sim/patterns/` | Bullet emitters — the authoring surface for every enemy and boss. |
|
|
| `src/sim/map_grid.gd` | Tile grid: collision, line of sight, chunk streaming. |
|
|
| `src/sim/map_gen.gd` | Dungeon generation; `build()` is the only entry point. |
|
|
| `src/content/rooms.gd` | Hand-authored room stamps (hub, boss arenas) as text. |
|
|
| `src/meta/` | Accounts, characters, persistence, XP curve. Server-owned. |
|
|
| `src/content/content.gd` | All enemies and bosses, defined in code. Source of truth. |
|
|
| `src/content/items.gd` | All items, same idea. `Items.ORDER` is the wire format — append only. |
|
|
| `src/net/` | Codec, `ServerRuntime`, `ClientRuntime`. |
|
|
| `src/instances/` | Lobby hub and dungeon runs. |
|
|
| `src/view/`, `src/ui/` | Read-only rendering. Never decides anything. |
|
|
| `src/autoload/net.gd` | The only autoload. RPC surface. |
|
|
| `tools/` | Headless tooling. |
|
|
|
|
The simulation must not import anything from `src/net/`, `src/view/` or
|
|
`src/ui/`, and must not touch `Net`. That is what lets tests drive a thousand
|
|
ticks in milliseconds with no SceneTree.
|
|
|
|
## Godot gotchas that will waste your time
|
|
|
|
1. **New `class_name` needs a cache refresh.** `.godot/global_script_class_cache.cfg`
|
|
is only rebuilt by the editor or `godot --headless --path . --import`.
|
|
Until then every use of the new class reports `Identifier not declared`,
|
|
which looks like a real error. `check.sh` does the refresh for you.
|
|
2. **Autoload names do not resolve under `--script`.** A `--script` run has no
|
|
main loop, so `Net` is `Identifier not found`. Tools that need autoloads must
|
|
run as a scene (see `tools/check.tscn`); tools that don't can use `--script`.
|
|
This is why `GameLog` and `GameOpts` are static classes rather than autoloads.
|
|
3. **`ResourceLoader.load()` returns non-null for a broken script.** Never test
|
|
the return value to detect a parse error; read the engine's stderr instead.
|
|
And never call `Script.reload()` on the script you are running — it hangs.
|
|
4. **Input events default to `device = 16`, which matches nothing.** Bindings
|
|
must use `device = -1`. `tools/setup_input_map.gd` generates the input map
|
|
correctly; edit that file, not the `[input]` block in `project.godot`.
|
|
5. **`set_anchors_preset(preset)` does not zero the offsets.** `keep_offsets`
|
|
defaults to `false`, which despite the name means "recompute offsets to keep
|
|
the control's *current* rect on screen" — for a freshly created Control that
|
|
rect is `(0,0)`-sized, so it comes out pinned to the top-left corner
|
|
regardless of the anchors. Use `set_anchors_and_offsets_preset()` for any
|
|
Control built in code. Separately: `.position` assigns an *absolute*
|
|
coordinate even on an anchored control; `offset_left`/`offset_top` are the
|
|
anchor-relative ones. This combination silently broke the main menu and
|
|
three pieces of the HUD.
|
|
6. **`ProjectSettings.save()` drops settings equal to the engine default** and
|
|
strips comments. Anything load-bearing (the 60 Hz tick) is asserted in code
|
|
in `src/main.gd` instead of trusted to `project.godot`.
|
|
|
|
## Non-obvious invariants
|
|
|
|
- **`ClientRuntime.process_physics_priority = -10`.** The client must sample and
|
|
send input before `ServerRuntime` ticks, or a listen server's drawn ship sits
|
|
a permanent tick ahead of the authoritative one and bullets trail it. Measure
|
|
with `godot --headless --path . res://tools/diag_prediction.tscn` (~0.1px is
|
|
healthy, 4px means the ordering broke).
|
|
- **`PLAYER_RADIUS` (hitbox) < `PLAYER_VISUAL_RADIUS` (sprite), and
|
|
`PLAYER_MUZZLE_OFFSET` derives from the visual one.** Prefer a visible
|
|
near-miss over an invisible hit; keep the muzzle clear of the sprite.
|
|
- **`INPUT_MAX_LEAD` must stay well above `INPUT_LEAD_MAX`.** The server's
|
|
input acceptance window has to be wider than the band in which the client
|
|
re-syncs its own numbering. Violate it and drifting clocks land in a silent
|
|
dead zone where the server rejects everything and the client never notices —
|
|
the ship and the authoritative position separate permanently. Pinned by
|
|
`tests/unit/test_input_lead.gd`.
|
|
- **Never send the map, or its seed.** Geometry is streamed per peer in chunks
|
|
around that peer's player (`ServerRuntime._stream_map`). The seed would let
|
|
any client regenerate the whole dungeon. `MAP_STREAM_RADIUS` must stay wider
|
|
than `FOG_VIEW_RADIUS`, or prediction runs on terrain the client lacks.
|
|
- **Bullet speed must stay under one tile per tick.** Wall collision samples
|
|
position once per tick, so anything faster tunnels. Pinned by
|
|
`test_bullet_speeds_stay_below_the_tunnelling_threshold`.
|
|
- **Only `ServerRuntime` writes progression and persistence.** The simulation
|
|
reads a player's level and max health, and moves items between the ground and
|
|
a bag; it never grants experience, retires a character, or touches the store.
|
|
It announces what happened and `ServerRuntime` banks it. One writer means a
|
|
level can never disagree with the experience that earned it, and an inventory
|
|
on disk can never disagree with the one in the world.
|
|
- **`Items.ORDER` is a wire format.** An item's index in it is the byte that
|
|
rides the snapshot and every item event. Append, never reorder — reordering
|
|
makes every existing client decode a potion as a ration, so it needs a
|
|
`Protocol.VERSION` bump.
|
|
- **Loot has two visibilities, and the instanced one is enforced in the codec.**
|
|
`NetCodec.encode_snapshot` filters items owned by another peer, exactly like
|
|
the actor interest radius. Never move that check into the client: hiding an
|
|
entity the client was handed defends nothing.
|
|
- **`LocalAuthProvider` is insecure on purpose.** Any client can claim any
|
|
account. It exists to have the same shape as Steamworks (opaque ticket in,
|
|
64-bit account id out) so swapping is one class. Do not ship it.
|
|
- **No contact damage.** Every enemy threatens through bullets only; touching
|
|
one is harmless. `tests/unit/test_content.gd` enforces that every hostile has
|
|
an emitter.
|
|
- **No i-frames.** Every bullet that touches a player lands; `spawn_grace` is
|
|
the only invulnerable state. Do not reintroduce post-hit immunity — it makes
|
|
dense patterns safer than sparse ones.
|
|
- **A disconnect is not an exit.** Dropping in a dungeon keeps the player in the
|
|
world as `linkdead`, channelling out over the same second the escape costs.
|
|
Damage must never cancel the escape channel, or quitting beats the button.
|
|
See [docs/NETCODE.md](docs/NETCODE.md).
|
|
|
|
## Adding content
|
|
|
|
A new enemy or boss is data, never code. Add a builder to
|
|
`src/content/content.gd` returning an `EnemyDef` / `BossDef` made of the
|
|
emitters in `src/sim/patterns/`, register its id in `enemy()` / `boss()`, and
|
|
add a test. `tests/unit/test_boss.gd::test_a_brand_new_boss_needs_no_engine_changes`
|
|
builds a boss from scratch and asserts the simulation needs no changes to run
|
|
it — if you find yourself adding a per-boss branch to `SimWorld`, stop and add
|
|
an emitter type instead.
|
|
|
|
`tools/export_content.gd` writes `.tres` copies into `resources/` for tuning in
|
|
the editor inspector. Those are an export, not the source; port changes back.
|
|
|
|
## Style
|
|
|
|
Typed GDScript everywhere (`untyped_declaration` is a warning). Tabs, snake_case
|
|
files, `PascalCase` class names. Comments explain *why* a thing is the way it is —
|
|
the netcode and anti-cheat decisions especially. Keep the existing density.
|