package org.ggp.base.player.gamer.statemachine;
import java.util.ArrayList;
import java.util.List;
import org.ggp.base.player.gamer.Gamer;
import org.ggp.base.player.gamer.exception.AbortingException;
import org.ggp.base.player.gamer.exception.MetaGamingException;
import org.ggp.base.player.gamer.exception.MoveSelectionException;
import org.ggp.base.player.gamer.exception.StoppingException;
import org.ggp.base.util.gdl.grammar.GdlTerm;
import org.ggp.base.util.logging.GamerLogger;
import org.ggp.base.util.statemachine.MachineState;
import org.ggp.base.util.statemachine.Move;
import org.ggp.base.util.statemachine.Role;
import org.ggp.base.util.statemachine.StateMachine;
import org.ggp.base.util.statemachine.exceptions.GoalDefinitionException;
import org.ggp.base.util.statemachine.exceptions.MoveDefinitionException;
import org.ggp.base.util.statemachine.exceptions.TransitionDefinitionException;
/**
* The base class for Gamers that rely on representing games as state machines.
* Almost every player should subclass this class, since it provides the common
* methods for interpreting the match history as transitions in a state machine,
* and for keeping an up-to-date view of the current state of the game.
*
* See @SimpleSearchLightGamer, @HumanGamer, and @RandomGamer for examples.
*
* @author evancox
* @author Sam
*/
public abstract class StateMachineGamer extends Gamer
{
// =====================================================================
// First, the abstract methods which need to be overriden by subclasses.
// These determine what state machine is used, what the gamer does during
// metagaming, and how the gamer selects moves.
/**
* Defines which state machine this gamer will use.
* @return
*/
public abstract StateMachine getInitialStateMachine();
/**
* Defines the metagaming action taken by a player during the START_CLOCK
* @param timeout time in milliseconds since the era when this function must return
* @throws TransitionDefinitionException
* @throws MoveDefinitionException
* @throws GoalDefinitionException
*/
public abstract void stateMachineMetaGame(long timeout) throws TransitionDefinitionException, MoveDefinitionException, GoalDefinitionException;
/**
* Defines the algorithm that the player uses to select their move.
* @param timeout time in milliseconds since the era when this function must return
* @return Move - the move selected by the player
* @throws TransitionDefinitionException
* @throws MoveDefinitionException
* @throws GoalDefinitionException
*/
public abstract Move stateMachineSelectMove(long timeout) throws TransitionDefinitionException, MoveDefinitionException, GoalDefinitionException;
/**
* Defines any actions that the player takes upon the game cleanly ending.
*/
public abstract void stateMachineStop();
/**
* Defines any actions that the player takes upon the game abruptly ending.
*/
public abstract void stateMachineAbort();
// =====================================================================
// Next, methods which can be used by subclasses to get information about
// the current state of the game, and tweak the state machine on the fly.
/**
* Returns the current state of the game.
*/
public final MachineState getCurrentState()
{
return currentState;
}
/**
* Returns the role that this gamer is playing as in the game.
*/
public final Role getRole()
{
return role;
}
/**
* Returns the state machine. This is used for calculating the next state and other operations, such as computing
* the legal moves for all players, whether states are terminal, and the goal values of terminal states.
*/
public final StateMachine getStateMachine()
{
return stateMachine;
}
/**
* Cleans up the role, currentState and stateMachine. This should only be
* used when a match is over, and even then only when you really need to
* free up resources that the state machine has tied up. Currently, it is
* only used in the Proxy, for players designed to run 24/7.
*/
protected final void cleanupAfterMatch() {
role = null;
currentState = null;
stateMachine = null;
setMatch(null);
setRoleName(null);
}
/**
* Switches stateMachine to newStateMachine, playing through the match
* history to the current state so that currentState is expressed using
* a MachineState generated by the new state machine.
*
* This is not done in a thread-safe fashion with respect to the rest of
* the gamer, so be careful when using this method.
*
* @param newStateMachine the new state machine
*/
protected final void switchStateMachine(StateMachine newStateMachine) {
try {
MachineState newCurrentState = newStateMachine.getInitialState();
Role newRole = newStateMachine.getRoleFromConstant(getRoleName());
// Attempt to run through the game history in the new machine
List<List<GdlTerm>> theMoveHistory = getMatch().getMoveHistory();
for(List<GdlTerm> nextMove : theMoveHistory) {
List<Move> theJointMove = new ArrayList<Move>();
for(GdlTerm theSentence : nextMove)
theJointMove.add(newStateMachine.getMoveFromTerm(theSentence));
newCurrentState = newStateMachine.getNextStateDestructively(newCurrentState, theJointMove);
}
// Finally, switch over if everything went well.
role = newRole;
currentState = newCurrentState;
stateMachine = newStateMachine;
} catch (Exception e) {
GamerLogger.log("GamePlayer", "Caught an exception while switching state machine!");
GamerLogger.logStackTrace("GamePlayer", e);
}
}
/**
* A function that can be used when deserializing gamers, to bring a
* state machine gamer back to the internal state that it has when it
* arrives at a particular game state.
*/
public final void resetStateFromMatch() {
stateMachine = getInitialStateMachine();
stateMachine.initialize(getMatch().getGame().getRules());
currentState = stateMachine.getMachineStateFromSentenceList(getMatch().getMostRecentState());
role = stateMachine.getRoleFromConstant(getRoleName());
}
// =====================================================================
// Finally, methods which are overridden with proper state-machine-based
// semantics. These basically wrap a state-machine-based view of the world
// around the ordinary metaGame() and selectMove() functions, calling the
// new stateMachineMetaGame() and stateMachineSelectMove() functions after
// doing the state-machine-related book-keeping.
/**
* A wrapper function for stateMachineMetaGame. When the match begins, this
* initializes the state machine and role using the match description, and
* then calls stateMachineMetaGame.
*/
@Override
public final void metaGame(long timeout) throws MetaGamingException
{
try
{
stateMachine = getInitialStateMachine();
stateMachine.initialize(getMatch().getGame().getRules());
currentState = stateMachine.getInitialState();
role = stateMachine.getRoleFromConstant(getRoleName());
getMatch().appendState(currentState.getContents());
stateMachineMetaGame(timeout);
}
catch (Exception e)
{
GamerLogger.logStackTrace("GamePlayer", e);
throw new MetaGamingException(e);
}
}
/**
* A wrapper function for stateMachineSelectMove. When we are asked to
* select a move, this advances the state machine up to the current state
* and then calls stateMachineSelectMove to select a move based on that
* current state.
*/
@Override
public final GdlTerm selectMove(long timeout) throws MoveSelectionException
{
try
{
stateMachine.doPerMoveWork();
List<GdlTerm> lastMoves = getMatch().getMostRecentMoves();
if (lastMoves != null)
{
List<Move> moves = new ArrayList<Move>();
for (GdlTerm sentence : lastMoves)
{
moves.add(stateMachine.getMoveFromTerm(sentence));
}
currentState = stateMachine.getNextState(currentState, moves);
getMatch().appendState(currentState.getContents());
}
return stateMachineSelectMove(timeout).getContents();
}
catch (Exception e)
{
GamerLogger.logStackTrace("GamePlayer", e);
throw new MoveSelectionException(e);
}
}
@Override
public void stop() throws StoppingException {
try {
stateMachine.doPerMoveWork();
List<GdlTerm> lastMoves = getMatch().getMostRecentMoves();
if (lastMoves != null)
{
List<Move> moves = new ArrayList<Move>();
for (GdlTerm sentence : lastMoves)
{
moves.add(stateMachine.getMoveFromTerm(sentence));
}
currentState = stateMachine.getNextState(currentState, moves);
getMatch().appendState(currentState.getContents());
getMatch().markCompleted(stateMachine.getGoals(currentState));
}
stateMachineStop();
}
catch (Exception e)
{
GamerLogger.logStackTrace("GamePlayer", e);
throw new StoppingException(e);
}
}
@Override
public void abort() throws AbortingException {
try {
stateMachineAbort();
}
catch (Exception e)
{
GamerLogger.logStackTrace("GamePlayer", e);
throw new AbortingException(e);
}
}
// Internal state about the current state of the state machine.
private Role role;
private MachineState currentState;
private StateMachine stateMachine;
}