# 🐑 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 Modern OOP front-controller architecture. The **document root points to `public/`**; everything else lives above it and is not web-accessible. ``` black-sheep-bluff/ ├── public/ # ← Docroot (only this folder is public) │ ├── index.php # Front controller — single entry point │ ├── .htaccess # Clean-URL routing + 301 redirects │ ├── assets/{css,js}/ # Global (base.css/site.js) + per-page assets │ ├── identity/ images/ sounds/ # static media │ ├── uploads/ # user avatars & stickers (gitignored) │ └── config.js # Client config (Giphy key, donation URL) ├── app/ │ ├── Core/ # Kernel, Router, Config, Database, Controller │ ├── Controllers/Pages/ # Home, Regeln, Legal, Play, Login, Profile, Admin │ ├── Controllers/Api/ # Auth, Room, Game, Voting, Chat, Group, Ad, Presence │ ├── Services/ # RoomService, AuthService (game & auth logic) │ ├── Database/ # Migrator + versioned migration definitions │ ├── Support/ # Global helper functions │ ├── Views/ # layout.php, partials/, pages/ │ └── routes/ # web.php (pages) + api.php (API actions) ├── config/ # config.php (DB creds, gitignored) + example ├── bin/migrate.php # CLI migration runner (`php bin/migrate.php`) └── schema.sql # Initial DB schema reference ``` > **Add a new SEO page:** drop a view in `app/Views/pages/`, add a controller in > `app/Controllers/Pages/`, and one line in `app/routes/web.php`. --- ## 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/` (auth actions: `/api/auth/`), 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