# Connect 4 - ESP32

A Connect 4 game with AI for the ESP32-C3 (Lolin C3 Mini), using an 8x8 NeoPixel LED matrix and rotary encoder.

## Hardware

### 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/Abort (SW) |

### LED Matrix Layout

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    ]
```

- **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`

## Game Modes

Use the rotary encoder to select a mode, press the button to start:

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.

### Demo Mode

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.

### Animations

- **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

The ESP32 creates a WiFi access point:

- **Network:** Configured via `WIFI_SSID` build flag (default: `Connect4`)
- **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**     | AI randomly picks a bad move at the configured chance %. |

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                 |
| `DEMO_RESET_PAUSE`     | `30000`    | Milliseconds before finished game enters demo      |
| `MAX_GAME_LOG`         | `5`        | Number of games stored in the game log             |
| `WIFI_SSID`            | `Connect4` | SSID for the WiFi access point                     |
| `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
```
