diff --git a/README.md b/README.md new file mode 100644 index 0000000..799b283 --- /dev/null +++ b/README.md @@ -0,0 +1,181 @@ +# 🐑 Black Sheep Bluff + +> *Imposters bekommen eine andere Frage. Findet sie!* + +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) + +--- + +## Spielprinzip + +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 + +--- + +## 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 + +### 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 + +### 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 + +### 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 + +--- + +## Tech Stack + +| Schicht | Technologie | +|---|---| +| 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) | + +Kein Frontend-Framework, kein Build-Step — alles lĂ€uft direkt im Browser. + +--- + +## Projektstruktur + +``` +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) +``` + +--- + +## Datenbank-Schema + +Das Migrations-System lĂ€uft automatisch beim ersten Request — kein manuelles Setup nötig. + +| Tabelle | Inhalt | +|---|---| +| `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) | + +--- + +## API-Übersicht + +Alle Aktionen laufen ĂŒber `api.php?action=` (GET oder POST mit JSON-Body). + +| Action | Beschreibung | +|---|---| +| `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 | + +**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. + +--- + +## Installation (Self-Hosting) + +**Voraussetzungen:** PHP 8.1+, MySQL 8+, Webserver (Apache/Nginx) + +```bash +git clone https://github.com//guessTheLiar.git +cd guessTheLiar +``` + +`config.php` anlegen: +```php + 'localhost', + 'dbname' => 'blacksheepbluff', + 'user' => 'dein_db_user', + 'pass' => 'dein_db_passwort', + 'charset' => 'utf8mb4', +]; +``` + +Datenbank anlegen: +```sql +CREATE DATABASE blacksheepbluff CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +``` + +Das Migrations-System erstellt alle Tabellen automatisch beim ersten Aufruf von `index.html`. + +--- + +## Voting-Regeln + +| Situation | Ergebnis | +|---|---| +| 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) | + +--- + +## Screenshots + +*Lobby → Spieler-Ansicht → Voting → Auswertung* + +--- + +## Lizenz + +MIT