Memory Matching Game

A highly polished, visually premium Memory Matching Game built with Java Swing (Java 17). The application features a curated dark-theme look, customizable setup options, career statistics tracking, and persistent leaderboard score listings.

---

✨ Features

• Dynamic Board Sizes: Play on 4x4 (16 cards), 6x6 (36 cards), or 8x8 (64 cards) grids with dynamic visual scaling to prevent text clipping.
• Preview Memorization Phase: Decoupled difficulty levels that control memorization countdowns before cards flip down:
  • Easy: 5 seconds preview
  • Medium: 3 seconds preview
  • Hard: 1 second preview
• Theme Selection: Choose from 5 different themes containing 32 unique, Unicode-safe text symbols:
  • Alphabets
  • Animals
  • Food
  • Vehicles
  • Emoji
• Game Controls: Fully integrated Pause / Resume overlays, Restart board shuffling, and Hint stubs.
• Dynamic Score & Stats:
  • Score calculates in real-time using the formula: score = Math.max(0, (remainingTime * 10) - moves).
  • Dynamic game timers scaling with board sizes (180s for 4x4, 300s for 6x6, and 480s for 8x8).
• Rank Achievement System: Automatically assigns ranks on victory:
  • Gold: Score >= 400
  • Silver: Score >= 250
  • Bronze: Score < 250
• Leaderboard and High Score: Persistent tracking of the Top 10 scores sorted descending, including a golden "NEW HIGH SCORE!" notification.
• Statistics Dashboard: Real-time career stats tracking Games Played, Wins, Losses, Total Moves, Best Score, and calculated Win Rate.

---

🛠 Technologies Used

• Core Language: Java 17
• GUI Framework: Java Swing & AWT (pure layout managers, custom button renderers, look-and-feel lookups)
• Audio Engine: Java Sound API (javax.sound.sampled)
• Persistence: Plain text CSV files (highscore.txt, leaderboard.txt, statistics.txt)

---

🏛 Object-Oriented Design (OOP) Concepts

1. Model-View-Controller (MVC) Pattern:
   • Model: Encompasses game entities (Card, GameBoard, GameSession, PlayerStats, ScoreRecord) representing current configurations and states.
   • View: Manages panels layout (GamePanel, SetupPanel, LeaderboardPanel, StatsPanel, CardButton) and rendering styling.
   • Controller: Triggers flow controls (GameController, NavigationController, AudioController) updating session data and coordinating screen switches.
2. Encapsulation: Strict accessor protections (private fields, clean public getters/setters) to prevent outer state mutations.
3. Enums: Strongly typed collections (Theme, Difficulty, BoardSize) mapping constant variables to properties.
4. Inheritance & Polymorphism: Custom GUI components inheriting from JButton (CardButton) and JPanel views.

---

📂 Folder Structure

e:\projects\game
├── data/                       # Local text file storage
│   ├── highscore.txt
│   ├── leaderboard.txt
│   └── statistics.txt
└── src/
    └── com/
        └── memorygame/
            ├── Main.java       # Main entry point
            ├── controller/     # MVC Controllers
            ├── model/          # Domain Models
            ├── service/        # Persistence Services
            ├── util/           # Mathematical & Theme helpers
            └── view/           # Custom JPanels and JButtons

---

🚀 How To Run

Prerequisites

• Java Development Kit (JDK) 17 or higher installed.
• PowerShell or command prompt.

1. Compile the Project

Open your terminal at the root of the directory and run:

javac -encoding UTF-8 -d bin (Get-ChildItem -Path src -Filter *.java -Recurse | Select-Object -ExpandProperty FullName)

2. Run the Game

Execute the compiled entry point:

java -cp bin com.memorygame.Main

3. Run Verification Tests

To run automated test suites programmatically:

# Verify card shuffling & pairing
java -cp bin com.memorygame.TestBoardGen

# Verify click selections & mismatch timer
java -cp bin com.memorygame.TestMatchingLogic

# Verify score math, timers, & pause states
java -cp bin com.memorygame.TestGameSystems

# Verify persistence, sorting, & file loading
java -cp bin com.memorygame.TestPersistence

---

🔮 Future Enhancements

• Image Textures Theme Integration: Load physical .png or .jpg card graphics in addition to unicode text symbols.
• Sound Effects Engine: Connect .wav clips to trigger audio on card clicks, flips, match, mismatch, wins, and timeouts.
• Dynamic Theme Additions: Create a settings menu to load custom theme lists dynamically from external text files.

---

✍️ Author

• Rajat Biradar - Memory Matching Game - GitHub