The (Unofficial) Official HW#4A Walkthrough. Abridged.

Oh wow! It's a bootleg copy of the HW#4A walkthrough! Man.. this will really help with that homework assignment. I'll just follow along with the walkthrough. If I do everything step by step with it (and think about what I'm doing as I go), I should understand the code way better.

Playing Around

I'll kick off by ignoring the code altogether and just running the skeleton code. It compiles... it runs... it doesn't seem to do much. Wait, let me hit a key.

Aha! It started a level after a couple of key presses. OK, I have a square with a little red dot. When I type on the numeric keypad (the 1 2 3 and 4 5 6 and 7 8 9 thing), the square moves around. Plus, the little red dot seems to point wherever I'm moving (although it seems to start off in a wierd spot.. why is that?).

Hey! I can probably keep running the program as I build my solution as long as I'm careful to do it piece by piece! That should make debugging way easier!

Getting Started

The best way to start looking in the code is probably to take a look at the file containing main. Why? Because that's where the computer will start looking when it executes my program. So, I'll open up hw4.c.
I'll read through the comments at the top. They help make sense of the file as a whole.
Great! Now, I'll just skip down to main. I'll look over the rest of the code up there later. For now, I just want to get an overall sense for the program. Read main's comment. (Boy, who wrote this code? These comments are great!)
OK, there's a bunch of variable declarations. Then, there's some GP142 setup stuff. Then, we get to the good stuff: the "main event loop".
This loop goes forever until quit becomes true. Well, let's start by figuring out when quit might become true. It must be assigned somewhere (or a pointer to it is passed to some function!).
Aha! There it is! Inside the switch. If the event is a keyboard event (GP142_KBD), and the key pressed was a 'q', then quit becomes true. Let's see... then, we hit the break. So, we exit the switch.. and, that's the end of the loop! That means we quit the loop and drop right back out to the GP142_close call and the end of main!
I'll build and run the program and try just hitting 'q' straight off. Does it quit? If so, we've understood the start of the code!

The Main Vein

OK, let's look at some more of this main. For now, though, we'll just assume any function that's called does about what we expect it to do if we can.

Start with main, again. It opens GP142, turns off logging (whatever that is! better look at the GP142 documentation later), starts animation, and "seeds the random number generator". All that is straight from the names of the functions and the comments. Hmmm.. seeding the random number generator is that thing where you get random numbers kicked off, right? We learned about that a bit in HW#2.
Inside the main loop, we await an event from GP142. It looks like an event is some type of thing that happens. Judging by that switch statement, there are four types of thing that can happen: a quit, mouse, keyboard, or periodic event. Looks like quit and mouse are pretty simple (mouse is ignored!). Let's take a closer look at keyboard and periodic.
OK, for a keyboard event we either quit (like we found out before) or call some function to handle input. That must just take care of any keyboard input (other than the 'q', of course!). So, if I hit '9' it sends my player up and to the right. If I hit '0', it's supposed to fire. I'll look at how that works later. Maybe part of that is what we're supposed to make work!
OK, that's it for the GP142_KBD case. Let's look at this GP142_PERIODIC thing. According to the comment, these just come up a few times a second no matter what the user does.. even if she's just sitting there not touching any keys, I suppose!
It looks like if the status of the game is that we're playing it, we update the screen (with a big, hairy function call). Otherwise, we skip that. Why would the status of the game ever be anything other than "playing"? Let's check out the declaration of gameStatus and GAME_PLAYING to find out!
Well, the declaration of gameStatus isn't very useful. It's just an int. And, GAME_PLAYING doesn't seem to be in this file. Where could it be? Well, it must be #included into this file or it wouldn't work!
Wait! Above #include "tron.h" it says that tron.h "defines symbolic constants". Let's open up that file and see if GAME_PLAYING is there!
Aha! There's GAME_PLAYING in tron.h! And, it's under a comment labeled "Game Status". So, what about the other statuses? Actually, looking at them, they make sense. Although, I'm glad I can use the symbolic constants and not deal with the numbers directly: those numbers make no sense. Back to main!
OK, so if we're playing (and the player hasn't died, and we're not on the flash screen (that's a title screen), and we're not starting or ending a level, etc.), we update the screen to reflect what ought to happen, I suppose. Otherwise, we draw the screen. Wait! That doesn't make sense! Aren't updating and drawing the screen the same thing? Let's look at the comments for those functions.
OK, drawScreen's comment says it "Draw[s] the entire screen." updateScreen says it "Perform[s] one frame of animation by updating the positions of everything." Ah! It doesn't actually draw anything, it says! It just moves stuff around. That makes sense: updateScreen moves things around while drawScreen doesn't worry about that; it just draws everything wherever it actually is right now. Updating is like moving the clay in a claymation move. Drawing is like taking a picture to get one frame of the movie! That make sense.. let's head back to main.
Now it makes sense that updateScreen isn't called if we're not playing the game. Why move stuff around when you're not actually playing?

The call graph

You should go and make a static call graph at this point. I'll do mine and then come back. It's pretty easy: it just involves looking in the code and seeing which function calls which other function.

