Alan is an application-oriented language. It features constructs that are natural to an author of interactive fiction. Alan is a strictly typed, compiled, object-oriented language with single inheritance. Classes inherit properties from their super-classes. The class system allows polymorphism so that instances of subclasses are valid wherever a super-class is specified. There are no explicit type declarations, except for instances of classes; instead, types are automatically inferred from expressions such as integers, strings or instances of a particular class.

There are probably four major types of readers of this document:

All readers are encouraged to share feedback on the documentation, particularly if you could not find the answer to what you were looking for by using the index, the table of content or skimming through what you thought might be relevant parts of the documentation.

You can contact the authors through the www.alanif.se website, and you can also enrol in the Alan IF mailing list, a virtual meeting place for new and seasoned Alan users alike!

A computer language is usually described as a set of rules for textual instructions for a computer. The idea is that a computer can follow those rules and perform the necessary and/or intended actions.

The Alan Adventure Language is a high-level computer language designed to make it easy to create text adventures. This means that the language have been designed so that the textual instructions are relatively easy to read and write if you understand the mechanisms that adventures are made from. In addition, it requires only for minimal additional instructions to make those mechanisms work.

Compared to programming in a typical programming language, the Alan system handles most of the tiresome tasks and supplies reasonable defaults so that you can concentrate on the plot, the puzzles, the objects and the map. This makes Alan a true high-level computer language.

The Alan system consists of two computer programs, one of which analyses an input following (or at least intended to follow) the Alan language. This program is called the compiler and the analysis ensures that the input (the game description, in fact) makes sense. The compiler also, at the same time, converts the input into something more compact, the game file. This game file can be transferred and used without the compiler. Instead, to run an adventure the interpreter is needed. The interpreter is another program that reads the information in the game file, communicates with the player of the game (or reader of the work, if you like) and interprets all the complex mechanisms in your game logic so that it gives the player the illusion of the activities and events that you have designed.

To create works of interactive fiction using Alan, you also need a program with which to construct your Alan source code, a standard text editor, like Notepad or similar programs. However, you cannot use a word processor, like Microsoft Word, since the files created with those usually contains formatting information that the Alan compiler doesn’t understand.

There are also special editors, or additions to standard editors, available, which supports Alan coding and helps with formatting and even compiling and running your game.

You might wonder why the game is not a single executable program. The answer is simple, compare the game with a Word-document. In order for the document to be visible, you need the Word-program that reads the Word-file and displays the content on the screen. As you probably know, the same program does not run on all computers. For example, you cannot install Word for Windows on a Macintosh.

In view of this, it might be considered a nice thing that there are programs for Macintosh that read, display and print Word-documents. This makes the document files portable. Once you have a reading program on your computer, you can use all similar files on it. This is also one reason behind the compiler-interpreter design of Alan.

The Alan language does not focus on variables, subroutines or other traditional programming constructs, because Alan is not primarily a programming language. Instead, Alan takes a descriptive view of the concepts of adventure authoring. The Alan language contains constructs that make it possible for you, the author, to describe the various features of these concepts. By describing for example, how the locations in the adventure are connected you have described the geography in which the story will take place. Much of what should be described is in terms of ordinary text shown to make the player experience the story that you have designed by reading them.

You will still need to understand how to vary your output depending on various conditions or information, how the player input controls which events will happen, how to connect one location to another and how to store information for later use. In a way this is programming, but in an unusual sense.

In order to understand the rules of the Alan language we will have to establish some common ground. As an author you’ll have to learn to view works of interactive fiction in the same way as the Alan language does. It will not be hard as most of the concept are familiar already.

The execution of an adventure is primarily driven by the input of player commands. A command is analysed by the interpreter according to the command syntax prescriped by the author and, if understood, it is transformed into execution of verbs or movements.

After the player has had his turn, any special conditions, or rules, that might have been programmed by the author are evaluated.

Then, other, scripted non-player characters, or actors, will move. Their movements and actions are controlled by the computer, again according to the definitions in the source.

Scheduled events are then run, and then the player takes another turn.

The following sections describe a number of the fundamental concepts that are present in an adventure game and what the Alan view of them is.

The scene for the game is a map of a number of connected locations. A location has a description that is presented to the player when that location is entered. A location may also have a number of exits stating in which direction there are exits and to which locations they lead. Alan places no restrictions on the layout of the map, any topology is allowed.

Most objects in an adventure are things that in real life would be objects too, like a knife or a key. In addition, other things that should be possible to manipulate 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 edible and movable, which may be changed during the execution of an Alan program. Most objects would e.g. probably not be edible so there is also a mechanism for declaring how these properties should be set by default, as well as mechanisms to override them, both for a particular object and for groups of objects.

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

An extra thrill and dimension are additional characters in the game. In Alan, these are called actors and may 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 or a dragon guarding the entrance to its lair.

Actors get their behaviour from scripts that, step by step, describe 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.

The player commands action by typing imperative statements. These statements are analysed and result in verbs executions (“calls”). The effects of these commands must be declared in verbs by the game author, either in an object (describing the effects of the verb when applied to an object) or as a general (global) that only applies without object.

