ChessCraft

ChessCraft is a modern web application that allows users to play chess with friends in real-time, improve their skills with puzzles, play against AI bots, analyze their games, and learn from curated chess content. It features a clean, intuitive interface with customizable preferences and interactive gameplay.

Core Features

• Game Creation: Create new chess games with custom time controls and color preferences.
• Join Game: Join existing games using a unique game code.
• Interactive Chessboard: Real-time display of the chessboard with highlighting of legal moves and the last move played. Supports drag-and-drop and click-to-move. Cursor changes to indicate interactable areas.
• In-Game Chat: Communicate with your opponent during the game.
• Game Timers: Displays timers for each player, indicating the current player's turn and handling time-outs. Includes increment logic.
• Move History (In-Game): Displays a move history in standard algebraic notation (PGN format).
• Game Actions: Offer and accept draws, or resign a game.
• Rematch: Offer, accept, or decline a rematch after a game concludes, with colors automatically inverted.
• Pawn Promotion: Choose your desired piece upon pawn promotion, with a dialog appearing for both drag-and-drop and click-to-move actions.
• Puzzle Solving:
  • Solve a wide variety of chess puzzles.
  • Puzzles can be filtered by theme and are selected based on your puzzle rating.
  • Interactive puzzle solving with immediate feedback. Opponent's first move has a slight delay for better visibility. Solution can be displayed in standard PGN format.
  • Persistent user puzzle rating and statistics saved locally.
• Play Against AI Bots:
  • Select and play against AI opponents with different personalities and skill levels (using Stockfish.js for levels > 0, and random legal moves for level 0) using a carousel-style interface. Each bot card displays its avatar, name, description, skill level (numeric and title), and bio.
  • Bots with skill level 0 make random legal moves, providing an accessible experience for absolute beginners.
  • The last played bot is preselected when returning to the bot selection screen (using localStorage).
  • Configure your color preference (White, Black, or Random). Player's color in "Play Again" is automatically inverted.
  • Standard game rules and result detection apply.
  • Bots provide simple, contextual chat messages during gameplay.
• Learning Center:
  • Access a curated list of YouTube channels providing chess lessons and tutorials.
  • Channels are filtered based on the user's selected application language.
  • Dynamically fetches and displays recent videos from selected channels using the YouTube Data API v3.
  • Video thumbnails, titles, and descriptions are shown, with direct links to watch on YouTube.
• Game Review & History:
  • Access a list of your past games ("My Games").
  • Review completed games move by move with an interactive board, including time taken per ply.
  • Client-side Stockfish.js engine analysis for position evaluation and best move suggestions during review. User can select from multiple Stockfish 17 versions (Large MT/ST, Lite MT/ST, ASM.js) and Stockfish 6 Legacy. Analysis settings (engine choice, time, lines, threads) are configurable and saved; settings are disabled with a clear warning when the engine is active. Includes a visual progress bar during analysis and improved engine switching UX.
  • Download game PGNs.
• User Preferences: Customize your experience with settings for:
  • Theme (Light, Dark, System)
  • Interface Language (English, Español)
  • Sound Effects (On/Off for moves and captures)
  • Board Color
  • Puzzle Settings (e.g., reset seen puzzle history)
  • Piece Style (placeholder for future implementation)
• Progressive Web App (PWA) Features:
  • Installable on supported devices for an app-like experience.
  • Basic offline access to your game history and cached chess puzzles. Updates automatically after new deploys (typically after a refresh or reopening).
• About & Contact Page:
  • Information about the ChessCraft project.
  • Placeholder for donation/support options.
  • Contact form for user feedback and suggestions, with messages stored in Firestore.
• Admin Panel (Role-Protected):
  • Dashboard with basic application statistics (total games, total puzzles).
  • Management of Bot Profiles:
    • View, create (via import from bot-profiles-data.json or manually), and edit bot details (name, description, bio, skill level).
    • Generate bot avatar images using AI (Genkit with Gemini), processing sequentially to respect API rate limits, and save them to Firebase Storage.
    • Import process preserves existing bot images if the source data specifies a null image.
    • Delete bot profiles.
  • View Contact Messages: Admins can view messages submitted through the "About/Contact" page.
  • Placeholder sections for managing users, puzzles, and site settings.

