[refactor] Game log, persistence, demo mode, indicator LED, and documentation.
This commit is contained in:
@@ -1,10 +1,10 @@
|
||||
# 🕹️ Connect 4 AI: Grandmaster Edition (v2.5)
|
||||
# Connect 4 - ESP32
|
||||
|
||||
A high-performance Connect 4 implementation for the ESP32-C3 (RISC-V). This version features a "Killer Instinct" AI, human-like animations, and a real-time interrupt system.
|
||||
A Connect 4 game with AI for the ESP32-C3 (Lolin C3 Mini), using an 8x8 NeoPixel LED matrix and rotary encoder.
|
||||
|
||||
## 🛠 Hardware Configuration
|
||||
## Hardware
|
||||
|
||||
### 🔌 Pin Mapping (Lolin C3 Mini)
|
||||
### Pin Mapping (Lolin C3 Mini)
|
||||
|
||||
| Component | ESP32-C3 Pin | Function |
|
||||
| :------------------- | :----------- | :------------------- |
|
||||
@@ -13,38 +13,112 @@ A high-performance Connect 4 implementation for the ESP32-C3 (RISC-V). This vers
|
||||
| **Rotary Encoder B** | `GPIO 1` | Directional DT |
|
||||
| **Encoder Button** | `GPIO 2` | Selection/Abort (SW) |
|
||||
|
||||
### 📐 Physical Layout
|
||||
### LED Matrix Layout
|
||||
|
||||
- **Game Board:** 7 Columns x 6 Rows.
|
||||
- **Top Row (Row 0):** Interaction row (Selection & AI Thinking pulse).
|
||||
- **UI Border:** Row 1 and Column 7 (Blue frame, toggleable via `SHOW_BORDER`).
|
||||
- **Coordinate Formula:** $Index = (y \times 8) + x$
|
||||
The 8x8 matrix (64 LEDs) is used as follows:
|
||||
|
||||
---
|
||||
```
|
||||
Row 0: [ col0 ] [ col1 ] [ col2 ] [ col3 ] [ col4 ] [ col5 ] [ col6 ] [ indicator ]
|
||||
Row 1: [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ ---- ] [ border ]
|
||||
Row 2-7:[ game board: 7 columns x 6 rows ] [ border ]
|
||||
```
|
||||
|
||||
## 🧠 Advanced AI Features
|
||||
- **Row 0 (columns 0-6):** Interaction row. Shows the current column selection cursor and AI thinking animation (pulsing disc).
|
||||
- **Row 0 (column 7):** Game mode indicator LED (dim). Yellow = player is yellow vs AI, Red = player is red vs AI, Blue = two player, Off = demo.
|
||||
- **Row 1 + Column 7:** Blue border frame (toggleable via `SHOW_BORDER` build flag). Glows softly during demo and finished states.
|
||||
- **Rows 2-7, Columns 0-6:** The 7x6 game board. Yellow and Red discs.
|
||||
- **LED index formula:** `index = (y * 8) + x`
|
||||
|
||||
### 1. Offense-Priority Strategy
|
||||
## Game Modes
|
||||
|
||||
The AI follows a strict 3-phase move evaluation:
|
||||
Use the rotary encoder to select a mode, press the button to start:
|
||||
|
||||
1. **Lethal:** If the AI can connect four this turn, it takes the win immediately.
|
||||
2. **Defensive:** If the human player has a lethal move, the AI blocks it.
|
||||
3. **Strategic:** If no immediate wins exist, it runs a deep Minimax search.
|
||||
1. **Player vs AI (Yellow)** - Player plays yellow (first move), AI plays red.
|
||||
2. **Player vs AI (Red)** - AI plays yellow (first move), player plays red.
|
||||
3. **Two Player** - Two humans alternate turns. Yellow goes first.
|
||||
|
||||
### 2. High-Priority Interrupts
|
||||
### Demo Mode
|
||||
|
||||
The AI's single-core RISC-V processor is kept responsive via an "Abort Flag." Pressing the button or turning the encoder during an AI calculation (Demo or Playing) immediately kills the recursion and returns the user to the Menu.
|
||||
When idle (no input for the configured timeout), the board enters demo mode where two AI players play against each other automatically. To make games more interesting, the two demo players are assigned different skill levels (asymmetric ply depths), so games frequently end in a win rather than a draw. Press the button or turn the encoder to exit demo mode and return to the menu.
|
||||
|
||||
### 3. Evolution Mode
|
||||
### Animations
|
||||
|
||||
AI difficulty scales dynamically: $DynamicPly = BasePly + \lfloor \frac{DiscsOnBoard}{7} \rfloor$.
|
||||
- **Disc drop:** Discs fall from the top with accelerating speed.
|
||||
- **Column movement:** Discs slide across the top row to the selected column.
|
||||
- **AI thinking:** The disc in the selected column pulses while the AI calculates.
|
||||
- **Win:** The winning four discs flash while the rest of the board dims. Displayed for 30 seconds.
|
||||
- **Draw:** All discs blink on and off.
|
||||
|
||||
---
|
||||
## WiFi Admin Interface
|
||||
|
||||
## 🛠 Installation & Build
|
||||
The ESP32 creates a WiFi access point:
|
||||
|
||||
1. **Environment:** VS Code with PlatformIO.
|
||||
2. **Dependencies:** `FastLED`, `Encoder`, `Preferences`.
|
||||
3. **Build Flags:** - `-D SHOW_BORDER=1` (Enables blue frame)
|
||||
- `-D SHOW_BORDER=0` (Full-screen board mode)
|
||||
- **Network:** `Connect4-Config`
|
||||
- **Password:** Configured via `WIFI_PASSWORD` build flag (default: `youlose4`)
|
||||
- **Admin page:** Connect to the network and open `http://192.168.4.1`
|
||||
|
||||
### Settings (via web interface)
|
||||
|
||||
| Setting | Description |
|
||||
| :--------------- | :------------------------------------------------------- |
|
||||
| **Base AI Ply** | Search depth for the AI (1-10). Higher = stronger. |
|
||||
| **Brightness** | LED brightness (0-255). |
|
||||
| **Idle Timeout** | Seconds of inactivity before demo mode starts. |
|
||||
| **Blunders** | Reserved for future use. |
|
||||
| **Evolution** | Progressive difficulty: AI gets stronger as game goes on.|
|
||||
|
||||
Settings are saved to flash (NVS) and persist across reboots.
|
||||
|
||||
### Game Log
|
||||
|
||||
The web interface shows a log of the last N games (configurable via `MAX_GAME_LOG` build flag). Each entry shows the game type, AI level, winner, and the sequence of columns played. Games where a player beats the computer are highlighted in red. The game log is persisted to flash and survives reboots.
|
||||
|
||||
## Build & Upload
|
||||
|
||||
Requires [PlatformIO](https://platformio.org/) CLI or VS Code with PlatformIO extension.
|
||||
|
||||
```bash
|
||||
# Build
|
||||
pio run
|
||||
|
||||
# Upload to board
|
||||
pio run --target upload
|
||||
|
||||
# Monitor serial output
|
||||
pio device monitor
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
|
||||
- [FastLED](https://github.com/FastLED/FastLED) >= 3.6.0 - LED control
|
||||
- [Encoder](https://github.com/PaulStoffregen/Encoder) >= 1.4.4 - Rotary encoder input
|
||||
- Preferences (built-in) - Persistent settings storage
|
||||
- WiFi / WebServer (built-in) - Admin interface
|
||||
|
||||
### Build Flags
|
||||
|
||||
All configurable parameters are defined as `-D` flags in `platformio.ini`:
|
||||
|
||||
| Flag | Default | Description |
|
||||
| :--------------------- | :------ | :--------------------------------------------- |
|
||||
| `LED_PIN` | `4` | GPIO pin for NeoPixel data line |
|
||||
| `ENC_A` | `0` | GPIO pin for encoder CLK |
|
||||
| `ENC_B` | `1` | GPIO pin for encoder DT |
|
||||
| `ENC_SW` | `2` | GPIO pin for encoder button |
|
||||
| `SENSITIVITY` | `4` | Encoder steps per detent (higher = less sensitive) |
|
||||
| `SHOW_BORDER` | `1` | Show blue border frame (0 = off, 1 = on) |
|
||||
| `DEFAULT_LOOK_AHEAD` | `8` | Default AI search depth (plies) |
|
||||
| `DEFAULT_BRIGHTNESS` | `25` | Default LED brightness (0-255) |
|
||||
| `DEFAULT_IDLE_TIMEOUT` | `45` | Seconds before demo mode activates |
|
||||
| `MAX_GAME_LOG` | `5` | Number of games stored in the game log |
|
||||
| `WIFI_PASSWORD` | `youlose4` | Password for the WiFi access point |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/main.cpp Single-file application (all game logic, AI, LED, web server)
|
||||
platformio.ini Build configuration, pin mappings, and tunable parameters
|
||||
README.md This file - technical and practical information
|
||||
Background information.md How the AI works (suitable for all ages)
|
||||
CLAUDE.md AI assistant project context
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user