To make it possible for the player to input more complex commands, a means to specify the syntax for a verb is also available. A particular syntax is connected to a verb and describes how the player must phrase his input in order to command the triggering of a particular verb. Using this mechanism, verbs can also be made to operate on literals (strings and integers) giving the player the possibility to input things like

In this document, there are some typographical clues. Example Alan source code is typeset in separate sections with a mono-spaced font:

You will also encounter sample game-play which will be formatted using a surrounding border (like paper…​) thus:

Later in the manual, you will find semi-formal definitions, grammar rules, for how various constructs may be constructed. These sections are typeset against a coloured background:

In running text, words that are keywords or signify an Alan construct are written in a mono-spaced font. This helps distinguish the English word ‘the’ from the Alan keyword The.

As shown in the last example, Alan keywords are written with the first letter capitalized. This is simply a convention and has no effect other than the visual. A keyword can be written Keyword, KEYWORD, keyword, or even KeYwOrD (if you are keen to show how good you are with a keyboard…​). This manual tries to be consistent with using the first version (except in grammar rules).

The scene for your adventure is a series of “rooms” or, rather, locations. Locations are connected by Exits, leading out of one location into another. This makes it possible for the hero to travel through the world of your design, exploring it and solving the puzzles.

What is required if we want to describe a location? Every location must have an identifier. This is so that you, the designer, may refer to that location easily, instead of having to remember a magic number for it.

Unless you plan to provide other means for transportation from a location, you should also describe in which directions there are Exits and to which locations they lead.

In fact, this is all that is necessary in a location, so lets look at an example.

This is a complete Alan adventure (although very primitive). As you can see, every Alan construct ends with a period (.) and there is a “Start At” sentence at the end, indicating in which location to put the hero when the game starts.

Type the above text into a text file, e.g. using a notepad program. Run this little Alan source through the Alan compiler and try the adventure (see Appendix A on how to do this). After starting the adventure, two lines will be shown on your screen.

The first line contains “Kitchen”, the name of the initial location, and the second a “>”, which is the default prompt for the player to input a command. Now try typing “east” and press the RETURN/ENTER key. The word “Hallway” and the prompt will appear. Typing “west” will take you back to “Kitchen” again. (Use Ctrl+C to exit the game if you are running it in a console window.)

The identifier for a location is automatically used as a description, a heading, shown when that room is entered. And the words listed in the Exit parts are translated into directional commands the player can use in his input.

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

However, just the name of the location is not much of a description. So in order to provide the “purple prose” descriptions often found in many adventures there is an optional Description clause that you can use. Let us describe the 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, even spanning multiple lines with extra white-space included.

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.

Another essential feature in Alan are the objects. Like the location, the object is a means to describe the “physical” world where your adventure is taking place. Many objects are probably used to provide puzzles, such as closed doors, keys, and so on, but other objects should be promoted to objects too. A large number of objects that can be examined and manipulated make a game so much more enjoyable.

Objects, like locations, have an identifier and a Description, so you might guess the general structure of an object:

An object may initially be located at a particular location. This is indicated by the At clause, in this case telling us that the door is initially located in the Hallway. Objects do not necessarily have to start at a particular place, in which case they are not present in the game until located, by executing some code, at some place where the player may lay his hands on them.

In addition, objects 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 door should have the attribute closed, which initially is set to TRUE (implying that 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").

The example also introduced 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 (Chapter 26 and Sect. 23.6.1).

Instead, let’s look at some other statements in relation to objects.

It must of course be possible to change the attributes value of an object. You can do this using the Make or the Set statements. For example, if the door should be opened (the player having said “open door”, perhaps) this could be performed by stating:

To close it (i.e. setting the closed attribute to TRUE again) you write:

The Make statement changes Boolean (or True/False) attributes. The Set statement changes numeric or string attributes, for example:

Of course, attributes are not only available on objects, but on locations and other types of entities also.

Another manipulation 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 limbo to the current location with:

You could also relocate it to a particular place using the statement:

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

An actor may have a Description and attributes, like objects and locations do. An actor performs his movements by following Scripts, each having a number of Steps. Each step corresponds to one player move.

Object-orientation is a term that is often used when talking about programming. The concept is modelled after a natural phenomenon first described by the Swedish botanist Carl Linnaeus (or Carl von Linné). He devised a naming system for flowers and plants that was based on features common between various species and families. The idea is that a general concept such as a mammal is defined by listing some features which all mammals share. Specialisations such as sub-species in turn have other, more specialised, features in common.

In nature, we talk about species and individuals. In object-oriented programming we talk about classes and instances, which are similar. Classes are abstract definitions of what the common features are and instances are individuals (data objects) having those features.

One basic property of instances is that they may contain other instances. Although conceptually simple there are twists that you should know about.

The Verb is the construct that implements the effects of an action requested by the player. Verbs are usually associated with a class or an instance. 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:

A Verb is either a simple command taking no parameters, like ‘look’, ‘save’ or ‘help’, or it involves one or more parameters that the player can reference. Simple verbs should be declared at the top level, globally, i.e. outside of any other declaration. Verbs taking parameters, on the other hand, must be declared within the class or instance with which they are associated. For example, if a verb will handle objects it should be declared in the object class. The example above should probably best be placed in the door object itself.

This defines the effects of applying the open verb to that specific door. The implementation makes direct references to the kitchen_door, so to make the verb more general it should be possible to apply to all doors. So let’s move the definition from the kitchen_door instance to the door class:

With this definition it is possible to apply the verb to all doors.

A reference to the exact object the player mentioned in his command is propagated in the parameter (see Sect. 4.8 and Chapter 15 for a more thorough discussion). Since this verb is now applicable to all door`s, the attribute `closed must also be available for all instances of the door classs. We can do that by ensuring that the attribute exists in the class using a normal attribute declaration. (See Chapter 14 on how to add an attribute to a predefined class such as object).

Of course, there are often also conditions that need to be checked before we can execute this code (perhaps to see if it was possible to open the object!). Therefore, Verbs may have Checks, as we will see next.

Normally a verb acts on an object or actor, henceforth called a parameter, referenced by the player in a command. This means that the format of player input is usually something like:

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

The question marks are placeholders and should be interpreted as the name of the verb.

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.

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, referred to as cont), as in:

