ENGG1110 Problem Solving by Programming
The Chinese University of Hong Kong
2024-2025 Term 1
Project
Due Date: 2024/12/04 06 (Wed Fri) 23:59

1. Introduction

In the basic gameplay, the gameboard consists of a grid filled with various types of candies, each represented by different shapes and colors. The player’s goal is to create matches of three or more identical candies by swapping adjacent one. When a match is made, the matched candies are cleared from the gameboard, and new candies will fall down to fill the empty spaces. This sometimes leads to “chain reactions”, where new matches are automatically created as the board refills.

Figure 1. Sample Gameplay. Snapshots from https://www.flickr.com/photos/alper/10330168576

In this project, you will develop a Candy Crush game using the C programming language. The project is structured in two phases: Part I focuses on implementing the basic version of the game, while Part II builds upon the first part by adding advanced features and additional gameplay mechanics.

You are required to complete the given source code main.c without modifying any existing code (except otherwise specified) or introducing new libraries. Marks will be deducted from every modification.

Part I 

3. Suggested Project Schedule

Part I (60%)
Week 10	InitGameBoard(), printGameBoard()
Week 11	AskForSwap()- Input/Validation, swap()
Week 12	FindAndRemoveMatch(), isGameOver()

Part II (40%)
Week 13/14	File I/O, applyGravity, fillEmpty(),Cascade
Week 14	Cascade

4. Sample Runs for Part I

Game Over! No more possible moves.

5. Detailed Program Design Flow – Part I

In this project, you are required to follow exactly the output format specified. Using other output formats will jeopardize your mark.

This program will

a. The player can only swap two candies at a time

b. The player will choose a candy by entering the coordinates (row, column)

c. The player will also input a direction (U for Up, D for Down, L for Left, R for Right) to specify where to swap the selected candy.

a. After each swap, check for matches of three or more identical candies in a row or column.

b. If a match is found, display a message indicating the match’s location, remove the matched candies, and update the game board.

a. Check if no further matches are possible on the gameboard.

b. If the board has no possible moves left, display the message and end the game.

5.1. Header files, Functions, and Variable Declarations

No other header files or library are allowed in the project.

We define several macros after the header line. Macros are identifiers defined by #define, which are replaced by their value before compilation. The first two are H and W.

His the height of the game board, while W is its width. Therefore, our Candy Crush game board is a 6x6 square. In our test cases, we do not have any test cases with varying board size. You may try it if you are interested.

Each cell on the game board stores a candy, with different types of candies represented by numbers. To assist in converting these numbers into their corresponding candy representations, the following global variable is provided.

No other global variables are permitted. All variables you define must be declared within functions and passed as parameters or return values as necessary. Violations of this rule will result in a deduction of marks.

Also, there are a number of helper functions declared in the project. You can add new functions to aid your work, but you CANNOT modify (function signatures – function names, return type, parameters), or delete the given functions.

5.2. Main Function

There are some local variables already declared for you. You can declare your own local variables for your use.

Variables	Usages
int board[H][W]	Stores the candies on the game board.

The main function controls the gameplay as follows:

5.3. Initializing Game Board

5.4. Print Game Board

First, print a line of five equal signs (=====) as a separator. Then, display the game board with row and column numbers labeled. Each cell should be separated by spaces and vertical bars to clearly distinguish rows and columns.

• Candies: Use the candies[] character array to convert the numerical values stored in board[][] into the corresponding candy symbols.

• Empty Space: Display the space character (' '), which is stored in board[][] as ASCII 32 (space).

5.5. Ask for input for swapping

5.5.1. User Input

5.5.1.1. Coordinates

Enter the coordinate (row, column) of the candy:

After receiving the user input, validate the input based on numerical correctness. You can assume the user will only input integers. Ensure that the coordinates are within the valid game board range. If the coordinates input is out of bounds, output the following error message and return zero (0).

Then, the function should check whether the selected cell is empty or not. If the cell is empty, output the following error message and return zero (0).

5.5.1.3. Direction to Swap

Enter the direction to swap (U for Up, D for Down, L for Left, R for Right):

You can assume that the user will input one character only. This input should be validated to ensure it is correct – i.e. Upper case and should be one of the four possibilities (U,D,L,R). If the direction is incorrect, output the following error message and return zero (0).

5.5.2. Valid Swapping Check

If the move is out of bounds, output the following error message and return zero (0).

In addition, the program should also check the Target cell (e.g. if swapping (1,3) to the left, Target cell is (1,2)) is empty. In this case, output the following error message and return zero (0).

5.5.3. Execute Swap

Similarly, if the direction is L (Left), the candy at (row, col) will be swapped with the candy to the left (row,col-1). After the swap, you may use printGameBoard() to inspect the result, but remember to remove this call after completing your inspection.

After the swapping, the findAndRemoveMatch() function is called to locate any matches involving the candy at both the target position and the original position, as a match may form in either direction. The function checks the neighboring cells around each of these positions to detect any sequence of three or more identical candies horizontally or vertically.

To facilitate auto-grading and maintain consistency, you should check the matches in the following order.

1. Order of Checks: When checking for matches, start with the Target Position (where swap has just placed a new candy). After completing all the checks and removal at the Target Position, move to the Start Position (the original cell where the candy was swapped from) and perform the same operations.

3. Vertical Matches: From the given cell, if it is not empty (‘ ’), check upwards (if any) to see if there are three or more consecutive identical candies in the same column. Then check the bottom direction (if any).

If a match is found in the horizontal/vertical direction, output the corresponding message on the screen and indicate the row and column where the match occurred.

After finding the match, the game should remove the matching candies from the game board. This is the intermediate status of the board after the removal.

5.6. Game Over Checking

