Gomoku

A high-performance Gomoku AI written in Rust and compiled to WebAssembly.

The project implements the complete 42 Gomoku ruleset, including captures, endgame capture validation, and double-three detection, while focusing on strong search performance, modern web technologies, and a polished user experience.

---

Features

AI Engine

• Alpha-Beta search with depth 10+ exploration
• Late Move Reductions (LMR)
• Advanced move ordering
• Zobrist hashing
• Transposition tables
• Bitwise pattern detection
• Threat-based position evaluation

Game Rules

• Capture mechanics
• Double-three detection
• Endgame capture validation
• Five-or-more alignment victory
• Full 42 Gomoku rules compliance

User Experience

• Human vs AI
• Human vs Human
• Move suggestions
• AI thinking timer
• Position analysis
• Game replay system
• Persistent game history

---

Architecture

┌─────────────────────┐
│     Visualizer      │
│  (Bun + Vite + TS)  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│     WebAssembly     │
│   Rust Bindings     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│    Gomoku Engine    │
│       Rust          │
└─────────────────────┘

All game logic lives inside the Rust engine.

The frontend is responsible only for rendering, user interactions, and visualization.

---

Technology Stack

Engine

• Rust
• WebAssembly

Frontend

• Bun
• Vite
• TypeScript
• Zustand

Infrastructure

• Web Workers (multithreaded search)
• IndexedDB (local persistence)
• GitHub Actions (CI/CD)
• GitHub Pages (deployment)

---

Search Architecture

Search

• Iterative Deepening
• Alpha-Beta Pruning
• Late Move Reductions (LMR)

Move Ordering

• Principal Variation ordering
• Transposition Table best move ordering
• Heuristic move sorting

Evaluation

• Pattern-based evaluation
• Threat detection
• Incremental board analysis

Performance

• Zobrist Hashing
• Transposition Tables
• Bitwise pattern scanning
• Incremental state updates

---

Project Structure

.
├── engine/          # Core game engine
├── engine-wasm/     # WASM bindings
├── visualizer/      # Frontend application
└── docs/            # Documentation

---

Development

Run Development Environment

make dev

Builds the WASM package and starts the development server.

Production Build

make build

Run Tests

make test

Watch Mode

make watch

---

Maintenance

Clean Rust Artifacts

make clean

Remove All Generated Files

make fclean

Rebuild Everything

make re

---

Bonus Features

Analysis

• Post-game analysis
• Alternative move suggestions
• Position review

Replay System

• Stored game history
• Move-by-move navigation
• Replay past games

Multiple Game Modes

• Human vs Human
• Human vs AI

Documentation & Deployment

• Automated documentation publishing
• GitHub Pages deployment
• GitHub Actions CI/CD pipeline