This will bind the parameter obj to the instance that represents the green pearl and the parameter cont will be bound to the black box.

It is also possible to restrict the types of the parameters:

This restricts the parameter obj to being an instance inheriting from the object class (as opposed to an actor for example) and the parameter cont to a Container (an instance with the Container property).

The parameters are used as normal identifiers in the Alan source code. The parameters can only be referenced if they are defined in the current context, i.e. they can only be used in the various bodies of the Verb for which the Syntax applies (see also Chapter 36 for a detailed discussion).

The Syntax construct allows for more than one parameter, in order to make it possible to define more complex player commands. Therefore, the verb execution order previously described regarding execution of verbs in one instance must be generalised to verb bodies in all the parameters. In the example above, verb bodies in the objects or actors referenced as obj and cont (the green pearl and the black box) are executed (if the verb is present in their definitions).

Text output on the screen is caused by what you have written in the Alan source code. However, since text is coming from various places it is not easy, or even possible, to anticipate the full context of a particular text.

Therefore, the Alan system takes care of some specific formatting issues. First, text will always flow neatly inside the window or screen. Long lines will be automatically split without breaking in the middle of words.

Secondly, a few special cases are also handled automatically:

The basic types of values available in the Alan language are:

Two other simple types are available:

There is one compound type in the Alan language:

Every time a reference to an instance is made, it can be considered an expression of instance type. In these cases, the class of the instance also often matters. E.g. assigning a reference attribute can only be made if the new value refers to an instance that belongs to the same class or a subclass of the initial value of that attribute.

Some types of expressions return a value referring to an a class or instance in the Alan source. Examples include an identifier bound to a parameter allowing instances and a reference attribute.

Event is a set of statements that can be scheduled to execute with a specified delay. Each reference to an identifier of an Event is of course of the Event type. Events can be referenced by attributes and any reference to such an attribute is of Event type.

Expressions of Event type can be used in Schedule and Cancel statements.

A Set is a collection of values that may be referenced as a single value, but also investigate, added to and removed from. An example might be a set of cards in a dealt hand, the set of spells that the hero have learned, or the set of numbers guessed so far.

The order of elements in the set is not specified. Each member can only occur once in the same set, but a member can occur in multiple sets. You could for example include one set of numbers (integers) in one set and another set of numbers in another set. It is then possible to investigate the sets and remove all members that are members in both.

The Set type is a compound type since it is not complete without a member type. You can only include members in a set if the type compatibility rules allow it. A Set may include members that are instances or integers.

If the Set includes instances, the subclass compatibility rule applies. All members in the set must inherit from the same class. See the section on type compatibility below.

Assignment and comparisons between values requires the values to be compatible. The three basic types (integer, string and Boolean) are only compatible with themselves.

Values of the Instance type can be compared without restriction, except that there is no notion of lesser or equal, so only equality can be tested. Assignment can be made if the new value is of the same class, or of a subclass, as the attribute or variable that receives the value. This class is normally inferred from the initial value of the declaration.

For example, a reference attribute (an attribute referencing an instance) is inferred to be restricted to instances of the class of its initial value. Any subsequent change of the attribute (setting it to refer to another instance) requires that the new instance be of the same class or a subclass thereof.

These rules ensure that attribute references and other properties are always retained during the execution of the whole game. Thus, it will never cause a run-time error on the player.

Some statements require their arguments to be of a specific type. This is enforced by the compiler. The compatibility rules apply here also, given that the required type is given by the statement itself.

Examples include the conditional If statement, that requires a Boolean value (or expression) to test, and the Use statement, which requires references to instances that are subclasses of the predefined class actor.

