DeepFive is a modern C++ implementation of Gomoku (Five-in-a-Row) featuring an intelligent bot engine that combines strategic MCTS planning with tactical forced-win detection, all wrapped in Bobcat UI user interface.
In Bot vs Bot mode, real-time win rate calculation will be paused to save computational overhead.
Funnel Decision Model
DeepFive's AI follows a multi-stage decision pipeline:
- Opening Book: Optimal start (Tengen)
- Instant Win/Loss: Direct win detection and immediate threat blocking
- Tactical Search: VCF (Victory by Continuous Four) and VCT (Victory by Continuous Three)
- Strategic Search: Monte Carlo Tree Search (MCTS) for long-term planning
Difficulty Modes
- Instant: Lightning-fast responses (~100ms) for casual play
- Thinking: Balanced depth and speed (1-2s), default mode
- Pro: Deep analysis (5-10s) for maximum strength
- Auto: Dynamic time allocation based on game stage and board complexity
- Tournament Mode: Self-play capability with candidate move visualization
Search Capabilities
- Parallel VCF search using both BFS and DFS strategies
- Path reconstruction for forced sequences
- Board pattern recognition and threat detection
- Efficient move ordering and pruning
- OpenGL Canvas: Smooth, hardware-accelerated board rendering
- Interactive Gameplay: Click-to-place stones with visual feedback
- Side Panel Analytics:
- Current player indicator
- Real-time Win rate estimation
- Current Algorithm Stage (MCTS, VCF, VCT, etc.)
- Simulation statistics (Count and SPS)
- Visual Debugging: Real-time rendering of candidate moves and their evaluation scores during self-play analysis
- Responsive Design: Clean, intuitive layout with FLTK widgets
- Cross-platform: Runs on macOS and Linux
Before building DeepFive, ensure you have:
- C++ Compiler: GCC 7+, Clang 5+, or MSVC 2017+ with C++17 support
- Bobcat UI: Fast Light Toolkit for cross-platform GUI development (Note: Please use the included Bobcat UI library due to custom modifications; the STEAMplug version is not supported)
- Make: Build automation tool
- Docker (optional): For containerized deployment
# Clone the repository
git clone https://github.com/MacroXie04/DeepFive.git
cd DeepFive
# Build the project
make
# Run the game
make runThe application will launch in a new window. Click on the board to place your stone, and the AI will respond automatically.
DeepFive includes Docker support with X11 forwarding via Xpra:
# Build the Docker image
docker build -t deepfive .
# Run the container
docker run -d -p 8964:8964 deepfive
# Connect with Xpra client
xpra attach tcp://localhost:8964Note: Install Xpra client on your host machine to view the GUI:
- macOS:
brew install xpra - Ubuntu/Debian:
sudo apt-get install xpra
Gomoku is played on a 15×15 grid. Two players alternate placing stones (black and white) on empty intersections. The first player to form an unbroken line of five stones horizontally, vertically, or diagonally wins the game.
- Left Click: Place your stone on an empty intersection
- Game Start: Human plays as Black (goes first), AI plays as White
- Auto-response: AI automatically calculates and plays its move after you
Side Panel Information:
- Current Player: Whose turn it is (Human/AI)
- Win Rate: AI's estimated probability of winning (0-100%)
- Algorithm: Current reasoning stage (e.g., MCTS, VCF, Block Threat)
- Simulations: Number of rollouts and simulation speed (SPS)
Difficulty Selection:
- Choose your difficulty level before the game starts
- Instant: Great for learning and quick games
- Thinking: Balanced challenge for most players
- Pro: Prepare for a serious match
- Auto: Let the AI decide based on game complexity
DeepFive/
├── src/
│ ├── core/ # Board representation and game logic
│ │ ├── board.h/cpp # Board state, move validation, win detection
│ ├── bot/ # AI engine implementation
│ │ ├── bot.h/cpp # Main bot interface and decision logic
│ │ ├── mcts.h/cpp # Monte Carlo Tree Search engine
│ │ ├── heuristics.h/cpp # Evaluation functions and patterns
│ │ └── benchmark.h # Performance testing utilities
│ ├── search/ # Tactical search algorithms
│ │ ├── ForcedBFS.h/cpp # Breadth-first VCF solver
│ │ ├── ForcedDFS.h/cpp # Depth-first VCF solver
│ │ ├── ForcedSearchNode.h/cpp # Search tree node representation
│ │ └── PathReconstruction.h/cpp # Solution path extraction
│ ├── game/ # Game state management
│ │ └── game.h/cpp # Game controller and flow
│ ├── ui/ # User interface components
│ │ ├── main_window.h/cpp # Main application window
│ │ ├── gomoku_canvas.h/cpp # OpenGL board rendering
│ │ ├── side_panel.h/cpp # Statistics panel
│ │ └── components.h/cpp # UI helper components
│ └── main.cpp # Application entry point
├── bobcat_ui/ # Custom UI component library
│ └── *.h # FLTK widget wrappers and utilities
├── test/ # Unit and integration tests
│ ├── test_board.cpp # Board logic tests
│ └── test_bot.cpp # AI engine tests
├── Makefile # Build configuration
├── dockerfile # Docker containerization
└── README.md # This file
Bot::chooseMove():
1. Instant Response
├─> Opening Book (Tengen)
├─> Direct Win (Five-in-a-row)
└─> Critical Block (Stop opponent's Five)
2. Tactical Analysis
├─> Double Threat Detection
├─> VCF Search (Victory by Continuous Four)
└─> VCT Search (Victory by Continuous Three, Tournament mode)
3. Strategic Search (MCTS)
├─> Initialize search tree
├─> Iterative UCT simulation
└─> Select move with highest visit count
Key Algorithms:
- MCTS: Upper Confidence Bound applied to Trees (UCT)
- VCF Search: Iterative Deepening Depth-First Search (IDDFS)
- Evaluation: Pattern matching (five-in-a-row, four-in-a-row, three-in-a-row)
- Move Ordering: Heuristic-based prioritization for pruning
# Build the main application
make
# The binary will be created at bin/app
./bin/app# Build and run test suite
make test
# Check for memory leaks (requires Valgrind)
make memcheck# Check code formatting (dry-run)
make lint
# Auto-format all source files
make format# Remove binaries and object files
make cleanmacOS:
- Uses Clang++ compiler
- OpenGL frameworks linked via
-framework OpenGL - Silences deprecated OpenGL warnings with
-DGL_SILENCE_DEPRECATION
Linux:
- Uses G++ compiler
- Links OpenGL via
-lGL -lGLU - Requires X11 development headers
Contributions are welcome! Here's how you can help:
- Check existing issues before creating a new one
- Provide detailed information: OS, compiler version, error messages
- Include steps to reproduce the problem
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature-name - Make your changes and ensure tests pass:
make test - Format your code:
make format - Commit with clear, descriptive messages
- Push to your fork and submit a pull request
- Follow C++17 best practices
- Use clear, descriptive variable and function names
- Add comments for complex algorithms
- Run
make formatbefore committing to ensure consistent formatting - Write unit tests for new features
This project is licensed under the MIT License - see the LICENSE file for details.