# 🕹️ Connect 4 AI: Master Edition (v2.0)

A high-performance, feature-rich Connect 4 implementation for the ESP32-C3. This version features a "living" AI that evolves as you play, human-like movement animations, and a robust win-detection engine.

---

## 🛠 Hardware Configuration

### 🔌 Pin Mapping (Lolin C3 Mini)

| Component            | ESP32-C3 Pin | Function         |
| :------------------- | :----------- | :--------------- |
| **NeoPixel Matrix**  | `GPIO 4`     | Data Input (DIN) |
| **Rotary Encoder A** | `GPIO 0`     | Directional CLK  |
| **Rotary Encoder B** | `GPIO 1`     | Directional DT   |
| **Encoder Button**   | `GPIO 2`     | Selection (SW)   |

### 📐 Physical Layout

The project is optimized for an 8x8 NeoPixel Matrix (65mm x 67mm).

- **Row 0:** Interaction & AI Decision Visualization.
- **Row 1:** Static Blue UI border.
- **Rows 2-7:** Active $7 \times 6$ game board.
- **Status Column:** Far right column (Index 7) manages UI framing and "Glow" effects.

---

## 🧠 Advanced AI & Logic Features

### 1. Progressive Difficulty (Evolution Mode)

To keep the game challenging and the CPU efficient, the AI search depth (Ply) scales as the board fills.

- **Formula:** $DynamicPly = BasePly + \lfloor \frac{DiscsOnBoard}{7} \rfloor$
- **Benefit:** The AI is "casual" in the opening but becomes a "Grandmaster" in the endgame when tactical precision is vital.

### 2. Intelligent Win Detection & Flashing

The win-engine has been refactored to prevent "color ghosting."

- **Winner Locking:** The `scanBoard()` function returns the specific ID of the winner (1 for Yellow, 2 for Red).
- **Flashing Accuracy:** The final animation uses this ID to ensure the winning 4-in-a-row flashes in the **correct player's color**, regardless of whose turn it was when the game ended.

### 3. Smart Watchdog (Tiered Timeout)

The game respects your "thinking time" by using a tiered idle-timeout system:

- **Menu/Finished State:** Standard timeout (e.g., 60s).
- **Playing State:** **Double Timeout** (e.g., 120s). This gives human players more time to analyze complex boards before the game auto-resets to Demo Mode.

### 4. Strategic Blunder Injection

To ensure Demo Mode doesn't end in an infinite loop of draws, a 20% "Blunder Chance" is injected. This forces the AI to occasionally make a human-like mistake, creating openings for a definitive winner.

---

## 📖 Code Architecture & Modules

### 🔄 State Machine

The core loop manages five distinct states:

1. **MENU:** Mode selection and board reset.
2. **PLAYING:** Active turn-based logic with gravity-accelerated drop animations.
3. **FINISHED_WIN:** Locks the winner ID and flashes the winning segment.
4. **FINISHED_DRAW:** Blinks the entire board to signify a stalemate.
5. **DEMO:** Auto-plays with randomized difficulty (Ply 3-6) and mandatory blunder logic.

### 🌐 Web Administration Portal

Accessible via the **"Connect4-Config"** AP at `192.168.4.1`.

- **Base Ply:** Sets the starting difficulty level.
- **Brightness:** Global LED intensity (0-255).
- **Evolution Toggle:** Turn on/off the progressive difficulty scaling.
- **Blunder Toggle:** Allow the AI to make mistakes during Human-vs-AI matches.

---

## 🛠 Installation

1. **Environment:** Use VS Code with the **PlatformIO** extension.
2. **Dependencies:** `FastLED`, `Encoder`, `Preferences`.
3. **Build Flag:** Define your WiFi password in `platformio.ini`: `-D WIFI_PASSWORD=\"your_password\"`.
4. **Flash:** Upload to your ESP32-C3 and enjoy the ultimate desktop Connect 4 experience.