org.jscience.computing.game
Class AbstractGame

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, GamePlay

Direct Known Subclasses:

AwariGame, BlackJack, CheckersGame, ChessGame, EightQueens, FourWinsGame, GomokuGame, MineSweeper, MuehleGame, ReversiGame, Solitaire, TickTackToe, TilePuzzle, WolfsheepGame, WSPuzzle

public abstract class AbstractGame
extends java.lang.Object
implements GamePlay

This class implements the generic behaviour of a game to ease GamePlay implementations. The following functions are abstract and need to be implemented to represent the domain knowlege:

 protected GameMove[] listLegalMoves ();
 protected boolean    pushMove       (GameMove);
 protected boolean    popMove        ();

If the game does not support undoing of moves, the method popMove() may always simply return false.
Other than the given abstract functions, the following methods need to be declared by an inheriting class to account for the fact that AbstractGame implements GamePlay:

public int    nextPlayer ()
 public int[]  getWinner  ()

The function getResult(int playerRole) is implemented in a way that it returns 1 if game is won, -1 if game is lost and 0 if no winners are present, which is appropriate for many games, but may have to be overwritten. Finally, the method clone() must be overwritten in case the extending class has non-primitive members to provide a deep copy. It is probably a good idea to also implement a useful toString() method, so that the game can be visualized properly.
In addition to the above, you will also have to provide a GameMove object that represents a move that can be applied to a game to alter its status.
Note that this implementation of GamePlay is designed for game that have a finite rather easily determinable list of legal moves. Also, this implementation assumes that the next player in a game is well defined at any given state.

See Also:

GamePlay, GameMove, Serialized Form

Constructor Summary

AbstractGame(java.lang.String name, int numberOfPlayers)
Creates a new AbstractGame object.

Method Summary

protected void	clearRedoList() may be called by the subclass if certain events alter the game status so that the given redo moves cannot be applied anymore
java.lang.Object	clone() Any inheriting class with non-primitive members must overwrite this clone() method to provide a full deep copy of the object, which is essential for spawnChild() to work correctly.
boolean	gameOver() This convenience function gameOver() simply checks whether there are any legal moves left; consequently, unless this function is overridden, listLegalMoves() must not check for gameOver().
java.lang.String	getGameName() DOCUMENT ME!
GameMove	getLastMove() getLastMove() is a convenience function which returns the last element of the GameMove[] from getMoveHistory() in case the array has any elements in it; null is returned otherwise.
int	getLastPlayer() getLastPlayer() is a convenience function which simply looks up the last move and then returns the playerRole that played it
GameMove[]	getLegalMoves() Instead of overwriting this (final) function, implement listLegalMoves() instead.
GameMove[]	getLegalMoves(int playerRole) getLegalMoves(playerRole) returns the subset of getLegalMoves() where player == move.getPlayer().
GameMove[]	getMoveHistory() DOCUMENT ME!
int	getNumberOfRedoMoves() DOCUMENT ME!
GameMove[]	getRedoList() DOCUMENT ME!
double	getResult(int playerRole) a default implementation for convenience which may suit most games that do not involve betting or any form of measuring how 'big' the win was.
boolean	isLegalMove(GameMove move) this implementation checks whether the move is contained in the array returned by getLegalMoves(); thus this method relies on GameMove.equals() being implemented properly for the move in question
boolean	isWinner(int gameRole) isWinner() checks whether the given gameRole is in the array retruned by getWinner().
protected abstract GameMove[]	listLegalMoves() listLegalMoves() returns the legal moves for this game.
static AbstractGame	loadFromFile(java.lang.String fileLocation) just a convenience function
boolean	makeMove(GameMove move) DOCUMENT ME!
int	numberOfMoves() DOCUMENT ME!
int	numberOfPlayers() DOCUMENT ME!
protected abstract boolean	popMove() popMove undoes the last move by altering the game board to the stage before the last move happened.
protected abstract boolean	pushMove(GameMove move) pushMove takes a GameMove and alters the game according to to the move.
boolean	redoMove() DOCUMENT ME!
protected void	resetLegalMoves() forces a recalculation of getLegalMoves() with listLegalMoves(); needed if the extending class alters the game status without calling makeMove(), redoMove() or undoLastMove() and the move history and redo list is to be maintained
protected void	resetLists() resetList() forces a recalculation of getLegalMoves() and also resets the move list and the redo list.
void	saveToFile(java.lang.String fileLocation) just a convenience function
GamePlay	spawnChild(GameMove move) spawnChild() creates a clone of the current game and advances the game by the given GameMove.
java.lang.String	toString() overwritten to provide useful information about the game
boolean	undoLastMove() DOCUMENT ME!
boolean	undoMoves(int n) calls undoLastMove() either n times or as many times as there are numberOfMoves(), whichever is smaller

