The Class Hierarchy

General Notes

Do not leave yourself less than a week to do this. If nothing else, start learning the code now. Read over the code. Also, be careful of reimplementing functions that we give you.

The purpose of this document is to try to help you digest this gigantic amount of code without losing what sanity you may have left. Fortunately, the code is relatively well commented, so you should be able to figure out what much of it does. This document assumes you have a copy of the code available to refer to as you read it.

Queue.ss
This sets up the basic queue structure - adding an element, taking an element off, and getting the top element without removing it. Recall that a queue is a data structure that operates on a FIFO (First In, First Out) organizational system - the first item added to the queue is also the first item removed, just like people lining up, for example, to go to the bathroom. (After all, in England you don't line up, you get in a queue - same thing, different name. The Brits are weird like that.) Also recall that a priority-queue just means that some items get priority and get better spots in the queue based on that priority. To return to the bathroom example, suppose Yakko really, really has to go potty, and threatens Bad Things if he doesn't get to go soon. Most people will give him priority, and he gets to go next, even if there were 5 people in line before him.

Events.ss
Everything that happens in the game is an event. Walking around, moving, fighting, picking up an object, everything. The game runs on an event-queue, which never empties. There's always someone like the Knights who say, "Ni!!!" adding additional events on the queue. See the do-something functions for more details. Events are sorted by time, and sometimes, like when you want to leave a room, you want to leave immediately, so there's a verb to insert an immediate event.

General.ss
This file defines a number of general methods. It sets up the top levels of the class hierarchy and defines some generic methods to be used on these classes. We're going to have a number of methods for transfer, so keep track of that. Also take note of the initialize method - it will show up in later files as well, specifically animates.ss.

Input.ss
Here's where it starts getting tough. We start by defining a couple of classes. Note that <command> isn't on the class hierarchy diagram, but that's only because it doesn't have any subclasses and isn't a subclass of anything other than <top> - we didn't want to clutter up the diagram any more than it already is. commands is defined as a generic function here - keep track of it, it'll be defined later. do-command handles everything that gets typed into the game command prompt. The rest of the functions aid the user interface.

Animates.ss
This file defines a lot more classes - study the class hierarchy provided if you get confused. Lots of the functions in this file are rather self-explanatory. instance-of? takes an object and a class and returns #t if the object is either that class or a subclass of that class. The initialize function is what starts the animate on its way by inserting an event into the event-queue. The comments should make the code pretty clear. place-message is defined in places.ss

Players.ss
Now that we've defined characters, we need to define special classes for interactive players. Again, the comments should make most of the code clear. do-something checks to see if there is any input from the player. If so, it parses and executes that input, and if not, it waits. Don't get too confused by the fact that it's a bit long. This is very highly commented in order to help you - you need not provide this level of commenting in your code when you turn it in to us unless you are doing something extraordinarily sneaky, in which case you can probably find a better, clearer way to implement the problem.

Places.ss
Places are easy. Places are basically nodes in a graph. describe-location looks long, but it's not so bad. It's implementing a couple of things to make your life easier: when you enter a room you've been in before, you don't see the full description again. place-message sends a message to everyone in the room saying you've left (or come in, or whatever) but not to you (unless it's an emote). "type" is set to #f in the case that a certain function wants to send a message to the entire room but doesn't have a specific command for that function. For example, leave, being a command, has a message already associated with it, but in fighting.ss, the outcome of a fight is not determined upon the function call, so fight handles its own messages.

Inanimates.ss
Inanimates are even easier: they're just objects. There are a lot of different methods defined for transfer - consult the class hierarchy if you're unsure as to which method is called with (call-next-method).

Fighting.ss
Now we get to define fighters and weapons. A character can only have one weapon at a time, which becomes their default potency. It's very difficult for one character to kill another. Right now, the draw-weight is set up at 1000 for players, which means that you're not supposed to fight other players - you'll probably end up in a draw.

Commands.ss
This defines all the commands that a player can do. Entering or leaving a room, picking up or dropping objects, fighting, and various other helpful commands (like 'help', for example). The reminder at the beginning of the file should explain the code well. If you're still confused, go to David's office hours.

World Files
These files create all the instances such as locations, characters, and objects. They also define the specializations that make the game fun. If you want to have fun exploring the game, don't try and spend too much time looking through these files - play the game first!!

Game Mechanics

The game consists of a world which contains places, inanimate objects (like books or grenades), animate objects (like the players or the Knights.) Animates can move from room to room, pick up or put down inanimate objects, fight, say things to one another, etc. As a player, you can type commands in to the game which cause your animate to perform certain tasks. Other animates, such as the Knight, are automated and have their own "plans" for moving around in the world and interacting with other animates and inanimates.

All of the activities that are going on in the world are organized into events. An event is just an abstraction of any possible thing that can happen in the future, like a particular Knight saying "Ni", or like a player throwing the hand grenade, or like the toilet flushing, or like a message being printed to the screen.

The core of the game engine is an event queue. The event queue keeps track of events that need to happen at some point in the future. The main part of the program is a loop that simply pulls events out of the event queue (in time order) and executes those events. Executing one event may place additional events into the queue to be executed at some later time.

For example, there is an event for Knights that when executed, causes the Knights to say "Ni!" and then inserts a new event so that the same Knight will say "Ni!" again some time in the future. As another example, there is an event which when executed, asks the player for input, parses the input, figures out what command to execute for the player, and inserts appropriate events into the event queue so that the command will be accomplished.