From 8250fefaff204179025d985619e23a4b55d06977 Mon Sep 17 00:00:00 2001 From: aaadrian Date: Sun, 22 Mar 2026 14:37:02 -0700 Subject: [PATCH 1/2] docs: rewrite README with solver overview, usage guide and feature table --- README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 79 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index d28deb2..d74d4b6 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,91 @@ ![Icon](https://user-images.githubusercontent.com/29038605/222264516-e8132d83-e9dc-4436-a1fd-7bdf046c0034.png) + # Alligator.Compact -Alligator = Algorithm library for game theory + +**Algorithm Library for Game Theory** — a generic, high-performance solver for two-player zero-sum games. [![.NET](https://github.com/boraaros/Alligator.Compact/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/boraaros/Alligator.Compact/actions/workflows/build.yml) -**Sonar** +## Overview + +Alligator.Compact provides an **abstract AI solver** that can play any two-player zero-sum game optimally — you only need to define the rules and the board representation. The solver handles the rest: search, pruning, caching, and move ordering. + +The core idea is simple: implement three interfaces (`IRules`, `IPosition`, `IConfiguration`), and get a fully working game AI out of the box. + +## Quick Start + +```csharp +// 1. Implement IRules and IPosition for your game + +// 2. Create a solver +var rules = new MyGameRules(); +var config = new MyGameConfiguration(); +var provider = new SolverProvider(rules, config); +ISolver solver = provider.Create(); + +// 3. Get the optimal move +IList moveHistory = new List(); +MyStep bestMove = solver.OptimizeNextStep(moveHistory); +``` + +## Interfaces to Implement + +### `IPosition` — the game board + +| Member | Description | +|---|---| +| `ulong Identifier` | Unique hash of the position (e.g. [Zobrist hashing](https://en.wikipedia.org/wiki/Zobrist_hashing)) | +| `sbyte Value` | [Static evaluation](https://en.wikipedia.org/wiki/Evaluation_function) from the current player's perspective | +| `void Take(TStep step)` | Apply a move to the board | +| `void TakeBack()` | Undo the last move | + +### `IRules` — the game logic + +| Member | Description | +|---|---| +| `TPosition InitialPosition()` | Create the starting board | +| `IEnumerable LegalStepsAt(TPosition)` | Enumerate all legal moves at a position | +| `bool IsGoal(TPosition)` | `true` if the game ended with a decisive result (not a draw) | + +## How the Solver Works + +The solver uses **iterative deepening** with **MTD(f)** (Memory-enhanced Test Driver with null-window alpha-beta), also known as *Best Node Search*. At each iteration depth (2, 4, 6, …), it performs a series of null-window alpha-beta searches to converge on the minimax value, then narrows the set of candidate moves. + +### Algorithm Features -[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=boraaros_Alligator.Compact&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=boraaros_Alligator.Compact) +| Feature | Status | Notes | +|---|---|---| +| Negamax alpha-beta pruning | ✅ Implemented | Core search framework | +| Iterative deepening | ✅ Implemented | Even depths: 2, 4, 6 | +| MTD(f) / Best Node Search | ✅ Implemented | Null-window search with candidate narrowing | +| Transposition table | ✅ Implemented | Zobrist hash, exact/lower/upper bound entries | +| Killer move heuristic | ✅ Implemented | 2 killer moves stored per depth | +| Static evaluation cache | ✅ Implemented | Avoids redundant `IPosition.Value` calls | +| Principal Variation move ordering | ✅ Implemented | Best move from TT tried first | +| Quiescence search | ❌ Not yet | Would reduce horizon effect | +| Aspiration windows | ❌ Not yet | Could speed up iterative deepening | +| History heuristic ordering | ❌ Not yet | Move ordering by historical beta-cutoff frequency | +| Late move reductions (LMR) | ❌ Not yet | Reduce depth for moves unlikely to be good | +| Null move pruning | ❌ Not yet | Skip a turn to get quick upper bound | +| Parallel search | ❌ Not yet | e.g. Lazy SMP or YBWC | +| Opening book support | ❌ Not yet | Pre-computed opening moves | +| Configurable search depth | ❌ Not yet | Currently hardcoded max depth | -[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=boraaros_Alligator.Compact&metric=bugs)](https://sonarcloud.io/summary/new_code?id=boraaros_Alligator.Compact) +## Solution Structure -[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=boraaros_Alligator.Compact&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=boraaros_Alligator.Compact) +| Project | Description | +|---|---| +| **Alligator.Solver** | The abstract solver — game-agnostic core library | +| **Alligator.SixMaking** | [Six Making](https://boardgamegeek.com/boardgame/149793/six-making) game implementation | +| **Alligator.TicTacToe** | Tic-tac-toe implementation (minimal example) | +| **Alligator.Demo** | Interactive console demo (human vs AI tic-tac-toe) | +| **Alligator.Benchmark** | Performance benchmarks for the solver | +| **Alligator.Test** | Unit tests | -[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=boraaros_Alligator.Compact&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=boraaros_Alligator.Compact) +## Requirements -[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=boraaros_Alligator.Compact&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=boraaros_Alligator.Compact) +- .NET 10 -This is the new and compact version. +## License -### Projects: -Alligator.Solver: The abstract core library of artificial intelligence for different two-player zero-sum games. +See [LICENSE](LICENSE) for details. From a9d1629c003e00222d47cbd75f94d9988fd15376 Mon Sep 17 00:00:00 2001 From: aaadrian Date: Tue, 24 Mar 2026 16:57:48 -0700 Subject: [PATCH 2/2] fix --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d74d4b6..55295f3 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,7 @@ The solver uses **iterative deepening** with **MTD(f)** (Memory-enhanced Test Dr | Static evaluation cache | ✅ Implemented | Avoids redundant `IPosition.Value` calls | | Principal Variation move ordering | ✅ Implemented | Best move from TT tried first | | Quiescence search | ❌ Not yet | Would reduce horizon effect | -| Aspiration windows | ❌ Not yet | Could speed up iterative deepening | -| History heuristic ordering | ❌ Not yet | Move ordering by historical beta-cutoff frequency | +| History heuristic ordering | ❌ Not yet | Move ordering by historical beta-cutoff frequency (scores already recorded) | | Late move reductions (LMR) | ❌ Not yet | Reduce depth for moves unlikely to be good | | Null move pruning | ❌ Not yet | Skip a turn to get quick upper bound | | Parallel search | ❌ Not yet | e.g. Lazy SMP or YBWC | @@ -76,7 +75,7 @@ The solver uses **iterative deepening** with **MTD(f)** (Memory-enhanced Test Dr | Project | Description | |---|---| | **Alligator.Solver** | The abstract solver — game-agnostic core library | -| **Alligator.SixMaking** | [Six Making](https://boardgamegeek.com/boardgame/149793/six-making) game implementation | +| **Alligator.SixMaking** | [Six Making](https://www.youtube.com/watch?v=FHdltzwaAJg) game implementation | | **Alligator.TicTacToe** | Tic-tac-toe implementation (minimal example) | | **Alligator.Demo** | Interactive console demo (human vs AI tic-tac-toe) | | **Alligator.Benchmark** | Performance benchmarks for the solver |