Description
1 Introduction
This project (Project B), and the next one (Project C), will continue with the same theme introduced in
Project A – namely, an implementation of the game of Nim. Please refer to the Project A specification
for a description of the game and its rules.
In Project A, a simple Java program was created to handle Nim’s core game play mechanics. In the next
two projects, the objective is to design and implement a more complete version of Nim, making full use
of Java’s object-oriented paradigm.
Key Knowledge Points Covered in Project B:
1. Design of the class structure for the project requires the knowledge of UML diagrams (taught in
Week 5).
2. Implementation requires understanding of Classes (taught in Week 4 – 6) and Arrays (taught in
Week 7).
You may start working on the project right away except the array part. If you would like to start to
work on the array part before week 7, you may learn basics of arrays by yourself.
2 Requirements
In this project, we introduce a third class NimGame. The game playing process is delegated from Nimsys
to NimGame. Since only one game will be active at any given time, only a single NimGame instance
is required at any time by Nimsys. Nimsys should also maintain a collection of players. Initially, this
collection will be empty – players will need to be added in order to play a game.
A NimGame instance needs to have the following information associated with it:
• The current stone count
• An upper bound on stone removal
c The University of Melbourne 1
• Two players
The system should allow for games of Nim to be played, with the rules of the game, and the players,
specified by the user.
A player, as described by the NimPlayer class, needs to have the following information associated with
it:
• A username
• A given name
• A family name
• Number of games played
• Number of games won
The system should allow players to be added. It should also allow for players to be deleted, or for their
details to be edited. Players should not be able to directly edit their game statistics, although they
should be able to reset them.
The system is a text based interactive program that reads and executes commands from standard input
(the keyboard) until an ‘exit’ command is issued, which will terminate the program. If a command
produces output, it should be printed to standard output (the terminal).
When Nimsys is first executed, it should display a welcome message, followed by a blank line. A
command prompt (a ‘dollar’ sign, i.e., $) should then be displayed.
In following description, all command line displays are put in a box. This is only for easier understanding
the format. The box should NOT be printed out by your program, only the contents in the
box should be printed. The command prompt is illustrated below:
Welcome to Nim
$
At any given time, the system can be in one of two states – either a game is in progress, or no game
is in progress. Hereafter, these will be referred to as the ‘game’ and ‘idle’ states, respectively. (Note:
the states are just used to explain the mechanism of Nimsys. You don’t need to create a variable called
‘state’ in your code).
When in the idle state, the system should accept the following commands. These commands are entered
at the Nimsys command prompt. If a command produces output, it should be printed immediately below the line where the command was issued. After the command has executed, a new command prompt
should be displayed. This new command prompt should be separated from the previous command (and
its output, if any) by a single blank line.
Note that in the syntax descriptions below, a term enclosed in square brackets indicates an
optional parameter. The input is assumed to be always valid, but not always correct. Valid
input suggests that entered data have the same type of the corresponding variables, e.g., String data
are entered for String variables, integer data are entered for int variables. Correct input suggests
that the entered data can be correctly processed by the corresponding command, e.g., adding an existing
user and removing a nonexistent user are incorrect input. Unless otherwise stated, you are NOT
required to check validness, but you ARE required to check the correctness of the input,
as shown in the below examples.
c The University of Melbourne 2
1. addplayer – Allows new players to be added to the game. If a player with the given username
already exists, the system should indicate this, as shown in the example execution.
Syntax: addplayer username,family_name,given_name
Example Execution:
(a) add a new user:
$addplayer lskywalker,Skywalker,Luke
$
(b) add a user who already exists in the system
$addplayer lskywalker,Skywalker,Luke
The player already exists.
$
2. removeplayer – Allows players to be removed from the game. The username of the player to be
removed is given as an argument to the command. If no username is given, the command should
remove all players, but in this case, it should display a confirmation question first. If a username
for a non-existent player is given, the system should indicate that the player does not exist. The
format of these messages is illustrated in the example execution below.
Syntax: removeplayer [username]
Example Execution:
(a) remove a nonexistent user
$removeplayer lskyrunner
The player does not exist.
$
(b) remove a user
$removeplayer lskywalker
$
(c) remove all users
$removeplayer
Are you sure you want to remove all players? (y/n)
y
$
3. editplayer – Allows player details to be edited. Note that the player’s username cannot be changed
after the player is created. If a username for a non-existent player is given, the system should
indicate that the player does not exist, as illustrated in the example execution.
Syntax: editplayer username,new_family_name,new_given_name
Example Execution:
(a) edit a nonexistent user
$editplayer lskyrunner,Skywalker,Laurence
The player does not exist.
$
c The University of Melbourne 3
(b) edit a user
$editplayer lskywalker,Skywalker,Laurence
$
4. resetstats – Allows player statistics to be reset. The username of the player whose statistics are to
be reset is given as an argument to the command. If no username is given, the command should
reset all player statistics, but as with the ‘removeplayer’ command, a confirmation question should
be displayed in this case. If a username for a non-existent player is given, the system should indicate
that the player does not exist, as illustrated in the example execution.
Syntax: resetstats [username]
Example Execution:
(a) reset a nonexistent user
$resetstats lskyrunner
The player does not exist.
$
(b) reset a user
$resetstats lskywalker
$
(c) reset all users
$resetstats
Are you sure you want to reset all player statistics? (y/n)
y
$
5. displayplayer – Displays player information. The username of the player whose information is to
be displayed is given as an argument to the command. If no username is given, the command
should display information for all players, ordered by username alphabetically. If a username for a
non-existent player is given, the system should indicate that the player does not exist, as illustrated
in the example execution. Please note when displaying player, the sequence of syntax is
username,givenname,familyname,number of games played,number of games won.
Syntax: displayplayer [username]
Example Execution:
(a) display a nonexistent user
$displayplayer lskyrunner
The player does not exist.
$
(b) display a user
$displayplayer lskywalker
lskywalker,Luke,Skywalker,3 games,3 wins
$
c The University of Melbourne 4
(c) display all users
$displayplayer
dvader,Darth,Vader,7 games,1 wins
hsolo,Han,Solo,4 games,3 wins
lskywalker,Luke,Skywalker,3 games,3 wins
$
6. rankings – Outputs a list of player rankings. There are three columns displayed. The first column
displays percentage wins or winning ratio, the second column displays the number of games played,
and the final column shows the player’s full name, that is, first name followed by last name. This
command takes the sort order as an argument. The sort order is desc or descending by default.
That is, if no argument or desc is provided, the program should rank the players by the percentage
of games they have won in descending order, i.e., players with highest percentage wins should
be displayed first. If the user provides asc as an argument, the players should be ranked by the
percentage of games they have won in ascending order. Round the percentages to the nearest integer
value. However, you should use the exact values of winning ratios when comparing and sorting two
users’ winning ratios. Ties should be resolved by sorting on usernames alphabetically. Only the
first 10 players should be displayed, if there are more than 10. The output should be formatted
according to the example below. For the purposes of formatting the output, you may assume that
no player has played more than 99 games. Note that the vertical lines need to be aligned, with
a single space appearing on either side. This means that in the first column you must have 5
characters consisting of a number, ’%’, and spaces. The first column must be left-justified.
Syntax: rankings [asc|desc]
Example Execution:
(a) rank all users in descending order
$rankings
100% | 03 games | Luke Skywalker
75% | 04 games | Han Solo
14% | 07 games | Darth Vader
$
(b) rank all users in descending order
$rankings desc
100% | 03 games | Luke Skywalker
75% | 04 games | Han Solo
14% | 07 games | Darth Vader
$
(c) rank all users in ascending order
$rankings asc
14% | 07 games | Darth Vader
75% | 04 games | Han Solo
100% | 03 games | Luke Skywalker
$
7. startgame – Creates and commences a game of Nim. The game’s rules, and the usernames of
the two players, are provided as arguments. You may assume that the initial stones and upperbound arguments are valid and correct. However, if at least one (i.e. one or two) of the
c The University of Melbourne 5
usernames doesn’t correspond to an actual player, the system should indicate this by the output
“One of the players does not exist.”, and the game should not commence.
Otherwise, the ‘startgame’ command will commence a game, i.e., after executing it, the system is in
the game state. When a game is in progress, the system should proceed according to the game play
mechanics discussed in Project A, i.e., players should, in an alternating fashion, be asked to enter
the number of stones they would like to remove, with the game state being updated accordingly. In
this project, bounds on stone removal should be enforced. That is, players should only be allowed
to remove between 1 and N stones inclusive, where N is the upper bound or the number of stones
remaining, whichever is smaller. Once all the stones are gone, a winner should be announced, and
the statistics for the two players should be updated accordingly. The system should then return to
the idle state, and a command prompt should be displayed again.
Syntax: startgame initialstones,upperbound,username1,username2
Example Execution:
(a) start game with a non-existent user
$startgame 10,3,lskyrunner,hsolo
One of the players does not exist.
$
c The University of Melbourne 6
(b) start a game
$startgame 10,3,lskywalker,hsolo
Initial stone count: 10
Maximum stone removal: 3
Player 1: Luke Skywalker
Player 2: Han Solo
10 stones left: * * * * * * * * * *
Luke’s turn – remove how many?
3
7 stones left: * * * * * * *
Han’s turn – remove how many?
4
Invalid move. You must remove between 1 and 3 stones.
7 stones left: * * * * * * *
Han’s turn – remove how many?
3
4 stones left: * * * *
Luke’s turn – remove how many?
3
1 stones left: *
Han’s turn – remove how many?
0
Invalid move. You must remove between 1 and 1 stones.
1 stones left: *
Han’s turn – remove how many?
1
Game Over
Luke Skywalker wins!
$
8. exit – Exits the Nimsys program.
Syntax: exit
Note that before you call the exit method in Java using System.exit(0); , you must
print a blank line first.
(a) exit the system
$exit
c The University of Melbourne 7
As was described earlier, it is important that your design makes good use of object-oriented design
principles. This is particularly relevant when it comes to implementing the actual gameplay. In a real
game, game proceeds with each player performing the action of removing some number of
stones from the game. Your design should reflect this structure.
Don’t worry about changing your output for singular/plural entities. Simply always use plural entities,
i.e., you should output ‘1 games’, ‘1 wins’, ‘1 stones’, etc.
Checklist For Solution
• Error handling issues
Only the following errors need to be handled (you may choose to handle more if you wish):
Adding a new player with an existing username.
Error message: The player already exists.
Follow-up operation: Print ‘$’ and prompt for user input again.
Removing a player with a non-existing username.
Error message: The player does not exist.
Follow-up operation: Print ‘$’ and prompt for user input again.
Resetting the statistics of a player with a non-existing username.
Error message: The player does not exist.
Follow-up operation: Print ‘$’ and prompt for user input again.
Displaying a player with a non-existing username.
Error message: The player does not exist.
Follow-up operation: Print ‘$’ and prompt for user input again.
Starting a game where at least one of the player’s username does not exist.
Error message: One of the players does not exist.
Follow-up operation: Print ‘$’ and prompt for user input again.
Removing stone outside of the range [1, stoneRemovalUpperBound], where stoneRemovalUpperBound
is the maximum number of stones allowed to be removed in one turn.
Error message: Invalid move. You must remove between 1 and stoneRemovalUpperBound
stones (do not need to consider the singular or plural form of “stone”).
Follow-up operation: Prompt for the same player to remove stone again.
• Blank line and whitespace related issues.
Make sure that between the output of last command (including indication for nonexistent
users, confirmation for all-user operations, display results, and game results) and the next
command prompt, there is one blank line.
Make sure that there is a whitespace between (y/n) and Are you sure… sentence.
Make sure that there is NO whitespace after each comma, e.g., when displaying users, it
should be davader,Darth instead of davader, Darth.
Make sure that in game state, there is one blank line before the Initial stone count…
and one blank line after the Player 2:….
Make sure that in game state, if a user input an invalid move, there is one blank line between
the user-input move and the indication sentence Invalid move….
Make sure that an extra blank line is printed out before calling System.exit(0); when
command exit is entered.
• Ranking display related issues.
Make sure that the ranking is in a descending order of winning ratio by default or when “desc”
is provided as an argument.
c The University of Melbourne 8
