transcience/CLAUDE.md

# 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       # 576 GUT tests, headless (~4s)
tools/smoke.sh      # real server + 5 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 . res://tools/diag_upgrades.tscn      # level -> choice -> taken at the NPC -> new stats
godot --headless --path . --script tools/bench.gd             # sim cost per tick
python3 tools/build_local_assets.py                           # rebuild the local-only bullet atlas
SHOT_DIR=/tmp/shots godot --path . res://tools/screenshot.tscn # every screen, the fog, a staged boss fight (needs a display; own store and account)
```

`diag_progression`, `diag_loot` and `diag_upgrades` exist because the bot smoke
test cannot cover any of them: bots are poor shots, so they rarely kill
anything, which means they neither earn levels, produce drops, nor ever reach
the quartermaster.

**Every key the game names to the player goes through `Settings.short_label()`.**
All of them are rebindable, and a prompt that names the default is wrong for
anyone who changed it — the HUD said "LMB fire" and the upgrade screen said
"Close (E)" whatever those were bound to.

**Nothing automated can see the screen.** `check.sh`, the suite and `smoke.sh`
have all passed with the entire interface rendering unstyled, an invisible
slider and an invisible scrollbar. After touching anything under `src/ui/` or
`src/view/`, run `screenshot.tscn` and open the files. It needs a display, so it
is not a gate.

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` | Connection details. |
| `--name` | Bots only: what a bot calls the character it creates. People name characters on the roster screen; the connect screen no longer asks. |
| `--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.**

There are exactly **five** client -> server messages, and that number is worth
watching:

| Message | Carries |
| --- | --- |
| `c_hello` | protocol version + an opaque auth ticket |
| `c_input` | an [InputFrame]: move vector, aim angle, five button bits, an inventory slot |
| `c_select_character` | a character id, checked against *that account's* list |
| `c_create_character` | a name, sanitised at the boundary |
| `c_choose_upgrade` | an index into the three options the SERVER put on the table |

Every one is pure intent. There is no message for "I moved here", "I hit that",
"I took damage", "my escape finished", "I now own this item", "I am in this
dungeon" or "my damage is X". 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`, `DungeonDef`, `UpgradeDef`. Shapes, not instances. |
| `src/sim/patterns/` | Bullet emitters — the authoring surface for every enemy and boss. Emitters are stateless: they are shared resources, and two bosses of the same kind must not stomp each other. |
| `src/sim/map_grid.gd` | Tile grid: collision, line of sight, chunk streaming. |
| `src/sim/map_gen.gd` | Dungeon generation. **Server-side only** — handing a client the seed would be a map hack with no work required. |
| `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/content/dungeons.gd` | The kinds of run. `Dungeons.ORDER` is both a wire format and the hub's portal order. |
| `src/content/upgrades.gd` | The seven upgrades and their draw weights. `Upgrades.ORDER` is a wire format. |
| `src/net/` | Codec, `ServerRuntime`, `ClientRuntime`. |
| `src/instances/` | Lobby hub and dungeon runs. |
| `src/view/`, `src/ui/` | Read-only rendering. Never decides anything. |
| `src/core/settings.gd` | Client-local preferences: key bindings and volumes. Never reaches the server. |
| `src/core/credits.gd` | Every third-party asset and its licence. Two are CC BY, so this is a legal requirement, not a nicety. |
| `src/view/ui_theme.gd` | The control theme, built in code from the UI pack. |
| `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. **A Control's theme is inherited from Control ANCESTORS only.** The chain
   breaks at the first parent that is a plain `Node` or a `CanvasLayer`, which
   here is every screen: they hang off `main.gd` or off a CanvasLayer. Setting
   `get_window().theme` therefore compiles, runs, changes the property — and
   styles nothing. Apply the theme to each screen's own root Control
   (`UiTheme.themed_root()`). `tests/unit/test_ui_theme.gd` instantiates every
   screen and asks what its buttons actually resolve, because this failure is
   invisible to every other kind of check.
7. **A themed `Slider` or `ScrollBar` takes its THICKNESS from the stylebox's
   minimum size**, which for a `StyleBoxTexture` is its content margins. Style
   one with margins of zero and it resolves correctly, reports the right
   texture, and draws a groove zero pixels tall — indistinguishable from having
   no theme at all. Both happened. `tests/unit/test_ui_theme.gd` asserts every
   slider and scrollbar stylebox has a non-zero minimum.
8. **`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. Upgrades multiply bullet
  speed, so `SimConfig.MAX_BULLET_SPEED` clamps the result — without it two
  Snipers put shots through walls. Pinned by
  `test_bullet_speeds_stay_below_the_tunnelling_threshold`.
