♟️ Chess — Java Desktop Chess Game

A fully-featured desktop chess game built with Java and JavaFX.
Implements all standard chess rules, a move-history tree, undo/redo, save/load, and a 30-second per-turn timer.

---

📌 Table of Contents

• About the Project
• Features
• Architecture & Data Structures
• Tech Stack
• Getting Started
• Project Structure
• How to Play
• Known Limitations
• What I Learned

---

📖 About the Project

This project was built as a Data Structures university assignment, with the goal of applying tree-based data structures in a real, interactive application.

Rather than a simple two-player board, the focus was on correctly modeling game state as a tree, where each node represents a board snapshot after a move. This allows navigating backwards and forwards through the entire game history — similar to how professional chess software works.

---

✨ Features

Feature	Description
♟️ Full Chess Rules	All pieces move correctly: Pawn, Knight, Bishop, Rook, Queen, King
🔀 Special Moves	En Passant, Castling, Pawn Promotion
👑 Check & Checkmate	Real-time detection with game-over alert
🤝 Stalemate Detection	Detects draws when no legal moves exist
⏱️ 30-Second Timer	Per-turn countdown; losing on timeout
↩️ Undo / Redo	Navigate back and forward through move history
🌳 Move Tree Viewer	Visual tree of all moves played, click any node to jump to that state
💾 Save / Load Game	Serializes full game tree to file.json using Gson
🗑️ Captured Pieces	Displays all captured pieces on both sides of the board
🎵 Background Music	Plays audio during the game using JLayer
🔄 Reset	Restart the game from initial position at any time

---

🏗️ Architecture & Data Structures

The core design decision of this project is modeling game history as a Tree data structure.

Game State Tree
──────────────
         [Start]
            │
     [White: e2→e4]
            │
     [Black: d7→d5]
          /    \
  [White: c2→c4]  [White: Nc3]
        │
  [Black: Bishop]
        ...

Key Classes

Class	Role
Tree	Manages the root and provides save/load/display of the game tree
TreeNode	A single game state — stores the full 8×8 board snapshot, move metadata, and child nodes
Game	Initializes the board, handles undo/redo stack, and wires all UI controls
CustomButton	Base class for all board squares; handles move validation, check detection, and piece movement
Pawn / Knight / Bishop / Rook / Queen / King	Each extends CustomButton and implements getRange() for legal move calculation
AlertBox	Modal dialogs for game-over messages and pawn promotion choice

How Move Validation Works

1. When a piece is clicked, getRange() calculates all candidate destination squares.
2. Before highlighting a square, possibleMove() simulates the move on a temporary board and checks whether it leaves the player's own King in check.
3. Only moves that pass this test are shown as valid.
4. Check is detected by computing all opponent moves via checkKingMove() / updateRange().
5. Checkmate/Stalemate is confirmed by checkMate() / staleMate() — which verify no legal moves exist.

---

🛠️ Tech Stack

• Language: Java 17
• UI Framework: JavaFX 17.0.2
• Build Tool: Apache Maven
• JSON Serialization: Google Gson
• Audio: JLayer (MP3 playback via javazoom)
• Module System: Java Platform Module System (JPMS) via module-info.java

---

🚀 Getting Started

Prerequisites

• Java 17 or higher
• Apache Maven 3.6+

Run

git clone https://github.com/your-username/Chess.git
cd Chess/Chess
mvn clean javafx:run

Note: The project currently references some asset files using absolute local paths (e.g., piece images and the background music file). Before running, update the file paths in App.java and Game to point to your local asset directory, or place assets relative to the project root.

---

📁 Project Structure

Chess/
├── Chess/
│   ├── pom.xml                          # Maven build configuration
│   └── src/
│       └── main/
│           └── java/
│               ├── module-info.java     # JPMS module descriptor
│               └── com/example/chess2/
│                   ├── App.java         # Main application + all game logic
│                   │                    # (Tree, TreeNode, Game, CustomButton,
│                   │                    #  all piece classes, enums)
│                   ├── AlertBox.java    # Modal dialogs (game over, promotion)
│                   ├── Test.java        # Standalone audio test
│                   └── fxStyle.css      # JavaFX stylesheet
└── file.json                            # Saved game tree (auto-generated)

---

🎮 How to Play

1. White always moves first. Click a piece to see its legal moves highlighted in blue.
2. Click a highlighted square to move there.
3. Each player has 30 seconds per turn. Running out of time forfeits the game.
4. Use the toolbar buttons:
   • Undo — revert the last move
   • Redo — re-apply an undone move
   • Show Tree — open the move history tree in a new window; click any node to jump to that game state
   • Save — write the current game tree to file.json
   • Load Data — load a previously saved game from file.json
   • Reset — restart from the beginning
5. When a Pawn reaches the opposite end, a promotion dialog appears to choose the new piece.

---

⚠️ Known Limitations

• Hardcoded absolute paths for image and audio assets — needs refactoring to use classpath resources.
• All classes reside in a single App.java file — intended as a learning project; production code would split these across separate files.
• No AI opponent — this is a two-player local game only.
• pom.xml references HelloApplication as the main class (leftover from project template); the actual entry point is App.

---

📚 What I Learned

• Modeling complex application state as a tree data structure and implementing tree traversal for undo/redo and game replay.
• Applying OOP principles — inheritance and polymorphism — to cleanly model chess pieces.
• Working with JavaFX for building interactive desktop UIs: event handling, layout management, custom styling.
• Serializing and deserializing complex object graphs with Gson.
• Using the Java Module System (JPMS) to manage dependencies between modules.
• Thinking carefully about move validation — specifically detecting check and checkmate by simulating moves before committing them.

---

Made with ☕ and Java