Every instance must inherit from a class (see Sect. 4.5). Furthermore, user-defined classes must also inherit from other classes. A class or an instance inheriting from a class will get all properties of that class. All properties explicitly declared in a class or instance inheriting from another class will extend, override or complement those properties as specified in the original, parent, class. This way, you can easily create new classes by extending existing ones.

You specify which class another class or an instance inherits from using a clause following the grammar:

For example:

and

The base class entity represents the lowest denominator of all instances. All other predefined classes inherit from entity. So adding a property to entity will add it to every instance.

Entities cannot have an initial location, nor can they be located anywhere. On the other hand, they can be considered to be available everywhere. They are not described when encountered. They can only be shown by explicitly executing a Describe statement.

So, if you want an instance to always be available but invisible, create an instance of entity. It is also possible to create subclasses of entity. Instances of such classes will follow the same rules.

Thing is a predefined subclass of entity that adds the property of having a location. This means that they can have an initial location and be located at locations and into containers. They will, however not show up in descriptions or listings, but the player can refer to and interact with them. They can be described by explicitly executing a Describe statement.

Creating an instance of thing is a good choice if you want an invisible instance that should only be available at particular locations, or under specific circumstances.

Objects are instances inheriting directly or indirectly from the predefined class object. Objects are all the things that can be manipulated by the player. They can be picked up, examined and thrown away (if the author has allowed it). In addition to the properties inherited from thing, any present object will by default, be described when the player enters a location or otherwise encounters it.

The predefined class actor is intended for providing so called NPCs, non-player characters, in your game. Like the player, they can move around but to do this they have to be scripted, i.e. programmed with some behaviour using scripts.

An instance inheriting from the actor class will be described when encountered. Actors can be located, as can any thing, but not be inside a container. In addition, they can have scripts.

Actors also exhibit special behaviour when they are described, e.g. when they are encountered. If an actor is executing a Script with a Description, (see SCRIPTs) this description will be used instead of the one declared in the description clause.

A location is a declaration of a place (a “room”) in the game that (normally) can be visited by the player, and have objects lying around, etc. In fact, the map of your game is a set of interconnected locations. A location is any instance inheriting directly or indirectly from the predefined class location. Inheriting from location implies the following semantic properties:

When a location is described (for example when entering it) it is presented with a heading (the location name), the description (in the Description clause) followed by descriptions of any present objects and actors not already, explicitly, described (using a Describe statement) in the description.

An interesting property of locations is that a location can be located at another, both initially and during run-time. The result of having such nested locations is that all things present at the “outer” location are also present in the inner. This can be used in multiple levels to allow access to sky, ground and other scenery items available at many locations at once. It can also be used for grouping locations into sets of similar locations and for implementing vehicles.

The classes literal, string and integer cannot be instantiated explicitly. Instead, you might say that they are implicitly instantiated when the player inputs a literal. For example:

The second parameter (see Chapter 15) in this player command is the integer 12. This parameter is automatically considered an instance of the predefined class integer.

It is possible to add Verbs to literal and its sub-classes. This way it is possible to create verbs that take strings and integers as parameters.

A property can be inherited from the parent of the class or instance. It is not necessary to repeat the declaration in the inheriting class or instance if it should retain its inherited value. Each inherited property may be amended or overridden by specifying it also in the declaration of the inheriting class or instance according to the following table.

The table also show which properties are inherited separately from the parent. E.g. you can override the Description but keep the description check, or even add another (since they are accumulated). You cannot override the Limits of a container and keep the Header section since the Container property is overridden in its entirety.

In an inheriting class, you can also add new properties. More attributes, Verbs, Exits and Scripts can be added to those already present through the inheritance.

The properties available for use in classes, and thus also for instances, are described in detail in the following sections. In general, all of these can be mixed freely, however, some semantic restrictions apply as to when a particular property is legal or not.

Where an instance will be located when the game starts is set using an optional WHERE clause. If no such clause is used the instance will have no location. An instance without location is not present (in the view of the player) in the game until it is moved somewhere by a Locate statement.

Only the At what and In what forms of the WHERE construct (see Chapter 24) are allowed when describing the initial location of an instance.

An instance inheriting from location cannot have an initial location that is In something, but it can be At some other location, creating a nesting of locations.

By default, the identifier (“author name”) of an instance is also the name shown to the player, and by which he will be able to refer to it. Normally you would want to override this with more elaborate and alternative names. You can do that using the Name clause.

The Name clause consists of a list of identifiers optionally followed by a full stop.

The identifiers given in the Name clause are used when the instance is presented to the player, and the player can use them in his commands to refer to the instance. For example:

The use of a quoted identifier in the last example causes the name to be a single string of text. (See Chapter 29 for more details.) This works fine for locations, since the player usually does not need to refer to them in his commands; but a more sophisticated mechanism is available for things which the player needs to interact with (i.e. things, objects and actors).

In this example, the name is a sequence of words. The semantics of this declaration is that the word “chair” is a noun and “little” and “wooden” become adjectives. When the player wants to refer in a command to the object with the author name (identifier) chair3, he may use just “chair” if it’s the only accessible object with “chair” as its noun, or he may distinguish between multiple chairs by also providing one or more adjectives to be more precise about which chair he means.