Methods inherited from class java.lang.Object

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

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

getWinner, nextPlayer

Constructor Detail

AbstractGame

public AbstractGame(java.lang.String name,
                    int numberOfPlayers)

Creates a new AbstractGame object.

Parameters:

name - DOCUMENT ME!

numberOfPlayers - DOCUMENT ME!

Method Detail

listLegalMoves

protected abstract GameMove[] listLegalMoves()

listLegalMoves() returns the legal moves for this game. This function is used by the final method getLegalMoves(), which is a wrapper around this method to avoid the overhead of generating the legal moves over and over again when called multiple times (as calculating legal moves is commonly expensive). Note that implementations of listLegalMoves() must not check for gameOver(), unless gameOver() is overridden not to check for listLegalMoves(). The same applies to isLegalMove().

Returns:

DOCUMENT ME!

pushMove

protected abstract boolean pushMove(GameMove move)

pushMove takes a GameMove and alters the game according to to the move.

Parameters:

move - DOCUMENT ME!

Returns:

true only if the move was put on the board successfully.

popMove

protected abstract boolean popMove()

popMove undoes the last move by altering the game board to the stage before the last move happened.

Returns:

true only if the move was taken back successfully.

getGameName

public java.lang.String getGameName()

DOCUMENT ME!

Specified by:

getGameName in interface GamePlay

Returns:

the name of this game which is supposed to be a qualified identifier

isWinner

public boolean isWinner(int gameRole)
                 throws GameRuntimeException

isWinner() checks whether the given gameRole is in the array retruned by getWinner(). If getWinner() returns null, a GameRuntimeException is thrown.

Throws:

GameRuntimeException

See Also:

GamePlay.getWinner()

getLastPlayer

public int getLastPlayer()
                  throws GameRuntimeException

getLastPlayer() is a convenience function which simply looks up the last move and then returns the playerRole that played it

Returns:

DOCUMENT ME!

Throws:

GameRuntimeException - if no move has been made, yet.

gameOver

public boolean gameOver()

This convenience function gameOver() simply checks whether there are any legal moves left; consequently, unless this function is overridden, listLegalMoves() must not check for gameOver().

Returns:

DOCUMENT ME!

getLastMove

public GameMove getLastMove()

getLastMove() is a convenience function which returns the last element of the GameMove[] from getMoveHistory() in case the array has any elements in it; null is returned otherwise.

Returns:

DOCUMENT ME!

getLegalMoves

public final GameMove[] getLegalMoves()

Instead of overwriting this (final) function, implement listLegalMoves() instead. This function serves as an optimization to ensure that if called more than once on the same game, this function will only have to compile the list of legal moves once. This function never returns null; if no legal moves are avaliable, it returns an array with 0 elements. If the method needs to recalculate the legal moves by calling listLegalMoves(), it is done so in a synchronized fashion.

Specified by:

getLegalMoves in interface GamePlay

Returns:

DOCUMENT ME!

See Also:

GamePlay.isLegalMove(GameMove)

resetLegalMoves

protected final void resetLegalMoves()

forces a recalculation of getLegalMoves() with listLegalMoves(); needed if the extending class alters the game status without calling makeMove(), redoMove() or undoLastMove() and the move history and redo list is to be maintained

clearRedoList

protected final void clearRedoList()

may be called by the subclass if certain events alter the game status so that the given redo moves cannot be applied anymore

resetLists

protected void resetLists()

resetList() forces a recalculation of getLegalMoves() and also resets the move list and the redo list. This is provided to allow an extending class to account for a situation where the game is altered to an extend where neither the move listory, the redo list, nor the the legal moves apply anymore.

isLegalMove

public boolean isLegalMove(GameMove move)

