2.3.1 The Map

In Alan, the map is a number of locations connected (or not!) by any number of exits. A location has a description that is presented to the player when it is entered. A location may also have a number of exits stating in which direction the exit is and to which location it leads. Alan places no restrictions on the layout of the map, any topology is allowed. Note, however, that since exits are one-way, an explicit declaration of a backward path (if such is desired) must be made.

2.3.2 The Objects

The other vital entity in Alan is the object. Most Alan objects are things that in real life would be objects too, like a knife or a key. In addition, other things that should be manipulable by the player, e.g. parts of the scenery, must be declared as an object. For example if you require the player to `whistle the melody', then the melody must be an Alan object.

Objects, like locations, have a description that is presented when they are encountered during the game.

Every object may also have a set of properties, like eatable and movable, which may be changed during the execution of an Alan program. Most objects would probably not be eadible so there is also a mechanism for giving default properties to objects.

Some verbs have special meaning or effects when applied to a certain object. These verbs and their effects are also declared within the object.

2.3.3 The Verbs

Verbs are imperative statements input by the player to command some action. These must also be declared in an Alan adventure, either in an object (as described above) or as a general (global) verb that describes the effects of the verb when applied to any object or for verbs to which no object may be given.

To make it possible for the player to input more complex commands a means to specify the syntax for a verb is also available. Using this verbs can also be made to operate on literals (strings and integers) giving the player the possibility to input things like

 
> write "Merry Christmas, Mr. Lawrence" on the xmas card

2.3.4 The Actors

An extra thrill and dimension are additional characters in the game. These are called actors and have a life of their own. For each move the player makes these programmed characters also get a turn to do their thing. An actor may be a thief running around and stealing your collected treasures, a dragon guarding the entrance to its lair and so on.

Actors get their behaviour from scripts that step by step describes what is going to happen for each player interaction.

One of the interesting things about playing adventure games with actors is to figure out how to interact with and influence the other characters.

2.4.1 The LOCATION

The scene for your Adventure is a series of "rooms" or, rather, locations. They are connected by paths that lead from one location to another, making it possible for the hero to travel through the world of your design, exploring it and solving the puzzles.

What is necessary to describe a location? Every location (or LOCATION , when we are referring to the Alan language construct) must have a name. This is so that you, the designer, may refer to that LOCATION easily, instead of having to remember a magic number for each LOCATION .

Unless you provide other means for transportation from a LOCATION , you should also describe in which directions there are exits and to which LOCATION s they lead.

In fact, this is all that is really necessary in a LOCATION , so lets look at an example (you would probably like to try this out, referring to SYSTEM DETAILS for instructions for your particular system).

 
LOCATION Kitchen
	EXIT east TO hallway.
END LOCATION Kitchen.

LOCATION Hallway
	EXIT west TO kitchen.
END LOCATION Hallway.

START AT Kitchen.

This is a complete Alan Adventure (although very primitive). As you see, every Alan construct ends with a period ('.') and there is also a " START AT" sentence at the end, indicating in which location to put the hero when the game starts.

Run this little Alan source through the Alan Compiler (see HOW TO USE THE SYSTEM and SYSTEM DETAILS ) and try the Adventure. After starting the Adventure, two lines will be shown on your screen. The first line will contain "Kitchen" and the second a ">", which is the prompt for the player to input a command. Now try typing "east". The word "Hallway" and the prompt will appear. Typing "west" will take you back to "Kitchen" again.

We see that the name of a LOCATION is automatically used as a description shown when that room is entered. We also see that the words used in the EXIT -parts are translated by Alan into directional commands that are usable by the player.

You should remember that exits are strictly one-way. An EXIT from a LOCATION to another does not automatically imply the opposite path. Thus one must explicitly declare the path back, in the definition of the other LOCATION .

But just the name of the location is not much of a description. So in order to provide the "purple prose" descriptions often found in high-class Adventures there is an optional DESCRIPTION -clause in the LOCATION . Let us describe the Hallway.

 
LOCATION Hallway
	DESCRIPTION
		"In front of you is a long hallway. In one end
		is the front door, in the other a doorway. From
		the smell of things the doorway leads to the
		Kitchen."
	EXIT west TO Kitchen.
END Hallway.

We introduce another feature in this example, namely the text enclosed in double quotation marks ('"') which is called a STRING or, when used on its own like this, an output statement. When executed this string will be presented to the player and formatted to suit the format of his screen.

Invent a description for the Kitchen, enter it in the Alan source and run the changed adventure. You notice, of course, that the text in the output statements is reformatted during output to suit your screen, in order to make room for as much text as possible. Note also that you do not have to worry about this at all - in your source file you may format the text any way you like.

This type of output statement is just one of the statements in the Alan Language, and we will see more of them later.

It is also possible to have conditions and statements in the EXIT -clauses of a LOCATION to restrict the access to the next location or to describe what happens during this movement.

 
EXIT west To Kitchen
	CHECK 		kitchen_door IS open
		ELSE "The door is closed."
	DOES
		"As you enter the kitchen the smell of
		something burning is getting stronger."
END EXIT west.

2.4.2 The OBJECT

Another essential feature in Alan is the OBJECT . Like the LOCATION , the OBJECT is a means to describe the "physical" world where your Adventure is taking place. Most objects are probably used to provide puzzles, like closed doors, keys and so on, but other objects should be promoted to OBJECT s too. A large number of objects that can be examined and manipulated makes a game so much more enjoyable.

OBJECT s, like LOCATION s, have names and descriptions, so you might guess the general structure of an OBJECT .

 
OBJECT door AT Hallway
	IS closed.
	DESCRIPTION
		"The door to the kitchen is a sliding door."
		IF door IS closed THEN
			"It is closed."
		ELSE
			"It is open."
		END IF.
END OBJECT door.

An OBJECT may initially be located at a particular LOCATION (although objects do not have to start at a particular place in which case they are not present in the game until located at some place where the player may lay his hands on them). This is indicated by the AT -clause, in this case telling us that the door is initially located in the Hallway.

In addition, OBJECT s may have attributes indicating the state of certain properties of the object. In this example with a door, the IS closed part indicates that the OBJECT door should initially have the attribute closed set to TRUE (i.e. the door is initially closed). The opposite would be indicated with a NOT, (i.e. IS NOT closed ).

Alternatively, attributes may be numeric (e.g. HAS weight 5 ) or be of string type (e.g. HAS inscription "Kilroy was here" ).

We also introduce another Alan statement, the IF statement. The IF statement allows you to select which statements to execute according to some condition. In the example, the closed attribute of the door selects which description to show. There are further variations of expressions and the IF statement, but we will come back to these later ( Expressions and If ).

Instead let's look at some other statements in relation to OBJECT s.

The attributes of an OBJECT must, of course, be changeable, and this is done with the MAKE statement or the SET statement. For example if the door should be opened (the player having said "open door", perhaps) this could be performed by

 
MAKE door NOT closed.

or closed (i.e. setting the closed attribute to TRUE again) by

 
MAKE door closed.

The SET statement changes numeric or string attributes, for example

 
SET level OF bottle TO 4.

Another OBJECT manipulating statement is the LOCATE statement. This is the statement to use when moving objects from one location to another. Opening a lid might cause a previously hidden object to fall to the floor, something that could be performed by moving the object from a limbo LOCATION to the current one with

 
LOCATE treasure HERE.

Or to a particular place with

 
LOCATE vase AT hallway.

2.4.3 The ACTOR

The ACTOR is used to populate the adventure with other creatures. They might be pirates or monsters, but the thing they have in common is that they move around and perform various actions more or less in the same way as the player does.

An ACTOR may have a DESCRIPTION and attributes like OBJECT s and LOCATION s. An ACTOR performs his movements by following scripts, each having a number of steps. Each step corresponds to one player move.

 
ACTOR charlie_chaplin NAME Charlie Chaplin
	SCRIPT going_out
		STEP
			LOCATE ACTOR AT outside_house.
		STEP
			LOCATE ACTOR AT hallway.
			USE SCRIPT going_out.
END ACTOR charlie_chaplin.

2.4.4 The VERB

The VERB is the construct that implements the effects of an action requested by the player. VERB s may be global, local to a particular LOCATION or associated with an OBJECT . We will look at the implications of various combinations of these in the next few sections.

To implement a VERB you need a name for it (which is also the default word the player should input to request that action). You must also decide which effects this verb should have under various circumstances.

If we want to implement the VERB open for the door we could use the following code

 
VERB open
	DOES
		MAKE door NOT closed.
END VERB open.

This implementation makes direct references to the door, so to make the verb more general it would instead need to reference the object the player mentioned in his command (see The SYNTAX for a discussion on this). In this case the attribute closed must also be available for all objects (by making it a default object attribute, see Attributes and Default Attributes ).

Of course, there are also conditions that have to be checked before we could execute this code (perhaps to see if it was possible to open the object!). Therefore VERB s may have CHECK s.

 
VERB open
	CHECK OBJECT IS openable 
		ELSE "You can't open the $o."
	DOES
		MAKE OBJECT NOT closed.
END VERB open.

 
VERB take
	CHECK OBJECT takeable
		ELSE "You can't take that."
	AND OBJECT NOT IN inventory
		ELSE "You already have it."
	DOES
		LOCATE OBJECT IN inventory.
END VERB take.

 
VERB throw
	CHECK OBJECT IN inventory ...
	DOES
		LOCATE OBJECT HERE.
END VERB throw.
LOCATION dark_place
	VERB throw
		CHECK "Too dark to aim."
	END VERB.
END LOCATION dark_place.
OBJECT vase
	VERB throw
		DOES
			"The vase breaks."
			LOCATE vase AT limbo.
	END VERB throw.
END OBJECT vase.

 
	> throw vase

2.4.5 The SYNTAX

Normally a verb acts on one object or actor, henceforth called a parameter. This means that the format of player input normally is something like

 
> take vase

This form, or syntax, is the default form when you don't specify anything else. The default syntax might thus be described as

 
SYNTAX
	? = ? (object)
		WHERE object ISA OBJECT.

where the question marks are replaced by the name of the verb.

But in order to allow different and more complex player input the SYNTAX construct is supplied.

The SYNTAX construct is a way to describe the words and parameters the player may use in order to execute a particular verb (its global and more specialised parts). Below is the syntax for put_in , the verb to put something inside a container.

 
SYNTAX
	put_in = 'put' (obj) 'in' (cont).

This syntax defines the put_in verb to be executed when the player has input the word `put' followed by a reference to an object or actor (a parameter named obj ), followed by the word `in' followed by a reference to a second parameter (the container), as in

 
> put the green pearl in the black box