It is possible to give an instance multiple names by listing a number of Name clauses. Each clause will define adjectives and a noun, as described above. As a result, the player can use any of those names to refer to the object. For example:

This would allow the player to refer to the object using either ‘rusty rod’ or ‘dynamite’. (Or, as a side effect, even ‘rusty dynamite’.) The first Name clause is used for building a default description, if necessary (see Sect. 13.7).

The letter case used in the original words is preserved in the adventure output, but player input will always be matched without taking into account letter case (i.e. case-insensitively). This allows you, for example, to give capitalized names to people actors, which would then be shown correctly in the output.

In player input, it is often handy and natural to refer to items using pronouns, such as “it”, “them” or “her”. Alan provides a means to define which pronouns each instance can be associated with.

The effect of associating a pronoun with an instance is that the player can refer to that instance explicitly in one command and then in a subsequent command use that pronoun to refer to it again. Assume the player input:

If the priest has been associated with the pronoun “him” and the bible with the pronoun “it”, the next command could be:

Pronouns are inherited as any other property, but are overridden as soon as a Pronoun clause is present.

An attribute is a labelled value that instances have. Attributes declarations are placed either inside a class definition (in which case they will apply to all instances of that class or any of its sub-classes) or inside an instance declaration (in which case only that instance will have those attributes, unless it’s overriding inherited attributes with new values). An attribute declaration, or a set of declarations, is introduced using one of the keywords:

And the actual declaration of an attribute follows the structure:

An attribute can be of Boolean (having truth values), numeric, string, event, instance or set type. The type of an attribute is automatically inferred from the type of its initial value.

Combining the keywords with well chosen attribute names can give natural reading to your attributes:

If you want some attributes to be present on every instance of a given class, then you must declare them in that class. E.g. to declare a Boolean attribute that will be shared by all instances of the animal class, the following code can be used:

The attribute human will now be available in all instances of the class, without further declarations, and it will be false. If you want the attribute to have a different value in a particular instance, you must declare it specifically in that instance and assign it the desired value, which will be effective only for that instance. You can override the value in a subclass, e.g.:

The attributes of an instance can be initialised using values in the attribute declaration. This is usually sufficient for many situations. For more flexibility, the Initialize clause can be used.

The clause makes it possible to execute arbitrary statements before the game is started. The statements are executed before the Start clause is executed. This enables calculation of more complex initial attribute values to be located within the instance, or class, that requires it. Of course general statements are also allowed so any prerequisites can be catered for.

The current location is set to the Start location, and the current actor is the hero during the execution of all Initialize clauses.

If the Initialize clause is inherited it will accumulate all clauses with clauses from base classes executing before the clause from the subclass. This lets the base classes do their initialisation before the initialisation of the more specialized, class or instance is performed.

The statements in the Description clause should print a description of the instance. These statements are executed when the hero encounters the instance. Depending on which base class the instance inherits from, this can be a location description presented when the hero enters the location or when executing a Look statement. Other possibilities are descriptions of objects and actors. See Chapter 12 for descriptions of what inheriting from the predefined base classes means.

See also Special Statements, concerning the Visits statement.

The syntax for simple descriptions is:

If the Description clause is missing for an instance (and no Description is inherited), the Alan system will supply a default description such as “There is a round ball here.”. If there is a Description clause but it contains no statements, the object will be ‘invisible’, i.e. no description of it will be printed, not even a default one. This can be useful for objects already described by the location description, or for objects with particular properties.

Here are some examples of simple description declarations:

Before executing a Description, you can check for various conditions to be met. A common example is the dark room. If there is no light source present, the description should not be printed. The syntax for such a description is:

You can guard the description with a Check in the same form as with Verb bodies (see Sect. 16.3 for a detailed description of checks). Of course, there are no qualifiers possible here. To be able to separate the checks statement from the actual description statements the keyword Does is required. This is an example of the checks for a dark location:

Note that it does not specify any description statements. This is because the checks and the actual description are inherited separately, as described in Table 2. The actual descriptions are left for the instances.

If multiple Description Checks are available in the inheritance chain, they are all tested and must be met before any description is attempted. So the inheritance of description checks is “additive”.

If any check fails, the description will not be executed. This particularly also implies that the default listings and description of present objects and actors in location instances will not occur either. Note, however, that any events and actor actions will be shown. See Locations below for a description of the default description mechanism for locations.

If neither a check nor any description statements occur after the keyword Description this is a description, but it is empty.

The syntax for articles and forms is:

The optional Definite, Indefinite and Negative Articles and Forms can be used to define how an instance is printed in its definite, indefinite and negative forms. There are two cases for each form, either as an article prepended to the short display form of the instance (its names or Mentioned clause), or a complete form replacing the normal name printing.

Indefinite forms are used in e.g. inventory listings and when presenting instances that have no Description clause. Definitive forms are usually used in messages of the type:

