Initial commit: Transcience MVP

Top-down twin-stick bullet-hell, Godot 4.7, server-authoritative dedicated
server with client-side prediction. Clients send input only; the server
resolves every hit for both players and enemies (no PvP).

- SimWorld: whole simulation as plain RefCounted objects (no nodes, no
  physics server), ~0.24ms/tick at peak load -- runs headless for free and
  drives 78 tests in under a second
- BulletPool: struct-of-arrays bullet storage, replicated as spawn/despawn
  events rather than per-tick state
- Emitter framework (Ring/AimedSpread/WallGap/ArcSweep) shared by trash
  enemies and bosses -- a new boss is data in src/content/content.gd, no
  simulation changes
- The Warden of the Fold: stationary 4-phase boss built entirely on that
  format
- Lobby hub with a portal into on-demand dungeon instances; one process
  hosts the hub plus every concurrent dungeon
- Emergency escape: 3s server-owned channel, cancelled by damage
- tools/check.sh, test.sh (GUT), smoke.sh (real server + bot clients over
  ENet), bench.gd; git hooks wired to the same scripts
- docs/ARCHITECTURE.md, NETCODE.md, WORKFLOW.md, ROADMAP.md

src/core/game_log.gd

@@ -0,0 +1,37 @@
+class_name GameLog
+extends RefCounted
+## Tagged logging that survives headless runs.
+##
+## Static rather than an autoload so it works from unit tests and from
+## `--script` tool runs, where autoload identifiers are not registered at all.
+## The dedicated server has no console UI, so every line carries the role that
+## produced it -- that is what makes a captured server log readable later.
+
+enum Level { DEBUG, INFO, WARN, ERROR }
+
+## Raise to WARN on a busy server; DEBUG is very chatty at 60 Hz.
+static var min_level: Level = Level.INFO
+static var role_tag: String = "?"
+
+
+static func _fmt(level: Level, tag: String, msg: String) -> String:
+	return "[%s][%s][%s] %s" % [Level.keys()[level], role_tag, tag, msg]
+
+
+static func debug(tag: String, msg: String) -> void:
+	if min_level <= Level.DEBUG:
+		print(_fmt(Level.DEBUG, tag, msg))
+
+
+static func info(tag: String, msg: String) -> void:
+	if min_level <= Level.INFO:
+		print(_fmt(Level.INFO, tag, msg))
+
+
+static func warn(tag: String, msg: String) -> void:
+	if min_level <= Level.WARN:
+		print(_fmt(Level.WARN, tag, msg))
+
+
+static func error(tag: String, msg: String) -> void:
+	printerr(_fmt(Level.ERROR, tag, msg))

src/core/game_log.gd.uid

@@ -0,0 +1 @@
+uid://dlmfc7pqn6p4s

src/core/game_opts.gd

@@ -0,0 +1,67 @@
+class_name GameOpts
+extends RefCounted
+## Process-wide options parsed from the command line.
+##
+## These are per-machine settings and must never affect the simulation -- if a
+## value would change how the world evolves, it belongs in [SimConfig] so server
+## and client cannot disagree about it.
+
+static var is_server: bool = false
+static var port: int = Protocol.DEFAULT_PORT
+static var host_address: String = "127.0.0.1"
+static var player_name: String = "player"
+## Replaces keyboard input with a scripted loop so CI can play the game with no
+## display. See `tools/smoke.sh`.
+static var bot_client: bool = false
+## Quit after this many physics ticks. 0 = run forever.
+static var autoquit_ticks: int = 0
+## Skip the menu and connect straight away. Implied by --bot.
+static var autojoin: bool = false
+## Skip the menu and start a listen server (host + local player).
+static var listen: bool = false
+## Server-side dev switch: new dungeons open straight onto the boss, skipping
+## the trash waves. For iterating on a pattern without clearing two waves first.
+static var boss_rush: bool = false
+static var parsed: bool = false
+
+
+static func parse(argv: PackedStringArray = PackedStringArray()) -> void:
+	if argv.is_empty():
+		argv = OS.get_cmdline_user_args()
+	var i := 0
+	while i < argv.size():
+		match argv[i]:
+			"--server":
+				is_server = true
+			"--bot":
+				bot_client = true
+				autojoin = true
+			"--join":
+				autojoin = true
+			"--listen":
+				listen = true
+			"--boss-rush":
+				boss_rush = true
+			"--port":
+				i += 1
+				if i < argv.size():
+					port = int(argv[i])
+			"--host":
+				i += 1
+				if i < argv.size():
+					host_address = argv[i]
+			"--name":
+				i += 1
+				if i < argv.size():
+					player_name = argv[i]
+			"--autoquit":
+				i += 1
+				if i < argv.size():
+					autoquit_ticks = int(argv[i])
+			"--verbose":
+				GameLog.min_level = GameLog.Level.DEBUG
+			"--quiet":
+				GameLog.min_level = GameLog.Level.WARN
+		i += 1
+	GameLog.role_tag = "server" if is_server else "client"
+	parsed = true

