2.2.4 Quit
The program should print a goodbye message, and safely terminate without crashing.
> 4
Goodbye
2.3 Base Gameplay
During base Qwirkle gameplay, the 2 players take turns placing tiles from their hand onto the board.
At the start of the player’s turn, the program should show (in order):
1. The name of the current player
2. The scores of both players
3. The state of the board
6
4. The tiles in the current player’s hand
5. The user prompt
The current player may then take one of two actions:
1. Place a tile onto the board
2. Replace on tile in their hand
Once the player successfully takes their action, their turn ends, and the other player’s turn starts.
Alternatively, the player may perform one of two game functions:
1. Save the game to a file
2. Quit the game
Below is an example of a sequence of actions and game functions for two players, named A and B. The next
sub-sections, describe the individual aspects of the base gameplay.
< previous output >
A, it's your turn
Score for A: 6
Score for B: 6
0 1 2 3 4 5
-------------------
A | | | | | | |
B | | |B4|B6|B5| |
C | | |R4| | | |
D | |Y1|Y4|Y2| | |
E | | |P4| | | |
F | | | | | | |
Your hand is
Y5,G5,R5,O2,B1,P6
> place G5 at C4
B, it's your turn
Score for A: 8
Score for B: 6
0 1 2 3 4 5
-------------------
A | | | | | | |
B | | |B4|B6|B5| |
C | | |R4| |G5| |
D | |Y1|Y4|Y2| | |
E | | |P4| | | |
F | | | | | | |
Your hand is
P2,P3,O6,G1,Y4,B2
> replace G1
< gameplay continues >
2.3.1 Tile Codes
Tiles are represented by a 2-character code:

To make it easier to visually differentiate tiles, colours are represented by letters, and shapes are represented
by integers. The codes are given in the table below
7
Colour Colour Code Shape Shape Code
Red R Circle 1
Orange O 4-Star 2
Yellow Y Diamond 3
Green G Square 4
Blue B 6-Star 5
Purple P Clover 6
For example, the Yellow Square tile is represented by the code: Y4
!
The Start-up code provides useful #define statements for these codes.
2.3.2 The Board
The display of the game board consists of two features:
1. Tile Display
2. Grid Co-ordinates
The board is a 2D grid of tiles, up to a maximum size of 26x26. However, some locations of the 2D grid may
be empty, meaning that no tile has been placed there. When the board is displayed, all locations that contain
a tile are filled with the tile code, and empty locations filled with two-spaces.
!
The examples is this spec use an expandable board (see the Minor Enhancements in Section 4.1). That is,
the board is only as large enough as necessary, and expands as the players add tiles.
For the base game-play you may use a fixed size board.
The grid co-ordinates use:
• Uppercase Letters for rows
• Integers for columns
Board locations are always referenced in row-column fashion:

