diff --git a/README.md b/README.md index 799b283..d0e82fd 100644 --- a/README.md +++ b/README.md @@ -1,181 +1,179 @@ # 🐑 Black Sheep Bluff -> *Imposters bekommen eine andere Frage. Findet sie!* +> *Imposters get a different question. Find them!* -Ein browserbasiertes Multiplayer-Party-Spiel für 3–15+ Spieler. Der Host stellt allen Spielern eine Frage — die **Imposters** bekommen heimlich eine andere. Wer fällt auf? Wer bleibt unentdeckt? - -**Live:** [guess.appform.de](https://guess.appform.de) +A browser-based multiplayer party game for 3–15+ players. The host asks everyone a question — but **Imposters** secretly receive a different one. Who blends in? Who slips up? --- -## Spielprinzip +## How to Play -1. Der Host eröffnet einen Raum und legt eine normale Frage sowie eine Imposter-Frage fest -2. Alle Spieler tippen ihre Antwort — Imposters haben eine abweichende Frage und müssen das verbergen -3. Der Host deckt die Antworten schrittweise oder auf einmal auf -4. Die Gruppe diskutiert und votet: Wer ist das schwarze Schaf? -5. Punkte gibt es für Innocents die den Imposter entlarven — und für Imposters die unentdeckt bleiben +1. The host opens a room and sets a normal question plus a separate imposter question +2. Every player types their answer — imposters have a different question and must hide it +3. The host reveals answers one by one or all at once +4. The group discusses and votes: who is the black sheep? +5. Innocents score a point for catching the imposter — imposters score for surviving undetected --- ## Features ### Gameplay -- **Gezieltes Aufdecken** — Host klickt einzelne Antwortkarten auf, um die Spannung zu steuern -- **Mehrfach-Votes** — Spieler können mehrere Verdächtige wählen oder explizit für „Niemand" stimmen -- **Demokratischer Voting-Start** — Spieler können das Voting gemeinsam beantragen (alle müssen zustimmen → öffnet automatisch) -- **Auto-Auswertung** — Sobald alle Spieler abgestimmt haben, wertet der Server automatisch aus -- **Imposter-Gewichte** — Host konfiguriert per JSON wie viele Imposters je nach Spieleranzahl gewählt werden (`{"3-5":1,"6-9":2,"10+":3}`) -- **Rundenhistorie** — Alle vergangenen Runden mit Fragen, Antworten und Ergebnis einsehbar +- **Targeted reveal** — the host clicks individual answer cards to control the pace of tension +- **Multi-vote** — players can vote for multiple suspects or explicitly choose "Nobody" +- **Democratic voting start** — players can collectively request the vote (everyone must agree → opens automatically) +- **Auto-resolution** — once all players have locked in their votes the server resolves the round automatically +- **Imposter weights** — host configures via JSON how many imposters to assign based on player count (`{"3-5":1,"6-9":2,"10+":3}`) +- **Round history** — all past rounds with questions, answers and outcomes are viewable in an accordion -### Live-Features -- **Live-Stimmentally** — Spieler sehen nach ihrem Vote in Echtzeit, wie viele Stimmen jeder hat -- **Animiertes Doughnut-Diagramm** — Chart.js visualisiert die Stimmverteilung live (Player- und Host-Ansicht) -- **Live-Emoji-Reaktionen** — 🐑 🔥 😂 👍 schweben animiert über dem Spielfeld (4 Sekunden TTL) -- **Lobby-Chat** — Integrierter Chat für alle Spieler und den Host -- **Polling alle 1,5 Sekunden** — Zustandsänderungen werden ohne Seitenreload übertragen +### Live Features +- **Live vote tally** — after locking their vote, players see real-time vote counts for every player +- **Animated doughnut chart** — Chart.js visualises the vote distribution live in both the player and host views +- **Live emoji reactions** — 🐑 🔥 😂 👍 float across the screen with a 4-second TTL +- **Lobby chat** — built-in chat for all players and the host +- **1.5-second polling** — state changes propagate without any page reload -### Host-Steuerung -- Imposter-Auswahl manuell oder per Zufalls-Button (mit konfigurierbaren Gewichten) -- Imposter-Auswahl wird während aktiver Runden automatisch gesperrt -- Manuelle Punktekorrektur (+/−) pro Spieler -- Spieler aus der Lobby entfernen -- Lobby löschen +### Host Controls +- Manual or randomised imposter selection (with configurable weights) +- Imposter selection is automatically locked once a round is active +- Manual score correction (+/−) per player +- Kick players from the lobby +- Delete the room -### Accounts & Profile -- Registrierung mit PIN (4–8 Ziffern) oder Admin-Passwort -- Persistente Spielerprofile mit Lifetime-Statistiken -- Avatar-Upload -- F5-Reconnect: Browser-Session wird wiederhergestellt, kein erneutes Einloggen nötig +### Accounts & Profiles +- Registration with a 4–8 digit PIN or an admin password +- Persistent player profiles with lifetime statistics +- Avatar upload +- F5 reconnect — browser session is restored automatically, no re-login needed --- ## Tech Stack -| Schicht | Technologie | +| Layer | Technology | |---|---| -| Backend | PHP 8, PDO/MySQL, native Sessions | +| Backend | PHP 8, PDO/MySQL, native sessions | | Frontend | Vanilla JS, CSS Grid, CSS Custom Properties | -| Datenbank | MySQL 8 mit automatischem Migrations-System | -| Diagramme | [Chart.js 4.4.4](https://www.chartjs.org/) | -| Schrift | Inter (Google Fonts) | +| Database | MySQL 8 with an automatic migration system | +| Charts | [Chart.js 4.4.4](https://www.chartjs.org/) | +| Font | Inter (Google Fonts) | -Kein Frontend-Framework, kein Build-Step — alles läuft direkt im Browser. +No frontend framework, no build step — everything runs directly in the browser. --- -## Projektstruktur +## Project Structure ``` guessTheLiar/ -├── index.html # Gesamtes Frontend (Lobby, Spieler- & Host-Ansicht) -├── api.php # REST-API für alle Spielaktionen -├── auth.php # Login, Session, PIN-Verwaltung -├── migrate.php # Automatisches DB-Migrations-System (V1–V8) -├── login.php # Login-Seite -├── profile.php # Spielerprofil & Statistiken -├── admin.php # Admin-Panel (Benutzerverwaltung) -├── config.php # DB-Zugangsdaten (nicht im Repo) -├── schema.sql # Initiales DB-Schema -└── identity/ # Logo & Favicon (PNG + PSD) +├── index.html # Entire frontend (lobby, player view, host view) +├── api.php # REST API for all game actions +├── auth.php # Login, session management, PIN handling +├── migrate.php # Automatic DB migration system (V1–V8) +├── login.php # Login page +├── profile.php # Player profile & lifetime statistics +├── admin.php # Admin panel (user management) +├── config.php # DB credentials (not in repo — see setup below) +├── schema.sql # Initial DB schema reference +└── identity/ # Logo & favicon (PNG + PSD) ``` --- -## Datenbank-Schema +## Database Schema -Das Migrations-System läuft automatisch beim ersten Request — kein manuelles Setup nötig. +The migration system runs automatically on first request — no manual setup required. -| Tabelle | Inhalt | +| Table | Contents | |---|---| -| `gtl_rooms` | Räume mit Fragen, Voting-Zustand, Reveal-Tracking, Emojis | -| `gtl_players` | Spieler pro Raum mit Antwort, Vote, Score | -| `gtl_users` | Registrierte Accounts (Username, PIN-Hash, Avatar, Rolle) | -| `gtl_user_stats` | Lifetime-Statistiken (Spiele, Siege, Imposter-Runs) | -| `gtl_game_rounds` | Archiv aller Runden | -| `gtl_round_players` | Spieler-Snapshots pro Runde (Frage, Antwort, war Imposter?) | -| `gtl_chat_messages` | Lobby-Chat (max. 200 Nachrichten pro Raum) | +| `gtl_rooms` | Rooms with questions, voting state, reveal tracking, active emojis | +| `gtl_players` | Players per room with answer, vote, score | +| `gtl_users` | Registered accounts (username, PIN hash, avatar, role) | +| `gtl_user_stats` | Lifetime stats (games played, wins, imposter runs) | +| `gtl_game_rounds` | Archive of all completed rounds | +| `gtl_round_players` | Per-player snapshot per round (question, answer, was imposter?) | +| `gtl_chat_messages` | Lobby chat (max. 200 messages per room) | --- -## API-Übersicht +## API Reference -Alle Aktionen laufen über `api.php?action=` (GET oder POST mit JSON-Body). +All actions go through `api.php?action=` (GET or POST with a JSON body). -| Action | Beschreibung | +| Action | Description | |---|---| -| `host_open` | Raum erstellen oder betreten | -| `player_join` | Als Spieler beitreten | -| `state` | Raumzustand abrufen (Polling) | -| `assign_questions` | Fragen verteilen & Imposters festlegen | -| `submit_answer` | Antwort abschicken | -| `reveal_answer` | Einzelne Antwort gezielt aufdecken | -| `reveal` | Alle Antworten aufdecken | -| `request_voting` | Demokratisch Voting beantragen | -| `open_voting` | Voting manuell öffnen (Host) | -| `lock_vote` | Stimme final abschicken | -| `resolve_round` | Runde manuell auswerten | -| `new_round` | Neue Runde starten | -| `send_emoji` | Emoji-Reaktion senden | -| `send_chat` | Chat-Nachricht senden | -| `score` | Punkte manuell korrigieren | -| `update_weights` | Imposter-Gewichte speichern | -| `get_host_history` | Rundenhistorie abrufen | -| `delete_room` | Lobby löschen | +| `host_open` | Create or re-enter a room | +| `player_join` | Join as a player | +| `state` | Fetch current room state (polling) | +| `assign_questions` | Distribute questions and assign imposters | +| `submit_answer` | Submit an answer | +| `reveal_answer` | Reveal a single player's answer | +| `reveal` | Reveal all answers at once | +| `request_voting` | Democratically request voting | +| `open_voting` | Open voting manually (host) | +| `lock_vote` | Submit final vote | +| `resolve_round` | Resolve the round manually | +| `new_round` | Start a new round | +| `send_emoji` | Send an emoji reaction | +| `send_chat` | Send a chat message | +| `score` | Manually adjust a player's score | +| `update_weights` | Save imposter weights | +| `get_host_history` | Fetch round history | +| `delete_room` | Delete the lobby | -**Sicherheits-Feature:** `liarKeys` (welche Spieler Imposters sind) wird im API-Response auf `[]` gesetzt, solange die Runde noch nicht ausgewertet ist — kein Client kann Imposters vorab im Netzwerktraffic lesen. +**Security note:** `liarKeys` (which players are imposters) is always returned as `[]` until `round_outcome` is set — no client can read imposter identities from network traffic before the round resolves. --- -## Installation (Self-Hosting) +## Self-Hosting -**Voraussetzungen:** PHP 8.1+, MySQL 8+, Webserver (Apache/Nginx) +**Requirements:** PHP 8.1+, MySQL 8+, web server (Apache or Nginx) ```bash -git clone https://github.com//guessTheLiar.git +git clone https://github.com//guessTheLiar.git cd guessTheLiar ``` -`config.php` anlegen: +Create `config.php`: ```php 'localhost', - 'dbname' => 'blacksheepbluff', - 'user' => 'dein_db_user', - 'pass' => 'dein_db_passwort', + 'dbname' => 'your_database', + 'user' => 'your_db_user', + 'pass' => 'your_db_password', 'charset' => 'utf8mb4', ]; ``` -Datenbank anlegen: +Create the database: ```sql -CREATE DATABASE blacksheepbluff CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +CREATE DATABASE your_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` -Das Migrations-System erstellt alle Tabellen automatisch beim ersten Aufruf von `index.html`. +All tables are created automatically by the migration system on the first page load. --- -## Voting-Regeln +## Voting Rules -| Situation | Ergebnis | +| Situation | Result | |---|---| -| Nur „Niemand" hat die meisten Stimmen | Niemand fliegt raus | -| Tie zwischen Niemand und einem Imposter | Imposter fliegt raus | -| Tie zwischen Niemand und einem Innocent | Niemand (Tie geht an Niemand) | -| Tie zwischen echten Spielern | Alle Tied fliegen raus | -| Alle Imposters rausgewählt | Innocents gewinnen (+1 Punkt) | -| Mind. ein Imposter überlebt | Imposter(s) gewinnen (+1 Punkt) | +| Only "Nobody" has the most votes | Nobody is eliminated | +| Tie between Nobody and an imposter | Imposter is eliminated | +| Tie between Nobody and an innocent | Nobody wins the tie — innocent survives | +| Tie between real players only | All tied players are eliminated | +| All imposters eliminated | Innocents win (+1 point each) | +| At least one imposter survives | Surviving imposter(s) win (+1 point each) | --- ## Screenshots -*Lobby → Spieler-Ansicht → Voting → Auswertung* +*Lobby → Player view → Voting → Resolution* --- -## Lizenz +## License MIT