♕ Phase 6 ‐ Chess Gameplay - softwareconstruction240/softwareconstruction GitHub Wiki

• Chess Application Overview
• Getting Started
• 🖥️ Videos

For the final part of the Chess Project, you will implement gameplay. Gameplay will use WebSocket to communicate between client and server (instead of Web APIs). When a user begins playing or observes a game, their client should establish a WebSocket connection with the server. The WebSocket connection exchanges messages between client and server (and vice versa). Figure 1 shows a recommended design for the chess client.

Figure 1: Recommended Chess Client Design

The gameplay UI should draw the current state of the chess board from the side the user is playing. If playing white, white pieces should be drawn on bottom. If playing black, black pieces should be drawn on bottom. If the user is observing the game, white pieces should be drawn on bottom.

The gameplay UI should support the following user commands:

Figure 2: Example Highlight Move

When the following events occur, notification messages should be displayed on the screen of each player that is involved in the game (player or observer).

1. A user connected to the game as a player (black or white). The notification message should include the player’s name and which side they are playing (black or white).
2. A user connected to the game as an observer. The notification message should include the observer’s name.
3. A player made a move. The notification message should include the player’s name and a description of the move that was made. (This is in addition to the board being updated on each player’s screen.)
4. A player left the game. The notification message should include the player’s name.
5. A player resigned the game. The notification message should include the player’s name.
6. A player is in check. The notification message should include the player’s name (this notification is generated by the server).
7. A player is in checkmate. The notification message should include the player’s name (this notification is generated by the server).

During gameplay all communication between the players is implemented by sending WebSocket messages between clients and the server. Using WebSocket allows the server to send a message at anytime to any of the connected clients. For example, a player sends a move message to the server. The server then asynchronously broadcast the move to everyone in the game.

When a user begins playing or observing a game, their client will do the following:

1. Call the server join HTTP API to join them to the game. This step is only done for players. Observers do not need to make the join HTTP API request.
2. Open a WebSocket connection with the server (using the /ws endpoint) so it can send and receive gameplay messages.
3. Send a CONNECT WebSocket message to the server.
4. Transition to the gameplay UI. The gameplay UI draws the chess board and allows the user to perform the gameplay commands described in the previous section.

The following sections describe the messages that will be exchanged between client and server (or vice versa) to implement the gameplay functionality.

Some WebSocket messages are sent from the client to server. As defined by the Chess application design, these are called user game commands. Other WebSocket messages are sent from the server to client. These are called server messages. In code, each of these message types are represented as a Java class that can be serialized and deserialized to and from JSON (similar to the Request and Result classes you created for the server’s Web API). The provided starter code includes a class named UserGameCommand which defines the required messages that originate from the client, and a class named ServerMessage which defines the required messages that originate from the server.

The UserGameCommand and ServerMessage classes are provided in the starter code, but you can extend these classes to provide functionality according the specifics of your design.

The following is a simplified representation of the UserGameCommand found in the starter code.

public class UserGameCommand {
    public enum CommandType {
        CONNECT,
        MAKE_MOVE,
        LEAVE,
        RESIGN
    }

    public CommandType commandType;
    public String authToken;
    public Integer gameID;
}

Here are the different command types that a user game command can represent.

The following diagram represents a possible extension of the UserGameCommand class that you could make in order to support the required ChessMove field of the MAKE_MOVE command. You are free to follow this design, or come up with a representation of your own.

classDiagram
    class UserGameCommand {
        commandType: CommandType
        authToken: String
        gameID: Integer
    }
    class MakeMoveCommand {
        move: ChessMove
    }
    UserGameCommand <|-- MakeMoveCommand

In the end, the important thing is that your design supports the additional move field when serializing the MAKE_MOVE command over the WebSocket. This must result in something like the following:

{
  "commandType": "MAKE_MOVE",
  "authToken": "tokengoeshere",
  "gameID": "337",
  "move": { "start": { "row": 3, "col": 3 }, "end": { "row": 5, "col": 5 } }
}

The following is a simplified representation of the ServerMessage found in the starter code.

public class ServerMessage {
   public enum ServerMessageType {
       LOAD_GAME,
       ERROR,
       NOTIFICATION
   }

   ServerMessageType serverMessageType;
}

Here are the different command types that a user game command can represent.

The following diagram represents possible extensions of the ServerMessage class that you could use to support the different ServerMessage commands. You are free to follow this design, or come up with a representation of your own. Just make sure the the required fields are included in your JSON serialization.

classDiagram
    class ServerMessage {
        serverMessageType : ServerMessageType
    }
    class LoadGameMessage {
        game: any
    }
    class ErrorMessage {
        errorMessage: String
    }
    class NotificationMessage {
        message: String
    }
    ServerMessage <|-- LoadGameMessage
    ServerMessage <|-- ErrorMessage
    ServerMessage <|-- NotificationMessage

A client will instigate all gameplay interactions by sending a CONNECT UserGameCommand to the server. We refer to the instigating client as the Root Client. The server will receive this Command and send appropriate ServerMessages to all clients connected to that game.

When sending a Notification that refers to one of the clients, the message should use the Clients username. (E.g., Bob left the game).

If a UserGameCommand is invalid (e.g. invalid authToken or gameID doesn’t exist) the server should only send an Error message informing the Root Client what went wrong. No messages should be sent to the other Clients. The Error message must contain the word error (case doesn’t matter).

Root Client sends CONNECT

1. Server sends a LOAD_GAME message back to the root client.
2. Server sends a Notification message to all other clients in that game informing them the root client connected to the game, either as a player (in which case their color must be specified) or as an observer.

Root Client sends MAKE_MOVE

1. Server verifies the validity of the move.
2. Game is updated to represent the move. Game is updated in the database.
3. Server sends a LOAD_GAME message to all clients in the game (including the root client) with an updated game.
4. Server sends a Notification message to all other clients in that game informing them what move was made.
5. If the move results in check, checkmate or stalemate the server sends a Notification message to all clients.

Root Client sends LEAVE

1. If a player is leaving, then the game is updated to remove the root client. Game is updated in the database.
2. Server sends a Notification message to all other clients in that game informing them that the root client left. This applies to both players and observers.

Root Client sends RESIGN

1. Server marks the game as over (no more moves can be made). Game is updated in the database.
2. Server sends a Notification message to all clients in that game informing them that the root client resigned. This applies to both players and observers.

Here is a sequence diagram that demonstrates the player communications.

• Console UI: Reading from the keyboard and writing out fancy text.
• WebSocket: Making WebSocket client and server requests.
• Debugging: Debugging multiple applications that communication over the network is a critical software engineering skill that you will need to master to complete this phase. Make sure you review the topics on how to debug both multiple applications and also how to debug multiple concurrent instances of same application.

The provided tests for this assignment are in the WebSocketTests class. These test the WebSocket interactions between client and server. To run the tests first start your server, and then run WebSocketTests.

For this phase the auto grader will grade the quality of your project's source code. The rubric used to evaluate code quality can be found here: Rubric

All of the tests in your project must succeed in order to complete this phase.

To pass off this assignment submit your work to the course auto-grading tool. When that is done, meet with a TA and demonstrate that your Chess client and server meet all requirements and assign you a final grade.

• 🎥 Phase 6 Overview (10:39) - [transcript]