For example, the blue square is at grid co-ordinate B2, and the yellow circle is at grid co-ordinate D1.
0 1 2 3 4 5
-------------------
A | | | | | | |
B | | |B4|B6|B5| |
C | | |R4| | | |
D | |Y1|Y4|Y2| | |
E | | |P4| | | |
F | | | | | | |
You could store the board as A vector of vectors of Tiles
!
In your implementation you must use a vector to store the board.
2.3.3 The Player’s Hand
The player’s hand is an ordered linked list of tiles.
!
In your implementation you must use a linked list to store the tiles in the player’s hand. You must
implement your own version of a Linked List.
The player’s hand is displayed as a comma separated list of tiles.
Your hand is
Y5,G5,R5,O2,B1,P6
The order of tiles in the player’s hand is important for testing purposes!
8
• When adding a tile, it is always added at the end of the list.
• When removing a tile, the remaining tiles stay in the same order.
2.3.4 The Tile Bag
The tile bag, contains the rest of the tiles that are not on the board or in player’s hands. The tile bag must
be stored as an ordered linked list. The contents of the tile bag is never displayed to the users. However, the
contents of the tile bag is stored in the saved game file.
!
In your implementation you must use a linked list to store the tiles in the tile bag. You must implement
your own version of a Linked List.
The order of the tile bag is determined when generating a new game. When a tile is drawn from the bag, it is
taken from the front of the linked list. If tiles are added to the bag, they are added to the end of the linked list.
2.3.5 Player Action: Place a Tile
The current player may place a tile onto the board using the command:
place at
The command contains two elements:
1. A tile to place
2. The grid location to place the tile
For example, using the above hand and board, if the player performs:
> place G5 at C4
This results in the board:
0 1 2 3 4 5
-------------------
A | | | | | | |
B | | |B4|B6|B5| |
C | | |R4| |G5| |
D | |Y1|Y4|Y2| | |
E | | |P4| | | |
F | | | | | | |
After the command is given, the program must:
1. Check that the command is correctly formatted.
2. Check that the placement of tile is legal according to the rules of Qwirkle.
If the player’s action is legal, the program should:
1. Place the tile onto the board
2. Update the player’s score
3. Draw a replacement tile from the tile bag and add it to the player’s hand, if there are available tiles
4. Continue with the other player’s turn
2.3.6 Player Action: Replace a Tile
The current player may replace one tile in their hand using the command:
replace
For example, using the above hand the player may take the following replace action:
> replace P6
After the command is given, the program must:
1. Check that the command is correctly formatted.
9
2. Check that the tile is in the player’s hand.
If the player’s action is legal, the program should:
1. Remove the tile from the players hand and place it in the tile bag. (If the player has two tiles with the
same code, the first tile in the list should be replaced)
2. Draw a new tile from the tile bag and add it to the player’s hand
3. Continue with the other player’s turn
2.3.7 Function: Saving the Game
The current player may save the game to a file using the command:
save
The program should save the current state of the game to the provided filename (overwriting the file if it already
exists). Then the program should display a message and continue with the gameplay. The current player does
not change, so that a player may save the game and then take a turn.
> save savedGame
Game successfully saved
>
If the program has problems saving the file, it should display a message, and continue with normal gameplay
without crashing.
The format of the saved file is as given below. Each item is saved on a new line.










The format for each of the items is:
• Name: ASCII text
• Score: Integer
• Player hand and tile bag: comma separated ordered list
• Current board shape: Height, width
• Board State: All tiles currently placed on the board should appear as a list of tile@position.
For example, if the game in Section 2.3 was saved the saved game file will look like:
A
8
Y5,R5,O2,B1,P6,Y3
B
6
P2,P3,O6,Y4,B2,O3
6,6
B4@B2, B6@B3, B5@B4, R4@C2, G5@C4, Y1@D1, Y4@D2, Y2@D3, P4@E2
P2,B5,.....
A
10
2.3.8 Function: Quit
The program should quit without crashing, as per the instructions in Section 2.2.4.
2.3.9 Special Operation: QWIRKLE!
If the player scores a Qwirkle (see the game rules) on their turn, then the program should print out an additional
message, before displaying the game information. Remember to update the player’s score accordingly.
> place .. at ..
QWIRKLE!!!

