Merge pull request #3 from fathzer-games/quiesce

First preview

Author: fathzer

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+name: Build
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: 'zulu' # Alternative distribution options are available.
+      - name: Cache SonarCloud packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.sonar/cache
+          key: ${{ runner.os }}-sonar
+          restore-keys: ${{ runner.os }}-sonar
+      - name: Cache Maven packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.m2
+          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+          restore-keys: ${{ runner.os }}-m2
+      - name: Build and analyze
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        run: mvn -B org.jacoco:jacoco-maven-plugin:prepare-agent test org.jacoco:jacoco-maven-plugin:report org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Dsonar.projectKey=fathzer-games_games-core

.gitignore

@@ -0,0 +1,3 @@
+/target/
+/.settings/
+.classpath

.project

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>games-core</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.m2e.core.maven2Builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.m2e.core.maven2Nature</nature>
+	</natures>
+</projectDescription>

README.md

@@ -1,2 +1,29 @@
+[![Maven Central](https://img.shields.io/maven-central/v/com.fathzer/games-core)](https://central.sonatype.com/artifact/com.fathzer/games-core)
+[![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](https://github.com/fathzer-games/games-core/blob/master/LICENSE)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=fathzer_games-core&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=fathzer-games_games-core)
+[![javadoc](https://javadoc.io/badge2/com.fathzer/games-core/javadoc.svg)](https://javadoc.io/doc/com.fathzer/games-core)
+
 # games-core
-A core library to help implement two players games
+A core library to help implement two players game engines.
+
+It provides you with a ready to use and highly configurable [iterative deepening](https://www.chessprogramming.org/Iterative_Deepening) [Negamax](https://en.wikipedia.org/wiki/Negamax) implementation using configurable [transposition table](https://en.wikipedia.org/wiki/Transposition_table).
+
+In order to have a working engine for your favorite game, you have to implement your own MoveGenerator and Evaluator for this game ... and use one of the provided ai (I recommend IterativeDeepeningEngine).  
+You can implement your own transposition table and its policy (which positions to save or how to reuse them during the search). This library contains a basic implementation, try it to see if it is enough for your needs.
+
+# Known bugs
+- The AI always supposes a player that can't move loosed or make a draw ... which is not always the case (typically in [Reversi](https://en.wikipedia.org/wiki/Reversi)).
+- The iterative deepening search always stops deepening when it finds a winning move. It prevents finding other deeper winning moves. It's not a problem when playing a game, but for analysis, it is one.
+
+## TODO
+- Filter the library moves with candidates moves in IterativeDeepengingEngine.
+- The transposition table *newPosition* method should have the board as an argument in order to, for instance, compute a generation number based on board characteristics.
+- There's probably a bug or something very misleading in ClockSettings: withNext has a number of plies arguments, but it seems that the usage is to deal with number of moves (not plies which are half moves).
+- Maybe TTAi scoreToTT and ttToScore would be at a better place in TranspositionTablePolicy. Another, maybe better, approach is to compute fixed (mat) values in Negamax class and have a flag in the table (and in its store method) to explicitly set the stored value as a fixed value. It would allow those values to be used regardless of the depth at which they are recorded.
+- EvaluatedMove.compareTo does not sort in natural order which can be confusing
+- There's a strange behavior with transposition table. There's some situations where a never replace strategy leads to a faster resolution. It is totally counter intuitive.
+- MoveGenerator:
+  - It would be more efficient to have the moveGenerator generating directly an iterator of moves instead of a list of moves. It would allow to use incremental move generators that starts by returning, what can hope to be the best moves (for instance captures), and other moves if these first moves are consumed. Indeed, in alpha/beta ai, the first moves are often enough to trigger a cut, so generating all the moves is a waste of time.
+- Write tests and Documentation ;-)
+- Test with Sonar
+- Publish artifact on Maven central

pom.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE xml><project xmlns="https://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<parent>
+		<groupId>com.fathzer</groupId>
+		<artifactId>parent-pom</artifactId>
+		<version>1.0.8</version>
+	</parent>
+	<artifactId>games-core</artifactId>
+	<version>0.0.12-SNAPSHOT</version>
+
+	<name>games-core</name>
+	<description>A core library to help implement two players games.</description>
+	<url>https://github.com/fathzer-games/games-core</url>
+
+	<scm>
+		<url>https://github.com/fathzer-games/games-core.git</url>
+		<connection>https://github.com/fathzer-games/games-core.git</connection>
+	</scm>
+
+	<properties>
+		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+		<sonar.organization>fathzer-games</sonar.organization>
+		<check-dependencies-java-version>17</check-dependencies-java-version>
+	    <maven.compiler.release>17</maven.compiler.release>
+	</properties>
+
+	<repositories>
+		<repository>
+			<id>jitpack.io</id>
+			<url>https://jitpack.io</url>
+		</repository>
+	</repositories>
+
+	<dependencies>
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter</artifactId>
+			<version>5.10.2</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.mockito</groupId>
+			<artifactId>mockito-junit-jupiter</artifactId>
+			<version>5.1.1</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>com.github.bhlangonijr</groupId>
+			<artifactId>chesslib</artifactId>
+			<version>1.3.3</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.awaitility</groupId>
+			<artifactId>awaitility</artifactId>
+			<version>4.2.2</version>
+			<scope>test</scope>
+		</dependency>
+	</dependencies>
+</project>

src/main/java/com/fathzer/games/Color.java

@@ -0,0 +1,24 @@
+package com.fathzer.games;
+
+/** A player's color.
+ * <br>Ok, there's a lot of games with two players and no "white" and "black".
+ * <br>For instance, the <a href="https://en.wikipedia.org/wiki/Tic-tac-toe">Tic Tac Toe</a>, has "X" and "O" players.
+ * <br>Ok, ok, so let say "white" means "X" and "black" means "O". The important thing is to identify both players, isn't it?.
+ */
+public enum Color {
+	WHITE, BLACK;
+
+	static {
+		WHITE.opposite = BLACK;
+		BLACK.opposite = WHITE;
+	}
+	
+	private Color opposite;
+
+	/** Gets the opposite color of this color.
+	 * @return a color.
+	 */
+	public Color opposite() {
+		return opposite;
+	}
+}

src/main/java/com/fathzer/games/GameHistory.java

@@ -0,0 +1,118 @@
+package com.fathzer.games;
+
+import java.util.LinkedList;
+import java.util.List;
+
+import com.fathzer.games.MoveGenerator.MoveConfidence;
+
+/** A game history with its start board, the list of its moves and its termination cause.
+ * @param <M> The type of the moves
+ * @param <B> The type of the {@link MoveGenerator} used to represent the board
+ */
+public class GameHistory<M,B extends MoveGenerator<M>> {
+	/** The termination cause of a game.
+	 */
+	public enum TerminationCause {
+		/** A player resigns */
+		ABANDONED,
+		/** Result determined by third-party adjudication */
+		ADJUDICATION,
+		/** A player died (hope he was a computer!) */
+		DEATH,
+		/** The game was ended because of an emergency (fire, etc...) */
+		EMERGENCY,
+		/** The game ended simply because a player won */
+		NORMAL,
+		/** A player was disqualified */
+		RULES_INFRACTION,
+		/** A player ran out of time */
+		TIME_FORFEIT,
+		/** The game is not terminated */
+		UNTERMINATED;
+	}
+	
+	private final B startBoard;
+	private final B board;
+	private final List<M> moves;
+	private Status extraStatus;
+	private TerminationCause terminationCause;
+
+	@SuppressWarnings("unchecked")
+	public GameHistory(B board) {
+		this.startBoard = (B) board.fork();
+		this.board = (B) board.fork();
+		this.moves = new LinkedList<>();
+		this.terminationCause = TerminationCause.UNTERMINATED;
+	}
+
+	/** Adds a move to this history.
+	 * @param move The move to add.
+	 * @return true if the move is legal. False if it is not. In such a case the move is also added to the list of moves.
+	 * <br>Please that if the move is illegal, the player is not automatically disqualified. The developer is free to implement
+	 * the punishment he wants.
+	 * <br>If the move is legal and changes the {@link Status} of the game to anything except {@link Status#PLAYING}, the termination
+	 * cause is set to NORMAL 
+	 * @throws IllegalStateException if game is already ended.
+	 */
+	public boolean add(M move) {
+		if (Status.PLAYING!=getStatus()) {
+			throw new IllegalStateException();
+		}
+		this.moves.add(move);
+		final boolean result = board.makeMove(move, MoveConfidence.UNSAFE);
+		if (result && Status.PLAYING!=getStatus()) {
+			this.terminationCause = TerminationCause.NORMAL;
+		}
+		return result;
+	}
+
+	public B getStartBoard() {
+		return startBoard;
+	}
+	
+	public B getBoard() {
+		return board;
+	}
+
+	public List<M> getMoves() {
+		return moves;
+	}
+	
+	/** Declares an early termination for the game.
+	 * <br>For instance, a player resigns or players agree to a draw.
+	 * <br>Any subsequent call to this method or {@link #add(Move)} will result in an IllegalStateException  
+	 * @param status The end status
+	 * @param terminationCause The termination cause
+	 * @throws IllegalStateException if game is already ended.
+	 * @throws IllegalArgumentException if termination is null or if status is {@link Status#PLAYING} or null.
+	 */
+	public void earlyEnd(Status status, TerminationCause terminationCause) {
+		if (Status.PLAYING==status || status==null || terminationCause==null || terminationCause==TerminationCause.UNTERMINATED) {
+			throw new IllegalArgumentException();
+		}
+		if (Status.PLAYING!=getStatus()) {
+			throw new IllegalStateException("Status is "+getStatus());
+		}
+		this.extraStatus = status;
+		this.terminationCause = terminationCause;
+	}
+	
+	public Status getStatus() {
+		if (extraStatus!=null) {
+			return extraStatus;
+		}
+		return getBoardStatus(board);
+	}
+	
+	public TerminationCause getTerminationCause() {
+		return this.terminationCause;
+	}
+	
+	protected Status getBoardStatus(B board) {
+		Status status = board.getContextualStatus();
+		if (status==Status.PLAYING && board.getLegalMoves().isEmpty()) {
+			status = board.getEndGameStatus();
+		}
+		return status;
+	}
+}

src/main/java/com/fathzer/games/HashProvider.java

@@ -0,0 +1,12 @@
+package com.fathzer.games;
+
+/** A class able to compute a hash key (for instance a <a href="https://en.wikipedia.org/wiki/Zobrist_hashing">Zobrist key</a>) for the current game state.
+ * <br>Typically, a chess {@link MoveGenerator} which supports Zobrist hashing will implement this interface.
+ */
+@FunctionalInterface
+public interface HashProvider {
+	/** Gets the hash key of the current game state.
+	 * @return a long
+	 */
+	long getHashKey();
+}