Connect Four is played on a 7 × 6 board (7 columns, 6 rows). Two players alternately drop a disc into one of the seven columns; a disc falls to the lowest empty cell of that column. The first player to connect four consecutive discs horizontally, vertically, or diagonally wins. If the board fills with no winner, the game is a draw.
This repository contains a modular Python implementation of a Connect Four game engine and a suite of seedable AI agents, alongside a responsive full-stack Web GUI sandbox for live agent evaluations.
To verify core engine correctness, win/draw state transitions, and agent decision logic:
python3 -m unittest discover -s testsRun the main script to play against the AI agents or local players:
- Player vs Player (Local):
python3 main.py --mode player-vs-player
- Player vs Random AI:
python3 main.py --mode player-vs-random
- Player vs Rule-Based AI:
python3 main.py --mode player-vs-rulebased
- Player vs Minimax AI:
python3 main.py --mode player-vs-minimax
To simulate games between agents with a deterministic seed for evaluation:
python3 main.py --mode minimax-vs-random --seed 42 --delay 0.5| Deliverable / Asset | Location / Link | Description |
|---|---|---|
| Live Hosted Sandbox | GitHub Pages Deployment | Interactive full-stack web GUI for real-time play and evaluation |
| Demonstration Video | Google Drive Walkthrough | Walkthrough demonstrating CLI runs, unit tests, and agent gameplay |
| Project Report | assets/report.pdf | Algorithm designs, evaluations, and analysis |
| Evaluation Data | evaluation_results.md · evaluation_results.json | Compiled pairing metrics, win rates, and step logs |
| Test Suite | tests/test_engine.py · tests/test_agents.py | Unit tests verifying core game rules and agent behaviors |
- Game State Engine: ConnectFourAI/engine.py — 2D board state, gravity-drops, horizontal/vertical/diagonal win scanners, deep clone state.
- Abstract Base Agent: ConnectFourAI/agents/base.py — Define contract for agents.
- Random Agent (Agent 1): ConnectFourAI/agents/random_agent.py — Seedable stochastic action selection.
- Rule-Based Agent (Agent 2): ConnectFourAI/agents/rule_based_agent.py — Heuristic priority rules (Win, Block, Center preference, Line builder).
-
Minimax Agent (Agent 3): ConnectFourAI/agents/minimax_agent.py — Depth-limited adversarial search with
$\alpha$ -$\beta$ pruning and heuristic evaluation.
- Implementation File: ConnectFourAI/engine.py
- Details:
- Board Representation: 6 rows × 7 columns grid (0 = empty, 1 = Player 1, 2 = Player 2).
- Gravity Simulation: Disc placement slides to the lowest empty index of the column.
- API Features: Out-of-bounds validation, legal moves generator, deep cloning for forecasting, and win scanners in all 4 planes.
- Implementation Files:
- ConnectFourAI/agents/random_agent.py (Agent 1 - Stochastic selection)
- ConnectFourAI/agents/rule_based_agent.py (Agent 2 - Heuristic priority matching)
- ConnectFourAI/agents/minimax_agent.py (Agent 3 - Adversarial tree search)
- Runner Script: evaluate.py (logs decision times using
time.perf_counter()) - Evaluation Data: evaluation_results.md · evaluation_results.json
- Protocol: 30 games per pairing, alternating starting player, seeded agents for reproducible actions.
| Agent | Wins | Win Rate | Draws | Avg Decision Time |
|---|---|---|---|---|
| Random | 1/30 | 3.33% | 0 | 0.0012 ms |
| Rule-Based | 29/30 | 96.67% | 0 | 0.2555 ms |
| Agent | Wins | Win Rate | Draws | Avg Decision Time |
|---|---|---|---|---|
| Rule-Based | 3/30 | 10.00% | 1 | 0.2719 ms |
| Minimax (depth 4) | 26/30 | 86.67% | 1 | 33.4204 ms |
| Agent | Wins | Win Rate | Draws | Avg Decision Time |
|---|---|---|---|---|
| Minimax (depth 4) | 30/30 | 100.00% | 0 | 42.5260 ms |
| Random | 0/30 | 0.00% | 0 | 0.0021 ms |
- Artifact: assets/report.pdf
- Walkthrough Link: Watch the Walkthrough Video
Computers rely on Pseudo-Random Number Generators (PRNGs) which are mathematical algorithms (e.g., Python's Mersenne Twister or JavaScript's Linear Congruential Generator) that compute sequences of numbers starting from an initial integer called a seed. Because these algorithms are fully deterministic, using the same seed ensures the exact same sequence of choices is generated every time.