black-sheep-bluff/README.md
danny f805552ff1 Merge remote-tracking branch 'origin/main'
# Conflicts:
#	README.md
2026-06-14 14:44:57 +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 get a different question. Find them!*
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?
---
## How to Play
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
- **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 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 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 & 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
| Layer | Technology |
|---|---|
| Backend | PHP 8, PDO/MySQL, native sessions |
| Frontend | Vanilla JS, CSS Grid, CSS Custom Properties |
| Database | MySQL 8 with an automatic migration system |
| Charts | [Chart.js 4.4.4](https://www.chartjs.org/) |
| Font | Inter (Google Fonts) |
No frontend framework, no build step — everything runs directly in the browser.
---
## Project Structure
```
black-sheep-bluff/
├── 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)
├── setup.php # One-time admin setup (self-deletes after use)
├── login.php # Login page
├── profile.php # Player profile & lifetime statistics
├── admin.php # Admin panel (user management)
├── config.php # DB credentials — not in repo, copy from below
├── config.example.php # Credential template (safe to commit)
├── schema.sql # Initial DB schema reference
└── identity/ # Logo & favicon (PNG + PSD)
```
---
## Database Schema
The migration system runs automatically on first request — no manual setup required.
| Table | Contents |
|---|---|
| `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 Reference
All actions go through `api.php?action=<name>` (GET or POST with a JSON body).
| Action | Description |
|---|---|
| `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 |
**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.
---
## Self-Hosting
**Requirements:** PHP 8.1+, MySQL 8+, web server (Apache or Nginx)
```bash
git clone https://github.com/<your-username>/guessTheLiar.git
cd guessTheLiar
```
Create `config.php`:
```php
<?php
return [
'host' => 'localhost',
'dbname' => 'your_database',
'user' => 'your_db_user',
'pass' => 'your_db_password',
'charset' => 'utf8mb4',
];
```
Create the database:
```sql
CREATE DATABASE your_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
All tables are created automatically by the migration system on the first page load.
---
## Voting Rules
| Situation | Result |
|---|---|
| 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 → Player view → Voting → Resolution*
---
## License
MIT