The negative forms are used in standard messages of the type:

Articles and Forms can of course, be inherited.

An instance can also be a container. This is declared by using the Container property clause. The grammar is

For example:

A Container is something that can contain instances. By default, the instances it can contain must be inheriting from the base class object, but by using the Taking clause, you can allow any instances.

Instances with the container property, “inherits” a special, predefined, Boolean attribute, opaque. This attribute can be manipulated in the same way as any other attribute. Its current value indicates if the instances inside the container are visible and accessible or not.

By default, containers expose their content, but by placing the keyword Opaque in the container declaration, you indicate that this container declaration will initially prohibit access to the contained instances. A typical use of this is to prohibit access to contents of closed cases, drawers and boxes. Once open such containers usually reveal the content, which then can be accessed. You can implement such behaviour by modifying the built in opaque attribute. For example:

When an instance with the Container property is encountered during game play, it will be described as usual. By default the contents of the container will be listed unless it is empty or opaque. If the default description has been overridden, the author will have to explicitly decide on how to handle the container aspect and its content.

Verbs declared inside an class or instance are inherited in the same way as other properties. See Sect. 13.10 for a description on how to declare verbs.

The verbs in a class or instance will only be a candidate for execution if the instance bound to a parameter is of the corresponding class, or is the instance. See Sect. 16.7 for a detailed explanation.

Syntax:

The Entered clause is only allowed in instances inheriting from the predefined class location. This clause will be executed whenever any actor enters the location. Game state changes can be made without restriction.

However, the Entered clause is primarily intended for setting up the location in a correct way, not for describing events, actions and states changes. For this the Description clause is recommended.

The Entered clause can also be used to restrict the movements of actors other than the Hero. (The hero’s travels are controlled by Exit checks as described in EXITs).

If some of the statements should only apply to a particular actor, it is possible to test for the Current Actor with a simple If statement.

The actor is located at the location before the clause is executed so Current Location will be the location having the clause.

Entered clauses are inherited and locations can be nested (see Locations). The order of execution is explained by the following table:

This means that the first Entered clause to be executed is the clause in the base class of the outermost location, if any, then moving down the inheritance of the outermost. After that, any parent classes for any intermediate locations are considered in the same way. Finally, running any Entered clauses in the parents of the new location, ending with the clause in the location itself.

To build a traversable world of locations, they must be connected. This is done using Exits. The syntax for an Exit declaration is:

An Exit has a list of identifiers, all of which are considered directional words. I.e. when any of those words is input by the player, he will be located at the location identified as the target of the exit. It is possible to customize the exit using a Check, that must be satisfied to allow passage through the exit, and statements (Does) that will be executed when the player passes through. The checks work as described in Verb CHECKs.

If either of the Check or Does clauses is present, the End Exit is required.

Two interconnected locations might be declared like this:

Exits are only allowed in classes or instances inheriting from the predefined class location.

The Script is the way actors perform things. In a way, it corresponds to what the hero is ordered to do by the player’s typed-in commands.

Every script has an identifier (the id) to identify it. A script is selected by the Use statement. When an actor starts following a script, it will continue with one step after the other, with all the other actors, including the hero, taking turns.

The optional Description allowed in the beginning of a script is used instead of the general description (from the instance declaration) whenever the actor is executing that particular script. If it is not present, the general description is used.

An actor continues executing its script until:

Following a parameter, indicators are allowed in Syntax declarations.

There are two indicators available (multiple and omnipotent):

An example:

This shows the syntax definitions for the verbs take and drop; where take also allows multiple objects. This would make the following inputs possible:

Refer to Chapter 34 for details on multiple parameters references in player’s input (such as objects).

The above declarations would force the interpreter to reject player input like:

This is because the syntax for the verb drop does not allow multiple references, as it doesn’t include the multiple indicator. Another example, this time using the ! indicator:

Even if the robber or the key are not present, it will allow the player to say:

For more information on player inputs, refer to Chapter 34.

Indicators given in one syntax declaration can affect other syntaxes if they have identical beginnings, like:

and

Even if only one of the syntax declarations indicate that the first parameter should allow multiple instances, both syntaxes will actually allow this because they have the same syntax part before the parameter, in this case the verb “put”.

To restrict the types of entities the player may refer to in the place of a parameter, its class can be defined by using explicit test in the syntax declaration.

The following example describes the syntax for a verb that only allows objects as its parameters (this is however also the default, see below).

Each parameter may be restricted to refer only to instances of particular classes or instances with the container property, or numeric or string literals. The statements following the Else will be executed if that restriction is not met, i.e. if the player refers to an instance not belonging to the specified class or classes. The default restriction is object, i.e. if no class restriction is supplied for that parameter identifier the player may only refer to objects at that position in his input.

A more elaborate example of prerequisites for conversation might look like:

You can provide multiple restrictions, even for the same parameter; but if they refer to the same parameter they must be presented in increasingly restrictive order. For example:

