# Connect Four: ESP32-C3 LED Edition

A hardware-based Connect Four game featuring an 8x8 NeoPixel matrix, a strategic Minimax AI, and a dynamic "Attract Mode" for public display.

## How the Program Works

The program is built as a **Finite State Machine (FSM)**.
It manages the game flow by transitioning between distinct states based on user input, game outcomes, or inactivity timers.

### 1. Game States

- **Menu**: Displays stylized Roman numerals (**I** or **II**) to select between Single Player or Two Player modes.
- **Game Play**: The main loop handles the real-time gravity of falling discs, encoder tracking for column selection, and the hand-off between the human and the AI.
- **Game Over**: Triggered when a win or draw is detected. It "locks" the board, dims the background discs to 15% intensity, and flashes the winning line.
- **Demo Mode**: Triggered after 60 seconds of inactivity. The AI plays against itself to act as a visual "attract mode."

### 2. Win Detection Logic

To ensure 100% accuracy, the program performs a synchronous, multi-directional scan of the 7x6 grid after every single move.
It checks for four matching non-zero values in the following patterns:

- **Horizontal**: `[column] [row]` to `[column + 3] [row]`
- **Vertical**: `[column] [row]` to `[column] [row + 3]`
- **Diagonal Up**: `[column] [row]` to `[column + 3] [row + 3]`
- **Diagonal Down**: `[column] [row]` to `[column + 3] [row - 3]`

---

## The AI: Strategic Minimax

The computer opponent uses the **Minimax Algorithm**, a classic artificial intelligence method for zero-sum games.

### 1. Look-Ahead (Depth Search)

The AI does not just look at the current board; it simulates the game **6 to 8 moves into the future**.
It explores a "tree" of possibilities: _"If I play here, and the player plays there, then I can play here..."_

### 2. Alpha-Beta Pruning

Because searching millions of possibilities would be too slow for a microcontroller, we use **Alpha-Beta Pruning**.
This allows the AI to "prune" (ignore) branches of the game tree that are mathematically
guaranteed to be worse than moves it has already found, significantly speeding up the calculation.

### 3. Immediate Threat Reaction

To prevent the AI from being "distracted" by deep strategies while missing a simple win or loss,
we implemented a high-priority **Reaction Scanner**:

- **Kill Move**: If the AI can win in exactly one move, it takes it immediately.
- **Block Move**: If the player is one move away from winning (3-in-a-row), the AI identifies the threat and blocks it regardless of the Minimax score.

### 4. Controlled Randomness (Demo Mode)

To keep the Demo Mode interesting for spectators, the AI has a 25% chance to ignore the "perfect" move and pick a random column.
This ensures that every demo game is unique and not a repetitive loop of the same strategy.

---

## Technical Specifications

### Hardware Pins (Lolin C3 Mini)

| Component   | Pin | Function                                 |
| :---------- | :-- | :--------------------------------------- |
| **LED_PIN** | 4   | WS2812B NeoPixel Data                    |
| **ENC_A**   | 0   | Rotary Encoder Phase A                   |
| **ENC_B**   | 1   | Rotary Encoder Phase B                   |
| **ENC_SW**  | 2   | Switch (Includes 50ms Software Debounce) |

### NeoPixel Grid Layout

The 8x8 matrix is mapped as follows:

- **Play Area**: 7 columns (0-6) by 6 rows (0-5).
- **Boundaries**: Row 1 and Column 7 are lit in **Blue** to mark the board limits.
- **Indicators**: The top-right pixel (7,0) pulses in the computer's color while it is "thinking."
- **Glowing Frame**: During Demo mode, the blue borders pulse with a white "glow" effect using a `beat8` sine wave to indicate autonomous play.

---

## Controls & Interaction

- **Rotate Encoder**: Move the cursor (top row) to select a column.
- **Press Encoder Button**: Drop a disc.
- **Full Column Warning**: If you attempt to play in a full column, the selection disc will blink rapidly, and the move will be ignored.
- **Reset**: After a game ends, press the button once to return to the Menu.

## Build Flags (platformio.ini)

Tweak the game performance without changing the source code:

- `IDLE_TIMEOUT`: Time (ms) before Demo Mode starts.
- `DEMO_RESET_PAUSE`: Delay (ms) between games in Demo Mode.
- `DEBOUNCE_DELAY`: Sensitivity of the encoder button.
- `BRIGHTNESS`: Global brightness of the NeoPixels.