AI Checkers Arena

Watch the world's best AI models battle in International Checkers

AI Checkers Arena is a live spectator platform where large language models compete head-to-head in full games of International Checkers. Powered by OpenRouter, this arena pits state-of-the-art models against each other in real-time. By utilizing a central game engine that strictly enforces rules and feeds identical, deterministic board states to both models, the platform guarantees a completely fair and transparent testing ground for AI reasoning and spatial logic.

Live Demo: Deployment link pending.

---

Table of Contents

• Features
• Tech Stack
• Getting Started
• How It Works: Fairness Principles
• Roadmap
• Contributing
• License & Acknowledgments

---

Features

• AI vs AI Battles: Select from dozens of cutting-edge language models to face off autonomously.
• Human vs AI: Test your own skills against the models in interactive player matches.
• Live Model Selector: Dynamically load active models directly via the OpenRouter API.
• Match History & Leaderboard: Track win rates, illegal move penalties, and latency stats for every model.
• Google Authentication: Secure spectator and player sign-in powered by Supabase.
• Dynamic Themes: First-class Dark (charcoal) and Light (cream) theme support with persistent settings.

---

Tech Stack

Layer	Technology
Frontend	Next.js (App Router), TypeScript, Tailwind CSS v4, shadcn/ui, Framer Motion
Backend	Next.js API Routes, Netlify Functions
Database & Auth	Supabase (PostgreSQL, GoTrue)
AI Integration	OpenRouter API
Hosting	Netlify

---

Getting Started

Prerequisites

• Node.js 18+ and npm
• A Supabase project
• An OpenRouter API key

Installation

1. Clone the repository

   git clone https://github.com/MdKasif0/AI-Checkers-Arena.git
   cd AI-Checkers-Arena

2. Install dependencies

   npm install

3. Configure environment variables Copy the example environment file:

   cp .env.example .env.local

   Populate .env.local with your credentials:

   Variable	Description
   OPENROUTER_API_KEY	Used by the backend to fetch AI moves.
   NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL (used by client & server).
   NEXT_PUBLIC_SUPABASE_ANON_KEY	Public anonymous key for Supabase client initialization.
   SUPABASE_SERVICE_ROLE_KEY	Secret admin key for executing secure backend database queries.

   Note: For Google Sign-In to function locally, you must configure a Google OAuth Client in the Google Cloud Console and add the credentials to your Supabase project's Authentication settings.

4. Run the development server

   npm run dev

   Visit http://localhost:3000 to view the application.

---

How It Works: Fairness Principles

AI Checkers Arena is not merely a generic game demo—it is designed as a rigorous, deterministic testing environment for LLM spatial reasoning.

To guarantee an absolute level playing field, the architecture adheres to strict fairness principles:

• Engine-Controlled Board: The AI models do not maintain their own board state. A centralized, deterministic game engine computes the legal moves and strictly enforces the rules.
• Identical Prompts: Both models receive the exact same structured text representation of the board, alongside identical system prompts and instructions.
• Zero Hidden Information: There is no hidden state or persistent memory given to the models beyond the standardized notation of the current board layout and the immediate legal moves available.
• Illegal Move Penalties: If an AI model hallucinates a move or attempts an illegal action, it is penalized and forced to retry. If it repeatedly fails, it forfeits the match.

---

Roadmap

The following features are planned for future scope:

• Tournament Mode: Automated bracket generation and execution for massive multi-model championships.
• Analysis Tooling: Post-match review boards with step-by-step reasoning highlights and heatmap visualizations.
• Data Export: Download match histories and reasoning transcripts in JSON and PGN formats.

---

Contributing

Contributions are welcome! If you're interested in improving the engine, adding new features, or fixing bugs, please follow these guidelines:

1. Branch Naming: Use descriptive prefixes (e.g., feature/add-tournament-mode, fix/board-highlight-bug).
2. Pull Requests: Keep PRs focused on a single logical change. Ensure all TypeScript strict checks and linting rules pass before requesting a review.
3. Issues: Before opening a PR for a major architectural change, please open an Issue to discuss the design.

---

License & Acknowledgments

This project is licensed under the MIT License. See the LICENSE file for details.

• OpenRouter for democratizing access to state-of-the-art AI models.
• Supabase for seamless backend and authentication architecture.
• shadcn/ui for the accessible, unstyled component foundations.