87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# 🕹️ 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.
|