PlotTwist

Deception, deduction, and drama await. Can you figure it out?

Comment

Inspiration

Picture this: Last week, my friends and I went on a road trip through New Mexico. During our stay, we packed a deck of cards. Late at night, we decided to play the game of Mafia: you know, the game of deduction, murder, and suspense. However, we faced an issue trying to make it so everyone could play. Waking up at different times was inconvenient, and often a civilian would wake up just as a mafia pair was making their move, so the game had constant bumps and hurdles. This experience gave me the idea of bringing Mafia with technology: roles randomized, easy round building, funny stories for each murder, and much more. So I built PlotTwist, a modern take on the classic Mafia game that transforms those frustrating road trip moments into smooth, engaging gameplay. It's the Mafia game we always wanted to play on that road trip, but better.

What it does

PlotTwist is a sophisticated, real-time multiplayer social deduction game that modernizes the classic Mafia/Werewolf game.

Gameplay

  • Multiplayer Social Deduction: 7-10 players engage in a strategic battle between Mafia (killers) and Town (civilians + medic)
  • Card-Based Role System: Traditional playing cards represent roles - Kings for Mafia, Ace of Hearts for Medic, Jacks for Jester, numbered cards for Civilians
  • Real-Time Communication: WebSocket-powered live chat, voting, and game state synchronization
  • AI-Powered Storytelling: Dynamic murder narratives generated by OpenAI GPT-4o-mini that adapt to game events and player actions

Key Features

  • Themed Scenarios: Multiple atmospheric themes (Classic Mafia, Noir Detective, Western Showdown, Space Station, Fantasy Realm)
  • Automated Game Flow: Intelligent phase management with configurable timers for night/day/voting phases
  • Interactive Voting System: Visual voting interface with real-time results and dramatic death announcements
  • Sound Design: Immersive audio feedback using Web Audio API for all game events
  • Cross-Platform: Works on any modern browser with a responsive design

How I built it

Frontend (React + TypeScript)

  • Built with React 18 using modern hooks and components
  • TypeScript ensures safer and more reliable code
  • Styled using Tailwind CSS for fast, clean design
  • Framer Motion adds smooth, professional animations
  • Uses Web Audio API to generate sound in the browser
  • Real-time updates handled with WebSocket

Backend (Python + FastAPI)

  • FastAPI powers the API with fast performance and auto docs
  • Supports WebSocket for live two-way communication
  • Pydantic helps with data validation and formatting
  • GPT-4o-mini is used to generate AI-powered stories
  • Uses async code for better speed and efficiency

Development & Quality

  • Full test coverage for backend, frontend, and integration
  • ESLint and TypeScript enforce clean, consistent code
  • Hot reloading allows fast updates during development

Challenges I ran into

Keeping 7-10 players perfectly synchronized across different phases. Managing complex game state across multiple phases (lobby, night, day, voting) with proper validation. Creating a consistent audio experience across different browsers and devices.

Accomplishments that I'm proud of

Complete Full-Stack Implementation: successfully built a production-ready multiplayer game from scratch, type-safe implementation across the entire stack, and a comprehensive test suite covering all major functionality. Exceptional User Experience: smooth animations and transitions using Framer Motion, immersive sound design with Web Audio API, responsive design that works across all devices, and intuitive UI that guides players through complex game mechanics.

What I learned

I learned how to build real-time web apps using WebSockets so players can connect and interact instantly. Using TypeScript on both the frontend and backend helps keep things organized and safe. I also learned how social deduction games work and what makes them exciting for players. I improved my skills with tools like React, FastAPI, Tailwind, and Web Audio.

What's next for PlotTwist

After Hackathon: Mobile apps, voice chat, smarter AI stories, and tournament mode. Next Steps: Custom roles, game replays, player stats, social features, and new game modes. Long-Term Vision: AI Game Master, VR support, cross-platform play, community tools, and team-building versions for businesses.

Built With

Share this project:

Updates