src/core/game_opts.gd.uid

@@ -0,0 +1 @@
+uid://cneth7xd6rb68

src/core/movement.gd

@@ -0,0 +1,31 @@
+class_name Movement
+extends RefCounted
+## Pure movement helpers. These run on the server (authoritative) and on the
+## client (prediction). They must stay side-effect free so a client can replay
+## them over a history of inputs and land on the same result as the server.
+
+## Clamp a raw analogue/keyboard vector to a unit disc.
+static func sanitize_move(raw: Vector2) -> Vector2:
+	if raw.length_squared() > 1.0:
+		return raw.normalized()
+	return raw
+
+
+## One tick of player locomotion. Returns the new position.
+static func step_player(pos: Vector2, move: Vector2, speed: float, bounds: Vector2) -> Vector2:
+	var next := pos + sanitize_move(move) * speed * SimConfig.TICK_DELTA
+	next.x = clampf(next.x, -bounds.x, bounds.x)
+	next.y = clampf(next.y, -bounds.y, bounds.y)
+	return next
+
+
+## Circle-vs-circle overlap test used for every hit in the game.
+static func circles_overlap(a: Vector2, ar: float, b: Vector2, br: float) -> bool:
+	var r := ar + br
+	return a.distance_squared_to(b) <= r * r
+
+
+## True when a point has drifted outside the arena plus the cull margin.
+static func outside_arena(p: Vector2, margin: float = SimConfig.BULLET_CULL_MARGIN) -> bool:
+	return absf(p.x) > SimConfig.ARENA_HALF.x + margin \
+		or absf(p.y) > SimConfig.ARENA_HALF.y + margin

src/core/movement.gd.uid

@@ -0,0 +1 @@
+uid://upjfa2xdgjct

src/core/sim_config.gd

@@ -0,0 +1,64 @@
+class_name SimConfig
+extends RefCounted
+## Tuning constants shared verbatim by the server simulation and the client
+## replica. Nothing here may differ between the two builds -- if a value needs
+## to differ, it belongs in [GameConfig], not here.
+
+# --- Time -------------------------------------------------------------------
+const TICK_RATE := 60
+const TICK_DELTA := 1.0 / 60.0
+## Server sends a snapshot every N ticks (60 / 3 = 20 Hz).
+const SNAPSHOT_INTERVAL := 3
+## How far behind the newest snapshot the client renders remote actors.
+const INTERPOLATION_DELAY_TICKS := 6
+
+# --- Arena ------------------------------------------------------------------
+const ARENA_HALF := Vector2(620.0, 340.0)
+## Bullets are culled once they leave the arena by this margin.
+const BULLET_CULL_MARGIN := 64.0
+
+# --- Player -----------------------------------------------------------------
+const PLAYER_SPEED := 240.0
+const PLAYER_RADIUS := 9.0
+const PLAYER_MAX_HP := 100
+const PLAYER_FIRE_COOLDOWN := 7          # ticks
+const PLAYER_BULLET_SPEED := 620.0
+const PLAYER_BULLET_RADIUS := 4.0
+const PLAYER_BULLET_LIFETIME := 90       # ticks
+const PLAYER_BULLET_DAMAGE := 6
+const PLAYER_IFRAMES := 36               # ticks of invulnerability after a hit
+const PLAYER_RESPAWN_DELAY := 180        # ticks
+
+# --- Anti-cheat guards ------------------------------------------------------
+## Inputs older than this (relative to the newest accepted) are discarded.
+const INPUT_MAX_AGE := 30
+## Inputs claiming to be further ahead than this of the server tick are clamped.
+const INPUT_MAX_LEAD := 12
+## Hard ceiling on inputs consumed from one peer in a single tick.
+const INPUT_MAX_PER_TICK := 4
+
+# --- Emergency escape -------------------------------------------------------
+const ESCAPE_CHANNEL_TICKS := 180        # 3 seconds
+## Taking damage while channelling cancels the escape.
+const ESCAPE_BREAK_ON_DAMAGE := true
+
+# --- Bullets ----------------------------------------------------------------
+const MAX_BULLETS := 4096
+const TEAM_PLAYER := 0
+const TEAM_ENEMY := 1
+
+# --- Bullet visual kinds (index into the renderer's atlas) ------------------
+const KIND_PLAYER_SHOT := 0
+const KIND_ORB := 1
+const KIND_NEEDLE := 2
+const KIND_HEAVY := 3
+
+# --- Instances --------------------------------------------------------------
+const LOBBY_INSTANCE_ID := 1
+const DUNGEON_PARTY_MAX := 4
+## How long a forming dungeon waits for more players before it locks.
+const DUNGEON_FORMING_TICKS := 300
+
+# --- Portal -----------------------------------------------------------------
+const PORTAL_POS := Vector2(0.0, -220.0)
+const PORTAL_RADIUS := 60.0

src/core/sim_config.gd.uid

@@ -0,0 +1 @@
+uid://msxyswmkdty1