transcience/docs/ARCHITECTURE.md

Architecture

The shape

				 ┌──────────────────────────────────────────┐
				 │  src/sim/  -- plain RefCounted objects    │
   authoritative │  SimWorld, SimPlayer, SimEnemy, SimBoss,  │ replica
   (server)      │  BulletPool, emitters                     │ (client)
				 │  no nodes · no physics · no rendering     │
				 └───────────────┬──────────────────────────┘
								 │
		┌────────────────────────┼────────────────────────┐
		│                        │                        │
┌───────▼────────┐      ┌────────▼────────┐      ┌────────▼────────┐
│ src/instances/ │      │    src/net/     │      │  src/view/ ui/  │
│ lobby, dungeon │      │ codec, server & │      │ read-only draw  │
│ progression    │      │ client runtimes │      │                 │
└────────────────┘      └────────┬────────┘      └─────────────────┘
								 │
						┌────────▼────────┐
						│ src/autoload/   │
						│ net.gd (RPC)    │
						└─────────────────┘

Dependencies point inwards only. src/sim/ imports nothing from net, view, ui or instances, and never touches the Net autoload. That is what makes the simulation runnable in a unit test, in a headless server and inside a client without a single conditional.

Why the simulation is not made of nodes

Godot's instinct is CharacterBody2D + Area2D + MultiplayerSynchronizer. This project deliberately does not, for four reasons:

1. Bullet count. Hundreds of live bullets. A node and an Area2D each would cost more than the entire simulation does. BulletPool is parallel packed arrays; a tick over ~350 bullets costs 0.24 ms including AI and hit checks.
2. Headless cost. The dedicated server allocates no nodes and touches no physics server.
3. Testability. A SimWorld is SimWorld.new(). The suite drives thousands of ticks in ~2 s with no SceneTree, no awaits and no frame timing.
4. Replication control. MultiplayerSynchronizer is excellent for prototyping and wrong for this shape: it would replicate per-bullet state and saturate the link. See NETCODE.md.

The trade is that there is no physics engine — no arbitrary collision shapes, no tilemap collision. The arena is a rectangle and every hit is circle-vs-circle. For a bullet hell that is not a limitation; hitboxes in the genre are circles by convention anyway. A dungeon with real geometry would need a static collision representation added to SimWorld, not a switch back to nodes.

Tick

Everything runs on Godot's physics tick, pinned to 60 Hz in src/main.gd (asserted in code, because project.godot drops settings equal to the engine default). SimConfig holds every constant both sides must agree on; per-machine options live in GameOpts and must never affect the simulation.

Content pipeline

BulletEmitter (Resource, abstract)
├── RingEmitter          count, arc, spin per shot   -> rings and spirals
├── AimedSpreadEmitter   fan at nearest player       -> punishes standing still
├── WallGapEmitter       curtain with a sliding gap  -> forces a committed dodge
└── ArcSweepEmitter      rotating arms               -> forces tracking

EnemyDef  = stats + movement enum + emitters
BossPhase = hp threshold + telegraph + looping timeline of emitters
BossDef   = stats + ordered phases

SimWorld._run_emitters() is shared by enemies and bosses, so any pattern can be dropped on either. A boss is four phases layering one idea at a time; a new boss is a new function in src/content/content.gd and zero simulation changes.

Entry point

One executable, one src/main.tscn. GameOpts.parse() reads the command line after --:

• --server → ServerRuntime, no view, max_fps pinned to the tick rate.
• --join / --bot → connect immediately, skipping the menu.
• otherwise → the connect menu, which can also start a listen server.

File map

File	Role
src/core/sim_config.gd	Every constant server and client must agree on.
src/core/movement.gd	Pure movement + overlap helpers. Shared by prediction.
src/core/game_log.gd, game_opts.gd	Static; usable from tools and tests.
src/sim/sim_world.gd	The simulation. Authority flag decides what runs.
src/sim/bullet_pool.gd	Struct-of-arrays bullet storage and integration.
src/sim/input_frame.gd	The only thing a client may assert about itself.
src/net/net_codec.gd	Snapshot / event / input binary codecs.
src/net/server_runtime.gd	Instances, ticking, transfers, broadcast.
src/net/client_runtime.gd	Prediction, reconciliation, interpolation, bot input.
src/instances/instance.gd	Lobby hub and dungeon progression.
src/autoload/net.gd	ENet lifecycle, RPCs, local loopback for listen servers.
src/view/bullet_renderer.gd	The whole bullet field in one MultiMesh draw call.