IPL Rapid-Fire Trivia

A small-scale live cricket arcade with two Socket.IO modes:

• IPL rapid-fire trivia for 3-4 players.
• Hand cricket for exactly 2 players.
• Hackathon extras: AI-style live commentary and one-use power cards.

It uses a single Node.js process, in-memory game state, server-owned rules, and a 70-question seed trivia fallback with optional Groq AI question prefetching.

Run Locally

npm install
npm run dev

Open the Vite URL, create a room, then join the same room code in a few more browser tabs.

Use the mode selector on the join screen to choose IPL Trivia or Hand Cricket.

Local npm run dev ignores VITE_SERVER_URL so it does not accidentally connect to a deployed Vercel URL. Production builds still use VITE_SERVER_URL.

Deploying With Vercel

Use Vercel for the Vite frontend only.

Do not deploy this Socket.IO backend as a Vercel Function. Vercel Functions do not act as a persistent WebSocket server, and Socket.IO needs a long-running Node process for live rooms, timers, and in-memory game state.

If the frontend has no backend URL configured, the browser will try:

https://your-vercel-app.vercel.app/socket.io/

That returns 404 because the Express + Socket.IO server is not running on the Vercel frontend.

Use this deployment split:

Vercel frontend  ->  long-running Node backend

Vercel environment variable:

VITE_SERVER_URL=https://your-node-backend-url

Then redeploy the Vercel frontend so Vite bakes the backend URL into the client bundle.

If VITE_SERVER_URL is not set in production, the frontend disables the Socket.IO client instead of calling the Vercel app origin. That prevents requests like:

https://your-vercel-app.vercel.app/socket.io/

Deploy the backend somewhere that supports a long-running Node server and WebSockets, such as Render, Railway, Fly.io, or Google Cloud Run. The backend start command is:

npm start

Quick checks:

curl https://your-node-backend-url/health
curl https://your-node-backend-url/socket.io/?EIO=4\&transport=polling

The first should return JSON. The second should not be a 404.

Recommended Vercel project settings:

Framework Preset: Vite
Build Command: npm run build
Output Directory: dist
Install Command: npm install

Optional Groq AI

Seed trivia works by default. To enable Groq-generated prefetch questions, create .env from .env.example and set:

GROQ_API_KEY=your_key_here
GROQ_MODEL=llama-3.1-8b-instant

The default Groq model is llama-3.1-8b-instant, which is listed in Groq's Free Plan limits. The app also caps Groq outputs to keep token usage small: trivia prefetches are short JSON responses and commentary is one short line.

The live game never depends on the AI call. If Groq is unavailable, over quota, or no key is configured, trivia generation uses the 70-question local seed pool and live commentary rotates through built-in fallback lines.

Scripts

npm run dev      # Express/Socket.IO server + Vite client
npm run build    # build frontend into dist/
npm start        # start backend, serving dist/ when present
npm test         # validate seed trivia

Gameplay

IPL Trivia

• 10 questions per game.
• 10 seconds per question.
• Correct answers score 100 + remainingSeconds * 5.
• One answer per player per question.
• Questions end on timeout or when all active players answer.
• Leaderboard is in-memory and room-only.
• Power cards:
  • Review: hides one wrong option for the current question.
  • Double Runs: doubles your next correct answer.

Hand Cricket

• Exactly 2 players per room.
• Host bats first in the first game.
• Both players secretly choose a number from 1 to 6.
• If the numbers differ, the batter scores their chosen number.
• If the numbers match, the batter is out.
• Each player gets one innings.
• The second innings ends when the batter is out or reaches the target.
• Host rematch swaps the first batter.
• Power cards:
  • Free Hit: batter cannot get out on the next ball.
  • Yorker: bowler blocks one random number for the next ball.

Hackathon Features

• Live commentary appears in both modes after big moments.
• If GROQ_API_KEY is present, commentary uses Groq's free-plan-friendly llama-3.1-8b-instant default for punchy cricket lines.
• If Groq is missing or unavailable, fallback commentary keeps the demo reliable.
• Power cards are server-authoritative, one-use-per-game, and validated before answers or number choices.