A progressive-difficulty football player guessing game where you identify players based on career statistics, transfer history, and biographical clues.
FootyGuess is a single-player web game that tests your knowledge of professional football players. Each round presents a mystery player from a database of real career data. You reveal clues incrementally—nationality, position, career stats, transfer timeline—and submit guesses until you identify the player correctly.
Choose your difficulty before each game:
| Difficulty | Multiplier | Max Base Score | Description |
|---|---|---|---|
| Default | 1×–3× | 100–300 pts | Random: Easy, Medium, or Hard |
| Easy | 1× | 100 pts | Famous players (high appearances) |
| Medium | 2× | 200 pts | Recognizable players |
| Hard | 3× | 300 pts | Obscure players |
| Ultra | 4× | 400 pts | Very obscure players |
The scoring system rewards speed, accuracy, and using fewer clues. A persistent streak system tracks consecutive correct guesses across sessions. All game state is validated server-side with rate limiting and secure headers.
- Node.js 20+ (LTS recommended)
- npm 9+
git clone https://github.com/dstN/footyguess.git
cd footyguess
npm installnpm run dev # Start at http://localhost:3000
npm test # Run unit tests
npm run test:e2e # Run end-to-end testsnpm run build
npm run preview # Preview production buildfootyguess/
├── pages/ # Route definitions (index, play, won)
├── components/ # UI components
├── composables/ # Reactive state management
├── server/
│ ├── api/ # HTTP endpoints
│ ├── services/ # Business logic layer
│ ├── utils/ # Scoring, validation, security
│ ├── db/ # SQLite database
│ └── scraper/ # Data acquisition
├── tests/ # Unit and E2E tests
├── .llm/ # Nuxt 4 / Nuxt UI 4 LLM context
└── ARCHITECTURE.md # Full technical reference
- Nuxt 4 — Full-stack Vue framework (SPA mode)
- Nuxt UI 4 — Component library
- SQLite + better-sqlite3 — Embedded database
- Valibot — Runtime validation
- Vitest / Playwright — Testing
| Document | Purpose |
|---|---|
| ARCHITECTURE.md | System design, conventions, decisions |
| PRODUCTION.md | Deployment and operations guide |
| IMPROVEMENTS.md | Roadmap and improvement tracking |
| CHANGELOG.md | Version history |
The game requires player data. Run the data acquisition process manually:
npm run scrapeserver/db/file/footyguess.db.
Private project. Not licensed for public use.
