claude
e0c1e0d5c6
ci / verify (push) Successful in 49s
Boss movement is a property of the PHASE, not of the boss -- a fight that
stands still and then starts hunting you is one boss with two phases. Four
modes (STATIC, ORBIT, CHASE, WAYPOINTS) handled generically in
SimWorld._move_boss, so a boss that moves is still data. BossDef.stationary
is gone rather than kept beside the phases: a flag claiming the boss stood
still while a phase walked around would be a second source of truth and the
wrong one, so moves() is derived.
CHASE holds a distance instead of closing, because a boss standing on top of
you is a boss whose bullets cannot be read. Waypoints are fractions of the
arena so one phase works in rooms of different sizes. Every mode is speed
clamped in one place -- ORBIT computes an absolute destination and would
otherwise snap onto its circle on the first tick -- and movement slides
against geometry so a boss cannot walk through the pillars its own arena was
designed around.
The room clamp moved to after movement, where it is finally load-bearing. It
was a no-op while every boss stood still, which is exactly when an invariant
is cheapest to establish: boss rooms deliberately do not lock, so walking out
is always an escape, and that only holds if the boss cannot follow.
TelegraphedStrikeEmitter marks spots and fills them a moment later. The moment
between is the feature: a burst at your feet is a coin flip, the same burst
with a second of notice is a question. It stays stateless like every other
emitter -- they are shared resources and two bosses of the same kind must not
stomp each other -- so strike positions are derived from the volley number and
a test asserts the burst lands where the marker promised. Markers are drawn
through fog and through walls, unlike everything else in the view, because a
warning you cannot see is an unavoidable hit with extra steps.
The Cantor of the Vault fights in the choir vault: static, then a four-corner
circuit, then a chase, then orbiting while marking. It exists to prove the
format stretched, and a test asserts it uses both new mechanisms.
Which boss a run has now comes from its SEED rather than its depth. Depth is a
dev flag nothing in play raises, so the arena was keyed to something no player
can change and the second boss was unreachable in an actual game.
Two things found while finishing:
- tools/export_content.gd had a hand-maintained boss list and had already
gone stale, silently not writing the Cantor. Content.ALL_ENEMIES and
ALL_BOSSES now feed the export tool, the renderer and five tests that each
kept their own copy.
- diag_loot failed intermittently after another diagnostic. Taking over from
the bot cleared its input queue but not its HELD input, so a starved server
coasted on the bot's last movement vector for half a second and walked the
player off the item it had been placed on. The press arrived correctly,
which is why "the press reached the simulation" passed while everything it
should have caused failed.
check.sh clean, 409 tests, SMOKE PASS (19 assertions), all four diagnostics
green.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
237 lines
14 KiB
Markdown
237 lines
14 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 . 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
|
|
```
|
|
|
|
`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.
|
|
|
|
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`, `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; `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/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/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. 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 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).
|
|
- **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.
|
|
- **A telegraph must be visible through fog.** `WorldView._draw_telegraphs`
|
|
ignores line of sight on purpose; everything else in the view respects 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.
|