PuzzleFuzz

A multiplayer word association game inspired by Codenames, powered by AI. Players take turns guessing words on a shared board based on clues generated by Google's Gemini API.

Tech Stack

• Frontend: React 18, React Router, Vite
• Backend: Vercel Serverless Functions
• Database: Firebase Firestore (real-time sync)
• AI: Google Gemini 3 Flash Preview (@google/genai SDK)
• Runtime: Bun

Getting Started

Prerequisites

• Bun installed
• A Firebase project with Firestore enabled
• A Google Gemini API key

Environment Variables

Set the following in your .env or Vercel project settings:

• GEMINI_API_KEY — Google Gemini API key
• Firebase config values (see src/firebase.js)

Development

bun install             # Install dependencies
bun run dev             # Start dev server (http://localhost:3000)
bun run dev:api         # Start local API server (http://localhost:3002)
bun run build           # Production build
bun run preview         # Preview production build
bun run seed:agents     # Seed AI agent data to Firestore

How It Works

1. Create or join a lobby — Players enter a 6-character lobby code to join a shared game session.
2. Board setup — 20 words are randomly selected and assigned colors: 8 pink, 7 green, 4 neutral, and 1 bomb.
3. AI clue generation — On each turn, the AI (Gemini) generates a one-word clue and a number indicating how many board words relate to it.
4. Guessing — Players click words on the board to guess. Correct guesses continue the turn; neutral words end it; the bomb loses the game instantly.
5. Real-time multiplayer — All game state syncs across players via Firestore's onSnapshot listeners.

Game Rules

• Clicking your team's color: continue your turn
• Clicking a neutral word: end your turn
• Clicking the bomb: instant loss
• First team to find all their words wins

Project Structure

puzzlefuzz/
├── api/                    # Vercel serverless functions
│   ├── gemini-test.js      # Gemini API endpoint for clue generation
│   └── secureEndpoint.js   # Authenticated endpoint
├── public/
│   └── words.txt           # Word list (newline-separated)
├── scripts/
│   └── seed-agents.js      # Seed AI agents to Firestore
├── src/
│   ├── components/
│   │   ├── Game.jsx        # Core game logic and state management
│   │   ├── Board.jsx       # Word grid layout
│   │   ├── WordBox.jsx     # Individual word tile
│   │   ├── ClueGiver.jsx   # AI clue request and display
│   │   ├── ClueJournal.jsx # History of past clues
│   │   ├── ScoreTracker.jsx# Turn and score display
│   │   ├── Welcome.jsx     # Lobby creation and join screen
│   │   ├── GameSetup.jsx   # Pre-game configuration
│   │   ├── AgentPicker.jsx # AI agent selection
│   │   ├── AgentMarketplace.jsx # Browse available agents
│   │   ├── HowToPlay.jsx   # Rules explanation
│   │   └── ...             # Additional UI components
│   ├── App.jsx             # Router setup
│   └── firebase.js         # Firebase initialization
└── CLAUDE.md               # AI coding assistant instructions

Deployment

Deployed on Vercel. GitHub Actions auto-deploys on push to main, and pull requests get preview deployments.