black-sheep-bluff/README.md
2026-06-14 14:19:37 +02:00

181 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🐑 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=<name>` (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/<dein-user>/guessTheLiar.git
cd guessTheLiar
```
`config.php` anlegen:
```php
<?php
return [
'host' => '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