- **A character becomes a live player only in `ServerRuntime._adopt_character`,
  from `_place`.** `SimWorld` knows nothing about characters and builds a blank
  player on every instance change, so any new path that puts someone in a world
  must go through `_place` or it hands them a level-1 body with an empty bag.
  Current health comes from the record too (`Character.hp`), and is banked by
  `_bank_health` wherever a player leaves a world — miss one and that door
  becomes a free heal.
- **One account, one session.** `on_hello` refuses a peer whose account is
  already playing; two live players on one character duplicate items.
- **Anything that calls `Net.host()` from a tool sets `GameOpts.store_path` and
  `GameOpts.account_override` first.** The default is the player's real store and
  account; `screenshot.tscn` once played their character into dungeons.
- **A player's combat numbers are derived, never stored.** `PlayerStats.build()`
  recomputes them from the character's upgrade ids every time, so a saved stat
  cannot disagree with the upgrades that produced it. Upgrade *riders* (split
  charges, poison, erase chance) travel on the bullet instead, because a shot
  in flight must keep what it was fired with.
- **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. `Dungeons.ORDER` is the same, and additionally
  decides which hub portal opens which dungeon (Nth `P` marker in the lobby
  stamp → Nth entry). A dungeon names the boss arena it ends in, so adding a
  boss means giving it a dungeon or nobody will ever meet it.
- **Which dungeon you enter comes from where you are standing, never from the
  client.** `SimWorld.portal_at()` resolves the player's server-side position
  to a portal, and the `PORTAL_USED` event carries the answer. There is no
  message that names a dungeon, and adding one would let any client pick the
  easy variant's loot rate.
- **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.
- **A boss never leaves its arena.** `SimWorld._step_boss` clamps to
  `SimBoss.room` *after* movement. Boss rooms deliberately do not lock, so
  walking out is always an escape — which only holds if the boss cannot follow.
- **Every actor the client draws is interpolated between snapshots.** Players,
  enemies and the boss all go through the same lerp. The boss did not for a
  long time, which is invisible while bosses stand still and looks broken the
  moment one moves.
- **The fog works by draw order, not by deciding per object.** `WorldView._draw`
  draws terrain and every actor within sight range, then the darkness from
  `Visibility` over them, then whatever must stay visible. That is what lets a
  tile or an enemy be half lit. Anything new that fog may hide goes *before*
  `_draw_darkness`; anything it must not goes after.
- **No enemy bullet may land without having been drawn first.** Bullets fade
  beyond the edge of sight, but `BulletRenderer.visibility()` stretches each
  enemy bullet's draw distance with its speed so it is always fully on screen
  `WARNING_TIME` before it could reach you. A faster bullet in new content is
  covered automatically; `test_bullet_draw.gd` fails if it is not. Never hide
  bullets by shadow alone — you can walk round a corner into one.
- **A telegraph must be visible through fog.** `WorldView._draw_telegraphs`
  is drawn after the darkness on purpose; everything else in the view is under it. A
  warning you cannot see is an unavoidable hit with extra steps.
- **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
in `ALL_ENEMIES` / `ALL_BOSSES`** (the export tool, the renderer and the tests
all iterate those), and add a test.

A boss phase can move — `BossPhase.Move` is `STATIC`, `ORBIT`, `CHASE` or
`WAYPOINTS`, handled generically in `SimWorld._move_boss`. Movement is a
property of the phase, not of the boss. `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.