org.jscience.computing.game
Class TemplatePlayer

java.lang.Object
  org.jscience.computing.game.TemplatePlayer

All Implemented Interfaces:

java.io.Serializable, Player

Direct Known Subclasses:

AwariPlayer, BJPlayer, CheckersPlayer, ChessPlayer, FourWinsPlayer, GomokuPlayer, MuehlePlayer, RandomPlayer, ReversiPlayer, TilePuzzlePlayer, WSPlayer

public abstract class TemplatePlayer
extends java.lang.Object
implements Player, java.io.Serializable

The TemplatePlayer provides a useful skeleton implementation for the Player interface. Inheriting Player classes only need to implement the following methods (at a minimum) to provide the necessary game domain specific knowlege:

• canPlayGame(GamePlay game)
• heuristic(GamePlay game, GameMove move, int[] role)

The TemplatePlayer provides game tree search capabilities by utilizing methods from the class GameUtilites and it can track its requests. Note that if the Player is serialized, it looses its tracking information. For a sample (non-game domain specific) implementation of the TemplatePlayer, see the RandomPlayer.
Known limitation:
The algorithm used for time constrained search is not quite satisfactory, yet. If a move evaluation is performed with a time constraint, the result may not be very informed as the tree may be searched 'uneven', as the algorithms used here from the class GameUtils don't currently use iterative deepening; see the description for the search algorithms in the GameUtils class for more details.

See Also:

Player, GameUtils, RandomPlayer, Serialized Form

Nested Class Summary

protected class	TemplatePlayer.MoveEvaluater MoveEvaluater is used by the method selectMove() from the enclosing TemplatePLayer class in case of a time-limited search to allow each move to be examined efficiently in a separate thread.
protected class	TemplatePlayer.Synchronizer Synchronizer is used consolidate the MoveEvaluater threads spanned off by the selectMove() method from the enclosing TemplatePlayer.

Field Summary

protected int	levelOverwrite
protected java.util.Vector<Monitor>	monitors
protected boolean	orderMoves
protected java.lang.String	playerName
static int	SEARCH_ALPHABETA when used as searchOption, Alpha-Beta Search algorithm is used
static int	SEARCH_MINMAX when used as searchOption, MinMax Search algorithm is used
protected int	searchOption

Constructor Summary

TemplatePlayer()
This constructor instanciates a Player with the name "unnamed DefaultPlayer", no game tree search option, tracking disabled and no game level overwrite.

TemplatePlayer(java.lang.String playerName)
instanciates a Player with no game tree search option, disabled tracking and no game level overwrite

TemplatePlayer(java.lang.String playerName, int searchOption, boolean trackingEnabled)
instanciates a player with the given playerName, searchOption and tracking; game level overwrite is set to 0; for searchOption values see #setSearchOption().

Method Summary

void	disableTracking() Deprecated. use setTracking(boolean enable) instead
void	enableTracking() Deprecated. use setTracking(boolean enable) instead
double	evaluate(GamePlay game, GameMove move, int[] role, int level, long milliseconds) This method will simply call the protected evaluate() method and in addition track the call if tracking is enabled.
protected double	evaluate(GamePlay game, GameMove move, int[] role, int level, long milliseconds, Monitor monitor) Internal evaluate function called by public evaluate() and selectMove().
int	getLevelOverwrite() This method returns 0 by default, meaning there is no level overwrite in place.
protected Monitor[]	getMonitors() returns an array of all Monitors if tracking is enabled
boolean	getOrderMoves() if enabled and Alpha-Beta tree search algorithm is used, the tree search employs ordering of the legal moves by their heuristic before the next level is searched (to enhance tree pruning)
java.lang.String	getPlayerName()
int	getSearchOption()
int	numberOfPositionsSearched() returns the sum of Monitor.getNumber() from all monitors tracked in this player during calls to selectMove() and evaluate() if tracking has been enabled
int	numberOfRequests() returns the number of calls to evaluate() or selectMove() since tracking has been enabled
float	performanceRatio() returns the quotient between numberOfPositionsSearched() and totalTimeTaken(); the result will be scaled to reflect how many positions have been searched per second.
boolean	pruneMove(GamePlay game, GameMove move, int[] role) unless overwritten, this method returns always false
GameMove	selectMove(GamePlay game, int[] role, int level, long milliseconds) This implementation selects the best move according to the given configuration.
void	setLevelOverwrite(int levelOverwrite) This method enables to overwrite the level parameter value given to selectMove() and/or evaluate(), so that the implementation will use this value instead of the level given by the parameters.
void	setOrderMoves(boolean enable) If set to true, Alpha-Beta search algorithm - if used - will order the legal moves according to their heuristic before searching the next level.
void	setPlayerName(java.lang.String name)
void	setSearchOption(int searchOption) This function sets the search algorithm used in selectMove() and evaluate().
void	setTracking(boolean enable)
java.lang.String	statsAsString() returns a String with the Player's statistics for logging/printing
java.lang.String	toString() overwritten to return some information about the player
long	totalTimeTaken() goes through all monitored requests and returns the sum of the elapsed time
boolean	trackingEnabled()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.jscience.computing.game.Player

