A browser based Connect Four game where the AI opponent thinks before it makes a move!
Note: While this project was primarily vibe-coded, all code was manually typed, reviewed, and adjusted as needed by myself.
I built this project to develop my Python skills and learn how to create a game where I can play against an AI opponent that uses actual logic before acting.
It's the classic Connect Four game where pieces are dropped into a column, and the first player to get four in a row wins. The twist is that you're playing against a computer opponent that looks several moves into the future** before it decides where to go. It isn't guessing and it isn't following a script. It plays out possible pathways, scores them, and picks the one that works out best for it.
On top of that, there's an optional AI coach that explains why the computer made each move in plain English.
| ๐ซก | Pick a difficulty: Easy, Medium, or Hard. |
| ๐ | Click any column to drop your red piece. |
| ๐ค | The AI answers with a yellow piece a split second later. |
| ๐ | Read the panel under the board to see how many positions the AI checked and why it chose that column. |
| ๐ซถ๐ป | Click Ask the AI coach if you want a friendlier explanation. |
Imagine you're about to make a move. A good player doesn't just ask "what looks good right now?" They ask:
"If I go here, what's the smartest thing my opponent could do back? And what would I do after that?"
That's exactly what my AI opponenet does. It uses an algorithm called minimax:
- On its own turn, it picks the move with the highest score.
- On your turn, it assumes you'll pick the move that's worst for it.
Assuming you'll always play perfectly might sound pessimistic, but it's what makes the AI hard to trick. It never walks into a trap hoping you won't notice.
There are way too many possibilities for wining a game, so it only looks a few moves ahead and then makes an educated guess based off the current board status. The computer is programed to view winning the game in tiers it can understand. It views the rewards as shown below:
| Pattern on the board | What the AI thinks about it |
|---|---|
| Four in a row | ๐ A win. Nothing beats this. |
| Three in a row with an open space | ๐ One move away from winning |
| Two in a row with room to grow | ๐ A decent start |
| Pieces in the middle column | ๐ The center is part of the most winning lines |
| You having three in a row | ๐จ Danger! Block it โ and this matters slightly more than building its own threat |
I also added a speed trick called alpha-beta pruning. If the AI already knows a move is good, it stops wasting time on moves that clearly can't beat it. The final choice is exactly the same, it just gets there much faster.
| Level | How far ahead it looks | Positions it checks | What it feels like |
|---|---|---|---|
| ๐ข Easy | 1 move | ~8 | Makes random moves. Very beatable. |
| ๐ก Medium | 4 moves | ~500 | Blocks your obvious threats and sets up its own. |
| ๐ด Hard | 6 moves | ~3,000 | Very tough, the computer views you as a threat. |
flowchart TD
A["๐ฑ๏ธ You click a column<br/>(game.js)"] -->|"POST /api/move"| B["๐ Flask server<br/>(app.py)"]
B --> C["๐ Rules engine<br/>(game/board.py)"]
B --> D["๐ง Minimax AI<br/>(game/ai.py)"]
D --> C
B --> E["๐ฌ Coach<br/>(game/coach.py)"]
E -.->|"only if an API key is set"| F["โจ OpenAI API"]
B -->|"JSON"| A
I kept each part in its own file with its own job:
| File | Its one job |
|---|---|
game/board.py | The rules. Is this move legal? Did someone win? |
game/ai.py | The brain. Which column should the computer play? |
game/coach.py | The explainer. Why did it play that? |
app.py | The messenger between the browser and the game. |
templates/ and static/ | What you see and click on. |
The rules file (board.py) doesn't know a website exists at all. This means that the game logic can be tested without starting a server, and I could reuse it for a totally different version of the game later.
The quickest way is GitHub Codespaces: click the green Code button above โ Codespaces โ Create codespace on main. Everything installs itself.
To run it on your own computer instead:
git clone <repository URL>
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.pyThen open http://localhost:5000 in your browser.
๐ก In Codespaces,
localhostwon't work from your own browser. Go to the Ports tab at the bottom of VS Code and click the ๐ globe icon next to port 5000.
๐ Words I had to learn while building this (click to open)
| Term | What it means in plain English |
|---|---|
| Minimax | Pick your best move while assuming your opponent always picks their best move back. |
| Alpha-beta pruning | Skip checking moves that can't possibly change the final decision. |
| Heuristic | An educated guess used when calculating the perfect answer would take too long. |
| Ply | One move by one player. "Looking 4 plies ahead" means my move, your move, my move, your move. |
| Recursion | A function that calls itself to solve a smaller version of the same problem. |
| Flask | A Python tool that turns functions into web pages and web addresses. |
| API route | A web address the browser sends data to, like /api/move. |
| Session | A small, signed piece of data that remembers your game between clicks, so you can't cheat by editing it. |
| Environment variable | A setting stored outside the code. It's how secrets like API keys stay out of GitHub. |
