Announcements

• Updated October 28: Deadline was postponed to November 8.

Introduction

In this and the coming assignment, you are going to implement a simple city simulation game, which we call it SimpleCity. In this assignment, you first implement the game logic that can be presented in a command-line program. In the next assignment, you are going to implement the graphical user interface (GUI) for the game.

The game consists of a city. A city consists of a square grid where buildings can be constructed on each grid cell. Also, a city has a budget for building constructions. A building can be built only if the cost to construct the building does not exceed the budget. At most one building can be constructed in each grid cell.

There are three categories of buildings:

• Residential buildings: These buildings house population for the city.
• Revenue buildings: These buildings provide revenue which increases the budget of the city. The amount of revenue depends on the population of the city.
• Health buildings: These buildings provide growth of population.

Therefore, it requires all three categories of buildings for a city to grow in both population and budget.

There are six types of buildings, each type of building belongs to one category:

• Residential buildings: House, Apartment
• Revenue buildings: Silver Mine, Gold Mine
• Health buildings: Clinic, Hospital

Buildings of the same category share some common attributes. The building hierarchy is visualized in the following diagram:

Game Mechanics

• At start, the Player is prompted to take one of two actions:
  1. Starting a new game. The Player is prompted to enter the size of the square grid, which is an even number between 10 and 20 inclusive. Then, a new city is created. The initial budget is $150.
  2. Loading an existing game from file. The Player is prompted to enter the filename of the save. Then, the city is loaded from the save.
• City simulation takes turn. During a turn, the Player can perform the following three actions for arbitrary number of times:
  1. Constructing a building at a grid cell. The Player is prompted to select the type of the building and enter the coordinates of the grid cell to build. The building can be constructed only if the cost does not exceed the budget and the grid cell has no buildings. If the building is constructed, the budget is reduced by the cost of the building. Here are the cost of each type of buildings:
     • House: $50
     • Apartment: $300
     • Silver Mine: $50
     • Gold Mine: $400
     • Clinic: $50
     • Hospital: $500
  2. Demolishing a building at a grid cell. The Player is prompted to enter the coordinates of the grid cell to demolish. The building at the grid cell is removed. This action does not reduce budget.
  3. Saving the city to a file to be loaded later.
