Main Menu & End Screens

Status: Designed Author: user + game-designer Last Updated: 2026-03-28 System Index: #18 — Vertical Slice, Presentation Layer

Overview

The Main Menu is the game's entry point — display name input, connect to server, and navigate to lobby. The end screens (Victory and Game Over) display run results and offer a path back to menu or lobby. These are simple, low-complexity UI screens that bookend the gameplay loop.

Player Fantasy

Main Menu: "I'm ready to play." Clean, fast, no obstacles between opening the game and joining friends.

Victory: "We did it!" A satisfying payoff after a tense boss fight. Brief celebration before the next run.

Game Over: "So close." Acknowledges the loss without punishing. Quick path back to try again.

Detailed Design

┌──────────────────────────────────┐
│                                  │
│       CO-OP DECKBUILDER          │
│       [game title art]           │
│                                  │
│  Your Name: [__________]         │
│                                  │
│  Server: [auto / custom IP]      │
│                                  │
│  [PLAY]                          │
│                                  │
│  [SETTINGS]    [QUIT]            │
│                                  │
└──────────────────────────────────┘

Element	Behavior
Name input	Persisted locally (`user://settings.cfg`). Pre-filled on return. 1-20 characters.
Server field	Default: connects to known server address. Optional: manual IP for LAN/dev.
PLAY	Connects to server, transitions to Lobby (Join/Create screen).
SETTINGS	Opens settings overlay (V1: volume only, placeholder for more).
QUIT	Exits game (desktop). Hidden on web.

Victory Screen

┌──────────────────────────────────┐
│                                  │
│          ✦ VICTORY ✦             │
│                                  │
│   Boss Defeated!                 │
│                                  │
│   Run Stats:                     │
│   Encounters: 7                  │
│   Cards Collected: 6             │
│   Players: Alice, Bob, Charlie   │
│                                  │
│   [PLAY AGAIN]    [MAIN MENU]    │
│                                  │
└──────────────────────────────────┘

Game Over Screen

┌──────────────────────────────────┐
│                                  │
│          DEFEATED                │
│                                  │
│   Reached: Node 5 / 8           │
│                                  │
│   Run Stats:                     │
│   Encounters: 4                  │
│   Cards Collected: 3             │
│   Players: Alice, Bob            │
│                                  │
│   [TRY AGAIN]     [MAIN MENU]   │
│                                  │
└──────────────────────────────────┘

Run Stats (both screens)

Stat	Source
Encounters completed	`RunData.encounter_count`
Cards collected	`deck.size() - 10` per player (starter deck = 10)
Players	`RunData.players` display names
Reached node (Game Over)	`RunData.current_node_index` / `map.layer_count`

Button Behavior

Button	Action
PLAY AGAIN / TRY AGAIN	Return to Lobby (room stays active, same players). Host can start a new run.
MAIN MENU	Disconnect from server, return to Main Menu.

States and Transitions

MAIN_MENU → PLAY → connect to server → LOBBY
VICTORY / GAME_OVER → PLAY AGAIN → LOBBY (same room)
VICTORY / GAME_OVER → MAIN MENU → disconnect → MAIN_MENU

Interactions with Other Systems

System	Direction	Interface
Game State Manager	Receives	Transitions to Victory/GameOver state with RunData
Networking Layer	Calls	Main Menu initiates server connection. End screens can disconnect.
Lobby System	Navigates to	PLAY and PLAY AGAIN navigate to lobby
Settings System	Opens overlay	SETTINGS button (future)

Formulas

None.

Edge Cases

Case	Resolution
Empty name field	PLAY button disabled. Minimum 1 character required.
Server unreachable	Show "Cannot connect to server. Check your connection." Retry option.
PLAY AGAIN but room was closed (all others left)	Create a new room automatically. Player is host.
Web build: no QUIT button	Hide QUIT on web exports. Detected via `OS.has_feature("web")`.
Return to menu after disconnect	Clean up connection state. Fresh start.

Dependencies

Upstream

System	Dependency Type	Interface
Game State Manager	Hard	Provides RunData for end screen stats
Networking Layer	Hard	Connection management

Downstream

System	Dependency Type	Interface
Lobby System	Hard	Navigates to lobby
Settings System	Soft	Opens settings overlay (future)

Tuning Knobs

Knob	Default	Safe Range	Affects
`default_server_address`	Configurable	—	Where clients connect
`name_max_length`	20	10-30	Name display

Acceptance Criteria

#	Criterion	Verification
1	Main menu loads with name input and Play button	Visual test: launch game, assert menu elements present
2	Play connects to server and transitions to lobby	Integration test: click Play, assert connection + lobby scene
3	Name persists between sessions	Integration test: set name, quit, relaunch, assert name pre-filled
4	Victory screen shows correct run stats	Integration test: complete run, assert encounter count and player names correct
5	Game Over shows progress (node reached)	Integration test: die at node 5, assert "Reached: Node 5 / 8"
6	Play Again returns to lobby with same room	Integration test: click Play Again, assert lobby with same players
7	Main Menu disconnects and returns to title	Integration test: click Main Menu, assert disconnected + title screen
8	Server unreachable shows error	Integration test: invalid server address, assert error message