< Previous page Contents Next page >

Object = Noun: person, place, or thing

Let's jump right in! The best way to learn is to do, so we'll make a simple game file. We'll create a (bland) room and compile a game. Open your editor and type the following text into it. (You could copy and paste the text from this page, but I think you'll get a better feel for creating files if you actually enter the text yourself.)

Constant Story "INFORM BEGINNER'S GUIDE";
Constant Headline "^A Tutorial^by <your name here>^";

Include  "Parser";
Include  "Verblib";

Object   BoringRoom "Boring Room"
   with  name "baseboard" "wood" "panelling" "panel",
         description "This room is empty. There is nothing here but the
         wood panelling on the walls and the baseboard.";

[Initialise;
   location = BoringRoom;
   "^^^^^^Oh man, this is too much already! What's with the ~Constant,~
   ~Include,~ ~Initialise,~ and all that other stuff? I thought we were
   going to take it slow...!^";
];

Include "Grammar";

American Alert!

Be sure you write Initialise, not Initialize.

Now save your file and run it through the compiler. You'll have to refer to the compiler's documentation for how to do that (sorry). Create a version 5 file. Once you have a story file created, play it with your interpreter. Once again, you're on you're own here, but it shouldn't be difficult.

Hey, who turned out the lights?

Sorry, I couldn't resist. I hope you didn't freak out too much when you couldn't see anything. (Give yourself 2 points if you knew when you were entering the source that you wouldn't be able to see anything. Take away 2 points if you read this part before you compiled. Party pooper.)

There is no light source, so you were in darkness. To fix this, change the end of the room description to look like this:

         wood panelling on the walls and the baseboard."
   has   light;

Now recompile and run. Really. No tricks this time. Try anything you can think of. If you get anywhere, let me know, because you sure shouldn't be able to.

Now that I've deluged you with this one-room source file, let's pick it apart and see what's going on. This examination will span a few chapters.

Constant Story "INFORM BEGINNER'S GUIDE";
Constant Headline "^A Tutorial^by <your name here>^";

What's a Constant?

A constant is something that doesn't change. You create a constant with the Constant directive [footnote 1], supplying the name of the constant and the value of the constant. Then, whenever you use the name of the constant, the compiler acts as though you typed in the value.

What's it good for?

A constant serves two main purposes: it can act as a "shortcut" for a value to save typing (and ensure consistency), and it can be used to allow the programmer to easily change a value once and have that change reflected throughout the entire source. A classic (and useful) example of a constant is the value of pi, however, pi is a fraction and Inform deals with integer numbers only, so I'm omitting the example lest it stick in your head and you try it.

Let's look at an example which would work in Inform. Suppose you implement a system where the player can carry a maximum weight. For the sake of example, let's make this weight 100. Let's also say that you refer to this weight in 8 different places in your source code. Then you decide that this maximum lets the player carry too much; you want the value to be 75. If you typed the value 100 every time you dealt with the maximum weight, you would now have to change this 100 to 75 in each of the 8 places it occurs. While this could be done with your editor's find and replace feature, what if you used the value 100 somewhere else for something that had nothing to do with maximum weight? This would also get changed to 75! The answer, then is to define a constant (MAX_WEIGHT comes to mind) to represent the maximum weight and use the constant in those 8 places. Then you would simply change this

Constant MAX_WEIGHT 100;

to this

Constant MAX_WEIGHT 75;

and you're done. It's basically a programming tradition to write constants in all capital letters. The idea behind this is that nothing else should be written in all caps, and therefore whenever you see something in all caps, it's got to be a constant. I find the idea sound and use it myself. It's a free country, folks (at least it is where I live), so do whatever you want.

Okay, smarty, what's the deal with Story and Headline? You don't use them anywhere

You're right: I don't use them anywhere. But the compiler does when creating the game. Run your sample game again. Notice that after the "Oh man, this is too much already" part, the values of the Story and Headline constants are printed. You'll find that there are several things that you can define and never use in your own code that will be used by the compiler. I'll point these out as they come up.

Notice also the use of the characters ~ (tilde) and ^ (circumflex). These characters have a special meaning to the compiler. The tilde, when used inside a string, tells the compiler to put a quotation mark (") in the game file. Why can't you type a quotation mark directly? Because it marks the beginning and end of the string, so if you entered

"What's with the "Constant" and "Include," stuff?"

the compiler would flag an error and refuse to create a game file, because it thinks the string ends at "the " and then it tries to interpret "Constant" as some action to take (which it is, just not here). The only thing the compiler expects to find at the end of a string being printed is a comma (and then more things to print) or a semicolon.

The circumflex means "start a new line." It's like pressing the Enter key (or Return, for you Mac folks). When the interpreter reads this character during the course of the game, it continues printing at the beginning of the next line (or prints blank lines if there are more than one). This character also stands for an apostrophe (') when used in object names. More on that later.

Yikes, we're only two lines in and you've already said a mouthful!

Yup. Go get some snacks and settle in. We haven't even gotten to the room yet.

Include  "Parser";
Include  "Verblib";

A brief side note: semicolons

You may have noticed that every statement ends with a semicolon (;). Inform requires this. Why? Well, I've never written a compiler, so I can't tell if a terminating character such as this really makes life easier for the compiler writer or not. I've dealt with languages that don't need special characters like this to mark the end of anything, so I can say that it's not absolutely necessary. We just have to live with the fact that this is the way it's done in Inform.

You should also be aware that although the compiler will eventually find an error in your file when a semicolon is dropped off the end of a statement, it doesn't always report that specific line as being the cause of the error, because it doesn't know there's a problem until it runs into things later that it didn't expect. Therefore, when you get a whole slew of errors when compiling, look at the first line it indicates an error on (in your source file) and back up a little bit. See if you can find a statement that's missing its terminator.