Filling in one step

Hey, when I was making that static call graph, I found out that a bunch of functions aren't implemented! They just say "TODO". That must be (some of?) the stuff that we need to do on this assignment. Plus, there's some functions that aren't called at all. I bet some of those are things that I can use to implement the TODO stuff!

I'm going to try filling in the very first TODO I found: startLevel.

According to the directions:

At the start of each level, [I should] clear the screen, place the hero in the middle of the screen, and randomly place 1 enemy on the screen.

From my call graph I know that's called from three different places! handleInput calls it (looks like when the level ends), startGame calls it, and updateScreen calls it (when the player is hit by an enemy? I'm not sure I get that.. later!). Anyway, the good news is as long as I do what the function descriptions says I need to do, I shouldn't have to worry about where it's called from or how it's used! It'll just work because it keeps its contract. I love functional decomposition!

OK, I've read the function comment, and it makes sense. (Although.. why does it single out the level number as important?) The TODO comment in the function repeats everything the instructions said to do and also says to "set the bullet's status appropriately". I'll ignore that for now, but I'll make sure not to delete that part of the TODO so that I know I haven't done it! OK, here goes nothing!

startLevel can only change the things that get passed to it as pointer parameters. So, I know I'm not going to change level. However, everything else is up for grabs!
Hm.. "initialize player's position". That sounds like setting the playerX and playerY variables. Perhaps I should set those both to 0? What would put things in the middle of the screen. Aargh! I can't find if (0, 0) is the middle of the screen in the code!! Well.. maybe if I look at how the player is drawn? I bet that function is called drawPlayer (according to the naming conventions). I'll look around for it.
Found it in my call graph! And.. found it in the files! It's in tronDraw.c. It just calls some GP142 functions with the x and y locations it's given. I guess that means that GP142 decides where the center of the screen is! Off I go to the GP142 documentation!
Aha! Look at the "Drawing Model" section! It tells me that (0, 0) is the dead center of the screen! Awesome! I'll try setting the playerX and playerY to 0 inside startLevel and see what happens.
Nothing happened when I ran the program. Player still starts out in the lower left. Must destroy computer! Grr..
Oh. Right. Duh. playerX and playerY are pointers to ints. So, I don't set them to 0, I set *playerX and *playerY to 0. I wonder why the compiler doesn't warn me that I'm doing something wrong when I do that?!
It worked! Triumph! Victory! The world is my oyster!

I finished that. So, I'll take "the player's position" out of the TODO comment.

A few more steps

OK, let's polish this function off (except maybe that "bullet status" part).

Facing next. That should be easy.. looks just like position. Except what do I set it to? Maybe GP142 defines facings as well? No.. that doesn't make sense: rectangles don't normally have facings!
I'll look around for the word "facing" with MSVC's search button (the binoculars thing).
Whoa! Too much information! But, the very first thing that it found looks promising. It says:
```
  #define PLAYER_START_FACING (-LEFT)
```
Hmm... what is LEFT and why is it negative?
Found LEFT back in tron.h again. There's a great comment that explains why the negative sign is there, too. But, if all that is right, isn't the PLAYER_START_FACING already set up to work? I'll run it again and check.
No! It faces like up and to the right or something. Except it doesn't really look right at all! The little red dot is in the wrong place. It's not even on the rectangle at all.
Oh, wait! Just #defining a symbolic constant called PLAYER_START_FACING doesn't do anything! I need to tell the computer to use my starting facing, and that must be supposed to happen in startLevel!
OK, back in the startLevel function. I'm going to go ahead and set the playerFacing to PLAYER_START_FACING. But, this time I'll remember the *! Let's run it again and see if it worked.
Oh! Victory again! HW#4A will fall before my might! HAHAHAHAHA!
Hey, looking at that PLAYER_START_FACING, I noticed a couple of other symbolic constants: PLAYER_START_X and PLAYER_START_Y. I can start playerX and playerY off with those values instead of the "magic numbers" (0, 0).

OK, I'll just create the enemy now. I checked out all the functions around here when I made my call graph.. so, I know there's a terribly useful function for this just a few lines down from startLevel. I'll call that to create my enemy. Then, I'll rerun it to see what happens.

That is so cool! The game actually works now (sort of). And, I've taken care of everything in startLevel's TODO list except setting the bullet status. I bet I can take that to.

Warning: descending into madness. Hey, I can finish this. I can do it right now! I'll do Part B today, too. And, I think I'll go ahead and ace the midterm but take only ten minutes of the period on it as well. Plus, I think I will polish Steve's bike!

P.S. I (Steve) wrote this walkthrough just as I did it. The steps were really the steps I took (although I admit I threw in the playerX = 0 error just for fun). Having done so, I want to say that the code is some of the most tear-jerkingly beautiful stuff I've ever seen. Congrats to Luke, David Du., Matt, and Hannah for producing such a masterwork!

P.P.S. If you're curious about the answers to any of the questions in this walkthrough, maybe you should post to the newsgroup about them. Remember to know what's cheating and what isn't first, though! No assignment code on the newsgroup!