References to attributes in the source are only allowed if it can be guaranteed that they exist during run-time. The class restrictions placed on a parameter are used by the compiler to make this guarantee for code executed by player input (verb bodies). The same applies for other semantic restrictions, e.g. you can only use a parameter in a List statement if it has been restricted to having the Container property.

You can use IsA Container to restrict instances to only those entities that are containers (have the Container property).

If there is no restriction for a parameter, it is restricted to the class object.

It is possible to create multiple syntax declarations for the same verb. The semantics of this is that any of the input formats will be accepted and trigger the same verb action. This is a way to define syntactical synonyms, which are useful to allow multiple forms of input for the same action, increasing chances that the player will find the correct form. For example:

The syntaxes must be compatible in the sense that the parameters must be named the same. However, the order of the parameters may differ, they will automatically be mapped as appropriate.

Restrictions are only allowed in the first of such syntax declarations. These restrictions will be applied regardless of which syntax was used.

If no Syntax is defined for a Verb at all, this is handled with one of two default syntaxes according to the two templates below:

The placeholders represent 1) the name of the verb, and 2) the class in which the verb is first encountered.

The first template is used for verbs that are declared globally, i.e. outside of any class or instance. Since these are only applied when no parameters are used, this will effectively work for simple ‘verb-only’ Verbs, such as ‘quit’, ‘look’, ‘save’, etc.

When a Verb declared in an instance or a class has no Syntax counterpart, it automatically receives a default syntax of the common verb/object type corresponding to the second template above. This is a reasonable syntax for many cases and restricts the parameters to instances of the class where the verb was declared. It also implies that the default name for the single parameter is the same as the name of that class, e.g. object, actor, thing, etc. (See Chapter 25 for the implications of this.)

If the player inputs a command following a syntax which requires parameters, the interpreter first determines if the referenced instance is in scope. This is performed even before the restrictions are executed.

There are a number of ways to get an instance into scope:

If the interpreter finds multiple instances matching the input (the set of given adjectives and noun), it will try to disambiguate giving preference to present instances — i.e. at the location of the hero. If there are still multiple candidates left after this, the interpreter will print a message and abort execution of the current command.

When all parameter positions in the syntax have been resolved this way, the restrictions are executed.

Any action from the player usually takes one ‘tick’ in the default simulated game time. Sometimes you want a player command to not consume a ‘tick’, for example administrative commands like ‘help’, ‘score’ etc.

You can achieve this by attaching Meta in front of the verb definition:

If your Verb has multiple definitions (e.g. for various classes) applying Meta to any one of them will make the verb a meta verb, meaning that if the player uses that verb in any context and on any instance, it won’t consume a tick, even if that particular definition did not have the Meta property explicitly expressed. A library might decide that 'score' was a meta verb and there is nothing you, as an author, can do to override that short of editing the library source.

Furthermore, a Meta verb does not trigger evaluation of rules and Events either, so they are genuinely “outside” the game and should only be used with verbs that are not considered part of the players progression inside the game.

A special case is a Verb declared in, or inherited by, the location where the player is currently located. If this verb is used, any checks or body of that verb will be considered before the verbs in the parameters. An example might be a location representing walking on a high wire. Anything dropped at the following location will disappear:

Syntax:

To determine if the action is possible to carry out, the checks in Check are executed. Which checks to run, is determined by the class of the instances bound to the verb by the parameters. All checks in the inheritance tree are tried by starting at the base class. This way, the more general checks are tried first, followed by increasingly more specific checks.

A typical use of Check is to verify if the parameter has a particular property:

If no expression is specified for a Check, that check will always fail, in effect becoming an unconditional Check. This is useful for preventing certain actions, for example at specific locations, since the checks are always executed first:

If any check should fail, the execution of the current verb is interrupted and the statements following the failing check are executed. The user (player) is then prompted for another command. So in the above example, the verb “jump” will always result in “You can’t do that here.” at the location jumpless.

With this in mind, Checks are also used when handling the user input ALL (see Chapter 34 for details on possible player input). The mechanisms for this involve examining all objects at the current location and evaluating all checks for the verb. Any objects that do not pass the checks are not considered for execution. This limits the handling of ALL to executing only the verb bodies of objects that are reasonable, i.e. whose Checks will not fail.

For example assuming the above definition of the verb take and a location containing the objects ball and box, where only the ball is moveable, the player input:

would result in ALL representing only the ball. See Chapter 34 for an explanation of the player view of this.

Syntax:

If all checks succeed, the execution of the verb will be carried out. Multiple verb bodies may be involved. The default order is to execute first the body of any verb declaration for the current location (including verb bodies inherited by it). Each parameter is then examined to find any declarations of that verb for the instance (including inherited verb bodies). These verb bodies are then executed in the order in which the parameters occurred in the Syntax declaration, for each parameter starting with the body in the most basic class. By default, all of the involved verb bodies are executed. This is the most natural order and covers most cases.

In some unfrequent situations, another order may be necessary. By using the qualifiers, Before/After/Only, the author can decide which verb bodies will be executed and in which order (see Verb Qualification below for details).

A simple verb example:

Syntax:

