client/overview/structure.md

Project Structure

File Tree

spacewar/                        ← repo root
└── spacewar/                    ← Godot project root (open this in Godot editor)
    ├── project.godot
    ├── autoload/
    │   └── game_config.gd        ← autoload singleton (tuning values, player state, signals)
    ├── menu/
    │   ├── main_menu.tscn/gd     ← entry point / main scene; HL2-style vertical nav
    │   ├── server_select.tscn/gd ← server list UI, backed by matchmaking-api's GET /servers
    │   ├── pause_menu.tscn/gd    ← in-game pause overlay (ESC / Start button)
    │   └── team_select.tscn/gd   ← race + ship selection overlay (shown on world load)
    ├── ships/
    │   ├── ship.tscn             ← player ship scene (formerly node_2d.tscn)
    │   ├── ship_movement.gd      ← player ship logic
    │   └── bullet.tscn/gd        ← projectile
    ├── chat/
    │   └── chat_box.tscn/gd      ← WoW-style chat overlay (T=all, Y=team), added to world.tscn
    ├── hud/
    │   └── player_list.tscn/gd   ← top-left player roster (white=team, yellow=enemy, "(b)"=bot), added to world.tscn
    ├── bots/
    │   ├── bot_manager.gd         ← autoload; server-only bot fill (join/leave reconciliation)
    │   ├── bot_ai.gd              ← class_name BotAI; seek-nearest-enemy-and-shoot brain
    │   └── bot_names.gd           ← class_name BotNames; procedural callsign pool
    ├── world/
    │   ├── world.tscn             ← game world; world.gd loads the active map into MapContainer
    │   ├── world.gd                ← picks/instances a map scene from world/maps/
    │   ├── world_tileset.tres      ← shared TileSet resource (walls.png + asteroids.png atlas sources)
    │   └── maps/
    │       └── map_01.tscn         ← hand-painted map: Walls + Asteroids TileMapLayers, team spawn Marker2Ds
    └── assets/
        ├── icon.svg
        └── images/
            ├── background/skybox/     ← 6 space background PNGs (1.png – 6.png)
            ├── effects/                ← explosion1.png
            ├── ships/example_ships/   ← 4 placeholder ship sprites (1.png, 1B.png, 2a.png, 3b.png)
            └── tiles/                  ← walls.png, asteroids.png, used by world_tileset.tres

Note: asteroid_movement.gd referenced in an earlier version of this doc does not exist yet — it's still an open task (see CLAUDE.md).

Scene Graph

menu/main_menu.tscn — entry point

MainMenu (Control)   ← main_menu.gd builds all UI in _ready()

menu/server_select.tscn — server list

ServerSelect (Control)   ← server_select.gd builds all UI in _ready(), fetches GET /servers

world/world.tscn — game world

World (Node2D)              ← world.gd instances MAP_SCENE into MapContainer on _ready()
├── MapContainer (Node2D)    ← holds the instanced map (world/maps/map_01.tscn), background included
├── Player                   ← instance of ships/ship.tscn
├── HUD (CanvasLayer)
│   └── HealthLabel
├── PauseMenu (CanvasLayer, layer=10)   ← menu/pause_menu.tscn
├── TeamSelect (CanvasLayer, layer=20)  ← menu/team_select.tscn; queue_free()s after selection
├── ChatBox (CanvasLayer, layer=5)      ← chat/chat_box.tscn
└── PlayerList (CanvasLayer, layer=4)   ← hud/player_list.tscn

world/maps/map_01.tscn — hand-painted map

Map01 (Node2D)
├── Background (TextureRect)     ← per-map space background (skybox/1.png); visible while editing this scene
├── Walls (TileMapLayer)         ← painted by hand in the Godot Tile Editor, uses world_tileset.tres
├── Asteroids (TileMapLayer)     ← painted by hand, same shared tileset
└── SpawnPoints (Node2D)
    ├── TeamASpawn1 (Marker2D)   ← group "team_a_spawn"
    └── TeamBSpawn1 (Marker2D)   ← group "team_b_spawn"

ships/ship.tscn — player ship

