adding documentation for game modes

documentation/game_modes.md

@@ -0,0 +1,83 @@
+# Game Modes
+
+This document describes the planned game modes for lila. Each mode uses the same lobby system and vocabulary data but differs in how answers are submitted, scored, and how a winner is determined.
+
+The first multiplayer mode to implement is TBD. The lobby infrastructure (create, join, WebSocket connection) is mode-agnostic — adding a new mode means adding new game logic, not changing the lobby.
+
+---
+
+## TV Quiz Show
+
+**Type:** Multiplayer
+**Answer model:** Buzzer — first to press gets to answer
+**Rounds:** Fixed (e.g. 10)
+
+A question appears for all players. The first player to buzz in gets to answer. If correct, they score a point. If wrong, other players may get a chance to answer (TBD: whether the question passes to the next buzzer or the round ends). The host or a timer controls the pace.
+
+Key difference from other modes: only one player answers per question. Speed of reaction matters as much as knowledge.
+
+---
+
+## Race to the Top
+
+**Type:** Multiplayer
+**Answer model:** Simultaneous — all players answer independently
+**Rounds:** None — play until target score reached
+
+All players see the same question and answer independently. No fixed round count. The first player to reach a target number of correct answers wins (e.g. 20). Fast-paced and competitive.
+
+Open questions: what happens if two players hit the target on the same question? Tiebreaker by speed? Shared win?
+
+---
+
+## Chain Link
+
+**Type:** Multiplayer
+**Answer model:** Turn-based — one player at a time, in rotation
+**Rounds:** None — play until a player fails
+
+Players answer in a fixed rotation: Player 1, Player 2, Player 3, then back to Player 1. Each player gets one question per turn. The game continues until a player answers incorrectly — that player is out (or the game ends). Last correct answerer wins, or the game simply ends on the first wrong answer.
+
+Key difference from other modes: turn-based, not simultaneous. Pressure builds as you wait for your turn.
+
+Open questions: does the player who answers wrong lose, or does the game just end? If the game continues, does it become elimination?
+
+---
+
+## Elimination Round
+
+**Type:** Multiplayer
+**Answer model:** Simultaneous — all players answer independently
+**Rounds:** Continue until one player remains
+
+All players see the same question and answer simultaneously. Players who answer incorrectly are eliminated. Rounds continue until only one player is left standing.
+
+Open questions: what if everyone gets it wrong in the same round? Reset that round? Eliminate nobody? What if it comes down to two players and both get it wrong repeatedly?
+
+---
+
+## Cooperative Challenge
+
+**Type:** Multiplayer
+**Answer model:** TBD
+**Rounds:** TBD
+
+Players work together rather than competing. Concept not yet defined. Possible ideas: shared team score with a target, each player contributes answers to a collective pool, or players take turns and the team survives as long as the chain doesn't break.
+
+---
+
+## Single Player Extended
+
+**Type:** Singleplayer
+**Answer model:** TBD
+**Rounds:** TBD
+
+An expanded version of the current singleplayer quiz. Concept not yet defined. Possible ideas: longer sessions with increasing difficulty, mixed POS/language rounds, streak bonuses, progress tracking across sessions, or timed challenge mode.
+
+---
+
+## Schema Impact
+
+The `lobbies` table includes a `game_mode` column (varchar) with values like `tv_quiz`, `race_to_top`, `chain_link`, `elimination`. Mode-specific settings (e.g. target score for Race to the Top) can be stored in a `settings` jsonb column if needed.
+
+The singleplayer modes (Single Player Extended) don't require a lobby — they extend the existing singleplayer flow.