Trivia Board Game

The Trivia board game is an interactive, fully client-side (serverless) quiz game built with HTML, Tailwind CSS, and vanilla JavaScript. The game allows for offline gameplay using built-in question databases (JSON files) and offers the ability to upload or paste custom question decks.

---

🚀 Main Features

1. Offline Gameplay (Question Database):

   • Convenient loading of built-in JSON question databases.
   • Ability to upload your own question database file (.json) or paste generated database text directly into the form.
   • Robust resilience to parsing errors (Json Healing).

2. Category Selection:

   • Convenient category selection screen allowing players to select exactly 6 categories for the game.
   • Random category choice option and filter by language (PL/EN).

3. Save and Restore Game State:

   • The game automatically saves state to localStorage after every move.
   • Download the current state as a .json file ("Download State") and upload it later ("Load Game") to continue playing on another device.

4. Premium Design and Space Optimization:

   • Clear top bar indicating the active player's turn and displaying scores alongside earned wedges in the form of horizontal capsules.
   • Floating 3D die in the bottom-right corner of the board, integrated with rolling mechanics and pawn movement animations.
   • Complete support for multiple themes (OLED, Dark, Light) with elegant background blur (backdrop-filter) and smooth transitions.

5. AI Question Database Generator:

   • An advanced built-in developer/admin tool (generator.html and js/generator.js) for direct question generation using LLM APIs (OpenRouter, OpenAI, LM Studio, Ollama).
   • Supports batch generation, custom difficulty levels, automatic spoiler checks (preventing questions containing their own answers), and ZIP exporting.

6. Progressive Web App (PWA) & Offline-First:

   • The game and database generator are fully installable on desktop and mobile.
   • Comprehensive caching strategy via Service Worker (sw.js) precaching the entire app shell, CDN resources (Tailwind, JSZip, Google Fonts), and default question databases.
   • Runtime cache with a Stale-While-Revalidate strategy for dynamic categories, enabling offline gameplay for previously played categories while automatically updating when online.

7. Responsive Play and Accessible Controls:

   • The setup wizard, board, player scores, die, and category legend adapt to phone portrait/landscape, desktop, and TV-sized screens without device-specific configuration.
   • Use Arrow keys or WASD to move focus, Enter/Space to activate, and Escape to close a dialog or return. Standard gamepads use the D-pad or left stick, A to activate, B to go back, and Start to open or close the game menu.
   • Long questions, answers, and explanations paginate automatically. Previous/Next also work with keyboard or gamepad; very long answer choices continue across pages and remain selectable.
   • Gamepad input uses the browser Gamepad API. Browsers require a secure context: use localhost for local play and HTTPS when hosting on another device.

---

📁 Project Structure

• /databases – Directory containing question databases.
  • /categories – Subdirectory containing standard category database files (e.g. general_pl.json, general_en.json, popkultura_pl.json).
  • list.json – Automatically generated index of available databases.
• /js/trivia – Main game modules:
  • main.js – Game entry point and initialization.
  • state.js – Dynamic game state.
  • client-adapter.js – Offline API database adapter.
  • board.js & ui-board.js – Grid layout generation, board, and pawn rendering logic.
  • ui-events.js – Event handlers and screen navigation.
  • utils.js – Helper functions, JSON parser.
  • /services/persistence-service.js – State saving, downloading, and restoring.
• index.html – Main game screen.
• style.css – Stylesheet (Vanilla CSS integrated with Tailwind Play CDN).
• generator.html – Independent database generator tool (with built-in API support).
• manifest.json – Web App Manifest for PWA properties.
• sw.js – Service Worker for offline asset and category caching.
• icons/ – Folder containing optimized launcher icons (icon-192.png, icon-512.png).

---

🛠️ Development and Workflow

Install development dependencies (ESLint, Prettier, Vitest):

npm ci

Running Locally

Run the game from a local static server. Python is available on most development machines:

python3 -m http.server 8220

The game will be available at: http://127.0.0.1:8220.

Automatic Database Scanning

After committing a new .json database file to the /databases folder, run the scan script to automatically update the list.json index:

npm run scan-db

The new database will immediately appear in the game setup screen!

Running Tests

Run automated unit tests (board logic, JSON parsing, persistence):

npm run test

Formatting and Linting

Format the code with Prettier:

npm run format

Lint the code for static errors with ESLint:

npm run lint

---

Gra Planszowa Trivia

Gra planszowa Trivia to interaktywna, w pełni kliencka (bezserwerowa) gra quizowa oparta na HTML, Tailwind CSS i czystym JavaScripcie. Gra pozwala na rozgrywkę offline przy użyciu wbudowanych baz pytań (plików JSON) oraz daje możliwość wczytywania własnych talii pytań.

---

🚀 Główne Funkcje

1. Rozgrywka Offline (Baza Pytań):

   • Wygodne wczytywanie wbudowanych baz pytań JSON.
   • Możliwość wgrania własnego pliku bazy pytań (.json) lub wklejenia wygenerowanego tekstu bazy bezpośrednio w formularzu.
   • Pełna odporność na błędy parsowania (Json Healing).

2. Wybór Kategorii:

   • Intuicyjny panel wyboru pozwalający graczom wybrać dokładnie 6 kategorii do rozgrywki.
   • Opcja losowego wyboru kategorii oraz filtrowanie po języku (PL/EN).