this implementation checks whether the move is contained in the array returned by getLegalMoves(); thus this method relies on GameMove.equals() being implemented properly for the move in question

Specified by:

isLegalMove in interface GamePlay

Parameters:

move - DOCUMENT ME!

Returns:

DOCUMENT ME!

See Also:

GamePlay.getLegalMoves()

getLegalMoves

public final GameMove[] getLegalMoves(int playerRole)

getLegalMoves(playerRole) returns the subset of getLegalMoves() where player == move.getPlayer().

Parameters:

playerRole - DOCUMENT ME!

Returns:

DOCUMENT ME!

makeMove

public boolean makeMove(GameMove move)

DOCUMENT ME!

Specified by:

makeMove in interface GamePlay

Parameters:

move - DOCUMENT ME!

Returns:

DOCUMENT ME!

redoMove

public boolean redoMove()

DOCUMENT ME!

Specified by:

redoMove in interface GamePlay

Returns:

DOCUMENT ME!

getNumberOfRedoMoves

public final int getNumberOfRedoMoves()

DOCUMENT ME!

Returns:

DOCUMENT ME!

undoMoves

public boolean undoMoves(int n)

calls undoLastMove() either n times or as many times as there are numberOfMoves(), whichever is smaller

Parameters:

n - DOCUMENT ME!

Returns:

DOCUMENT ME!

undoLastMove

public boolean undoLastMove()

DOCUMENT ME!

Specified by:

undoLastMove in interface GamePlay

Returns:

DOCUMENT ME!

numberOfMoves

public final int numberOfMoves()

DOCUMENT ME!

Returns:

DOCUMENT ME!

numberOfPlayers

public int numberOfPlayers()

DOCUMENT ME!

Specified by:

numberOfPlayers in interface GamePlay

Returns:

DOCUMENT ME!

See Also:

AutoPlay, Player

getResult

public double getResult(int playerRole)
                 throws GameRuntimeException

a default implementation for convenience which may suit most games that do not involve betting or any form of measuring how 'big' the win was.

Specified by:

getResult in interface GamePlay

Parameters:

playerRole - DOCUMENT ME!

Returns:

1 if game is won, -1 if game is lost and 0 if no winners are present

Throws:

GameRuntimeException - if the game is still in progress

getMoveHistory

public final GameMove[] getMoveHistory()

DOCUMENT ME!

Specified by:

getMoveHistory in interface GamePlay

Returns:

DOCUMENT ME!

getRedoList

public final GameMove[] getRedoList()

DOCUMENT ME!

Specified by:

getRedoList in interface GamePlay

Returns:

DOCUMENT ME!

spawnChild

public GamePlay spawnChild(GameMove move)
                    throws GameRuntimeException

spawnChild() creates a clone of the current game and advances the game by the given GameMove. The purpose of this function is to have a separate game instance that can be used by a Player to do whatever with it while determining heuristics. Note that the proper functionality of this method relies on the inheriting class to properly implement the clone() method to ensure a deep copy if the subclass has non-primitive members.

Specified by:

spawnChild in interface GamePlay

Parameters:

move - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

GameRuntimeException - if the given move is not legal or cannot be performed because the game is not cloneable

See Also:

GameMove, clone()

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Any inheriting class with non-primitive members must overwrite this clone() method to provide a full deep copy of the object, which is essential for spawnChild() to work correctly. Ay overwriting of this method should still begin with a call to super.clone(), though. Also, note that this clone() method does not clone the embedded GameMove objects, i.e. those are expected not to change (except for their heuristics, which shouldn't affect game functionality) - or the subclass will have to take care of this.

Specified by:

clone in interface GamePlay

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

See Also:

spawnChild(GameMove)

saveToFile

public void saveToFile(java.lang.String fileLocation)

just a convenience function

Parameters:

fileLocation - DOCUMENT ME!

Throws:

GameRuntimeException - DOCUMENT ME!

loadFromFile

public static AbstractGame loadFromFile(java.lang.String fileLocation)

just a convenience function

Parameters:

fileLocation - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

GameRuntimeException - DOCUMENT ME!

toString

public java.lang.String toString()

overwritten to provide useful information about the game

Overrides:

toString in class java.lang.Object

Returns:

DOCUMENT ME!