$INCLUDE Statement Our example game is getting a little big to be quickly read so we will now make use of a nice feature of Alan called 'include' files. Alan allows the author to split the source code into two or more text files but compile the multiple files as if they were a single big file by using $INCLUDE statements. A $INCLUDE statement can appear anywhere in the source code for a game and looks like this
$INCLUDE 'filename'
If Alan finds an $INCLUDE statement in a source file while its compiling, the text in the second file is compiled into the game as well.
One of the main benefits of the $INCLUDE statement is it allows game authors to split source code into more readable chunks. For example, we can save the verb definitions created in earlier lessons into a separate file so the example source code for this lesson doesn't become too cluttered.
The library1.ala file contains the definitions for the look, brief, verbose, score and quit verbs. If we put the statement $INCLUDE 'library1.ala' into the example source code for lesson five, all those commands will be compiled just as if they had been typed into the lesson5.ala file.
The other main benefit of the $INCLUDE statement is that chunks of useful source code like those basic commands can be used in any number of games. Such chunks of code are referred to as 'libraries.' You can write your own libraries or make use of code that other people have written to instantly add features to your own programs.
There are a couple of examples of libraries at the Interactive Fiction Archive which you may like to look at. (Look in the 'Sources' appendix to his tutorial for details.) The 'Etudes' contain a file called SHELL.ALA which contains some features shared by all the Etude examples. There is also a file called STANDARD.ALA which defines an extensive range of standard verbs and other features. This library won't compile without modification and most of the verb definitions don't actually do anything but it gives a good idea of what sort of things an author may need to program in a complicated game.
So far in this tutorial we've discussed the definition of locations and verbs. The third main component of an adventure game definition is 'objects' - things which the player can perhaps pick up and manipulate in some way during the course of the game.
The basic definition of an object called 'note' would look like this
OBJECT note END OBJECT.
An object's initial location in a game is specified with an AT statement. The following example will place the note at the city street location
OBJECT note AT street END OBJECT.
Alan automatically adds a message to the location's description - "There is a 'objectname' here." The author can change this message to something else but we'll leave that until the next lesson.
The game author must specify some new verbs to enable the player to interact with objects. For example, the player will normally expect to be able to pick up and put down objects.
In adventure game terminology, when a player gathers objects it is said that a player is adding objects to the player's 'inventory.' For a player to pick up the note we have placed in our Street we need a verb that moves the note from the street to the inventory. So a command called 'take' to allow a player to pick up an object could be defined like this
VERB take
DOES
LOCATE OBJECT IN Inventory.
END VERB.
The verbs we defined in earlier lessons required a syntax statement. The 'take' verb doesn't require a syntax definition because it conforms to the default Alan verb syntax of the 'verbname' being followed by an 'objectname.' By default, when a player types a verb name Alan expects it to be followed by the name of the object which the verb will be applied to. (For example: 'eat the cake' and 'shoot rabbit'.)
The word OBJECT in the DOES section of the verb definition is a reference to whatever object the player mentioned after he wrote the word 'take.' So if the player wrote "take note" then the DOES clause will mean 'LOCATE note IN Inventory'
LOCATE is an Alan statement that means place the object at the following location. In the case of the 'take' verb that location is 'Inventory.' Alan automatically defines an object called 'Inventory.' It is a 'container' that the player always has with them for holding objects they collect during an adventure game.
To allow the player to put things down again we can define a 'drop' verb
VERB drop DOES LOCATE OBJECT HERE. END VERB.
The DOES part of this verb is very similar to that of the 'take' verb except instead of 'IN Inventory' there is just the word 'HERE'. HERE is another Alan keyword. It means 'the location where the player currently is.' So this DOES clause will remove the object the player mentioned from the 'Inventory' object and put it at the current location.
The player may find an 'inventory' command to list their collection of objects useful. Because there is already a container object called 'inventory' pre-defined in the game we can't name a verb called 'inventory.' It's not the same as using an Alan keyword as a verbname where quote marks around the name solves the confusion. In this case we would have two entities, one a container and one a verb, with the same name. That is a situation that Alan could not compile. So we'll simply name the inventory verb something else - for example 'list_inventory' - but define the syntax for it (ie: the command that the player types) as 'inventory'.
SYNTAX list_inventory= inventory.
The player will probably get tired writing 'inventory' all the time so defining an abbreviation, such as 'i', with a synonym statement would be a good idea.
The Alan statement 'LIST containername' means list the names of the objects in the specified container. So the definition of the 'list_inventory' verb could be
VERB list_inventory DOES LIST Inventory. END VERB.
The Alan system doesn't dynamically create and destroy objects during the playing of a game.
Often, though, a game author will want the player to think objects are being created or destroyed - for example when the player waves a magic wand a white rabbit appears at the current location or when the player eats the chocolate bar the bar should no longer be in the player's inventory. However, like a magician, the game designer cannot really create and destroy things but only make them appear and disappear - in the game designer's case - with the LOCATE command.
All the objects that will appear in a game need to be defined by the author. The Alan author can simulate the creation of an object by leaving its initial location undefined - by leaving out the 'AT' clause in the object's definition, eg:
OBJECT rabbit END OBJECT.
Then a certain verb or event can place the object where the player can see it - hey presto!, an object appears to be 'created'
VERB shazam DOES LOCATE rabbit IN tophat. END VERB.
To destroy an object it must be moved out of the player's view, to a location inaccessible to the player. The author can define a location - called 'nowhere' for example - which he can move destroyed objects to. If there are no other locations with exits leading to that location, the player will never see the 'destroyed' objects again.
If we define a 'Nowhere' location, we can define an 'eat' verb which 'destroys' the object the player eats by moving it to 'Nowhere.'
LOCATION Nowhere END LOCATION. VERB eat DOES LOCATE OBJECT AT Nowhere. END VERB.
When the player types 'eat note' nothing much will happen. He simply gets the normal > prompt asking for his next command. Only if the player does an 'inventory' will he see that the object is no longer in his possession. So we should add some descriptive text to the eat verb so the player knows what has happened.
VERB eat DOES LOCATE OBJECT AT Nowhere. "The note is surprisingly tasty. But, now that you think about it, eating it was rather pointless." END VERB.
That 'eat' verb definition is not quite right. If the player tries to eat some other object a message about the 'note' object will be displayed - something the player will find a bit puzzling.
Frequently, like the eat verb, the player may like to try actions that only make sense for certain objects or have unusual results if the player tries them on certain objects. The Alan language handles these object-specific actions by allowing the definition of verbs within object definitions.
So far in this tutorial we have always placed verb definitions in the main body of the source code. By entering a verb definition within an object definition, the game author can define verbs that apply only to specific objects.
You can also define a verb within a location definition so that it applies only when the player is at that particular location.
So we can define the eat verb within the note object definition like this
OBJECT note AT Street
VERB eat
DOES
LOCATE Note AT Nowhere.
"The note is surprisingly tasty. But, now that
you think about it, eating it was rather
pointless."
END VERB.
END OBJECT.
So now, if the player tries to 'eat the note', the verb's DOES clause will be executed. If the player tries to eat some other object, a default Alan message - 'You can't do that' - will be displayed.
You can also give the player some points for performing an action by putting a SCORE statement in the verb's definition.
VERB eat DOES LOCATE Note AT Nowhere. "The note is surprisingly tasty. But, now that you think about it, eating it was rather pointless." SCORE 5. END VERB.
This is a 'good' example of bad programming - the text says "rather pointless" and then we proceed to give five points to the player with the SCORE 5 statement. This sort of problem can easily sneek in when writing a game. Although it is perfectly good Alan code so it will compile just fine, its a 'bug' from the player's point of view. Hopefully the game author will notice it while they or someone else is testing the game. The author can then rectify it by removing the score statement or making the text more appropriate - perhaps like this:
VERB eat DOES LOCATE Note AT Nowhere. "The notepaper tastes awful. You only just succeed in swallowing it without choking but now you know that the message can not fall into enemy hands." SCORE 5. END VERB.
As well as creating and destroying objects, the game author can simulate changes in an object by replacing one object with another. In the following example if the player eats the apple he is carrying, the apple object is moved to 'nowhere' and the 'applecore' object appears in the Inventory instead.
OBJECT apple IN Inventory END OBJECT. OBJECT applecore END OBJECT. VERB eat DOES LOCATE apple AT Nowhere. LOCATE applecore IN Inventory. "You munch happily on the crisp apple until you're left holding nothing but the core." END VERB.
'-listing' Option You may notice when you compile the sample game for lesson five that the Alan compiler reports that there were four informational messages.
"Well, where are these messages?" you might think.
The messages aren't displayed on screen because they're unimportant default messages that shouldn't cause you any concern. But you can see them by running the Alan compiler again with the '-infos' option. You will probably then get too many messages to read before they scroll off the screen so you can also use the '-listing' option to view all the messages generated by the compiler - you can abbreviate it to -l like this
alan -l lesson5
The -listing option, you may recall from the introduction, produces a text file containing the messages generated by the Alan compiler. If you open the file lesson5.lis with your text editor you'll see that the 'informational messages' are telling you that the Alan compiler assumed that the object verbs we defined use the default Alan syntax and that the location 'Nowhere' has no exits. Interesting stuff but no cause for concern because that is what we intended.
Remember, though, that the '-listing' option becomes very useful when your source code has so many errors that you can't see all the messages scrolling up the screen when Alan attempts to compile the code.