# 🐑 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) ├── 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) ``` --- ## 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=` (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//guessTheLiar.git cd guessTheLiar ``` Create `config.php`: ```php '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