3. Zapis i Odtwarzanie Stanu Gry (Save/Restore):

   • Gra automatycznie zapisuje stan po każdym ruchu w localStorage.
   • Możliwość pobrania aktualnego stanu jako plik .json („Pobierz zapis”) i późniejszego wgrania („Wczytaj grę”) w celu kontynuowania rozgrywki na innym urządzeniu.

4. Premium Design i Optymalizacja Przestrzeni:

   • Przejrzysta górna belka informująca o aktualnej turze gracza oraz wyświetlająca punktację wraz ze zdobytymi cząstkami (klinami) w formie poziomych kapsułek.
   • Pływająca kostka 3D w prawym dolnym rogu planszy, zintegrowana z systemem rzutów i animacji ruchu pionków.
   • Pełne dopasowanie do motywów (OLED, Dark, Light) z efektownym rozmyciem tła (backdrop-filter) i płynnymi animacjami.

5. Generator Baz Pytań AI:

   • Zaawansowane wbudowane narzędzie (generator.html i js/generator.js) do bezpośredniego generowania pytań za pomocą API modeli LLM (OpenRouter, OpenAI, LM Studio, Ollama).
   • Wspiera generowanie partiami (batch), dostosowanie poziomu trudności, automatyczne sprawdzanie spoilerów (wykrywanie pytań zawierających własne odpowiedzi) oraz eksport do plików JSON/ZIP.

6. Aplikacja PWA i Tryb Offline (Offline-First):

   • Gra oraz generator baz pytań są w pełni instalowalne na urządzeniach mobilnych i stacjonarnych.
   • Zaawansowana strategia cache'owania za pomocą Service Workera (sw.js) – zapisuje w pamięci podręcznej pliki aplikacji, zasoby CDN (Tailwind, JSZip, czcionki Google) oraz domyślne bazy pytań.
   • Strategia Stale-While-Revalidate dla kategorii wczytywanych w trakcie gry, umożliwiająca zabawę offline we wcześniej uruchamiane tematy z automatyczną aktualizacją pytań po połączeniu z siecią.

---

📁 Struktura Projektu

• /databases – Katalog na bazy pytań.
  • /categories – Podkatalog zawierający pliki baz danych poszczególnych kategorii (np. general_pl.json, general_en.json, popkultura_pl.json).
  • list.json – Indeks dostępnych baz pytań generowany automatycznie.
• /js/trivia – Moduł główny gry:
  • main.js – Punkt wejścia i inicjalizacja gry.
  • state.js – Dynamiczny stan gry.
  • client-adapter.js – Offline'owy adapter API baz danych.
  • board.js & ui-board.js – Logika generowania siatki pól oraz rysowania planszy i pionków.
  • ui-events.js – Obsługa zdarzeń i nawigacja ekranów.
  • utils.js – Funkcje pomocnicze, parser JSON.
  • /services/persistence-service.js – Zapis, pobieranie oraz przywracanie stanu rozgrywki.
• index.html – Główny ekran gry.
• style.css – Arkusz stylów (arkusz stylów Vanila CSS zintegrowany z Tailwind Play CDN).
• generator.html – Niezależne narzędzie do bezpośredniej generacji baz pytań przez API LLM (z obsługą weryfikacji spoilerów, edycji CMS oraz eksportu ZIP).
• manifest.json – Manifest PWA z konfiguracją aplikacji.
• sw.js – Service Worker do obsługi trybu offline i cache'owania zasobów.
• icons/ – Katalog z ikonami launchera (icon-192.png, icon-512.png).

---

🛠️ Praca z Projektem i Rozwój

Instalacja zależności deweloperskich (ESLint, Prettier, Vitest):

npm ci

Uruchomienie lokalne

Uruchom grę przez lokalny serwer statyczny. Python jest dostępny na większości komputerów deweloperskich:

python3 -m http.server 8220

Gra będzie dostępna pod adresem: http://127.0.0.1:8220.

Automatyczne skanowanie baz pytań

Po zacommitowaniu nowego pliku .json z bazą pytań w katalogu /databases, uruchom skrypt skanujący w celu automatycznego zaktualizowania indeksu list.json:

npm run scan-db

Nowa baza pytań natychmiast pojawi się na liście wyboru w grze!

Testy

Uruchomienie automatycznych testów jednostkowych (logika planszy, parsowanie JSON, persistence):

npm run test

Formatowanie i Linting

Formatowanie kodu za pomocą Prettiera:

npm run format

Sprawdzanie błędów statycznych w kodzie (ESLint):

npm run lint

Sterowanie i ekrany

• Strona dopasowuje układ do telefonu w pionie i poziomie, komputera oraz dużego ekranu TV; nie wymaga ręcznego wyboru urządzenia.
• Strzałki lub WASD przenoszą fokus, Enter/Spacja aktywują element, a Escape zamyka okno lub cofa.
• Standardowy kontroler używa krzyżaka lub lewej gałki, A do aktywacji, B do cofania oraz Start do otwierania i zamykania menu gry.
• Długie pytania, odpowiedzi i wyjaśnienia dzielą się automatycznie na strony. Przyciski Poprzednia/Następna działają też z klawiatury i kontrolera; bardzo długą odpowiedź można wybrać z każdego fragmentu.
• Obsługa kontrolera korzysta z Gamepad API przeglądarki. API wymaga bezpiecznego kontekstu: lokalnie używaj localhost, a na innym urządzeniu hostuj aplikację przez HTTPS.