Tech Stack

• Frontend:
  • Next.js (App Router)
  • React
  • TypeScript
  • ShadCN UI (Component Library)
  • Tailwind CSS (Styling)
  • Lucide React (Icons)
  • react-chessboard for the chessboard UI.
  • chess.js for chess logic (move validation, game state, random moves for level 0 bots).
  • next-intl for internationalization.
  • Stockfish.js (v17 Large MT/ST WASM, v17 Lite MT/ST WASM, v17 ASM.js, v6 Legacy WASM) for client-side game analysis and AI bot play (skill levels > 0). Specifically, stockfish-17-lite-single.js is used for bot play.
• Backend & Real-time:
  • Firebase Firestore (Database for game state, chat, puzzles, bot profiles, user roles, contact messages).
  • Firebase Storage (For storing bot avatar images and other static assets like the homepage image).
  • Next.js Server Actions (for mutations like making moves, sending chat messages, admin actions, contact form submission, fetching YouTube videos).
  • Google API Client Library for Node.js (googleapis): Used by Server Actions to interact with the YouTube Data API v3.
• AI (Generative):
  • Genkit (Firebase Genkit) for generating bot avatar images using Google's Gemini model, with images stored in Firebase Storage.
• Authentication:
  • Firebase Authentication for email/password user accounts.
  • Role-based access control (user, admin).
  • Persistent anonymous user IDs for non-logged-in users (localStorage).

Getting Started

Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Node.js (v18 or newer recommended)
• npm, yarn, or pnpm

Installation

1. Clone the repository:

   git clone <your-repository-url>
   cd chesscraft-online 

2. Install dependencies:

   npm install
   # or
   # yarn install
   # or
   # pnpm install