You can try swapping each candy with its right neighbour (if any) and its bottom neighbour (if any). After the swap, matches may be formed in any four directions (Up, Down, Left, Right). Therefore, you will implement a helper function isMatching() to do the checking. This function will do a simple checking to see if there is at least one match-three that can be formed by the given cell in any of the directions. It shall return one (1) if there is at least one match; If there is no match found, return zero (0).

You may need to call it twice to check both the original position and swapped position for any potential matches.

After each check, immediately undo the swap to restore the board to its original state.

6. Detailed Program Design Flow – Part II

6.1. Main Function

In the main function, three more variables are introduced for the next section.

int stacks[100]	stores the extra candies, which are used to fill empty spaces after matched candies are removed. Maximum 100 candies can be stored.
numCandies	Represents the total number of candies available in the stacks[] array for refilling the board.
current	Acts as a pointer or counter that keeps track of the current candy being used from stacks[] to refill the board during gameplay. The current variable will be initialized to 0 and will be incremented as each candy is used during gameplay.

6.2. Read board and stacks from file

The main() function will first call the initGameBoardFromFile() function, which initializes these arrays. The contents of the arrays should be read from a file named “board.txt”. Finally the function should return the number of candies in the stack, which will be stored in the numCandies variable in the main function.

• First Line: Contains two integers representing the game board dimensions – the number of rows r and columns c.

• Next r Lines: A grid of r x c integers representing the initial game board. Each integer corresponds to a candy type.

• Following Line: Contains a single integer n, which corresponds to numCandies and represents the total number of extra candies in the stacks[].

• Final Line: A list of n integers, each representing an extra candy that will be used to fill the board when matches are removed.

Please ensure that the file is read correctly, and handle file operations properly. If an error occurs (e.g., the file cannot be opened), output the following message and terminate the program with an exit code of -1.

6.3. Applying Gravity

You should implement the gravity algorithm in the applyGravity() function for simulating “gravity”. The main() function will call this function if the swapping is

In this function, implement the gravity feature to shift candies downwards into empty spaces.

Starting from the bottom of the each column, the function should upward to find empty spaces (represented by ASCII 32 ‘ ’). When such empty space is detected, shift any  candies above it down by one row . Repeat this process until each column has no empty space remaining below any candies.

At the end of the applyGravity(), call printGameBoard() to output the game board.

In this example, the candies at the top of column 2 should fall down to fill the empty spaces below. and the result should look like this:

6.3.1. Fill Empty Spaces

After candies are removed from the board, empty spaces will be left behind, which need to be refilled after applying the gravity. The main function will call fillEmpty() to fill these spaces using the candies stored in the stacks[] array after applying the gravity. You can track the current position in the array using the current variable, which indicates where the next candy should be retrieved from.

As you retrieve candies from the array, fill the empty spaces from bottom-to-top, left-to - -right manner to simulate the real candy crush.

Once the original candies have fallen to the bottom (highlighted in yellow above), any remaining empty spaces are refilled sequentially using candies from the stacks[] array. The current variable in the parameter keeps track of the position in stacks[] from where the next candy should be drawn. Each time after the candies is drawn, current is incremented to point to next candies.

Here is the example of how current variable works with the stacks[]. After the beginning of the game, the current variable is set to zero (0) to indicate the candy drawn next is the first item in the stack.

With this array, you can observe that the empty cells are filled with “#”, “@” and “%” from bottom to top, which is 1,2,3 in the stacks array respectively.

This check will naturally handle both cases: if stacks[] is exhausted during normal game play, or if stack[] is empty from the very beginning, as both conditions would trigger the same error and exit the program at this point.

If multiple columns contain empty spaces, fill these spaces in a bottom-to-top order within each column, moving from the leftmost column to the rightmost column. Here is the example of the case of filling in multiple column spaces. The number in red italic and brackets indicates the filling sequence.

6.3.2. Cascade Matching

When the candies are refilled, new matches may form on the board. To mimic real gameplay, the game should continuously check for new matches as the board refills, repeating the process until the board is stable with no further matches.

The main function will call cascade() function right after the matching process. Within the function, you should call both the applyGravity() and fillEmpty() for the cascade process. As a result, any previous calls to these functions in the main function should be removed, as they are now called within cascade().

In the cascade function, you are required to check if there are any matches for each cell. For this, you will call findAndRemoveMatch() function (developed in part I) to find all matches on each non-empty cell. You can make use of the return value of findAndRemoveMatch() to determine whether a match is found.

In the cascade function, repeat the process until no further matches can be found in the board. In each checking round:

a. Row by Row, Column by Column: For each cell, proceed across each row from left to right, then move down to the next row.

b. Check Directions: For each cell, check for matches in the order of Left, Right, Top, and Bottom

c. Clear Matches: If a match is found, clear the matching candies immediately before proceeding to the next cell.

Repeat these steps until no matches are left, ensuring that all cascading actions are completed before returning to the main function.

7. Academic Honesty and Declaration Statement

Attention is drawn to University policy and regulations on honesty in academic work, and to the disciplinary guidelines and procedures applicable to breaches of such policy and regulations. Details may be found at

You are required to fill in the following declaration statement as the comment at the beginning of the main.c source code with your information. Assignments without the properly signed declaration will not be graded.

Tools such as software similarity measurement, AI-tool fingerprint detection, etc., might be used to inspect all submissions.

8. Grading Platform and Submission

Please follow the steps below to submit your work by the deadline.

Please only submit the source file (.c). You may submit many times before the due date, but the latest attempt will be graded.

9. Late Submission

• Within 3 days (72 hours): 10% per 24 hours

• 3-7 days: 50% penalty

• More than 7 days: 100% penalty (Your work will not be graded)