This will bind the parameter obj to the object that represents the green pearl and the parameter cont to the black box. It is also possible to restrict the types of the parameters:

 
SYNTAX
	put_in = 'put' (obj) 'in' (cont)
		WHERE obj ISA OBJECT
			ELSE "You can't put that into anything."
		AND cont ISA CONTAINER OBJECT
			ELSE "Nothing fits inside that."

This restricts the parameter obj to being an object (as opposed to an actor for example) and the parameter cont to a container object (an object with the container property).

The parameters are used as normal identifiers in the Alan source, provided they are defined in the current context, i.e. they can only be used in the bodies of the verb (see also Run-time Contexts for a detailed discussion).

The SYNTAX construct generalises the verb execution order described previously from execution of verbs in one object, to verb bodies in all the parameters. In the example above, verb bodies in both the object or actor referenced as obj and cont (the green pearl and the black box) are executed (if present in their declarations).

Another use for the SYNTAX is to define the syntax for simple verbs such as quit , score etc. They also need a SYNTAX definition as they do not fit into the default verb/object format. An example would be

 
SYNTAX q = 'quit'.

But for simple verb/object forms no SYNTAX is actually necessary.

• Note: In expressions, OBJECT always refers to the first parameter. This makes it consistent with the default syntax of verb/object (and also with the definition of OBJECT in version 1).