Executive Summary

You will be implementing a relatively complex old-school arcade-style game, which we're calling "Escape!". The game will run in the terminal and be based on ncurses, which you are familiar with from our prior lab. In this game, you are a player on a game board:

Honor: The course policy and the instructions it references, most pertinently COMPSCIDEPTINST 1531.1C, spell out what kinds of assistance are permissible for programming projects. The instructor can give explicit permission for things that would otherwise not be allowed. For this project, you have explicit permission
  1. to get help from other current SI204 instructors as well as your own and from current SI204 MGSP leaders (any assistance must be documented though), and
  2. to use general purpose C++ resources online (though such use must be documented). Resources that might specifically address this project, say looking through code of programs that implement a maze-navigation game using ncurses, are not allowed.
Put the instructions referenced in the course policy and the explicit permissions above, and what you get is summarized as:

Part 0: Download Required Files


All required files in one download. This contains everything below. To extract its files, run the following command:
tar -xvf p3files.tgz

The following are the individual files contained in the archive "p3files.tgz" above.



Your interface to drawing in the terminal.


These functions and structs will make your life easier.
You must use both Pos.cpp/Pos.h, and you cannot modify them.






The program that handles debug output & opens a 2nd terminal for you.


Part 0.1: Review Material

Easycurses.h: Review Lab 10 for easycurses.h and how to use it.

Debugging: easycurses takes over your terminal, so you can't just cout helpful debug messages anymore. Look at Parts 1b and 1c of Lab 10 for a reminder of how to do this with 2 terminals.

Important: be sure to check out further information on design suggestions!

Part 1: Read the board! [Up to 25pts]

Name your .cpp file containing main() part1.cpp

How to compile: g++ part1.cpp <other-files.cpp> Pos.cpp easycurses.cpp -l ncurses

This part is about reading in the board, and not much else. Don't do it all at once, break this part into your own smaller steps. A valid Part 1 solution:

Board files look something like this:
10 x 20 1
#                  #
#  Z  ########     #
#            #     #
#####        #     #
#   #        #     #
# X #        #     #
#   #####    #  Y  #
#            #     #
The first line gives number of rows x number of columns, followed by the number of Z's you'll find on the board. The X marks the goal position on the board. This is where the player is trying to get to. The Y marks the player's starting position. Zs are "spawn spots". These are positions that moving, death-dealing objects spawn from. There can be multiple spawn spots.
Note: Walls are always # characters, and walls always surround the edges of the board.
  1. Reads a filename for a board from the user (before ncurses is initialized!); it must print an error message and return if the file is not found!
  2. Reads the board file and stores the information in it, then prints the board on the screen using easycurses. If the terminal window is too small, the program must exit easycurses, print an appropriate error message, and exit the program.
    Note 1: Don't print spawn spots or the player's start spot, but do print X for the goal.
    Note 2: Spaces are important here. You'll have to use the special ifstream function get() which returns char by char each time you call it: char ch = fin.get(); rather than fin >> because you have to read in the whitespace characters.
  3. After the board is printed to the screen, use the following loop;
    do {
      usleep(150000); // pause (sleep) for .15 seconds
      char c = inputChar();
      if( c == 'y' )
        break; // loop exits with a 'y'
    } while(true);
    ... so that the board stays on the screen until the user presses y on the keyboard. After exiting the loop, the program must exit easycurses by calling endCurses(), and then print out the row,col coords of the player start spot and the spawn spots, just so we're sure we've got them right.

Note 3: You should make a struct to represent all the info you read from the file, and make a separate function to read in the file and give values to all the members of that struct.
Note 4: You must split your program into .h and .cpp files as we have discussed.

hit enter press y

Note: Check out this video of a running solution.

Important: be sure to check out further information on debugging with ncurses!

Part 2 Implement the player! [Up to 45pts]

Name your .cpp file containing main() part2.cpp

How to compile: g++ part2.cpp <other-files.cpp> Pos.cpp easycurses.cpp -l ncurses

If you like, you can use the arrow keys to move rather than a,s,d,w. Here's how to do that:
  1. When reading keyboard input, store the result of calling inputChar() in an int, not a char:
    int kb = inputChar();
  2. You can still check for characters like "kb == 'a'", but you can also compare kb to the constants KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN that ncurses defines. So, for example,
    int kb = inputChar();
    // if a-key was pressed
    if( kb == 'a' ) { }
    // if left-arrow was pressed
    if( kb == KEY_LEFT ) { }