And now, back to our regularly-scheduled subtopic: Include

The Include directive tells the compiler to read and compile the entire contents of another file as if those contents had been typed into your source code. For right now, just know that you must include the three files Parser, Verblib, and Grammar, and they must be in that order. Grammar is at the end because there are certain things you can do before including Grammar which will take precendence over how the Library handles things. Basically, about the only thing that should come after Grammar is any grammar that you create yourself. That's a few chapters away.

Cool, you didn't talk forever about that one

That was to lull you into a false sense of security. On to the room.

Object   BoringRoom "Boring Room"
   with  name "baseboard" "wood" "panelling" "panel",
         description "This room is empty. There is nothing here but the
         wood panelling on the walls and the baseboard."
   has   light;

Oh boy, do we ever have some fun stuff here! Remember how I said that the two main parts of an I-F game are objects and the things you do to/with them? Well, here's an object. It even says so: Object. What more do you want?

Altogether, the first line of an object's definition is called the object header.

Another (not so) brief side note: variables

In programming, a variable is a named reference to a value. Sound like a constant? It's very similar, with the main exception being that the value of a variable can change. (Get it: variable?) Let me get into an analogy, which I'll beat to death:

Imagine a variable as a box with a label on it.

Variable: x

The label on the box is the variable's name. No two boxes in the same place can have the same label. What does "in the same place" mean? I'll get to that. The box can contain anything. I mean it, anything. Imagine that it expands to hold a value of any size. Therefore it could contain a number, a single character, or a whole chapter of a book. It could also contain a reference to an object, an action, or other things we haven't covered yet.

You can change the value of the variable whenever you want, as long as you're "in the same place." (I'll get to that, really I will.) You change the value by specifying the name of the variable (the label), an equals sign (=), and the new value. This can mess with your mind if your only experience with variables has been in math class. For example, let's say you've created a variable called x. You give x the value of 10:

x = 10;

Variable: x = 10

Now let's add 1 to the value of x:

x = x + 1;

How can this be? How can something be equal to itself plus 1? The answer is that we are not making a statement of fact that x is equivalent to itself plus 1; rather we are taking the current value of x, adding 1 to it, and assigning the result back to x. x now contains 11.

Variable: x = x + 1

You can also assign the value of another variable to the first one.

x = y;
x = z * 4;
x = y + z;

All these examples deal with variables that contain numeric values. Variables containing text or object references will be dealt with later.

A constant is even a special type of a variable, an "unchanging variable," oxymoron though that may be. Think of a constant as being a glass box with its lid locked. You can see the value inside, and therefore use it, but you can't open the lid to put something else in. However, I will try really hard to refer to constants as constants throughout this guide.

Constant

Variables must be declared before they can be used. Sometimes, as in the case of objects, the variable (actually a constant, see below) is declared and assigned at the same time. Other, standalone variables must be explicitly declared, either in the header of a routine or with the Global directive. This brings us to "in the same place."

To simplify things, let's say that a variable can either be accessible (I'll use the term "visible" from here on) anywhere in your file or only in certain parts. All objects (and hence their constants) are visible anywhere in the file. All variables declared as global are visible anywhere in the file. All constants are global, and thus visible anywhere in the file. Variables declared within routines are visible only between the brackets ([]) that frame the rountine. I haven't introduced routines yet, so just remember that when we get to them. I will of course mention it again and give examples to clarify.

You weren't kidding about that not so brief thing, were you?

Well, we got past the first word: Object, and then I started talking about the second word, BoringRoom. That's because BoringRoom is a constant which contains a reference to the room. Actually, it contains the only reference to the room. A constant must be assigned to any object that needs to be referred to later. Rooms need to be referred to at least as the target of a direction in some sense or another. For example, we'll add another room to the file later. We need to be able to tell the compiler that from the Boring Room we can go west into the Interesting Room. We also need to say that we can go east from the Interesting Room to the Boring Room. We humans could identify these rooms by their descriptions: "Boring Room" and "Interesting Room." Inform cannot. The only way to refer to the Boring Room is with its constant, BoringRoom. (Any variable can be called whatever you want. It just makes your code more readable to name them similarly to what they refer to.)

About the only time you wouldn't give an object a constant is when you are creating something that will not be referred to anywhere else in your code. The best rule of thumb as far as I'm concerned is to name a constant for each object. Definitely give all rooms constants, or you'll never be able to get the player into them!

Short description

Next comes "Boring Room". This is known as the object's short description. In the case of a room, the short description is used as a header when printing out the long (Look) description, as a complete description when returning to a room that's already been visited (assuming the VERBOSE command has not been given), in the title bar to indicate the current room, and when the PLACES and OBJECTS commands are used.

For an non-room object, the short description is printed in inventory lists, room descriptions ("You see a <...> here"), and the OBJECTS command. There are ways that you can step in and print your own text instead of letting the compiler print the short description. That's for later.

After the short description optionally comes a constant indicating the parent of an object. In truth, the object's constant and short description are optional, too. (There is also another way of indicating an object's parent by using arrow notation after the word Object, but I find this rather difficult to read. I like it spelled out right in front of my face that the parent of Toilet is Bathroom.) Rooms don't have parents, so no constant is included here. This is basically what makes a room a room.

Let's talk about that...

Footnotes

I had originally called this a "keyword," but Graham Nelson pointed out to me that in the Designer's Manual, he refers to this word as a directive. So I did a little experimenting and determined that words like Constant are definitely not keywords, because they can be used as variable names! I strongly urge you never to do this, as it will cause you nothing but confusion.

< Previous page Contents Next page >

This page hosted by Get your own Free Home Page

And yes, folks, it's really free. I'm too cheap to pay for this.