187 lines
6.8 KiB
Markdown
187 lines
6.8 KiB
Markdown
# 🐑 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
|
||
|
||
```
|
||
guessTheLiar/
|
||
├── 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)
|
||
|
||
**1. Clone the repo**
|
||
```bash
|
||
git clone https://github.com/daniediekert-blip/guessTheLiar.git
|
||
cd guessTheLiar
|
||
```
|
||
|
||
**2. Create the database**
|
||
```sql
|
||
CREATE DATABASE your_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
```
|
||
|
||
**3. Create `config.php`** (copy from the template)
|
||
```bash
|
||
cp config.example.php config.php
|
||
```
|
||
Then fill in your credentials — `config.php` is in `.gitignore` and will never be committed.
|
||
|
||
**4. Run the setup wizard**
|
||
|
||
Open `https://yourdomain.com/setup.php` in your browser. Enter a username and password for the admin account and submit the form.
|
||
|
||
The setup wizard will:
|
||
- Run all database migrations automatically (creates every table)
|
||
- Create the admin account
|
||
- **Delete itself** — `setup.php` is removed from the server automatically on success
|
||
|
||
If auto-delete fails due to file system permissions, remove `setup.php` manually.
|
||
|
||
**5. Done** — open `index.html` and start playing.
|
||
|
||
---
|
||
|
||
## 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
|