canPlayGame, heuristic

Field Detail

SEARCH_MINMAX

public static final int SEARCH_MINMAX

when used as searchOption, MinMax Search algorithm is used

See Also:

Constant Field Values

SEARCH_ALPHABETA

public static final int SEARCH_ALPHABETA

when used as searchOption, Alpha-Beta Search algorithm is used

See Also:

Constant Field Values

playerName

protected java.lang.String playerName

searchOption

protected int searchOption

levelOverwrite

protected int levelOverwrite

orderMoves

protected boolean orderMoves

monitors

protected transient java.util.Vector<Monitor> monitors

Constructor Detail

TemplatePlayer

public TemplatePlayer()

This constructor instanciates a Player with the name "unnamed DefaultPlayer", no game tree search option, tracking disabled and no game level overwrite.

TemplatePlayer

public TemplatePlayer(java.lang.String playerName)

instanciates a Player with no game tree search option, disabled tracking and no game level overwrite

TemplatePlayer

public TemplatePlayer(java.lang.String playerName,
                      int searchOption,
                      boolean trackingEnabled)

instanciates a player with the given playerName, searchOption and tracking; game level overwrite is set to 0; for searchOption values see #setSearchOption().

Method Detail

enableTracking

@Deprecated
public void enableTracking()

Deprecated. use setTracking(boolean enable) instead

enables tracking of requests by instanciating a List of monitors that will be maintained when requests are made to this player; if tracking is alreay enabled, nothing happens. Tracked requests include calls to evaluate() and selectMove(). Calls to heuristic() are counted as it is called by this class within the Monitors maintained for calls to evaluate() and selectMove(). Further direct tracking of calls to heuristic() is left to extending classes, as heuristic() is abstract in this class TemplatePlayer. To reset tracking, first call disableTracking() before you call this method. Note that this type of tracking does not maintain the game information of the requests processed; if you wish to do so, overwrite the tracking mechanism accordingly.

disableTracking

@Deprecated
public void disableTracking()

Deprecated. use setTracking(boolean enable) instead

disables tracking of requests; all previous tracked information is lost

setTracking

public void setTracking(boolean enable)

trackingEnabled

public boolean trackingEnabled()

numberOfRequests

public int numberOfRequests()
                     throws java.lang.IllegalStateException

returns the number of calls to evaluate() or selectMove() since tracking has been enabled

Throws:

java.lang.IllegalStateException - if tracking is disabled

totalTimeTaken

public long totalTimeTaken()
                    throws java.lang.IllegalStateException

goes through all monitored requests and returns the sum of the elapsed time

Throws:

java.lang.IllegalStateException - if tracking is disabled

numberOfPositionsSearched

public int numberOfPositionsSearched()
                              throws java.lang.IllegalStateException

returns the sum of Monitor.getNumber() from all monitors tracked in this player during calls to selectMove() and evaluate() if tracking has been enabled

Throws:

java.lang.IllegalStateException - if tracking is disabled

performanceRatio

public float performanceRatio()
                       throws java.lang.IllegalStateException

returns the quotient between numberOfPositionsSearched() and totalTimeTaken(); the result will be scaled to reflect how many positions have been searched per second.

Throws:

java.lang.IllegalStateException - if tracking is disabled

getMonitors

protected Monitor[] getMonitors()
                         throws java.lang.IllegalStateException

returns an array of all Monitors if tracking is enabled

Throws:

java.lang.IllegalStateException - if tracking is disabled

See Also:

Monitor

getSearchOption

public int getSearchOption()

setSearchOption

public void setSearchOption(int searchOption)
                     throws java.lang.IllegalArgumentException

This function sets the search algorithm used in selectMove() and evaluate(). Valid values for searchOption are:

