# 🕹️ Connect 4 AI: Master Edition

A high-performance Connect 4 implementation for ESP32-C3 and 8x8 WS2812B matrices. Features dynamic difficulty scaling, "humanized" AI movement, and a mobile-friendly web administration portal.

---

## 🛠 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 Dimensions

Designed for standard 8x8 matrix modules (approx. 65mm x 67mm).

- **Top Row (0):** Interaction and AI decision visualization.
- **Game Board:** Standard $7 \times 6$ grid.
- **UI Borders:** Fixed blue frame for visibility.

---

## 🧠 Advanced AI Features

### 1. Progressive Difficulty (Evolution Mode)

The AI search depth (Ply) increases as the board fills. This ensures the AI is fast in the opening and lethal in the endgame.

- **Formula:** $DynamicPly = BasePly + \lfloor \frac{DiscsOnBoard}{7} \rfloor$
- **Benefit:** High-level tactical precision exactly when the game becomes critical.

### 2. Strategic Blunder Injection

To avoid endless stalemate draws between high-level AIs, a "Blunder" logic is used.

- **Demo Mode:** Always active; 20% chance to make a suboptimal move.
- **Player Mode:** Toggleable via Web Portal to make the AI more "human."

### 3. Alpha-Beta Pruning & Column Ordering

The engine evaluates the center column first. This triggers pruning earlier in the search tree, skipping millions of unnecessary calculations and keeping the ESP32-C3 responsive.

---

## 📖 Code Architecture Details

### 🔄 State Machine

The software cycles through states:

- **MENU:** Select mode using the rotary encoder.
- **PLAYING:** Manages player turns and the gravity-acceleration drop animation.
- **DEMO:** Auto-starts after inactivity. Randomizes Ply (3-6) and enforces blunders to ensure definitive game results.

### 🎨 Rendering & Mapping

The `getIdx(x, y)` function maps the 2D game board to the 1D NeoPixel array. The `updateThinkingVisuals()` function provides real-time feedback of the AI's internal search process by moving a pulsing disc across the top row.

---

## 🌐 Web Admin Portal

Connect to the **"Connect4-Config"** Access Point to adjust:

- **Base Ply:** Minimum search depth.
- **Brightness:** Global LED intensity.
- **Idle Timeout:** Inactivity period before Demo Mode.
- **Toggles:** Enable/Disable Blunders and Evolution Mode.

---

## 🛠 Setup & Installation

1. Install **PlatformIO**.
2. Add dependencies: `FastLED`, `Encoder`.
3. Set your WiFi Password in `platformio.ini`: `-D WIFI_PASSWORD=\"your_pass\"`.
4. Upload to ESP32-C3.