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 # 🐑 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? 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?
**Live:** [guess.appform.de](https://guess.appform.de)
--- ---
## Spielprinzip ## How to Play
1. Der Host eröffnet einen Raum und legt eine normale Frage sowie eine Imposter-Frage fest 1. The host opens a room and sets a normal question plus a separate imposter question
2. Alle Spieler tippen ihre Antwort — Imposters haben eine abweichende Frage und müssen das verbergen 2. Every player types their answer — imposters have a different question and must hide it
3. Der Host deckt die Antworten schrittweise oder auf einmal auf 3. The host reveals answers one by one or all at once
4. Die Gruppe diskutiert und votet: Wer ist das schwarze Schaf? 4. The group discusses and votes: who is the black sheep?
5. Punkte gibt es für Innocents die den Imposter entlarven — und für Imposters die unentdeckt bleiben 5. Innocents score a point for catching the imposter — imposters score for surviving undetected
--- ---
## Features ## Features
### Gameplay ### Gameplay
- **Gezieltes Aufdecken** — Host klickt einzelne Antwortkarten auf, um die Spannung zu steuern - **Targeted reveal** — the host clicks individual answer cards to control the pace of tension
- **Mehrfach-Votes** — Spieler können mehrere Verdächtige wählen oder explizit für „Niemand" stimmen - **Multi-vote** — players can vote for multiple suspects or explicitly choose "Nobody"
- **Demokratischer Voting-Start** — Spieler können das Voting gemeinsam beantragen (alle müssen zustimmen → öffnet automatisch) - **Democratic voting start** — players can collectively request the vote (everyone must agree → opens automatically)
- **Auto-Auswertung** — Sobald alle Spieler abgestimmt haben, wertet der Server automatisch aus - **Auto-resolution** — once all players have locked in their votes the server resolves the round automatically
- **Imposter-Gewichte** — Host konfiguriert per JSON wie viele Imposters je nach Spieleranzahl gewählt werden (`{"3-5":1,"6-9":2,"10+":3}`) - **Imposter weights** — host configures via JSON how many imposters to assign based on player count (`{"3-5":1,"6-9":2,"10+":3}`)
- **Rundenhistorie** — Alle vergangenen Runden mit Fragen, Antworten und Ergebnis einsehbar - **Round history** — all past rounds with questions, answers and outcomes are viewable in an accordion
### Live-Features ### Live Features
- **Live-Stimmentally** — Spieler sehen nach ihrem Vote in Echtzeit, wie viele Stimmen jeder hat - **Live vote tally** — after locking their vote, players see real-time vote counts for every player
- **Animiertes Doughnut-Diagramm** — Chart.js visualisiert die Stimmverteilung live (Player- und Host-Ansicht) - **Animated doughnut chart** — Chart.js visualises the vote distribution live in both the player and host views
- **Live-Emoji-Reaktionen** — 🐑 🔥 😂 👍 schweben animiert über dem Spielfeld (4 Sekunden TTL) - **Live emoji reactions** — 🐑 🔥 😂 👍 float across the screen with a 4-second TTL
- **Lobby-Chat** — Integrierter Chat für alle Spieler und den Host - **Lobby chat** — built-in chat for all players and the host
- **Polling alle 1,5 Sekunden** — Zustandsänderungen werden ohne Seitenreload übertragen - **1.5-second polling** — state changes propagate without any page reload
### Host-Steuerung ### Host Controls
- Imposter-Auswahl manuell oder per Zufalls-Button (mit konfigurierbaren Gewichten) - Manual or randomised imposter selection (with configurable weights)
- Imposter-Auswahl wird während aktiver Runden automatisch gesperrt - Imposter selection is automatically locked once a round is active
- Manuelle Punktekorrektur (+/−) pro Spieler - Manual score correction (+/−) per player
- Spieler aus der Lobby entfernen - Kick players from the lobby
- Lobby löschen - Delete the room
### Accounts & Profile ### Accounts & Profiles
- Registrierung mit PIN (4–8 Ziffern) oder Admin-Passwort - Registration with a 4–8 digit PIN or an admin password
- Persistente Spielerprofile mit Lifetime-Statistiken - Persistent player profiles with lifetime statistics
- Avatar-Upload - Avatar upload
- F5-Reconnect: Browser-Session wird wiederhergestellt, kein erneutes Einloggen nötig - F5 reconnect — browser session is restored automatically, no re-login needed
--- ---
## Tech Stack ## 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 | | Frontend | Vanilla JS, CSS Grid, CSS Custom Properties |
| Datenbank | MySQL 8 mit automatischem Migrations-System | | Database | MySQL 8 with an automatic migration system |
| Diagramme | [Chart.js 4.4.4](https://www.chartjs.org/) | | Charts | [Chart.js 4.4.4](https://www.chartjs.org/) |
| Schrift | Inter (Google Fonts) | | 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/ guessTheLiar/
├── index.html # Gesamtes Frontend (Lobby, Spieler- & Host-Ansicht) ├── index.html # Entire frontend (lobby, player view, host view)
├── api.php # REST-API für alle Spielaktionen ├── api.php # REST API for all game actions
├── auth.php # Login, Session, PIN-Verwaltung ├── auth.php # Login, session management, PIN handling
├── migrate.php # Automatisches DB-Migrations-System (V1–V8) ├── migrate.php # Automatic DB migration system (V1–V8)
├── login.php # Login-Seite ├── login.php # Login page
├── profile.php # Spielerprofil & Statistiken ├── profile.php # Player profile & lifetime statistics
├── admin.php # Admin-Panel (Benutzerverwaltung) ├── admin.php # Admin panel (user management)
├── config.php # DB-Zugangsdaten (nicht im Repo) ├── config.php # DB credentials (not in repo — see setup below)
├── schema.sql # Initiales DB-Schema ├── schema.sql # Initial DB schema reference
└── identity/ # Logo & Favicon (PNG + PSD) └── 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_rooms` | Rooms with questions, voting state, reveal tracking, active emojis |
| `gtl_players` | Spieler pro Raum mit Antwort, Vote, Score | | `gtl_players` | Players per room with answer, vote, score |
| `gtl_users` | Registrierte Accounts (Username, PIN-Hash, Avatar, Rolle) | | `gtl_users` | Registered accounts (username, PIN hash, avatar, role) |
| `gtl_user_stats` | Lifetime-Statistiken (Spiele, Siege, Imposter-Runs) | | `gtl_user_stats` | Lifetime stats (games played, wins, imposter runs) |
| `gtl_game_rounds` | Archiv aller Runden | | `gtl_game_rounds` | Archive of all completed rounds |
| `gtl_round_players` | Spieler-Snapshots pro Runde (Frage, Antwort, war Imposter?) | | `gtl_round_players` | Per-player snapshot per round (question, answer, was imposter?) |
| `gtl_chat_messages` | Lobby-Chat (max. 200 Nachrichten pro Raum) | | `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 | | `host_open` | Create or re-enter a room |
| `player_join` | Als Spieler beitreten | | `player_join` | Join as a player |
| `state` | Raumzustand abrufen (Polling) | | `state` | Fetch current room state (polling) |
| `assign_questions` | Fragen verteilen & Imposters festlegen | | `assign_questions` | Distribute questions and assign imposters |
| `submit_answer` | Antwort abschicken | | `submit_answer` | Submit an answer |
| `reveal_answer` | Einzelne Antwort gezielt aufdecken | | `reveal_answer` | Reveal a single player's answer |
| `reveal` | Alle Antworten aufdecken | | `reveal` | Reveal all answers at once |
| `request_voting` | Demokratisch Voting beantragen | | `request_voting` | Democratically request voting |
| `open_voting` | Voting manuell öffnen (Host) | | `open_voting` | Open voting manually (host) |
| `lock_vote` | Stimme final abschicken | | `lock_vote` | Submit final vote |
| `resolve_round` | Runde manuell auswerten | | `resolve_round` | Resolve the round manually |
| `new_round` | Neue Runde starten | | `new_round` | Start a new round |
| `send_emoji` | Emoji-Reaktion senden | | `send_emoji` | Send an emoji reaction |
| `send_chat` | Chat-Nachricht senden | | `send_chat` | Send a chat message |
| `score` | Punkte manuell korrigieren | | `score` | Manually adjust a player's score |
| `update_weights` | Imposter-Gewichte speichern | | `update_weights` | Save imposter weights |
| `get_host_history` | Rundenhistorie abrufen | | `get_host_history` | Fetch round history |
| `delete_room` | Lobby löschen | | `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 ```bash
git clone https://github.com/<dein-user>/guessTheLiar.git git clone https://github.com/<your-username>/guessTheLiar.git
cd guessTheLiar cd guessTheLiar
``` ```
`config.php` anlegen: Create `config.php`:
```php ```php
<?php <?php
return [ return [
'host' => 'localhost', 'host' => 'localhost',
'dbname' => 'blacksheepbluff', 'dbname' => 'your_database',
'user' => 'dein_db_user', 'user' => 'your_db_user',
'pass' => 'dein_db_passwort', 'pass' => 'your_db_password',
'charset' => 'utf8mb4', 'charset' => 'utf8mb4',
]; ];
``` ```
Datenbank anlegen: Create the database:
```sql ```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 | | Only "Nobody" has the most votes | Nobody is eliminated |
| Tie zwischen Niemand und einem Imposter | Imposter fliegt raus | | Tie between Nobody and an imposter | Imposter is eliminated |
| Tie zwischen Niemand und einem Innocent | Niemand (Tie geht an Niemand) | | Tie between Nobody and an innocent | Nobody wins the tie — innocent survives |
| Tie zwischen echten Spielern | Alle Tied fliegen raus | | Tie between real players only | All tied players are eliminated |
| Alle Imposters rausgewählt | Innocents gewinnen (+1 Punkt) | | All imposters eliminated | Innocents win (+1 point each) |
| Mind. ein Imposter überlebt | Imposter(s) gewinnen (+1 Punkt) | | At least one imposter survives | Surviving imposter(s) win (+1 point each) |
--- ---
## Screenshots ## Screenshots
*Lobby → Spieler-Ansicht → Voting → Auswertung* *Lobby → Player view → Voting → Resolution*
--- ---
## Lizenz ## License
MIT MIT