org.jscience.computing.game
Class TemplatePlayer

java.lang.Object
  extended by 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:

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