Merge pull request #2 from fathzer-games/game-classes

Game classes

Author: fathzer

README.md

@@ -4,7 +4,7 @@
 [![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 game engines
+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).
 
@@ -17,13 +17,13 @@ You can implement your own transposition table and its policy (which positions t
 
 ## TODO
 - Filter the library moves with candidates moves in IterativeDeepengingEngine.
-- The transposition table *newPosition* method should have the board has an argument in order to, for instance, compute a generation number based on board characteristics.
+- 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 start 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.
+  - 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

@@ -53,5 +53,11 @@
 			<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/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/ai/evaluation/QuiesceEvaluator.java

@@ -3,6 +3,17 @@
 import com.fathzer.games.MoveGenerator;
 import com.fathzer.games.ai.SearchContext;
 
+/** An evaluator that performs quiescence search before evaluating.
+ * @param <M> The type of moves 
+ * @param <B> The type of the evaluator
+ */
 public interface QuiesceEvaluator<M, B extends MoveGenerator<M>> {
+	/** Gets the position evaluation after performing a quiescence search. 
+	 * @param ctx The search context (The position can be found using {@link SearchContext#getGamePosition()}
+	 * @param depth The current depth
+	 * @param alpha The current alpha value
+	 * @param beta The current beta
+	 * @return The evaluation
+	 */
 	int evaluate(SearchContext<M, B> ctx, int depth, int alpha, int beta);
 }

src/main/java/com/fathzer/games/ai/iterativedeepening/DeepeningPolicy.java

@@ -21,17 +21,28 @@ public class DeepeningPolicy extends SearchParameters {
 	private long start;
 	private boolean deepenOnForced;
 
+	/** Constructor.
+	 * <br>By default there's no time limit to deepening and forced moves are not evaluated.
+	 * @param maxDepth The maximum search depth.
+	 */
 	public DeepeningPolicy(int maxDepth) {
 		super(maxDepth);
 		this.maxTime = Long.MAX_VALUE;
 		this.start = -1;
 		this.deepenOnForced = false;
 	}
 
+	/** Start counting time. 
+	 * <br>This method should be called when the search starts in order to have {@link #getSpent()} and {@link #isDeepenOnForced()} works
+	 */
 	public void start() {
 		this.start = System.currentTimeMillis();
 	}
 
+	/** Gets the number of milliseconds elapsed since the call to {@link #start}
+	 * @return a positive long.
+	 * @throws IllegalStateException if {@link #start()} was not called
+	 */
 	public long getSpent() {
 		if (start<0) {
 			throw new IllegalStateException("Not yet started");
@@ -45,6 +56,7 @@ public long getSpent() {
 	 */
 	public void setMaxTime(long maxTime) {
 		this.maxTime = maxTime;
+		this.start = -1;
 	}
 
 	/** Gets the maximum time to spend in the search.
@@ -54,13 +66,17 @@ public long getMaxTime() {
 		return maxTime;
 	}
 
+	/** Check whether the search should be deepened on forced moves.
+	 * @return true it should be deepened.
+	 * @see #setDeepenOnForced(boolean)
+	 */
 	public boolean isDeepenOnForced() {
 		return deepenOnForced;
 	}
 
 	/** Sets if the search should be deepened when only one move remains to evaluate.
-	 * <br>Please note, that if this attribute to false (The default value), searching for two best moves (size=2), and
-	 * you having n possible moves and only one that isn't yet evaluate to win or loose, will stop the evaluation
+	 * <br>Please note, that if this attribute is false (The default value), searching for two best moves (size=2), and
+	 * having n possible moves but only one not yet evaluated to win or loose, will stop the evaluation
 	 * @param deepenOnForced true to force the deepening until max depth or maxtime is reached.
 	 */
 	public void setDeepenOnForced(boolean deepenOnForced) {

src/main/java/com/fathzer/games/clock/Clock.java

@@ -1,16 +1,16 @@
 package com.fathzer.games.clock;
 
 import java.util.concurrent.ConcurrentLinkedQueue;
-import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.ScheduledThreadPoolExecutor;
-import java.util.concurrent.ThreadFactory;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Consumer;
 
 import com.fathzer.games.Color;
 import com.fathzer.games.Status;
+import com.fathzer.games.util.exec.CustomThreadFactory;
+
 import static com.fathzer.games.clock.ClockState.*;
 
 /** A clock.
@@ -21,12 +21,7 @@
  * <br>This class is thread safe.
  */
 public class Clock {
-	private static final ThreadFactory FACTORY = r -> {
-	    Thread t = Executors.defaultThreadFactory().newThread(r);
-	    t.setDaemon(true);
-	    return t;
-    };
-	private static final ScheduledExecutorService TIMER = new ScheduledThreadPoolExecutor(1, FACTORY);
+	private static final ScheduledExecutorService TIMER = new ScheduledThreadPoolExecutor(1, new CustomThreadFactory(new CustomThreadFactory.BasicThreadNameSupplier("Clock"), true));
 
 	static {
 		((ScheduledThreadPoolExecutor)TIMER).setRemoveOnCancelPolicy(true);

src/main/java/com/fathzer/games/util/exec/CustomThreadFactory.java

@@ -0,0 +1,44 @@
+package com.fathzer.games.util.exec;
+
+import java.util.concurrent.Executors;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.Supplier;
+
+public class CustomThreadFactory implements ThreadFactory {
+	
+	public static class BasicThreadNameSupplier implements Supplier<String>{
+		private final AtomicLong count;
+		private final String prefix;
+		
+		public BasicThreadNameSupplier(String prefix) {
+			super();
+			this.prefix = prefix;
+			this.count = new AtomicLong();
+		}
+
+		@Override
+		public String get() {
+			return  prefix + " " + count.incrementAndGet();
+		}
+	}
+	
+    private final Supplier<String> threadNameSupplier;
+    private final boolean isDaemon;
+
+    public CustomThreadFactory(Supplier<String> threadNameSupplier, boolean isDaemon) {
+        this.threadNameSupplier = threadNameSupplier;
+        this.isDaemon = isDaemon;
+    }
+
+    @Override
+    public Thread newThread(Runnable runnable) {
+        final Thread thread = Executors.defaultThreadFactory().newThread(runnable);
+        thread.setName(threadNameSupplier.get());
+        if (isDaemon) {
+        	thread.setDaemon(true);
+        }
+		return thread;
+    }
+
+}