>
2.3.10 Special Operation: Starting a New Game
When a new game is started, a special sequence of operations must be conducted:
1. Create the ordering for the tile bag
2. Set up the initial player hands
3. Start with an empty board, with player 1 as the starting player
You will need to devise your own algorithm to “shuffle” the bag of tiles to create a “random” initial order. This
is left up to your own invention. The lectures will talk about randomness is C++ programs.
Then the initial tiles are added to the player’s hands. 6 tiles are drawn from the tile bag and placed in the 1st
player’s hand. Then 6 tiles are drawn from the tile bag and placed in the 2nd player’s hand.
Finally, the board starts with no tiles placed, so that when displayed, it should be empty.
2.3.11 Special Operation: Ending a Game
The game ends when:
1. The tile bag is empty, and
2. One player has no more tiles in their hand
If the game ends, the program should:
• Display the end game message
• Display the scores
• Display the name of the winning player
• Then quit, according to Section 2.2.4.
For example:
Game over
Score for : 000
Score for : 000
Player won!
Goodbye
2.3.12 Special Operation: Loading a Game
To load a game from a saved game file, the program should read the contents of the saved game file, and update
all data structures in the program using the information in the saved game file. See Section 2.3.7 for the format
of the saved game file. Specifically, the program should take note of:
• The player’s name and scores
• The tiles in each players hand
• The state of the board
11
• The order of the tiles in the tile bag
• The current player - the next player to take a turn
Once the game has been loaded, gameplay continues resumes with the current player.
2.4 User Prompt
The user prompt is displayed whenever input is required from the user. It is a greater-than symbol (>), followed
by a space. It is assumed that all user inputs are provided as a single line of input.
When shown the prompt, the user should see in their terminal window:
> v
If at any point the user enters invalid input, or the validation checks of the input fail (see each section) then
the program should print Invalid Input and re-show the prompt.
> qwerty
Invalid Input
> v
2.4.1 EOF Character
If an any time the user enters the EOF (end-of-file) character, the the program should Quit, following the
procedure in Section 2.2.4. That is:
> ^D
Goodbye
This behaviour with the EOF character is necessary to ensure your program terminates at the end of every test
case.
2.5 Rule Changes
For the base Qwirkle implementation, the following rules have been modified:
• A New game always begins with Player 1 and an empty board
• Tiles are placed one at a time.
• Players can only replace one tile at a time
• Maximum board size of 26x26
• There are only 2 tiles of each type (rather than 3 of each type). This makes it highly likely the game will
fit within the 26x26 board, and reduce the complexity of your test cases. The modified game will have 72
blocks, in 6 colors and with 6 different shapes and 2 of each type.
For your Milestone 3 enhancements, you may restore some or all of these rules to their original form.
3 Deliverables
3.1 Mandatory Requirements
As part of your implementation, you must:
• Implement your own Linked List
• Use your Linked List implementation to store the player’s hands and the tile bag.
• You should use vectors to store the current board state.
• You may only use the C++14 STL. You may not incorporate any additional libraries.
If you fail to comply with these mandatory requirements, marks will be deducted.
12
3.2 Milestone 1: Test Cases (Group Component)
For Milestone 1, you must develop test cases for your Qwirkle implementation, including your enhancements.
These test cases will help ensure that your Qwirkle implementation is correct.
A single test case consists of 4 files, 2 mandatory and 2 optional.
1. .input - Input to provide to the Qwirkle program via stdin
2. .output - Expected output from the Qwirkle program on stdout
3. (Optional) .save - Input save file to provide to the Qwirkle program if required by the test.
4. (Optional) .expsave - Expected output saved game file.
A test is run using the following sequence of commands.
./qwirkle < .input > .gameout
diff -w .output .gameout
if [-e .expsave] diff -w -y .expsave
If this command displays any output, then the test has failed. Testing uses the diff command. This
command checks to see if two files have any differences. The -w options ignores any white-space.
To make testing reliable, you should note if the test evaluates the saved game output, then ensure the test uses
a suitable filename in place of .
!
The Qwirkle program has some degree of randomness due to the random ordering of the tile bag. To
overcome this issue when testing, when appropriate, you may start your test with loading a saved game
(will contain the ordering of the tile bag, hence the execution from that point is deterministic).
3.3 Milestone 2: Basic Qwirkle Implementation (Group Component)
For Milestone 2, your group must implemented the base Qwirkle program as described in Section 2.
Section 2 lists the components that your group must implement. Generally, it is up to your group to decide the
best way to implement these components. However, there are some important requirements that your group
must satisfy.
Aspects of this specification are flexible and open to your interpretation. It is up to your group to determine the
best course of action. You will need to analyse and justify your choices in the report.
3.3.1 Requirements
Your group will implement a game of Qwirkle that:
• Is a 2-player game.
• Both players are “human users” that play the game by interacting with the terminal, that is, through
standard input/output.
• Using the Qwirkle board of fixed size.
You will implement a simplified version of Qwirkle. These changes are listed in section 2.5.
Your implementation should provide the following functionality:
• A main menu, that allows users to perform actions such as setting up a new game, loading an existing
game, showing “credits” (details of the people who wrote the software), and quitting the program.
• Save a game to a file.
• Load a previously saved game from a file, and resume game play from the saved state.
• A way to represent and display the Qwirkle board and player hands the user.
• A User prompt for entering all commands from standard input.
• Base gameplay functionality as described in Section 2.3.
• The program should terminate without crashing if the EOF character is given on standard input.
• Completely error free. Your program must not crash, segfault or otherwise contain logic errors.
Your group will also need to consider the data structures that are used to represent aspects of Qwirkle, and
functionality. It is up to your group to make this decision provided that you meet the requirements in section
3.1. In your report your group will be marked on your analysis of the above choices.
Finally, remember to do the the group contribution spreadsheet described in 5.3.
13
3.4 Milestone 3: Enhancements (Individual Component)
In Milestone 3, as an individual you will make signification expansions(s) to the functionality of your group’s
Qwirkle program. This milestone is your opportunity to showcase to us your skills, capabilities and knowledge!
You will select your enhancements from the provided options in Section 4. Additionally, if you
group’s Milestone 2 solution has significant errors or is significantly incomplete, please read Section 4.3.
Milestone 3 is a very open-ended. You are given some directives, however, there is a lot of room for you to make
considered choices. However, this showcase of your skills is not just about “making the code work”. A major
focus is on how you choose to implement an enhancement, and the justifications of the reasons why you chose
a given data structure, class hierarchy, language feature, or algorithm to name a few examples. Enhancements
are classified as minor or major. Enhancements must be substantially functional to get marks.
To get a higher grade you will need to implement one or more minor or major enhancements. This is described
in the marking rubric.
3.4.1 Configurable Enhancements
Where reasonably possible, your enhancements should be configurable. That is, it should be possible to enable/disable
each enhancement at run-time (not through compilation). In particular, this means your enhancements
can be “turned-off” so that your program runs the same as Milestone 2 (verbatim).
3.4.2 Changes to Saved Game file
Some enhancements may require you to modify the format of the saved-game file. However, it is recommended
that your program with enhancements still supports loading games from the default saved-game format used in
Milestone 2.
To distinguish your new saved-game format from the “default” milestone 2 format, we recommend adding a
special code at the start of your new saved-game format, such as:
#myformat

...
3.5 Milestone 4: Written report & Demonstration (Group + individual Component)
3.5.1 Written report
Your group must write a report, that analyses what your group has done in this assignment. Additionally,
each individual must write a short report that analyses their individual enhancement(s). The group should
combine the group report and the individual report and one group member should submit it via canvas. The
combined report is due at the same time as the individual submission (11.59pm, Friday 28 May 2021).
• The report should be A4, 11pt font, 2cm margins and single-space.
• The section of the report describing the group’s work must be no more than 4 pages.
• Each individual must add 1 additional page about their enhancements.
• Thus the final report must not exceed 8 pages for a group of four.
• Only the first 4 pages (group), and 1 page (individual) will be marked.
• Modifying fonts and spacing will count as over length.
• Figures, Tables and References count towards these page limits.
In this assignment, you are marked on the analysis and justification of the choices you have made. Your report
will be used (in conjunction with the demonstration) to determine the quality of your decisions and analysis.
Good analysis provides factual statements with evidence and explanations.
Statements such as:
“We did because we felt that it was good” or “Feature is more efficient”
do not have any analysis. These are unjustified opinions. Instead, you should aim for:
“We did because it is more efficient. It is more efficient because