AbaloneWeb

A modern web experience for playing Abalone against an AI opponent. The project couples a React (Next.js) frontend with a high‑performance C++ backend that exposes move suggestions via a REST API. The Python/PyQt legacy UI has been fully retired.

---

📦 Project Structure

AbaloneWeb/
├── frontend/           # Next.js 15 app (App Router, Tailwind v4, shadcn/ui)
├── AbaloneAI/          # C++ AI engine + REST server (no Python frontend)
├── README.md           # Project overview (this file)
└── .gitignore

Key points:

• frontend/ contains the live web client with interactive board, move validation (inline/sidestep), AI integration, capture scoring, and move history.
• AbaloneAI/ houses the reusable C++ engine and the abalone_rest_server binary.

---

🚀 Quick Start

1. Run the AI backend

cd AbaloneAI
cmake -S . -B build
cmake --build build -j
./build/abalone_rest_server        # defaults to port 8080

If you prefer a different port, pass it as an argument (e.g. ./build/abalone_rest_server 9000). For non-default ports, export NEXT_PUBLIC_ABALONE_API in the frontend.

2. Launch the frontend

cd ../frontend
npm install       # first run only
npm run dev

Open http://localhost:3000. The frontend automatically talks to the backend whenever the AI must respond to a move.

---

🧩 Gameplay Highlights

• Hex board rendered in React with real Abalone coordinates (A1 … I9).
• Human move input supports selecting up to 3 marbles (Shift-extend), inline pushes, and side-steps.
• Extensive move validation before sending to the backend.
• AI replies are fetched via REST, updating the board, move history, and capture scoreboard.
• Game ends once either side captures 6 marbles (overlay + restart button).
• Console logs annotate capture-based game overs for debugging.

---

🔧 Frontend Tech Stack

• Next.js 15 with the App Router (/src/app).
• React 19 function components.
• Tailwind CSS v4 + shadcn/ui for styling.
• clsx for class helpers.
• TypeScript throughout.

Key files:

• frontend/src/app/page.tsx – game page, board logic, AI integration.
• frontend/src/components/board/Board.tsx – presentational board component.
• frontend/src/lib/abalone/logic.ts – ported move validation (inline/sidestep, pushes, captures).

---

🤖 Backend Tech Stack

• C++17 AI implementation (heuristic evaluation, iterative deepening search, transposition table).
• REST server built on POSIX sockets (no dependency on Python).

Key files:

• AbaloneAI/cpp_backend/ – main engine sources (AbaloneAI.cpp, Board.cpp, rest_server.cpp).
• AbaloneAI/README.md – backend-specific documentation.

---

🧪 Testing & Linting

Frontend:

cd frontend
npm run lint

Backend:

cd AbaloneAI
cmake --build build -j            # builds tests, rest server, simulation tools

---

🗺️ Roadmap Ideas

• Persist match history & analytics.
• Add AI difficulty presets (depth/time tuning exposed via UI).
• Visualize legal moves on hover (pre-commit to backend).
• Expand REST API to report additional analytics (evaluation score, principal variation).

---

🙌 Credits

Originally developed by AIML Group 1. Modern web integration and ongoing enhancements by the AbaloneWeb maintainers.

Contributions welcome! Submit PRs or open issues to propose improvements.

---

📄 License

MIT License. See LICENSE for details.