• When the Player decides to make a turn, the following steps are performed:
  1. The turn number of the city is increased by one.
  2. The budget of the city is increased by the sum of revenue generated by all Revenue buildings.
     • For Silver Mines, the revenue is city's population + population in neighboring buildings.
     • For Gold Mines, the revenue is 2 * (city's population + population in neighboring buildings).
     • The city's population is the sum of population of all Residential buildings.
  3. The population is increased by the following steps.
     1. The population growth rate of the city is calculated, as the sum of population growth rate contribution of each building:
        • For Residential buildings, it is -population of the building.
        • For Clinics, it is 60 / (1 + number of neighboring Health buildings).
        • For Hospitals, it is 360 / (1 + number of neighboring Health buildings).
        • For other buildings, it is 0.
     2. For each Residential building, the maximum population is calculated:
        • For Houses, it is 50 * (1 + neighboring Residential building)
        • For Apartments, it is 250 * (1 + neighboring Residential building)
     3. For each Residential building, the population growth (can be negative) is calculated, as the minimum of two terms:
        1. population growth rate of the city * (number of neighboring Health buildings - number of neighboring Gold Mines) / 10
        2. The remaining population: maximum population - population
     4. For each Residential building, the population is increased (or decreased) by its population growth.
        • If the new population exceeds the max population, set it to the max population.
        • If the new population is smaller than 0, set it to 0.
        • The new population does not affect population population of other buildings. You need to save the population growth of each Residential building and apply them in a batch.
• This figure illustrates a city grid with size 12.
  The yellow grid cells are the neighbors of the red grid cells.
  

Code Structure

                pa3
                ├── City.cpp
                ├── City.h
                ├── GameEngine.cpp
                ├── GameEngine.h
                ├── Makefile
                ├── buildings/
                │   ├── Apartment.cpp
                │   ├── Apartment.h
                │   ├── Building.cpp
                │   ├── Building.h
                │   ├── BuildingInformationFormatString.h
                │   ├── Clinic.cpp
                │   ├── Clinic.h
                │   ├── GoldMine.cpp
                │   ├── GoldMine.h
                │   ├── Health.cpp
                │   ├── Health.h
                │   ├── Hospital.cpp
                │   ├── Hospital.h
                │   ├── House.cpp
                │   ├── House.h
                │   ├── Residential.cpp
                │   ├── Residential.h
                │   ├── Revenue.cpp
                │   ├── Revenue.h
                │   ├── SilverMine.cpp
                │   └── SilverMine.h
                ├── main_cli.cpp
                ├── test-city.txt
                ├── test-info.txt
                └── test-load.txt
              

• Makefile: Makefile to build SimpleCity and create ZINC submission zip file. See Submission & Grading
• GameEngine.h, GameEngine.cpp: Code for the implemented command-line game engine. No need to modify.
• main_cli.cpp: The main() function. No need to modify.
• City.h, City.cpp: Implementation of the City class. Implement the methods in City.cpp. Do not modify City.h
• buildings/Building.h, buildings/Building.cpp: Implementation of the Building abstract base class. Implement the methods in Building.cpp. Do not modify Building.h
• buildings/BuildingInformationFormatString.h: Contains useful strings to display building information.
• Other files in buildings/: Implementations of classes derived from Building. Complete the class declarations in corresponding .h files. Implement the methods in corresponding .cpp file.
• test-city.txt, test-info.txt and test-load.txt: Three save files for testing.

Part 1: City

Implement the following functions of the City class.

Part 2: Buildings

Implement the following functions of the Building class and its derived classes.

Example

In the skeleton files, you can find the save file test-city.txt. Here are the city status and city map.

                Turn: 8
                Budget: $3
                Revenue: 99
                Max Population: 200
                Population: 35
                Population Change: 25
                Population Growth Rate: 85
              

   0123456789
  +----------+
 0|          |
 1|          |
 2|          |
 3|    S     |
 4|    EEC   |
 5|    CCS   |
 6|          |
 7|          |
 8|          |
 9|          |
  +----------+

Compilation

Use the Makefile provided in the skeleton file for compilation. Simply run make in the directory that contains main_cli.cpp and Makefile. After successful compilation, an executable, simplecity (or simplecity.exe) will be produced.

Note: If you are a Windows user and you wish to run simplecity.exe outside VSCode, change line 6 of Makefile from:

                LDFLAGS :=
              

                LDFLAGS := -static
              

Submission & Grading

Deadline: 8 November 2021 Monday HKT 23:59.
You may earn 8% course grade for each PA via Automated Grading on the ZINC Online Submission System. Please check here for a usage overview of ZINC.

Files to Submit

There are a number of files you need to submit to ZINC. A Makefile target is provided to automate the creation of the zip file. Run the following command in the directory that contains Makefile:

                make pa3.zip
              

Then, pa3.zip is produced. Submit pa3.zip to ZINC. It contains the following files:

• City.cpp
• buildings/Building.cpp
• buildings/Health.h
• buildings/Health.cpp
• buildings/Revenue.h
• buildings/Revenue.cpp
• buildings/Residential.h
• buildings/Residential.cpp
• buildings/Clinic.h
• buildings/Clinic.cpp
• buildings/Hospital.h
• buildings/Hospital.cpp
• buildings/SilverMine.h
• buildings/SilverMine.cpp
• buildings/GoldMine.h
• buildings/GoldMine.cpp
• buildings/House.h
• buildings/House.cpp
• buildings/Apartment.h
• buildings/Apartment.cpp

Late Submission Policy

There will be a penalty of -1 point (out of a maximum 100 points) for every minute you are late. For instance, since the deadline is 23:59:00 on 8 November 2021, if you submit your solution at 1:00:00 on 9 November 2021, there will be a penalty of -61 points for your assignment. However, the lowest grade you may get from an assignment is zero: any negative score after the deduction due to late penalty (and any other penalties) will be reset to zero.

Test Cases

Here are the revealed test cases on ZINC and the input.

Memory Leak

Before the program terminates, you need to ensure you have deallocated all dynamic memory you have allocated in the entire execution of the program.

Memory leak is checked by using the sanitizer, invoked by the -fsanitize=address,leak,undefined option (See related documentation here). Some revealed test cases on ZINC also check for memory leak (See Test Cases).

Checking Memory Leak Yourself

Although some test cases on ZINC already check for memory leak, you may still want to check for memory leak yourself. However, the above option does not work in Windows minGW g++. Instead, you can do so by remote connecting using SSH to the machines in the Linux Lab (Lab 2). The following shows you how to do so by using the Virtual Barn. You may want to adjust the steps accordingly if you are familiar with using SSH on your own computer.

1. Remote control a Windows machine in HKUST virtual barn. After following the installation guide and user guide there to install the remote control client and connect to the HKUST network, choose the Programming Software server when you are offered a selection of different servers.
2. Copy your files to Virtual Barn. If you have no idea, you can email yourself the files and then download them there.
3. Open PuTTY. There is a shortcut on your Desktop. Enter a lab 2 machine (csl2wkXX.cse.ust.hk, where XX=[01 ... 53], for example csl2wk13.cse.ust.hk) as the Host Name. Note: If that server doesn't work, you may try other servers by changing XX.
   
4. Click Open. If a warning about the security key shows up, click Yes to dismiss it.
   
5. Enter your CSD login and password. (Register one if you haven't done so in lab 1 by following the lab 1 instructions.) It may not show what you type when you are typing in the password. Don't worry, just type your password and hit the Enter key. You should login to your home directory. Enter the command pwd (Print Working Directory) to verify this. It should show /homes/your_login
   
6. Open FileZilla from Start Menu. Click "File" -> "Site Manager" -> "New Site". Choose SFTP for protocol according to the screenshot below. Enter csl2wk13.cse.ust.hk (or the server you used in the previous step) as Host. Choose "Ask for password" for the Logon Type.
   
7. Click Connect and then enter your CSD login and password.
8. If the connection succeeds, the right side should show your home directory at Linux Lab. Copy all PA2 files including cpp files, header files, the include directory, by dragging them to the right side. Do NOT drag a folder containing all those files, instead, you should drag the files themselves only. That would upload the individual files (without any folder) to /homes/your_login. Also, you need to use this Makefile in the machines in Linux Lab. This Makefile includes the sanitizer option on compilation. You can close FileZilla after doing so.
9. Go back to PuTTY, and compile your program using the make command:

   
                       make
                     

10. If no compilation errors occurred, you should be able to run your program by:

    
                        ./simplecity
                      

11. Note: Memory leak check is enabled along with other runtime errors check for your program. If there are any errors, some error messages (just like what you would see in the Error tab on Zinc) will appear in the terminal as you run your program.

Acknowledgments

This assignment was originally proposed and designed by Yu Hei CHAU.