CS 61C, Spring 2008
Due Saturday, February 16th @ 11:59pm
Last Updated 2/10 @ 6:30pm
TAs: Matt Johnson and Casey Rodarmor
Yet Another Note: The files you'll need for proj1 are available in this archive.
Another Note: To be sure that you're using the correct game files, check out the newly updated Playing the Game section.
Note: If you're having trouble compiling, make sure you have the latest version of the code.
Project Overview Getting Started File Summary Playing the Game Assignment Part 0: Let there be rooms! Level File Format Part 1: Get go()-ing! Part 2: Monster Mash_t Part 3: Magic Survival Tips Mini SVN Tutorial Submission Extra for Experts
The usual story with video games is that there are programmers who play the game and gamers who play the game—the two parties and their actions are completely separate. But for this project game, programming the game is part of playing it! To progress through the game world you will need to implement game features, and every feature you complete will allow you to progress further. After you complete each part of the assignment, you should try playing the game to explore how far you can get.
We made this brand new project because other 61C projects have been seriously lacking in FUN! And what's more fun than an adventure game?! We've done our best to make this framework simple and extensible, and we hope that you'll have fun creating new monsters, spells, and levels; and even adding new features!
Wow. I am super excited. Are you? Awesome. Let's move on and check out the framework that you'll build on.
The first step is to copy the game framework files into your home directory:
cs61c-tm@quasar ~ > cp -r ~cs61c/proj/01/ ~/proj1
cs61c-tm@quasar ~ > cd proj1
cs61c-tm@quasar ~/proj1 > ls
Makefile cs61c-world.lvl globals.h monsters.c testworld.lvl
commands.c game.c level.c monsters.h util.c
commands.h game.h level.h obj util.h
common.h globals.c main.c puzzles.o
Here's a short description of each file, with the ones you'll need to edit in bold:
gmake to build your project with the directives in Makefile. Make sure you take a look inside, we've given you a few useful shortcuts. For instance, try gmake debug.
room_array, num_rooms, and the_player. Declarations are in globals.h
This is a very large codebase for a 61 series project! Make sure you check out theSurvival Tips section for ideas about how to make it more manageable.
Before you program and after you finish each part of the project, *make sure* to test out your implementation in cs61c-world.lvl. It's where you will begin your zany adventure, use your newly implemented skills and learn what you will need in the tough hours to come! (You can also use testworld.lvl to quickly test out some of the simpler implementation details, but its not very exciting).
Once you implement some of the features, you will be able to play the test world. An example transcript of interacting with the game is below:
cs61c-tc@pulsar ~ > ./game testworld.lvl
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Welcome to game, the CS 61C adventure extravaganza!
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
You wake up.
you are in room #0
There is an exit to the east
> go east
you are in room #1
There are exits to the north and west
> dawdle 15
You dawdle for 15 seconds...
> ^D
cs61c-tc@pulsar ~ >
However, the real fun is in cs61c-world.lvl, which will run automatically if you run gmake or call ./game with no arguments. When you start the game, you should see the following lines:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Welcome to ./game, the CS 61C adventure extravaganza!
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
You wake up.
You are in a cold, concrete-floored room. There are no windows and almost
no light. The only thing you can make out is the faint outline of a door
to the south.
There is an exit to the south.
>
If you don't see lines like those above (and instead see something about a button), you have some old framwork files. Update puzzles.c, cs61c-world.lvl, and Makefile from the ~cs61c/proj/01 directory, run gmake clean and be sure it removes the puzzles.o file, and try running gmake again. Post to the newsgroup if you have any further problems.
Here is a list of commands in the game (some of them not implemented):
look -- Look around the current room.
attack monster_name -- Attacks the first monster with monster_name. If multiple monsters with the same name are present, successive calls to attack will target the same monster.
dawdle num_seconds or wait num_seconds -- Wait the given number of seconds of the game time. If it is called with no argument, it will wait for 15 seconds.
quit or exit -- Ends the game.
status -- Prints out the player's status, including hit points and experience.
help -- Prints out all currently available command names.
cast spell target -- Cast the spell at the given target.
interact -- Interact with a room's puzzles or people.
go direction -- Move around the level. Valid directions are north, south, east, west, up, and down.
To make sure that everything's ready to go, make sure you can compile and run the game. Do this by running gmake from within the proj1 directory. The project will compile and run, but will immediately crash. This is by design; it's trying to load the level file, but load_level() isn't doing a whole lot of anything at the moment. Let's fix that.
To initialize the game world from disk, you need to complete load_level(), found in level.c. The function prototype from level.h is reproduced below:
room_t *load_level(char *filename);The function should open the file named by filename, set up room_array[] (a global array of room_t structs), and return a pointer to the starting room. The function will allocate memory on the heap, but because that memory will exist for the duration of the program, there is no need to free any of the memory allocated in load_level().
The load_level() function itself is partially implemented in level.c. You will need to fill in the code to perform three tasks:
room_array[] data structure. The data structure must be allocated and initialized so that all of the room_t fields, as well as fields of sub-structs, are initialized to NULL or false, as appropriate. The exceptions are room_id, which should be set to the room index from the level file; and mob, which you'll take care of in part 2. You should set the function pointers in the puzzle_t to each be NULL.
description field of each room_t should point to the human readable room description which follows that room's room_id in the level file. The string should not end with a newline. fgets() will return a string with a newline, so overwrite it with a null terminator. Room description strings should NOT include the room number, but instead should begin with the first non-whitespace character after the room number.
exits[] array in each room_t is indexed by the direction enum. Each entry in the array should contain a pointer to the appropriate room if there is an exit in that direction, and locked exits (specified by cant-go lines) should have the locked field set to true. Each exit_t that is not used (does not exist in the game) should keep its dest pointer set to NULL. Note that every exit is meant to be bi-directional: if you can-go north 1 2, that implies that you can also go south from 2 to 1.
A level file has the general format shown below, where lines starting with "***" are not literally in the file. An simple example can be found in the testworld.lvl file.
NUM_ROOMS 0 This is a room description, printed whenever a player enters the room. 1 This is another description. 2 And another! *** MORE LINES HERE, UP TO INDEX (NUM_ROOMS - 1) *** can-go north 0 1 *** AN UNLOCKED EXIT *** cant-go west 1 2 *** A LOCKED EXIT *** *** MORE LINES HERE ***
A level file must start with an integer number that indicates the total number of rooms.
Next, there is whitespace (at least two newlines, as in the above example). In the next block each room is described: at the start of each line is a room number, then there is non-newline whitespace, and then the room description string. The description string is ended by a newline. The room description block will always have one line per room, and the room index at the start of each line is guaranteed to be valid (within bounds) but it may be multiple digits.
The room description block is followed by more whitespace (at least two newlines, as above). The final block is the connection block, which describes how rooms should be linked. Each line will start with either "can-go" or "cant-go," which declare an unlocked or locked exit between rooms (respectively). Locks are NOT bi-directional: a "cant-go north 0 1" line will set up a door that is locked from 0 going north, but it will also set up an exit in room 1 going south that is not locked.
After either "can-go" or "cant-go" there is non-newline whitespace, followed by a direction name, which is the direction of the exit from the FROM_ROOM to the TO_ROOM. The possible direction names can be found in direction_names[] in level.c. Finally, two numbers are given, separated by non-newline whitespace, which are the FROM_ROOM and TO_ROOM, in that order, which are the room indices to be connected. The indices will always be valid room indices. As an example, the line cant-go north 0 1 should connect the north exit of room 0 to room 1, the south exit of room 1 to room 0, and set the locked boolean of room 0's north exit to true. (while leaving the locked boolean of room 1's southern exit alone)
We will not test your solution on level files with repeated, poorly formed, or conflicting connecting statements, e.g. can-go north 0 1 followed by can-go north 0 2.
puzzle_t struct and any puzzle_t fields. Puzzles are only for TA usage.
skip_characters() in util.c
member() in util.c
flip_direction macro in level.h
load_level() in level.c.
go()-ing!Try loading the game and see what you can do! Not much, huh? Being able to moving around is fun, so why don't you implement the go() function in commands.c. Go() moves the player from room to room by updating the current_room pointer in the_player, a global variable.
Since the go() command is issued in the game just like a command line in the shell, the arguments are passed exactly as in main(). For example, if you type the following when in game:
> go north
The arguments passed to go will be argc = 2, argv = {"go", "north"}.
Your go() function should check to see if the exit in the direction to move is locked, and only move the player if it is not. All commands return the amount of time that command took, and go() is no exception. It should return 0 if the player attempts to move in a direction where there is no exit, FAILED_MOVE_TIME if there is but it is locked, and MOVE_TIME if the move is successful.
room_t and exit_t in level.h
commands[] and cmd_entry_t in commands.c
lookup_command in commands.c
tokenizer() in util.c and strtok() the library functions
In order for every room in the game to hold a variable number of monsters, you will implement a variable length data structure called a mob_t. This part is relatively self contained within monsters.h and monsters.c. A mob_t is just a dynamic data structure of monster_ts. It supports a function called spawn_new_monster(mob_t *mob) which adds a random monster_t to the mob_t, get the first monster of a particular type with find_monster(mob_t *mob, char *type). You'll also support append_monster(mob_t *mob, monster_t *monster) and delete_monster(mob_t *mob, monster_t *monster), which add and remove monsters from mobs.
But wait, there's more. In order to provide the best data-structure interface ever, you'll also implement a mob_iterator_t, which will provide a convenient interface for outside code to access the monsters in a mob_t.
Check out this snippet, a loop which sets the hp of all monsters in a mob to 0:
monster_t *monster;
// create a new mob_iterator_t
mob_iterator_t *iter = make_mob_iterator(&the_player.current_room->mob);
// iterate over every monster in the mob_t
while((monster = next_monster(iter))) {
monster->hp = 0;
}
// and finally, call delete_mob_iterator() to delete any space
// that make_mob_iterator may have allocated
delete_mob_iterator(iter);
Yu are not responsible for what happens if delete_mob_iterator() is never called by outside code. Also, it is assumed that outside code will not add or remove monsters from a mob_t between calls to make_mob_iterator() and delete_mob_iterator().
Once you're done with with monsters, make sure you update the room initialization code you wrote before. You'll have to do whatever initialization is needed to make sure that the mob in each room starts off in a good state.
monster_t exists, since your data structure will contain monster_t*s.
mob_iterator_t thoroughly. The fact that you must support it will influence your choice of data structure to use for mob_t.
rand(), which lives in stdlib.h. Here's a good description.
Before you head on to the next implementation section, try playing the game! You should be able to do quite a bit in the game world before you need magic.
You'll come to a point where you need at least one magic spell, so this last implementation section is all about getting the cast command to work to imbue the world with magic.
To get casting to work, you need to implement the get_spell() function in game.c. After a player issues the cast command, get_spell() checks the level_table[] for a spell entry whose name matches the provided string. For example, after receiving the in-game command "cast fireball" we want to check for a spell called "fireball" and, if we find it, return its corresponding function pointer.
You also need to implement the get_spell_level() function in game.c, which takes the name of a spell being cast and returns the level required to use that spell according to the level table.
Finally, you must implement the cast() function in commands.c. You will need to understand function pointer syntax, since you need to call the function returned by get_spell(). Also, notice that the fireball() spell we have implemented expects arguments like argc = 2, argv = {"fireball", "goblin"}. In other words, it doesn't expect to see "cast" as the first entry in its argv argument, so you shouldn't just past the exact same argc and argv that cast() is called with. Be sure to have checks in case the cast command is issued with an unexpected number of arguments.
level_table[] and level_entry in game.c
fireball() in game.c
damage() in game.c
Getting lost in a large codebase is easy, but there are a few things you can do about it.
grep is a great tool for finding functions, types, and variables. Don't know where the_player is declared? Just run grep the_player *.h from within the project directory. Nobody is blessed with the natural ability to navigate large projects, and it's one of the most useful skills you can learn.
Make it a habit to read the code which surrounds and makes use of your own. You can learn a lot from context, like how your function will be called, when it will be called, and what it's expected to do. Code reading is an oft overlooked skill, but it can save you a whole mess of time and effort.
Experiment! Don't be afraid to write some C to verify your model of how things work. Any time you're not sure about something, think of a way to verify it from within a little test program. Writing, compiling, and fixing something is the best way to learn. After all, the compiler is the final authority.
Version control is a wonderful tool for simplifying development. You can use it to track changes to your files, revert to previous reversions, and figure out exactly where you introduced a bug. For those of you who already know svn, or want to take the time to learn, here's a whirlwind tutorial on making your own repository on the inst machines:
First create a new repository named proj1_repository:
cs61c-tc@nova [~] svnadmin create proj1_repository
Get the full path of your homedir, and check out a working copy of proj1_repository. Make sure file: is followed by three forward slashes. Two because it's a URL, and one for the root directory:
cs61c-tc@nova [~] pwd
(YOUR HOME DIR)
cs61c-tc@nova [~] svn co file://(YOUR HOME DIR)/proj1_repository proj1_wc
Checked out revision 0.
Copy all the framework files into your working copy, add them via svn, and commit them to the repository:
cs61c-tc@nova [~] cd proj1_wc
cs61c-tc@nova [~/proj1_wc] cp -r ~cs61c/proj/01/* .
cs61c-tc@nova [~/proj1_wc] svn add *
A Makefile
A commands.c
<snip>
A util.c
A util.h
cs61c-tc@nova [~/proj1_wc] svn commit -m "Initial check-in of proj1 framework"
Adding Makefile
Adding commands.c
Adding util.c
Adding util.h
Transmitting file data ...................
Committed revision 1.
Once you've got the repo working, you'll need to know some svn commands to interact with it. Here are some important ones: , , , and commit.
It might seem silly to keep a repository just for you, but once you experience the wonders of version control you'll never go back. It will improve your work flow, prevent file deletion disasters, and help you track your changes. It will also make experimentation and exploration easier, since you'll always be able to roll back your changes.
All your code should be contained in the provided files, and gmake should build your program without any warnings.
When you're ready to submit, cd into your project directory, gmake clean, and then submit proj1.
Wow, you rock. You built a whole world from raw text files, populated it with dire monsters, and gave our protagonist some spells to fight them. You may have even plumbed the depths of cs61c-world.lvl, and discovered the dark secrets lurking within.
You might think that the fun is over—but the adventure doesn't have to end here!!! Proj1's unofficial extra for experts is to implement something cool. Seriously, anything. A new spell, a new game feature, or even your own world. Although you can't share code, feel free to post new puzzle.o/puzzle.h and level files to the newsgroup. Go nuts and have fun with it; game programming can be a lot of fun!
PS As much as I am dying to see all of your awesome new stuff, please keep the extra for experts separate from your submission. This project is going to be hard enough to auto-grade as it is!