| .claude | ||
| .idea | ||
| identity | ||
| .gitignore | ||
| admin.php | ||
| api.php | ||
| auth.php | ||
| config.example.php | ||
| index.html | ||
| login.php | ||
| migrate.php | ||
| profile.php | ||
| README.md | ||
| schema.sql | ||
| setup.php | ||
🐑 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
- The host opens a room and sets a normal question plus a separate imposter question
- Every player types their answer — imposters have a different question and must hide it
- The host reveals answers one by one or all at once
- The group discusses and votes: who is the black sheep?
- 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 |
| 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=<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)
git clone https://github.com/<your-username>/guessTheLiar.git
cd guessTheLiar
Create config.php:
<?php
return [
'host' => 'localhost',
'dbname' => 'your_database',
'user' => 'your_db_user',
'pass' => 'your_db_password',
'charset' => 'utf8mb4',
];
Create the database:
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