org.jscience.computing.game
Interface GamePlay

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Implementing Classes:

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

public interface GamePlay
extends java.io.Serializable, java.lang.Cloneable

GamePlay provides all methods needed to play a game. A game is played by players represented by integer game roles. It is assumed that an integer should always be sufficient to represent a game role. AutoPlay then introduces the concept of Player objects more in detail. Further assumptions for GamePlay objects are that as long as the game is in progress, there is a finite set of moves that can be performed in any given game status and one of the moves can be picked to advance the game to another state with its own set of legal moves. Another important assumption is that given any game status, there is always one player determinable that makes the next move (if the game is not over). Instead of implementing all functionality from scratch, it is recommended to take advantage of classes that already provide a good portion of the functionality - such as AbstractGame; for many games, this class provides a good basis. There are games that have many different variants of legal moves, which may be hard to return with getLegalMoves(). If that is the case, getLegalMoves() could simply return templates for legal moves; the method isLegalMoves() would then be responsible to determine whether the move constructed by a player is actually legal. This is why both functions are part of this interface. GamePlay extends Serializable to ensure that a game and its moves can be used over e.g. an Internet connection or can be written to a file.

See Also:

AbstractGame, GameMove, Player, AutoPlay

Method Summary

java.lang.Object	clone() To support several other methods, the clone() method needs public access and must be implemented so that the returned object is a deep copy of the object at hand.
java.lang.String	getGameName() returns the name of the game for display in titles (as toString() may be used to display something else)
GameMove[]	getLegalMoves() returns an array containing all moves that can be legally performed with the current game status; each move should successfully be able to advance the game when called with makeMove().
GameMove[]	getMoveHistory() returns an array containing all moves that have been applied to the current game status; the last move that was applied is the last move in the array at index (getMoveHistory().length-1)
GameMove[]	getRedoList() returns an array containing all moves that have been taken back and could be reapplied; the GameMove at the index 0 is the next object that can be reapplied.
double	getResult(int playerRole) getResult() returns the final outcome for a player, which could be a dollar amount, points gained or anything else
int[]	getWinner() getWinner() returns an array of all winning game roles - as there could be more than one winner.
boolean	isLegalMove(GameMove move) This function is needed for games where getLegalMoves() may not return a complete list of all possible moves (so that a determination on whether the given move is legal could simply be made by checking whether the move is included in the array returned by getLegalMoves()); then, isLegalMoves() will make the determination whether the given move is legal.
boolean	makeMove(GameMove move) If the move is successfully carried out, the function returns true, false otherwise.
int	nextPlayer() nextPlayer() returns the integer representing the game role of the next player.
int	numberOfPlayers() numberOfPlayers() returns the number of game roles in the GamePlay.
boolean	redoMove() returns true only if last move previously taken back is successfully reapplied.
GamePlay	spawnChild(GameMove move) spawnChild returns a deep copy of an identical game that represents the status of the game after the given move is carried out.
boolean	undoLastMove() If the last move is successfully taken back, this method returns true, false otherwise.

Method Detail

getGameName

java.lang.String getGameName()

returns the name of the game for display in titles (as toString() may be used to display something else)

numberOfPlayers

int numberOfPlayers()

numberOfPlayers() returns the number of game roles in the GamePlay. Each role in the game is represented by an integer so that (0 <= game_role < numberOfPlayers()). The association to actual Player objects is then done by AutoPlay objects.

See Also:

AutoPlay, Player

makeMove

boolean makeMove(GameMove move)

If the move is successfully carried out, the function returns true, false otherwise. This function should work with any legal moves as returned by getLegalMoves().

nextPlayer

int nextPlayer()

nextPlayer() returns the integer representing the game role of the next player. If there is no next player, it is assumed that there are no more legal moves left in the game, in which case the value of nextPlayer() should be irrelevant.

getLegalMoves

GameMove[] getLegalMoves()

returns an array containing all moves that can be legally performed with the current game status; each move should successfully be able to advance the game when called with makeMove(). Although it is not required that getLegalMoves() returns all existing legal moves, it helps for most implementation if it does (as isLegalMove() can then just check for a move being in the array returned here); other implementations (where it is hard to create a finite list of all possible moves) may return templates to create moves where isLegalMoves() will then check for their consistency.

See Also:

isLegalMove(GameMove)

isLegalMove

boolean isLegalMove(GameMove move)

This function is needed for games where getLegalMoves() may not return a complete list of all possible moves (so that a determination on whether the given move is legal could simply be made by checking whether the move is included in the array returned by getLegalMoves()); then, isLegalMoves() will make the determination whether the given move is legal.

See Also:

getLegalMoves()

getMoveHistory

GameMove[] getMoveHistory()

returns an array containing all moves that have been applied to the current game status; the last move that was applied is the last move in the array at index (getMoveHistory().length-1)

getRedoList

GameMove[] getRedoList()

returns an array containing all moves that have been taken back and could be reapplied; the GameMove at the index 0 is the next object that can be reapplied.

undoLastMove

boolean undoLastMove()

If the last move is successfully taken back, this method returns true, false otherwise. If there are no moves to be taken back, the method also returns false. Undoing moves may not be supported by a game implementation, in which case this method would simply always return false.

redoMove

boolean redoMove()

returns true only if last move previously taken back is successfully reapplied.

getWinner

int[] getWinner()

getWinner() returns an array of all winning game roles - as there could be more than one winner. If the function returns null, it doesn't necessarily mean that the game is still in progress, but it could also mean that there is no winner in this game even though it is over (alternatively, an empty array could be returned depending on the requirements of the game). Also, if winners are returned, the game could still be in progress. Maybe, a game keeps playing to determine who is the second winner, etc.

getResult

double getResult(int playerRole)
                 throws GameRuntimeException

getResult() returns the final outcome for a player, which could be a dollar amount, points gained or anything else

Throws:

GameRuntimeException - if there is not a final result determined for the given player in the game, yet

spawnChild

GamePlay spawnChild(GameMove move)
                    throws GameRuntimeException

spawnChild returns a deep copy of an identical game that represents the status of the game after the given move is carried out. This method relies on the implementing class to provide a deep copy, so that any alterations to the retuned game (incl. its redoList etc.) don't affect the original game.

Throws:

GameRuntimeException - if the given move is not legal

clone

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

To support several other methods, the clone() method needs public access and must be implemented so that the returned object is a deep copy of the object at hand.

Throws:

java.lang.CloneNotSupportedException

See Also:

spawnChild(GameMove)