3. Set up Firebase:

   • Create a new project in the Firebase Console.
   • In your project, go to Project settings (click the gear icon ⚙️).
   • Under the "General" tab, find your web app configuration (if you don't have one, click "Add app" and select the Web platform </>).
   • Copy the Firebase configuration object.
   • Create a .env.local file in the root of your project by copying .env.local.example (if it exists, otherwise create it).
   • Fill in your Firebase configuration values in .env.local:

     NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
     NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
     NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
     NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket_id.firebasestorage.app
     NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
     NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
     YOUTUBE_API_KEY=your_youtube_data_api_v3_key

   • Enable Cloud Firestore in your Firebase project.
     • Go to Firestore Database in the Firebase console.
     • Click Create database.
     • Choose Start in production mode or Start in test mode. For development, test mode is easier. Remember to secure your rules before deploying to production!
     • Select a Cloud Firestore location.
   • Enable Firebase Authentication and the "Email/Password" sign-in provider.
   • Enable Firebase Storage.
   • (Required for Genkit and Admin SDK Features) Set up a service account key for Firebase Admin SDK:
     • In Firebase Console: Project settings > Service accounts.
     • Generate a new private key and save the downloaded JSON file as serviceAccountKey.json in the root of your project.
     • Important: Add serviceAccountKey.json to your .gitignore file to prevent committing sensitive credentials.
     • This key enables the Admin SDK to perform privileged operations, like interacting with Firebase Storage for bot images or bypassing security rules for administrative tasks. The Admin SDK initialization in src/lib/firebase-admin.ts will attempt to use this key.
   • (Required for Learning Center) Set up a YouTube Data API v3 Key:
     • Go to the Google Cloud Console.
     • Create a new project or select an existing one.
     • Navigate to "APIs & Services" > "Library".
     • Search for "YouTube Data API v3" and enable it.
     • Navigate to "APIs & Services" > "Credentials".
     • Click "Create credentials" > "API key".
     • Copy the API key. It's highly recommended to restrict this API key to only allow access to the YouTube Data API v3 and, if possible, by IP address or HTTP referrers (though for server-side use, IP restrictions might be complex depending on your deployment).
     • Add this key to your .env.local file as YOUTUBE_API_KEY=your_youtube_data_api_v3_key.
     • You will also need to add this as a secret in apphosting.yaml for production deployment.

4. Add Stockfish Engine Files:

   • You will need to download the Stockfish.js engine files. Place them directly into the public/ directory of your project. The application expects:
     • For Stockfish 17 Lite Single-Threaded WASM (Default, most compatible, used for Bot Play and default Review):
       • stockfish-17-lite-single.js
       • stockfish-17-lite-single.wasm
     • (Other versions as previously listed for Review: Lite MT, Large ST, Large MT, ASM.js, v6 Legacy)
   • Download these from a reliable source (e.g., the official Stockfish.js GitHub repository or a trusted mirror).
   • Note on Multi-Threaded Versions: To use the multi-threaded WASM versions for Review, your hosting environment must serve the correct Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers. See src/middleware.ts and firebase.json for examples.
   • Note on Large WASM Versions: These may be split into multiple .wasm part files. All parts must be in the public/ directory alongside the main .js file.

5. Run the development server:

   npm run dev
   # or
   # yarn dev
   # or
   # pnpm dev

   The application should now be running, typically on http://localhost:9002. To use Genkit flows locally (e.g., for bot image generation in admin), run the Genkit developer UI in a separate terminal:

   npm run genkit:watch 

   This usually starts on http://localhost:4000.

Project Structure

• src/app/[locale]/: Contains the Next.js App Router pages and layouts, supporting internationalization.
  • src/app/page.tsx: The root page (currently redirects to default locale or serves default locale content).
  • src/app/[locale]/page.tsx: The homepage for a given locale (references main image from Firebase Storage).
  • src/app/[locale]/game/[gameId]/page.tsx: The main online game page.
  • src/app/[locale]/puzzles/page.tsx: Puzzle solving page.
  • src/app/[locale]/play/bot/page.tsx: Play against AI bot page (handles bot move logic, including random moves for level 0).
  • src/app/[locale]/learning/page.tsx: Learning Center page, displays curated YouTube channels and their videos.
  • src/app/[locale]/review/[gameId]/page.tsx: Game review page.
  • src/app/[locale]/my-games/page.tsx: User's game history page.
  • src/app/[locale]/preferences/page.tsx: User preferences page.
  • src/app/[locale]/about/page.tsx: About & Contact page.
  • src/app/[locale]/login/page.tsx: User login page.
  • src/app/[locale]/register/page.tsx: User registration page.
  • src/app/[locale]/admin/: Admin panel pages (dashboard, bot management, contact messages, etc.).
  • src/app/actions/: Server Actions for backend logic (game actions, auth actions, admin actions, contact actions, youtubeActions).
• src/components/: Reusable UI components, categorized by game, layout, ui (ShadCN), admin, play/bot (including BotSettingsForm and BotBoard), providers.
• src/lib/: Utility functions, Firebase initialization (firebase.ts, firebase-admin.ts), chess utilities (chess-utils.ts), bot profile data (bot-profiles-data.json) and loader (bot-profiles.ts), learning content data (learning-content.ts).
• src/hooks/: Custom React hooks.
• src/types/: TypeScript type definitions.
• src/ai/: Genkit related files.
  • genkit.ts: Genkit initialization.
  • flows/: Genkit flows (e.g., generate-bot-image-flow.ts).
• messages/: JSON files for next-intl translations (e.g., en.json, es.json).
• public/: Static assets.
  • img/: General images (e.g., favicons). Bot avatar images are no longer primarily stored here.
  • img/bots/: This directory is now deprecated for storing generated bot images; images are in Firebase Storage.
  • sounds/: Sound effect files.
  • PWA manifest, Stockfish worker files (e.g., stockfish-17-lite-single.js).
• docs/: Project documentation files (ARCHITECTURE.md, BUGS.md, DONE.md, TODO.md, etc.).

Further Development

• Implement missing preferences (Piece Style actual visual change).
• Save bot games to "My Games" or a separate history.
• Enhance AI features using Genkit (e.g., puzzle hints).
• Refine UI/UX based on feedback.
• Improve PWA offline capabilities, especially for game review and bot play.
• Add functionality to mark contact messages as read/responded in admin panel.
• Optionally integrate a YouTube video player directly within the Learning Center instead of linking out.

---

Happy Coding!