Floppy Bird is a canvas-based, forest-themed Flappy Bird-style game built with Next.js. It includes power-ups, quests, cosmetics, local and global leaderboards, and accessibility options.

Requirements

• Node.js 20+ (recommended)
• pnpm 9+ (or npm/yarn, but examples use pnpm)
• MongoDB (for global leaderboard)

Quick Start

1. Install dependencies: pnpm install
2. Create a local env file: cp .env.example .env
3. Set MONGODB_URI in .env.
4. Run the dev server: pnpm dev
5. Open http://localhost:3000.

Environment Variables

• MONGODB_URI (required for global leaderboard)
  • Example (Atlas): mongodb+srv://<user>:<password>@<cluster>/<db>?retryWrites=true&w=majority

If MONGODB_URI is missing or invalid, the global leaderboard endpoints will fail, but the game still runs locally.

Gameplay Controls

• Flap: Space or Arrow Up
• Glide: hold Space/Arrow Up (or touch/hold on mobile)
• Pause: P
• Settings: Esc
• Shop: B
• Use power-ups: 1 (shield), 2 (slow), 3 (magnet)

Features

• Global leaderboard (MongoDB)
• Local leaderboard (browser storage)
• Daily/weekly quests and rewards
• Power-ups (shield, slow, magnet)
• Cosmetics (skins, trails, nameplates, banners)
• Accessibility toggles (reduced motion, color-blind palette, forgiving hitbox, haptics)

API Reference (Leaderboard)

Base path: /api/scores

• GET /api/scores

  • Returns top 50 scores
  • Response: { scores: [{ username, score, createdAt }] }

• POST /api/scores

  • Body: { "username": string, "score": number, "coins"?: number }
  • Saves or updates a user's best score and coin bank
  • Validation: username is trimmed to 2-20 chars; score/coins are non-negative integers

• POST /api/scores/check-username

  • Body: { "username": string }
  • Checks if username exists; returns suggestions when taken

• GET /api/scores/profile?username=<name>

  • Returns { exists: boolean, user?: { username, score, coins, createdAt } }

Database Model

Collection: scores

• username (string, unique, 2-20 chars, trimmed)
• score (number)
• coins (number)
• createdAt / updatedAt (timestamps)

Deployment Notes

• Set MONGODB_URI in your hosting provider.
• Build: pnpm build
• Start: pnpm start

Customization

• Game logic and UI: components/floppy-bird.tsx
• Styling: app/globals.css
• Theme images: public/assets/themes/
• Audio assets: public/audio/

When replacing assets, ensure you have the correct license/rights to distribute them.

Troubleshooting

• Global leaderboard not working:
  • Verify MONGODB_URI and MongoDB network access.
• Build errors:
  • Run pnpm lint and pnpm build to identify issues.