A real-time multiplayer web adaptation of the classic bluffing card game.
Play Coup with 2–6 players from any device — no app install, no accounts. Create a room, share the code or QR link, add bots if you want, and start bluffing. The server enforces every rule so nobody can cheat, and the mobile-first UI keeps the game moving with timed challenge, block, and turn windows.
- Real-time WebSocket gameplay — instant action broadcasts via Socket.io
- Server-authoritative — all game logic runs server-side; clients never see hidden cards
- Room codes — 4-letter codes for easy sharing, no accounts required
- Public/private rooms — browse public lobbies, join open games, or watch live games as a spectator
- QR sharing — lobby share button opens a scannable room link
- Practice vs Bot — first-time players can start a disposable private tutorial game against a conservative bot from main menu settings, without affecting local stats
- Computer players — add 1–5 AI opponents with 7 personality types (Aggressive, Conservative, Vengeful, Deceptive, Analytical, Optimal, Random)
- Reconnection — signed session tokens let players rejoin mid-game without losing their seat
- Host moderation — hosts can remove lobby players or spectators before the game starts
- Disconnect recovery — disconnected in-game players are replaced by an optimal bot after 60 seconds
- Auto-cleanup — rooms expire after 24 hours; abandoned in-progress games with no connected humans are removed after 120 seconds
- Complete 2012 base game — Income, Foreign Aid, Tax, Steal, Assassinate, Exchange, Coup
- Reformation expansion — Factions (Loyalist/Reformist), Convert, Embezzle, Treasury Reserve, Inquisitor character with Examine action
- Full challenge system — any player can call a bluff; failed challenges cost an influence
- Block and counter-block — Duke blocks Foreign Aid, Contessa blocks Assassination, Captain/Ambassador/Inquisitor block Steal
- Forced Coup — 10+ coins means you must Coup
- Timed responses — configurable 10–60 second action windows and 15–90 second turn windows keep the pace up
- Mobile-first — portrait-optimized touch UI with 48px+ tap targets
- Dark table theme — generated tabletop backgrounds, compact illustrated cards, readable role/action labels, and character-colored borders
- Haptic feedback — vibration on taps for mobile devices (with iOS Safari fallback), togglable in settings
- Settings modal — accessible from home, lobby, and in-game via gear icon. Controls for sound, haptic feedback (touch devices only), reduced animation, and text size (Normal / Large / Extra Large)
- Player stats — local lifetime stats, awards, and match history are available from the home screen
- Live activity stats — players online and games in progress shown on the home page
- Sound effects — synthesized audio cues for game events (your turn, coup, challenges, etc.) with mute toggle
- Emoji reactions — 12 reactions (GG, LOL, Nice bluff!, RIP, etc.) visible to all players. Bots fire context-aware reactions driven by per-bot personality traits (emotiveness and meanness)
- Phase status banner — always shows what's happening and what you need to do
- Rules and Reformation guides — built-in rules include a quick-start Reformation guide for factions, Convert, Embezzle, and Inquisitor
- Urgency-coded prompts — red for threats (assassination), gold for decisions, gray for waiting
- Action log — scrollable history of every action, challenge, and block
- Contextual game over screen — winners and losers get personalized flavor text, staged winning-hand/table-truth reveal, recap cards, up to 4 awards, and copy/download recap export
- Truth reveal — post-game summaries show who bluffed, who stayed honest, which bluffs got away, and key table reads
- Player mute controls — locally hide a player's chat messages and reaction bubbles without changing the table for everyone else
- PWA polish — install prompt, app icons, standalone display metadata, and production asset caching for weak Wi-Fi
- Node.js 20.19+ (or 22.12+) to satisfy the current Vite/Vitest toolchain
git clone https://github.com/8tp/Coup.git
cd Coup
npm install
npm run devThe server starts at http://localhost:3000. Open it in multiple browser tabs to test multiplayer.
- Click Create Room and enter your name
- Share the 4-letter room code with friends
- Friends click Join Room, enter the code, or scan the QR link
- Optionally, make the room public so others can find it in Browse Public Games
- Optionally, the host can click Add Computer Player to fill seats with AI opponents
- The host clicks Start Game once 2–6 players have joined
- Bluff, challenge, and eliminate your way to victory
The host can add AI opponents from the lobby. Each bot has a personality type:
| Personality | Play Style | Bluffing | Challenges | Targeting |
|---|---|---|---|---|
| Random | Hidden random personality | Varies | Varies | Varies |
| Aggressive | Offensive actions, high risk | High bluff rates | Aggressive | Always targets leader |
| Conservative | Safe play, rarely bluffs | Very low | Rarely challenges | Avoids conflict |
| Vengeful | Retaliates against attackers | Moderate | Moderate | Targets last attacker |
| Deceptive | Constant bluffs, avoids scrutiny | Highest across all types | Avoids challenging | Leader-focused |
| Analytical | Evidence-based, calculated | Low-moderate | High with evidence | Strong leader targeting |
| Optimal | Strategic card counting | Selective (~12%) | Card counting-based | Highest-coin player |
All bots share the same underlying architecture — card counting, bluff persistence, deck memory, endgame tactics — with personality parameters modulating behavior. Strategies were tuned by analyzing 689,000+ real games from the treason online Coup server. See Bot Strategy Deep Dive for the full methodology.
Core bot capabilities (all personalities):
- Card counting — tracks publicly revealed cards to calculate challenge probabilities
- Bluff persistence — establishes a "bluff identity" by re-claiming the same character (3.5x weight boost)
- Dynamic card values — context-aware rankings for exchange and influence loss decisions
- Demonstrated character tracking — remembers opponents' successful blocks and unchallenged claims
- Endgame tactics — 1v1 Steal preference, 3P1L anti-tempo strategy, hail-mary challenges at 1 influence
Bots make decisions with realistic randomized delays (1.5–3.5s for actions, 0.8–2s for reactions) and follow all the same rules as human players — they never peek at hidden cards or the deck.
| Character | Action | Effect | Blocks |
|---|---|---|---|
| Duke | Tax | +3 coins | Foreign Aid |
| Assassin | Assassinate | Pay 3, target loses influence | — |
| Captain | Steal | Take 2 coins from target | Steal |
| Ambassador | Exchange | Draw 2 from deck, return 2 | Steal |
| Contessa | — | — | Assassination |
| Inquisitor* | Exchange / Examine | Draw 1, swap or keep / Look at opponent's card | Steal |
*Inquisitor replaces Ambassador in Reformation mode (optional)
| Action | Effect |
|---|---|
| Income | +1 coin (safe — cannot be challenged or blocked) |
| Foreign Aid | +2 coins (blockable by Duke) |
| Coup | Pay 7 coins, target loses influence (unblockable, unchallengeable) |
The host can enable Reformation mode in the lobby settings. This adds factions, new actions, and the Inquisitor character.
Factions — Players are assigned to Loyalists (blue) or Reformists (red). You cannot target same-faction players with Coup, Assassinate, Steal, or Examine. Challenges and blocks are unrestricted. When all surviving players share a faction, restrictions lift.
| Action | Cost | Effect |
|---|---|---|
| Convert | 1 (self) / 2 (other) | Switch a player's faction. Coins go to Treasury Reserve |
| Embezzle | 0 | Take all coins from the Treasury Reserve. Inverse challenge: challenger wins if you DO have Duke |
| Examine | 0 | Look at an opponent's card (claim Inquisitor). Force swap it or return it |
- Bluffing — claim any character action whether you hold that card or not
- Challenging — call someone's bluff. If they were honest, you lose an influence. If they lied, they lose one and the action is cancelled
- Blocking — certain characters counter certain actions. Blocks can themselves be challenged
- Elimination — lose both influences and you're out. Last player standing wins
The server is the single source of truth. Clients send intents (e.g. "play Tax") and receive filtered state — they can only see their own hidden cards and public information.
Client A Server Client B
| | |
|-- game:action (Tax) ----->| |
| |-- ActionResolver (pure) |
| |-- Apply side effects |
|<-- game:state (filtered)--|-- game:state (filtered) -->|
The ActionResolver is a pure state machine: (state, input) → (newPhase, sideEffects[]). The GameEngine applies side effects (mutate coins, reveal cards, set timers) and broadcasts per-player views through StateSerializer.
AwaitingAction
├─ Income ───────────────────────────> resolve ──> next turn
├─ Coup ─────────────────────────────> AwaitingInfluenceLoss ──> next turn
├─ Convert ──────────────────────────> resolve ──> next turn
├─ Tax / Steal / Assassinate / Exchange / Examine / Embezzle
│ └─> AwaitingActionChallenge
│ ├─ Challenge ──> resolve
│ └─ All Pass ──> AwaitingBlock (if blockable)
│ or AwaitingExamineDecision (Examine)
│ or resolve
└─ ForeignAid
└─> AwaitingBlock
├─ Block ──> AwaitingBlockChallenge
└─ All Pass ──> resolve
Coup/
├── server.ts # Express + Socket.io + Next.js entry point
├── docs/ # Project documentation
│ ├── BOT-STRATEGY.md # AI strategy research and tuning methodology
│ ├── ASSETS.md # Visual asset generation notes and prompts
│ ├── CONTRIBUTING.md # Contribution guidelines
│ ├── PRD.md # Product requirements document
│ ├── ROADMAP.md # Prioritized post-main product polish and follow-ups
│ └── REFORMATION_PLAN.md # Reformation expansion implementation plan
├── public/ # PWA icons, Open Graph image, and generated game art
│ ├── assets/ # Card, banner, and table background raster assets
│ ├── icons/ # PWA install icons
│ ├── coup-logo.png # Project/app icon used in docs
│ ├── coup-logo-transparent.png # Transparent-corner icon for docs/social art
│ ├── embed-image.png # Twitter/large-card social preview
│ ├── favicon.ico # Browser favicon
│ ├── sw.js # Production service worker for static game assets
│ └── og-image.png # Open Graph social preview
├── tests/ # Test suite
│ ├── engine/ # Engine unit tests
│ └── server/ # Server unit tests
├── src/
│ ├── shared/ # Shared types, constants, protocol
│ │ ├── types.ts # All TypeScript interfaces and enums
│ │ ├── constants.ts # Game rules and action definitions
│ │ └── protocol.ts # Socket.io event contracts
│ │
│ ├── engine/ # Pure game logic (no I/O)
│ │ ├── GameEngine.ts # Orchestrator: timers, state, broadcasts
│ │ ├── ActionResolver.ts # State machine: phase transitions + side effects
│ │ ├── BotBrain.ts # AI decision logic: personality-parameterized choices
│ │ ├── Game.ts # Game state: players, deck, turns, treasury
│ │ ├── Player.ts # Player model: influences, coins
│ │ └── Deck.ts # Card deck: shuffle, draw, return
│ │
│ ├── server/ # Networking and room management
│ │ ├── RoomManager.ts # Room CRUD, player tracking, TTL cleanup
│ │ ├── SocketHandler.ts # Routes socket events to engine
│ │ ├── BotController.ts # Bot timing/execution: delays + engine calls
│ │ ├── ContentFilter.ts # Name/chat sanitization and moderation checks
│ │ └── StateSerializer.ts # Per-player state filtering
│ │
│ └── app/ # Next.js App Router (client UI)
│ ├── page.tsx # Home: create/join room
│ ├── lobby/[roomCode]/ # Lobby: player list, start game
│ ├── game/[roomCode]/ # Game view
│ ├── hooks/useSocket.ts # Socket.io client with auto-reconnect
│ ├── stores/
│ │ ├── gameStore.ts # Zustand store: connection, room, game state
│ │ ├── statsStore.ts # Local player stats persisted in localStorage
│ │ └── settingsStore.ts # Zustand store: text size, haptic, motion prefs
│ ├── utils/haptic.ts # Haptic feedback (vibration + iOS fallback)
│ ├── utils/statsRecorder.ts # Local post-game stat recording
│ ├── audio/SoundEngine.ts # Synthesized sound effects (Web Audio API)
│ └── components/ # GameTable, ActionBar, prompts, settings, cards
| Command | Description |
|---|---|
npm run dev |
Start dev server (Express + Next.js + Socket.io) |
npm run build |
Build for production |
npm start |
Run production build |
npm test |
Run test suite (550 tests across 21 files) |
npm run test:e2e |
Run socket browser-flow E2E tests |
npm run test:watch |
Run tests in watch mode |
# Run all tests
npm test
# Run browser-flow E2E tests
npm run test:e2e
# Watch mode during development
npm run test:watchThis project requires persistent WebSocket connections. Vercel will not work — use a platform that supports long-lived server processes.
- Railway — Git-based deploys, free tier available
- Render — Web Service type with WebSocket support
- Fly.io — container-based, globally distributed
Set the build command to npm run build and the start command to npm start. The PORT environment variable is read automatically.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
MIT — see the LICENSE file for details.
- Coup is a card game designed by Rikki Tahta, originally published in 2012 by La Mame Games and Indie Boards & Cards
- This is a fan-made digital adaptation for personal and educational use — it is not affiliated with or endorsed by the original creators
- If you enjoy the game, please support the creators by purchasing the physical game