Overview of Play Mode

When playing a game of checkers there are only three possible states:

• it's your turn and you can make moves and submit your turn
• it's not your turn and you have to wait for your opponent to complete her turn
• or the game is over and you can review the final board state and then exit the game

These three states control the behavior of the Game View client-side (JavaScript) code.

The Play Mode States

The following statechart defines the Game View behavior in Play mode.

As seen in the state model above there are two guard variables that determine which state is used: isGameOver and isMyTurn.

The isGameOver guard variable is supplied directly in the modeOptions object; see: End-of-Game UX: modeOptionsAsJSON. If this object is not supplied, then the isGameOver variable is assumed to be false.

The isMyTurn guard is determined by this code:

function isMyTurn() {
  return (currentUser === redPlayer && activeColor === 'RED')
    || (currentUser === whitePlayer && activeColor === 'WHITE');
};

<script>
window.gameData = {
  "currentUser" : "${currentUser.name}",
  "viewMode" : "${viewMode}",
  "modeOptions" : ${modeOptionsAsJSON!'{}'},
  "redPlayer" : "${redPlayer.name}",
  "whitePlayer" : "${whitePlayer.name}",
  "activeColor" : "${activeColor}"
};
</script>

<script>
window.gameData = {
  "currentUser" : "Jane",
  "viewMode" : "PLAY",
  "modeOptions" : {},
  "redPlayer" : "Jane",
  "whitePlayer" : "Fred",
  "activeColor" : "RED"
};
</script>

<script>
window.gameData = {
  "currentUser" : "Fred",
  "viewMode" : "PLAY",
  "modeOptions" : {},
  "redPlayer" : "Jane",
  "whitePlayer" : "Fred",
  "activeColor" : "RED"
};
</script>

<script>
window.gameData = {
  "currentUser" : "Jane",
  "viewMode" : "PLAY",
  "modeOptions" : {
    "isGameOver": true,
    "gameOverMessage": "Fred resigned."
  },
  "redPlayer" : "Jane",
  "whitePlayer" : "Fred",
  "activeColor" : "RED"
};
</script>

Playing My Turn State

The Playing My Turn state is a composite state and the following is its internal state model:

When the Game View enters the Playing My Turn state it immediately transitions to the Empty Turn state. In this state the user may drag any piece to an open space on the board. When the piece is dropped on an open space the JavaScript code transitions to the Waiting for Move Validation state, which sends an Ajax request to the server to validate the move; this is the POST /validateMove Ajax action detailed below. If the move is valid then the client-side code transitions to the Stable Turn state. In this state the Game View only has the starting piece active; no other piece can be moved (dragged-and-dropped).

At this point the user can click the Submit turn button that issues an Ajax HTTP request to the POST /submitTurn action and transition to the Waiting for Turn Validation state. If the whole turn is valid then the user's turn is done and the Game View will refresh, by invoking the GET /game URL showing the result of the turn. If the turn is not valid then the Ajax call must return a message of type ERROR with a text string explaining why the turn is not valid.

Also in the Stable Turn state the player may decide they didn't like the last move. The user can click the Backup button to tell the server to undo this move. This action is handled by the POST /backupMove Ajax HTTP request. This tells the server to remove the most recent move the user issued; the server returns a message object telling the client-side code that the action was taken and the client-side code then moves the user's piece back to the most recent starting point. If the user backs out of all of their moves then they are returned to the Empty Turn state at which point all of their pieces are enabled and they can choose a different sequence of moves.

There is one other Ajax action not shown in the diagram: the Resign button allows either player to resign from the game. If the user is waiting for their turn then they can click the Resign button at any time. If the user is taking their turn then the Resign button is only active in the Empty Turn state. Once they start a move the Resign button is disabled. They can back-out of all of their moves and then resign.

Below are details about how to code each of these page-level and Ajax actions. If you have any questions please post the question to the Term Project topic in the myCourse Discussions List.

Waiting for My Turn State

The Waiting for My Turn state is used when it is not the current user's turn and the game has not ended. This composite state has two inner states that oscillate until the opponent's latest turn has been completed.

The Waiting for 5 Second Delay state tells the browser to wait for 5 seconds. After the timeout the Game View transitions to the Checking for My Turn state. An Ajax call to the server, the POST /checkTurn action, is invoked on the transition. The Checking for My Turn state waits for the server response. The server responds with a Message object with type of INFO and the message text must be either "true" or "false": true if it is this user's turn or false if the user must continue waiting.

When it becomes the user's turn then the client-side code will issue a page-level HTTP request to GET /game to have the server update the Game View to show the opponent's move. The Game View leaves the Waiting for My Turn state and halts.

End-of-Game User Experience

There is a special Game View state that tells the client-side code when the game is over. The following screenshot shows the Game View is this state:

The Info panel must show the names of the two players of the game. The Controls panel provides a single button:

• The Exit button tells the system to exit from this game. Clicking this button sends the user back to the Home page.

This state will be used by the Game End Conditions and Resignation stories. Both of these features require that no additional turns/moves can be made and that both users can see the end state of the board and the message of how the game ended.

To get the Game View into this new state you need to create a mode options map that tells the client-side Game View code to transition to the game over state. The map must also supply the message from the server about how the game ended: capture all pieces, block all pieces or resignation. This message is shown in bold in the message box above the controls.

The View-Model attributes for the game.ftl View component are the same as for Sprint 1: Game View-Model Specification. But now we use the modeOptionsAsJSON variable to hold data especially designed to represent the end of game to the user.

This attribute must be stored in the View-Model as a JSON string of a Java Map. This is sample code of how to do that:

final Map<String, Object> modeOptions = new HashMap<>(2);
modeOptions.put("isGameOver", true);
modeOptions.put("gameOverMessage", /* get end of game message */);
vm.put("modeOptionsAsJSON", gson.toJson(modeOptions));

The team's goal when coding the Game End Conditions and Resignation stories is to determine when a game ends or when a player resigns and render the Game View for the user to see the last board state and the reason why the game ended. These mode options supply that information to the Game View client-side (JavaScript) code.