Archive‎ > ‎Fall 2009‎ > ‎Course Project‎ > ‎Buddy Suite‎ > ‎

Milestone 4:

Please keep in mind the Collaboration Policy. If you have any questions regarding the assignment, do ask the course staff. For this milestone, we will meet with each team to discuss the details of your server message handling. These meetings will last for maximum one hour. We will coordinate with you on the time slots for meeting with the TAs.

The total number of points for this milestone is 100.
The points are awarded as follows:

  • 5 points - functional ant build file (if the build fails, we will not grade your code further)
  • 10 points - creating a game
  • 10 points - moving a piece
  • 10 points - handling promotion of pieces
  • 10 points - resigning from a game
  • 10 points - handling draws
  • 10 points - handling checkmates
  • 10 points - handling game timers
  • 10 points - multiple chess games at the same time
  • 13 points - state diagram
  • 2 points - workload information
  • 20 points - Extra functionality
1. Overview
In the previous milestone, you implemented the chess logic, whose purpose was to validate the moves made by the player. Hence, it was only a single-player game, where the user played with himself, alternating white and black moves.
In this milestone, your task will be to add the ability to play chess with your friends.
2. Implementation
Playing with friends is done via the mediation of a server. The client submits his move to the server, which checks whether it is a valid move, and if so, sends it to the other clients, who updates the game view accordingly.
The client communicates with the server following a protocol. As in previous milestones, it is based on XML. You can find its specification here. The following explanations will give you a few concrete examples on how to use the protocol. These examples are not exhaustive, and you should read the more detailed specifications for a complete understanding.
2.1. Starting a Game (10 pts)
Suppose that you are Bob and you want to play chess with Alice.
The first step to play chess with a friend, is to create a new game and specify the maximum duration of the game. Following the protocol, the message you, Bob, will send to the server is the following.
  • <chess username="alice"><create timers="10"></create></chess>
The timers argument specifies the maximum duration of the game in minutes. The username that you must specify in each chess message corresponds to the opponent with whom you are playing.
The server will send this game creation message to the opponent, who will have to opportunity to accept or refuse it. For example, the player Bob will receive the following from Alice:
  • <chess username="bob"><inviteaccept /></chess> in case Alice accepts
  • <chess username="bob"><invitedecline /></chess> in case Alice refuses

When the user accepts an invitation, a chess window is created and the game is started.

2.2. Moving Pieces (10 pts)
Since Bob started the game, he starts playing with white pieces. After he has validated his move, it is Alice's turn to move. For example, if Bob wants to move the pawn on "d2" to "d4", he would send the following message to the server:
  • <chess username="alice"><move from="d2" to="d4" /></chess>
This message tells Alice that Bob wants to move from "d2" to "d4". Chess moves are expressed in algebraic notation.
Likewise, Alice will send the following to move here knight from "b8" to "c6":
  • <chess username="bob"><move from="b8" to="c6" /></chess>
2.3. Handling promotions (10 pts)
Promotions are handled in a similar way, except that each player has to specifiy the desired piece she/he wants to get after the move completes.
If a received move is not correct, you have to notify the user (normally the server checks the moves, but it might be faulty). All moves have to be checked, including promotions. In case an incorrect move is detected, you must notify the user and resign from the game (see next section).
2.4. Ending a Game (10 + 10 + 10 pts)
Either player can resign from a game at any time, by sending the "resign" command to the opponent. In this case, the server will send to the opponent an "end of game" message, specifiying the winner. For example, if Alice resigns, the server will send to Bob and Alice:
  • <chess username="bob"><end winner="white" /></chess>

Draws can only be initiated by the player in turn, but contrary to resigns, they must be accepted or declined by the opponents. For instance, if Bob requests a draw and Alice refuses it, the communication would look as follows:

  1. Bob ==> Alice <chess username="alice"><drawask /></chess>
  2. Alice ==> Bob <chess username="bob"><drawdecline /></chess>
Checkmates are handled by the server automatically, similarly to "resign". The server will send the notification about the winner to the opponents.
2.5. Handling Timers (10 pts)
The timers keep track of how much time each user spent on playing. They are managed by the server. Each client can request the current value of the timer, in order for example, to display it on the screen. For instance, if Alice wants to know how much time she still has to play, the communication would look like this:
  1. Alice ==> Server <chess username="bob"><timers /></chess>
  2. Server ==> Alice <chess username="bob"><timers white="5" black="7" /></chess>
In this example, the server notifies Alice, that she has 7 seconds left and that Bob has 5 seconds.
When the time is up, the server sends an end of game message to the players.