0 for no tree search

SEARCH_MINMAX for MinMax tree search algorithm

SEARCH_ALPHABETA for AlphaBeta pruning during tree search

Throws:

java.lang.IllegalArgumentException - if searchOption is unknown

getLevelOverwrite

public int getLevelOverwrite()

This method returns 0 by default, meaning there is no level overwrite in place. If set to another value than 0, the TemplatePlayer will use this value instead of the level given when selecting or evaluating a move.

See Also:

setLevelOverwrite(int)

setLevelOverwrite

public void setLevelOverwrite(int levelOverwrite)

This method enables to overwrite the level parameter value given to selectMove() and/or evaluate(), so that the implementation will use this value instead of the level given by the parameters.

See Also:

getLevelOverwrite()

getOrderMoves

public boolean getOrderMoves()

if enabled and Alpha-Beta tree search algorithm is used, the tree search employs ordering of the legal moves by their heuristic before the next level is searched (to enhance tree pruning)

setOrderMoves

public void setOrderMoves(boolean enable)

If set to true, Alpha-Beta search algorithm - if used - will order the legal moves according to their heuristic before searching the next level. This option makes sense if the used heuristic is discriminating enough to prune the search efficiently; otherwise it just adds substantial overhead to the search as every node (and not just the leafs) will have to be run through the player's heuristic function.

getPlayerName

public java.lang.String getPlayerName()

Specified by:

getPlayerName in interface Player

setPlayerName

public void setPlayerName(java.lang.String name)

pruneMove

public boolean pruneMove(GamePlay game,
                         GameMove move,
                         int[] role)

unless overwritten, this method returns always false

Specified by:

pruneMove in interface Player

Returns:

true only if the given move is to be pruned from the game tree search; false otherwise

evaluate

public double evaluate(GamePlay game,
                       GameMove move,
                       int[] role,
                       int level,
                       long milliseconds)
                throws CannotPlayGameException

This method will simply call the protected evaluate() method and in addition track the call if tracking is enabled. If tracking is enabled, a Monitor is used to track the number of node examinations, the total time taken for the request and the result calculated (stored as a Double in the monitor's setObject()); also, the used monitor will be disabled in time given that milliseconds is greater than 0 - otherwise, only the level will limit the search. If tracking is disabled, no monitor will be used; game tree search is also limited to level and given milliseconds; in that case, this method does nothing but calling the protected evaluate() method.

Specified by:

evaluate in interface Player

Throws:

CannotPlayGameException - if the game cannot be played by the player

See Also:

evaluate(GamePlay,GameMove,int[],int,long,Monitor)

evaluate

protected double evaluate(GamePlay game,
                          GameMove move,
                          int[] role,
                          int level,
                          long milliseconds,
                          Monitor monitor)

Internal evaluate function called by public evaluate() and selectMove(). This function doesn't track the request, it uses the given monitor and assumes that the calling function tracks the monitor properly. Based on what search algorithm is configured for this player and whether or not this is a time-limited evaluation or not, it will use an appropriate method from the GameUtils class to perform the evaluation. Note that with the given algorithms, the search goes strictly in a depth first search (dfs) fashion, which may lead to unwanted results if the search is cut off before all levels have been searched (because no iterative deepening is used, wich means that in case the search is cut off early, some moves may not be searched beyond level 0); this is subject to future improvements!

See Also:

GameUtils.minMaxSearch(GamePlay,GameMove,Player,int[],int,Monitor), GameUtils.alphaBetaSearch(GamePlay,GameMove,Player,int[],int,Monitor,boolean), Monitor

selectMove

public GameMove selectMove(GamePlay game,
                           int[] role,
                           int level,
                           long milliseconds)

This implementation selects the best move according to the given configuration. If the time is constrained by milliseconds > 0, a thread is spanned for each move; each thread will evaluate that move within the given time constrain. If no time constrain is given, all evaluations will happen in the same thread limited by the given level. If tracking is enabled, a monitor will be added containing the number of nodes examined, the time taken and the best move stored in Monitor.setObject().

Specified by:

selectMove in interface Player

See Also:

TemplatePlayer.Synchronizer, TemplatePlayer.MoveEvaluater

toString

public java.lang.String toString()

overwritten to return some information about the player

Overrides:

toString in class java.lang.Object

statsAsString

public java.lang.String statsAsString()

returns a String with the Player's statistics for logging/printing