When a Verb is declared within an instance declaration, verb alternatives are allowed. These alternatives are used in conjunction with the Syntax declaration defined for the verb and allow differentiating between the instance occurring at different parameter positions in the input.

When a player inputs a command, each parameter in the syntax (see above) is bound to an actual instance or receives the value of a literal, depending on the specified syntax. To determine which checks to test for, and which verb bodies to execute, the parameters are examined in turn according to the algorithm described in the section Verb Qualification below. Each instance may have different verb bodies executed depending on which position it occurred at (to which parameter it was bound).

For example, assume the following syntax definition:

If used with the delicate_vase, the resulting actions could differ depending on whether it occurs as the direct object (o) or as the indirect object (w). To implement this, the Verb body for break_with should differentiate between the two cases. For each parameter in the Syntax, you may define different actions by supplying a verb alternative for each parameter identifier. The verb declaration could look like:

If no alternative is explicitly specified the verb body will be considered for all positions in the syntax. The compiler will warn for this when it detects a syntax that allows the class or instance to occur at every parameter positions.

Syntax:

The order in which the different verb bodies are executed is normally from the most general to the most specific. But, to allow for local differences (i.e. special handling of the verb at the current location) any definition of the verb in the current location (including inherited verb bodies) are considered first. Then, the verb bodies in the parameters on which the verb was applied are examined (in their order of appearance in the syntax definition) to find and execute their verb definitions. For each parameter, its most general definition is executed first, then verb bodies down the inheritance tree are executed next, ending with any verb body declared in the specific instance bound to that parameter.

In most circumstances, this is the most logical order, but if another order is required, the Verb qualifiers After, Before and Only may be used to alter this behaviour. These qualifiers alter the order of execution, as described in full detail below.

First all parameters are evaluated according to the Syntax restrictions (see Parameter Restrictions). Then, if they passed, the Checks of all verb declarations are evaluated (see Sect. 16.3). Finally the Verb bodies are executed in the normal order, as explained in the following table.

The table above illustrates the normal order of execution of verb bodies and checks. Starting with any base classes to the outermost region (containing location), continuing to the actual instance of that location, as illustrated by the first column. It then continues with any inner regions (second column) and the current location itself (third column). The execution then proceeds to the parameters of the syntax in order (columns four through six), traversing the inheritance tree from the base class to the instance.

Message sections must be declared at the global level, but to make it possible to create high-quality messages, parameters are available in message sections. Which parameters are available vary depending on the message, the details for each message is available in Sect. C.1.

The parameters can be used in the same way as in verb bodies. The names of the parameters are “parameter1”, “parameter2”, etc. The type of the parameters will also vary.

For some messages, a parameter is an instance. In these cases, the instance is always of the predefined entity class. Any attribute available for this class will be available in message sections with instance parameters.

There are various ways to present output to the player: string output, descriptions, printing expressions, listing container content and showing pictures.

The interpreter intersperses your output with spaces whenever needed. This might for example occur between two output strings:

If handled simple-mindedly the two texts would be adjoined and you as an author would need to cater for this. Instead Alan realizes that a space is required between them. This space is automatically inserted by the interpreter during game play. This is also the case if the output from a Say statement is followed by an output string.

However, as in this example, this is not always the intended output. Particularly, if the Say statement terminated the previous sentence, as in the example, we want the full stop to be placed immediately after the output. So, the Alan interpreter will leave out the space between two outputs if the second starts with a period (full stop) followed by a space, or is the single character in the string. This special handling also applies to strings starting with a comma.

Whenever an output statement is executed, the result will be printed on the players terminal with the following important exception: if an output statement is executed at a game location other than the hero’s location, the output won’t be shown. This important feature will relieve the author from the burden of constantly considering what the player will see. It can be used in the following way:

If the hero is inside the house or out in the street, he will get different views of the situation. This feature ensures that the player only sees what is going on at the current location, and allows for easy adaptation to various viewpoints on the events without the need for any special tests. But see Distant Events for a solution in case the hero need to be informed about things happening in other locations.

Alan has some multimedia provisions, although they may not be available on every platform and implementation. The Show statement, presents an image in the output window, and the Play statement plays a sound.

The Alan compiler will always support the multimedia statements, but a particular interpreter might not do so. Most GLK-based interpreters will support them, but other kind of interpreters might too. The game will still play fine, but the multimedia resources will be silently ignored. There is also no way to check for this in your source code. So, don’t rely on them for your story, particularly do not give the player necessary information only through pictures.

Image and sound files are analyzed by the compiler and copied into an Alan v3 resource file (file extension .a3r) that must be distributed with your game file, otherwise they will not be available during game play. The original file will be left untouched.

The format of the resource file follows the standard interactive fiction resource file format “blorb” and supports images of JPEG and PNG types, and sounds in MOD and AIFF formats.

If a resource file is referenced from multiple statements, it will only be copied once. The Alan compiler uses the file extension to determine the media type of the file. The following extensions are recognized: .jpg, .jpeg, .png, .mod, .aif and .aiff.