Note that timers will continue during a draw request.
2.6. Multiplayer Mode (10 pts)
In this part, you will enable multiplayer mode for the chess game. In this mode, a player is allowed to play concurrent games with different friends. However, the player cannot play multiple games with the same friend.
As you noticed from the previous sections, every chess message contains the username of the opponent. This allows the server to track who you are playing with. It is possible to start a concurrent game by issuing a create game request with different user names. For example, if Bob wants to start a game with both Alice and Carol, he will send to the server: 
  • <chess username="alice"><create timers="10"></create></chess>
  • <chess username="alice"><create timers="10"></create></chess>
3. Extra Functionality (20 pts)
3.1. Viewer Mode (15 pts)
As an extra functionality, you will implement an on-line viewing functionality. This viewing functionality consists in asking your friends who they are playing with, and then selecting one of them and have the friend forward you all the moves of the game.  
This functionality can be useful as an e-learning tool. Suppose that two chess champions are playing with each other. You can follow their game in real time by asking one of them to forward all the game moves to you. Multiple people can assist to a game at the same time.
Since the protocol for this functionality is not defined, your task will be to design and implement one. For this, you will have to use the protocol extensions defined in the specification.
3.2. Improving Battery Life (5 pts)
It is crucial to design programs so that they consume the least amount of energy, especially when they run on embedded devices. In this part of the assignment, you will optimize your application for battery life. To get a broad understanding of the various challenges that come up in improving battery life, watch the following Google Talk:
You task will be to pick one of the power-saving issues presented in the video, which you think is the most relevant for the Buddy Suite, explain why you think it is important, and present an approach towards addressing that issue.
4. State Diagram (13 pts)
You are required to provide the state diagram of your implementation of the chess protocol. This state diagram must show what actions your program makes when it receives incomming messages, such as "checkmate" or "resign".
The state diagram shows how your program reacts to inputs from the server and what output it produces in the given state. Each state has a set of valid inputs that will trigger a transition to the next state. For example, consider a dummy chess game that can accept play requests, process moves, and react to checkmate messages. A possible state diagram would be the following:
The filled black circle is the initial state of the program, while the filled circle with a thin shell is the final state of your program (e.g., program exit). Note that only one transition is allowed to be triggered at each time (deterministic state diagram).
There are many software packages available for drawing state diagrams. If you like WYSIWYG tools, you can use DIA. If you prefer writing code instead, you can use Graphviz. To get you started quickly with Graphviz, here is the code that generates the above state diagram. You can generate a PNG image by issuing dot -Tpng > example1.png.

Graphviz code for sample diagram

digraph "G" {

 label = "State diagram for dummy chess game";


 rankdir = "LR";

 node [color="gray",style="filled"];

 edge [fontname="courier"];


 initial [shape=circle,style=filled,label="",color=black,size="0.5"];

 final [shape=circle,style=filled,peripheries=2,label="",color=black];


 progstarted [label="Waiting for\ngame request"];

 playing [label="Playing"];

 lost [label="Lost"];

 win [label="Win"];


 initial -> progstarted;

 progstarted -> progstarted [label="GameRequest\nrejected"];

 progstarted -> playing [label="GameRequest\naccepted"];


 playing -> lost [label="msg checkmate &&\nplayer==me"];

 playing -> win [label="msg checkmate &&\nplayer!=me"];


 lost -> final;

 win -> final;


5. Deliverables

Please send an email to the SwEng Staff with the link to the SVN repository where your project is located. Remember, the structure of the folder defined by the address you provide must pass the check_structure.bat test. The link to your SVN repository should be sent by December 7, the latest.

By December 8, you have to hand in:
  • The code for FriendFinder + ChessGameUI + ChessGame Logic +
  • ant build file that:
    • compiles the code
    • creates the apk file
    • installs FriendFinder+ChessGameUI+ChessGame Logic on the two running emulators, corresponding to two friends

    A functionally complete build file will be rewarded with 5 points. If your build file does not do all of the required actions, you will get 0 points. Furthermore, your project will not be evaluated.

  • Note: The code you deliver must run on the client's machine. A client is not going to be happy if the developers tell him/her that the program worked on the developers' machines. The computers in the BC07-08 laboratory are the client's machines. Your code must run on the BC machines.
  • The code must also run on the phones we provided to you
  • You must use the script check_structure.bat on the BC machines to check that your build system complies with the requirements. Download the attached check_structure.ba_ and rename it to check_structure.bat. Run it by invoking c:\path_to_check_structure\check_structure.bat path_to_project, for example using check_structure.bat "c:\Documents and Settings\myname\sweng".
    You must send the path to the SVN repository of your project reported by the script to the sweng staff mailing list.