A Discord bot that runs a Spyfall-style party game in a dedicated channel: players join, roles are assigned (Spy vs Civilian), civilians share a secret location, spies try to infer it, and everyone votes to eliminate suspected spies.

If you like social deduction, chaos, and watching humans pretend they’re good at lying, you’re in the right place.

Game loop (high level):

1. Join Phase: A join embed is posted with a persistent Join / Leave button.
2. Role Assignment: Players are assigned as Spy or Civilian and a secret Location is chosen.
3. Reveal Phase: Players privately reveal their role (civilians see the location, spies do not).
4. Discussion Phase:
   • Players speak in turn (timed).
   • Then there’s an open discussion window.
   • Spies can attempt an instant win by guessing the location in chat.
5. Voting Phase: Players vote on who they think is the spy.
   • Ties trigger a short tie-breaking discussion + revote.
6. Win Conditions:
   • Spy Majority (spies outnumber civilians) → spies win.
   • All spies eliminated → civilians win.
   • Spy guesses location correctly → spies win immediately.
   • No one votes → spies win by default (humans, impressive).

All commands only work in your configured Find the Spy channel.

• !find_the_spy start (alias: !fts start)
  Starts a new join window.

• !find_the_spy end (alias: !fts end)
  Ends the current game (authorized user only).

• !end
  Optional global alias for ending the game (authorized user only).

In the Discord Developer Portal:

• Create an application → add a bot
• Copy the bot token
• Under Privileged Gateway Intents, enable:
  • Message Content Intent (required by this bot)

Copy the example env file and set your token:

cp .env.example .env

Edit .env and set:

DISCORD_TOKEN="your_token_here"

Edit config.py:

• FIND_THE_SPY_CHANNEL_ID = the channel where the game runs
• AUTHORIZED_USER_ID = the Discord user ID allowed to end games quickly
• Timers and MIN_PLAYERS are also configured here

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

python bot.py

The bot persists join state to JSON in:

games/find_the_spy/storage/fts_state_<guild>_<channel>.json

This is used to resume/continue a join window if the bot restarts, and to keep the join embed’s player list in sync.

• bot.py – entry point, bot startup, registers cog + persistent join view
• cog.py – command group (!fts ...) and admin end logic
• state.py – in-memory game state and phase constants
• storage.py – JSON persistence helpers (atomic writes)
• utils.py – helpers for game instance, task tracking, permission cleanup
• phases/ – phase controllers for join/reveal/discussion/vote
• services/ – embeds, messaging, permissions, timers, victory handling

• Permissions: the bot changes channel overrides to enforce timed speaking. Make sure it has:
  • Manage Channels / Manage Roles (or enough to set channel permission overwrites)
  • Send Messages / Embed Links / Read Message History
• Intents: if Message Content Intent is not enabled in the portal, timed speaking (waiting for messages) won’t work reliably.
• Multiple games: the code keeps one game per guild in memory (GAMES in state.py).
• State files: games/find_the_spy/storage/*.json are generated and should not be committed (already ignored in .gitignore).

1. Type !fts start
2. Click Join / Leave
3. Reveal your role when prompted
4. Talk when it’s your turn
5. Vote like you’re not biased

MIT (see LICENSE).