Advanced Programming Techniques

COSC1076 | Semester 1 2021

Assignment 2 | Implementing Qwirkle

Contents

1 Introduction

1.1 Overview

In this assignment you will implement a 2-player text-based version of the Board Game Qwirkle.

For an explanation of the rules and gameplay:

• TableTop rules explanation of full game: https://youtu.be/Hp3IwPbZYSE?t=60

• Rules: Available on Canvas (https://www.ultraboardgames.com/qwirkle/game-rules.php).

However, this assignment will use a modified version of the rules, detailed in Section 2.5.

In this assignment you will:

• Practice the programming skills covered throughout this course, such as:

– ADTs

– Linked Lists

– Pointers

– Dynamic Memory Management

– File Processing

– Program State Management

– Exception Handling

• Practice the use of testing

• Implement a medium size C++ program:

– Use features of C++14

– Use elements of the C++ STL

• Work as a team

– Use group collaboration tools

This assignment is divided into four Milestones:

• Milestone 1 (Group work): Test Cases, to be developed to ensure your Qwirkle implementation is correct.

• Milestone 2 (Group work): A fully functioning implementation of the base Qwirkle game play, which pass Milestone 1 tests. The group work (milestone 1 & 2) is worth 30% of the course mark. The group component (M1 & M2) is due 11.59pm, Friday 14 May 2021(Week 10).

• Milestone 3 (Individual work): You will individually extend upon your group’s implementation with additional functionality (called enhancements). The individual work is worth 15% of the course mark. The individual component (M3) is due 11.59pm, Friday 28 May 2021(Week 12).

• Milestone 4: Written report & demostration. The report analysing the design and implementation of your software, and the use of your test cases. You will demonstrate your group and individual work. This is where your final work will be graded. The report is due 11.59pm, Friday 28 May 2021(Week 12).

Group Progress Update (Group work): Your group will provide regular updates on your progress in this assignment to your tutor during your weekly lab classes. This will require your group to have completed a list of activities. Group Progress Update will not be marked directly, however, this will influence the final grade.

1.2 Group Work

The group work must be completed in groups of 4.

1. You may form groups with any student in the course.

2. We strongly recommend that you form groups from within your labs, because:

• Your tutor will help you form groups,but only within your lab.

• You will have plenty of opportunity to discuss your group’s progress and get help from your tutor during the rest of the course. It will be extremely helpful for your whole group to be present, but this can’t happen if you have group members outside the lab.

Groups for Assignment 2 must be registered with your tutor by week 8 lab1 . Your tutor “register” your group on Canvas. If you are unable to find a group, discuss this with your tutor as soon as possible.

If at any point you have problems working with your group, inform your tutor immediately, so that issues may be resolved. This is especially important with the online delivery of the course. We will do our best to help manage group issues, so that everybody receives a fair grade for their contributions. To help with managing your group work we will be requiring your group to use particular tools. These are detailed in Section 5.

There are important requirements about keeping your tutor informed if you have been unwell or other wise unable to contribute to your group. Remember your actions affect everybody in your group.

1.3 Learning Outcomes

This assessment relates to all of the learning outcomes of the course which are:

• Analyse and Solve computing problems; Design and Develop suitable algorithmic solutions using software concepts and skills both (a) introduced in this course, and (b) taught in pre-requisite courses; Implement and Code the algorithmic solutions in the C++ programming language.

• Discuss and Analyse software design and development strategies; Make and Justify choices in software design and development; Explore underpinning concepts as related to both theoretical and practical applications of software design and development using advanced programming techniques.

• Discuss, Analyse, and Use appropriate strategies to develop error-free software including static code anal-ysis, modern debugging skills and practices, and C++ debugging tools.

• Implement small to medium software programs of varying complexity; Demonstrate and Adhere to good programming style, and modern standards and practices; Appropriately Use typical features of the C++ language include basic language constructs, abstract data types, encapsulation and polymorphism, dy-namic memory management, dynamic data structures, file management, and managing large projects containing multiple source files; Adhere to the C++14 ISO language features.

• Demonstrate and Adhere to the standards and practice of Professionalism and Ethics, such as described in the ACS Core Body of Knowledge (CBOK) for ICT Professionals.

2 Base Program Game play & Functionality

The base Qwirkle program implements a 2-player text-based version of Qwirkle, using a reduced rule-set. In the base game, the players take turns placing tiles from their hand onto the board. The rule changes for the base Qwirkle game are described in Section 2.5.

This section details the behaviour of the base Qwirkle program. What is presented in this spec is a description of the main functionality of your Qwirkle program. Some parts are left open for you to decide the best course of action.

This spec does not give the rules of Qwirkle. Canvas contains a link to the rules.

2.1 Launch

Your base Qwirkle program will be run using the following terminal command:

On launch, the program should display a welcome message:

Following the welcome message, the program should continue to the main menu.

2.2 Main Menu

The main menu shows the options of your Qwirkle program. By default there should be 4 options. The menu is followed by the user prompt.

The user selects an option by typing a number, and pressing enter. Each menu option is described below. The user prompt is described in Section 2.4, including what to do for invalid input.

2.2.1 New Game

The program should:

1. Print a message for starting a new game

2. Ask for the player names

3. Create a new game of Qwirkle,

4. Proceed with normal gameplay.

As an overview, this process may look like:

The players should only consist of letters (no numbers or symbols). Your program should validate (check) that the player name is valid.

The Qwirkle gameplay is described in Section 2.3. Make sure you take note of the requirements for starting a new game, described in Section 2.3.10.

2.2.2 Load Game

The program should first ask the user for a filename from which to load a game.

The user enters the relative path to the saved game file, and presses enter.

After the filename is provided, the program must then conduct two validation checks:

1. Check that the file exists.

2. Check that the format of the file is correct. The format for saved games is described in Section 2.3.7.

If the filename passes both checks, the program should print a message, then load the game as described in Section 2.3.12, and continue with normal gameplay as described in Section 2.3.

2.2.3 Credits (Show student information)

The program should print the name, student number, and email address of each student in the group, separated by new lines. Note that you should replace , and sections with your full name, student number and student email address.

After printing the student details, the program should return to the main menu.

2.2.4 Quit

The program should print a goodbye message, and safely terminate without crashing.

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

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.

2.3.1 Tile Codes

Tiles are represented by a 2-character code:

<colour><shape>

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

For example, the Yellow Square tile is represented by the code: Y4

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 grid co-ordinates use:

• Uppercase Letters for rows

• Integers for columns

Board locations are always referenced in row-column fashion:

<row><column>

For example, the blue square is at grid co-ordinate B2, and the yellow circle is at grid co-ordinate D1.

You could store the board as A vector of vectors of Tiles

2.3.3 The Player’s Hand

The player’s hand is an ordered linked list of tiles.

The player’s hand is displayed as a comma separated list of tiles.

The order of tiles in the player’s hand is important for testing purposes!

• 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.

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 <tile> at <grid location>

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:

This results in the board:

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 <tile>

For example, using the above hand the player may take the following replace action:

After the command is given, the program must:

1. Check that the command is correctly formatted.

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 <filename>

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.

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:

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.

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:

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

• 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:

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.

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:

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.