Player (CharacterBody2D)   ← ship_movement.gd
├── CollisionShape2D        ← CircleShape2D
├── Sprite2D                ← texture set at runtime from GameConfig.player_ship_path
└── VisibleOnScreenNotifier2D

Input Map

Action	Key	Controller
move_up	W	—
move_left	A	—
move_right	D	—
move_down	S	—
shoot	Space	—
toggle_pause	Esc	Start / Options button (JoyButton 6)
chat_all	T	—
chat_team	Y	—

Game Flow

main_menu.tscn
  ├── QUICK PLAY → matchmaking queue (casual) → world.tscn
  │     ├── TeamSelect overlay: pick race (both offered every match)
  │     ├── TeamSelect overlay: pick ship
  │     └── Player spawns → game live
  ├── SERVER SELECT → server_select.tscn → pick a server → world.tscn (same TeamSelect flow)
  ├── OPTIONS → stub, coming soon
  ├── PROFILE → callsign-edit overlay (also auto-opens from QUICK PLAY if no callsign is set)
  └── QUIT

Ranked matchmaking is removed from the menu entirely (not just disabled) until it's real — see CLAUDE.md Current Tasks.

Display

Launches borderless fullscreen at the real screen resolution (window/size/mode=3 in project.godot) with stretch mode disabled — 1 game pixel = 1 screen pixel everywhere, no UI/world scaling. Chosen over Godot's default canvas_items+expand stretch (which scales the whole 2D canvas to fill the window) because the game's design canvas is deliberately sized to the Steam Deck's native 1280×800; scaling that up to fill a PC monitor made everything look zoomed in. With stretch disabled, PC monitors just reveal more of the world/HUD at native size instead — the actual map (world/maps/map_01.tscn) is already a fixed-size 14016×6000 arena, not viewport-sized, so there's more world to reveal.

This means every menu Control has to position itself relative to the real window size, not a fixed 1280×800 design canvas — anchors (0.0=edge, 0.5=center, 1.0=opposite edge) plus fixed pixel offsets from that anchor, not raw absolute pixel coordinates. main_menu.gd and team_select.gd both have a _place()/direct-property-assignment helper for this — always set anchor properties directly (node.anchor_left = ...) rather than through sequential set_anchor_and_offset() calls: that method's default push_opposite_anchor=true drags the opposite side's anchor/offset along whenever two sequential calls momentarily disagree (e.g. left set to a 0.5 anchor while right is still its 0.0 default), corrupting layout — hit this exact bug converting the play-mode buttons to be centered.

Key Autoload — GameConfig

Property	Type	Set by
player_name	String	Main menu callsign input
player_race	int	TeamSelect race pick
player_ship_path	String	TeamSelect ship pick
team_selected	signal	Emitted by TeamSelect when done
ship_thrust	float	Tuning constant
ship_max_speed	float	Tuning constant
ship_rotation_speed	float	Tuning constant
ship_fire_rate	float	Tuning constant
bullet_speed	float	Tuning constant
ship_max_health	int	Tuning constant
ship_respawn_delay	float	Tuning constant
ship_invincibility_time	float	Tuning constant
bullet_damage	int	Tuning constant
ship_wall_damage	int	Tuning constant
chat_focused	bool	Set by ChatBox while its input line has keyboard focus; gates ship movement/fire input
bot_min_team_size	int	Tuning constant — min humans+bots per race, see bots/bot_manager.gd
bot_engage_range	float	Tuning constant — bot max shoot distance
bot_stop_distance	float	Tuning constant — bot stops closing distance below this
bot_aim_tolerance_deg	float	Tuning constant — how precisely a bot must face a target to fire

Key Autoload — BotManager

Server-authoritative bot fill for casual (bots/bot_manager.gd). Keeps each of the match's 2 offered races at GameConfig.bot_min_team_size total humans+bots, reacting to PlayerRegistry.loadout_updated/player_removed and World.decide_offered_races(). See overview/bots.md.

Key Autoload — ChatManager

Server-relayed chat (autoload/chat_manager.gd). send_chat(text, team_only) sends; message_received(sender_name, sender_race, team_only, text) signal delivers incoming messages to ChatBox. "Team" messages are filtered server-side to peers sharing the sender's race (race doubles as team — see PlayerRegistry).