A Part 2 solution adds on to the Part 1 solution by implementing the player — i.e. the figure in the game that the user controls. Here are the details:
  1. The player (represented in the game by a "P") can either be moving or stopped. It starts the game stopped, and at the position marked on the input file by a "Y".
  2. The r key stops a moving player. The a,s,d,w keys set the player's direction to W, S, E, or N respectively and, if the player is stopped, set it to moving. A moving player moves one step forward per round in its current direction.
  3. The player must bounce off the walls. If the next step moving forward would put the player inside a wall (a "#" on the game board), the game turns the player 180 degrees, stepping in that direction instead (unless there is a wall there as well, in which case remain in the same position but maintain your direction — the next random maneuver will hopefully unstick the player).

    Important: be sure to check out further information on on bouncing!

  4. The game stops when the player comes within distance 1 or less of the X.
  5. If the game stops because you reach the goal, print out the player's "score", which is 500 minus the number of steps (i.e. times through the main loop) it took to get to the goal.
Note: Check out this video of a running solution.

Part 3: Implement the space ships [Up to 75pts]

Name your .cpp file containing main() part3.cpp

Part 3 adds on to Part 2 by implementing "space ships", which are randomly moving figures (represented by *'s in the game) that kill the player if they collide with them. These ships bounce off walls, but simply pass through one another. Here are the details:

  1. At the start of the game, there are five overlapping ships on each spawn spot, each with a randomly chosen direction.
  2. Just as with the player, ships move one step per round in their current direction, and they bounce off walls in the same manner as the player. Colliding ships simply pass through one another.
  3. Every round there is a 1-in-10 chance that the ship will turn before stepping (not counting turning because of walls). This turn will be a 90deg left turn with probability 1/2, and otherwise a 90deg right turn.
    You're using our provided Pos.h and Pos.cpp code, right??
  4. If a ship and a player collide, the player dies (the game should then pause for two seconds, then exit the program). Here's how to define "collision":
    After each object has made its step for the round, we will say that player P and ship S have collided if P's current position and S's current position are the same, or both P's current position is the same as S's previous position and P's previous position is the same as S's current position.
    This may seem a bit complicated, but we have to handle the situation in which P and Q are in adjacent squares and heading straight for one another. In this case, after one step they will have crossed, swapping positions. So even though their previous positions are different from one another and their current positions are different from one another, we still want to consider them to have collided.
    Note: Because of this rule, I strongly recommend that whatever struct you use to represent moving objects actually has a data member that stores the previous position.
    Note: I also strongly recommend that you implement a cheat — for instance the i key could make you immortal (i.e. collisions don't kill you). That makes life a whole lot easier when debugging along the way.
Note: Check out this video of a running solution.

Important: be sure to check out further information on on collisions and death!

Part 4: Implement the Hunters [Up to 85pts]

Name the .cpp file containing main() part4.cpp

Part 4 adds on to Part 3 by implementing "hunters" which are game figures that kill the player on collision but which, unlike ships, actually track down the player. Here are the details:

  1. At the start of the game, there is one hunter on each spawn spot, each with a randomly chosen direction.
  2. Hunters are represented on screen by K
  3. Hunters move (and kill) exactly like ships except that instead of having a 1-in-10 chance each turn of turning randomly either left or right, a hunter has a 1-in-2 chance each turn of reassessing its direction. When it does so, it chooses a direction toward the Player. according to the following rule:
    1. let dc = (Player column position) - (Hunter column position)
    2. let dr = (Player row position) - (Hunter row position)
    3. if dc < 0  then let cdir = 3  // West
    4. if dc >= 0 then let cdir = 1  // East
    5. if dr < 0  then let rdir = 0  // North
    6. if dr >= 0 then let rdir = 2  // South
    7. With prob 1/2 set Hunter's direction to rdir, otherwise set Hunter's direction to cdir
Note: Check out this video of a running solution.

Part 4.5: Make your own board [Up to 90pts]

This isn't really programming, but you should do it anyway. Make your own board file, call it boardYYXXXX.txt, where YYXXXX is your alpha code. Be creative, but make sure your program still works with your board file as input!
Note: be sure to put walls on all edges!

Part 5: Make it a game [Up to 100pts]

Name the .cpp file containing main() part5.cpp

Part 5 builds on Part 4 to make this a real game: if you die three times the game's over, you get "points" as you progress, if you win one board you go on to the next, each board getting more difficult but worth more points. Looked at one way, Part 5 is a fairly major rewrite of Part 4. Looked at another way, if you package your entire Part 4 solution up into a function, Part 5 is nothing more than calling that function repeatedly. Here are the details:

  1. The file gameScript.txt contains lines like the following:
                  ,-|number of ships spawned per spawn-spot
    board2Rm.txt 5 1 points = 1000 ←|number of points for winning this board
    ------------    \  
    board file name  `-|number of hunters spawned per spawn-spot
    A player working through the game plays the board as described by the first line of gameScript.txt until either dying three times (on that board) or winning. If the player wins, the game moves on to the board described by the second line of gameScript.txt, and so on and so forth. Nobody except Neo could possibly finish the entire script, so we don't worry about it.
  2. A valid Part 5 solution must read the gameScript.txt file completely at the very beginning of the program, and store the relevant information in it in a linked list. Yes, it has to be a linked list! After it's in the linked list you can transfer it into an array if you want, but you have to read it into a linked list. Why? Because you don't know ahead of time how many lines there will be in the file ... and also because I told you so.
  3. After a victory on a given board, your score is the points value for that board plus 500 minus the number of rounds/steps it took you to get to the goal.
  4. After a victory, restart the game with the next board on the list. Instead of a fixed value of five ships and one hunter per spawn spot, use the values given in the line from gameScript.txt.
  5. After three deaths at any level, exit but print the total score first.
Note: Check out this video of a running solution.

Extra Credit [+15Pts] - name the .cpp file containing main() partX.cpp

You may earn extra points by adding on interesting (or difficult to implement) features to the basic game described in Parts 1-5. Extra credit will be considered only for correct working solutions to either Part 4 or Part 5. How much extra credit you get is at your instructor's discretion. The amount will be based on creativity, improvement of the game experience, and difficulty or sophistication of implementation. Using a linked list as part of your extra features will definitely improve your chances of getting big points! Here's some extra information that might be useful in adding extra credit features.
Adding Color
To add color to ncurses we need to start color support. This will require you to look into easycurses.h and make the proper addition in the right place.
  1. Add start_color(); when ncurses is first initialized.
  2. Then we need to initialize colors we want. This doesn't turn them on yet, but makes them easily available.
    init_pair(1, COLOR_RED, COLOR_BLACK);    // Red on Black
    init_pair(2, COLOR_BLACK, COLOR_RED);    // Black on Red
    init_pair(3, COLOR_RED, COLOR_RED);      // Red on Red (Red Block)
    init_pair(4, COLOR_GREEN, COLOR_GREEN);  // Green on Green (Green Block)
  3. To actually use colors in plotting use functions attron(.) and attoff(.) like this:
    attron(COLOR_PAIR(1));   // Start using Red on Black
    attroff(COLOR_PAIR(1));   // Stop using Red on Black
Using an extended character set
Full unicode in ncurses seems to be a bit messy. But it does support a more modest extended character set pretty nicely: altcharset chart, extended charset chart.
The altcharset has predefined constants like ACS_CHKBOARD. You write them to the screen like this:
For the extended charset there are simply numeric codes. If you look at chart you'll see that the copyright symbol has code 169, so you'd write it like this:
waddch(W, 169 | A_ALTCHARSET);


Therefore, your total score will be
Your original score - (3A + 4B - 1).

What to submit

Your electronic submission must include:
  1. Coversheet coversheet.pdf. Fill out and attach this coversheet when you submit your work.
  2. All .cpp and .h files required to compile and run your program.
  3. Your boardYYXXXX.txt file, your gameScript.txt file, and all board files (e.g. boardCenter.txt) it references, including those that are linked off this page
  4. A file named README whose first line is the proper g++ command to compile your project — the basic project, that is, the furthest Part you successfully completed without any extra credit. We will use this to compile your code, so it better be right! The following lines should include your name and alpha, and a description of your game (especially any extra credit goodies that you've added on). If you did any extra credit, the last line should be the proper g++ command to compile your extra credit assignment.

How to submit

The paper portions of your submission should be stapled together and slid under your prof's door. For electronic submission, continue to use the same method from the previous projects. Within the directory in which you have been saving your project, type:
~/bin/submit -c=SI204 -p=proj03 files-to-include
Where files-to-include is a list of all .cpp and .h files specific to this project, as well as your gameScript.txt file, README file, the boardYYXXXX.txt file you created, and all board-files required to run your project. Submitting more than you need to submit is always OK. Just be sure that all the files needed to compile and run your project (including the extra credit version of your project) are there. So, assuming you have a directory for this project and that you are in that directory, you could submit like this:
~/bin/submit -c=SI204 -p=proj03 README *.cpp *.h *.txt
Remember to include the g++ lines used to compile your program as the first line in the README file, and if you did any extra credit the g++ line used to compile the extra credit should be the last line of the README file. You may submit files at any time, but only the last submission will be used for grading.

How projects are graded / how to maximize your points

Things to keep in mind to receive full marks:
  1. Submit all required items (as described above) on time.
  2. Make sure the form of your output matches the form of the example output in all ways.
  3. Make sure you follow the SI204 Style Guide. This means proper indentation, use of whitespace within lines of code, logical organization of chunks of code,
  4. Make sure you do a good job of putting things in functions, packaging data into structs, and breaking the program into .h and .cpp files.
Most important: Look at the the grading sheet.