README: translate to English, remove live URL and credentials

This commit is contained in:
danny 2026-06-14 14:36:58 +02:00
parent 933583e5bb
commit 1ae870a011

202
README.md
View file

@ -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=<name>` (GET oder POST mit JSON-Body).
All actions go through `api.php?action=<name>` (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/<dein-user>/guessTheLiar.git
git clone https://github.com/<your-username>/guessTheLiar.git
cd guessTheLiar
```
`config.php` anlegen:
Create `config.php`:
```php
<?php
return [
'host' => '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