Four in a Row

This repository contains two playable implementations of Four in a Row (Connect Four):

• a Python application with CLI and GUI front ends
• an HTML5/JavaScript browser version with an MCTS-based AI

Both versions implement the classic 7x6 game and focus on clear engine structure, testability, and documented architecture.

Repository Overview

Python

Path: python/

Highlights:

• command-line interface for human and engine-driven play
• graphical interface built with matplotlib
• multiple AI engines: random, minimax, negamax, alpha-beta, MCTS with UCB
• SGF import/export support
• pytest-based test suite

Quick start:

cd python
uv sync --dev
uv run python -m four_in_a_row

Launch the GUI:

cd python
uv run python -m four_in_a_row.gui

Run tests:

cd python
uv run pytest

See python/README.md for commands, engine options, GUI usage, and test details.

HTML5 / JavaScript

Path: javascript/html5/src/

Highlights:

• browser-based Connect Four with responsive board rendering
• independent human/AI configuration for both players
• AI powered by UCT / MCTS in a Web Worker
• unit tests with Vitest and end-to-end tests with Playwright

Quick start:

cd javascript/html5/src
npm install
node tests/server.js

Then open http://localhost:4173 in a browser.

Run tests:

cd javascript/html5/src
npm test
npm run test:e2e

See javascript/html5/src/README.md for browser, testing, and architecture details.

Project Structure

four_in_a_row/
├── README.md
├── python/
│   ├── four_in_a_row/
│   ├── tests/
│   └── doc/
└── javascript/
    └── html5/
        └── src/
            ├── js/
            ├── tests/
            └── doc/

Documentation

Repository documentation is organized per implementation:

• Python engine and architecture docs: python/doc/
• HTML5 engine and architecture docs: javascript/html5/src/doc/

Generated site output for the Python documentation is committed under python/site/.

Requirements

• Python version: 3.13+
• Python package manager: uv
• Node.js and npm for the browser version

On some Windows systems, node may resolve to Microsoft HPC tools instead of Node.js. If that happens, prepend C:\Program Files\nodejs to PATH before running npm-based commands.

Authors

See the AUTHORS files at the repository root and within each implementation.

License

This repository is licensed under the terms in LICENSE.