This file is part of the TADS 2 Author’s Manual.
Copyright © 1987 - 2002 by Michael J. Roberts. All rights reserved.
Edited by NK Guy, tela design.

Appendix A

Adventure Definitions (adv.t)

The TADS interpreter provides a great deal of support for text adventure games, but it doesn’t pre-define very much specific to adventures. To make the game author’s job easier, the file adv.t provides definitions for a great many basic objects and classes that underlie most adventure games. These classes are very general, and most games will customize them further, but they vastly reduce the amount of work required to write a game. This section describes these classes, what they do, and how to use them to write a game.

Note that in addition to everything listed in the following pages, adv.t also defines the articles “a,” “an,” and “the.”

These definitions become part of your game when you include the standard adventure definitions file adv.t in your source file. You can, of course, omit these definitions and rewrite your own from scratch if you’re feeling ambitious. Or, if you’re not feeling quite that ambitious but want to try something else you can also substitute an alternative TADS library file, such as Dave Baggett’s WorldClass, Kevin Forchione’s Alt, Tenthstone’s Pianosa or Whizzard’s wadv.

Note, however, that this appendix provides only a partial description of each object class in adv.t. For a more complete understanding of how they work please consult the adv.t file itself. It’s fully commented, and reading the source code is always a good way to learn the details.

Objects, Classes, and Functions

This section lists the objects and functions defined in the standard adventure definitions file adv.t.

The descriptions of the objects indicate the object’s superclass or superclasses. For complete information on an object, you need to refer to the description of its superclasses as well. The descriptions also indicate the main properties defined in the object; in customizing the object, you will generally need to override one or more of these properties. For example, most descendants of thing will specify an sdesc to provide the object with a name.

The function descriptions provide information on how to call the functions, what they do, and what they return.

For clarity, the objects are described in inheritance order; that is, the lower-level (parent) classes are described first, then the descendants of those classes, then the descendants of those, and so on. (This is the same order in which they appear in adv.t.)


inputline: function: A simple cover function for the built-in function input(). This cover function switches to the ‘TADS-Input’ font when running in HTML mode, so that input explicitly read through this function appears in the same input font that is used for normal command-line input. Introduced with adv.t 2.?.


_rand: function(x) A modified version of the built-in random number generator, which may improve upon the standard random number generator’s statistical performance in many cases. To use this replacement, simply call _rand instead of rand in your code. Introduced with adv.t 2.?.


initRestart(param): function. This function is used when adv.t calls the restart() built-in function to start the game over from the beginning. The initRestart() in adv.t simply sets the property global.restarting to true. Your game can inspect this flag in the init() function (or elsewhere) to take a different course of action when restarting a game than when starting up for the first time. The parameter is not used by adv.t implementation of the function, but if you replace the initRestart function defined in adv.t, you might find the parameter useful for passing information through the restart.

The “restart” verb passes a pointer to the initRestart function when it calls the restart() built-in function. This causes initRestart() to be invoked after the game has been restarted, but before init(). Note that the call to restart() passes global.initRestartParam as the parameter to the initRestart function. If you replace initRestart() with your own function, and you need to pass some information to this function, simply store the necessary information in global.initRestartParam at any time before restarting, and the information will automatically be passed to initRestart() when it’s invoked.


checkDoor: function(d, r) If the door d is open, this function silently returns the room r. Otherwise, it prints a message (“The door is closed.”) and return nil.


checkReach: function(loc, actor, v, obj) Determines whether the object obj can be reached by actor in location loc, using the verb v. This routine returns true if obj is a special object (numObj or strObj), if obj is in actor’s inventory or actor’s location, or if it’s in the ‘reachable’ list for loc.


isIndistinguishable: function(obj1, obj2) Returns true if the two objects are indistinguishable for the purposes of listing. The two objects are equivalent if they both have the isEquivalent property set to true, they both have the same immediate superclass, and their other listing properties match (in particular, isworn and (islamp and islit) match for both objects).


itemcnt: function(list ): Returns a count of the “listable” objects in list. An object is listable (that is, it shows up in a room’s description) if its isListed property is true. This function is useful for determining how many objects (if any) will be listed in a room’s description.


sayPrefixCount: function(cnt) This function displays a count (suitable for use in listcont when showing the number of equivalent items. We display the count spelled out if it’s a small number, otherwise we just display the digits of the number.


listcontgen: function(obj, flags, indent) This is a general-purpose object lister routine; the other object lister routines call this routine to do their work. This function can take an object, in which case it lists the contents of the object, or it can take a list, in which case it simply lists the items in the list.

The flags parameter specifies what to do. LCG_TALL makes the function display a “tall” listing, with one object per line; if LCG_TALL isn’t specified, the function displays a “wide” listing, showing the objects as a comma-separated list. When LCG_TALL is specified, the indent parameter indicates how many tab levels to indent the current level of listing, allowing recursive calls to display the contents of listed objects. LCG_CHECKVIS makes the function check the visibility of the top-level object before listing its contents. LCG_RECURSE indicates that we should recursively list the contents of the objects we list; we’ll use the same flags on recursive calls, and use one higher indent level. To specify multiple flags, combine them with the bitwise-or (|) operator.


listcont: function(obj ): This function displays the contents of an object, separated by commas. The thedesc properties of the contents are used. It is up to the caller to provide the introduction to the list (usually something to the effect of “The box contains” is displayed before calling listcont) and finishing the sentence (usually by displaying a period). An object is listed only if its isListed property is true. If there are multiple indistinguishable items in the list, the items are listed only once (with the number of the items).


nestlistcont: function(obj, depth) This function will produce a nested listing of the contents of obj. It will recurse down into the objects contents until the list is exhausted. An object’s contents are listed only if they are considered visible by the normal visibility rules. The depth parameter is used to control the tabbing of the listing: an initial value of 1 will produce a listing with indented top-level contents, which is normally what you want, but 0 might also be desirable desirable in certain cases.


showcontcont: function(obj) List the contents of the object, plus the contents of any fixeditems contained by the object. A complete sentence is shown. This is an internal routine used by listcontcont and listfixedcontcont.


listfixedcontcont: function(obj ): List the contents of the contents of any fixeditem objects in the contents list of the object obj. This routine makes sure that all objects that can be taken are listed somewhere in a room’s description. This routine recurses down the contents tree, following each branch until either something has been listed or the branch ends without anything being listable. This routine displays a complete sentence, so no introductory or closing text is needed.


listcontcont: function(obj ): This function lists the contents of the contents of an object. It displays full sentences, so no introductory or closing text is required. Any item in the contents list of the object obj whose contentsVisible property is true has its contents listed. An Object whose isqcontainer or isqsurface property is true will not have its contents listed.


scoreStatus: function(parm ): This function simply calls setscore() with the same arguments. All other calls to setscore() in adv.t have been replaced by calls to scoreStatus(), which makes it easy to provide a new scoring format simply by using the replace keyword to substitute your own implementation of scoreStatus() for the one in adv.t. Also, note scoreFormat below.


Added: TADS 2.5.2.

The way that adv.t displays the status line was changed slightly in version 2.5.2, in order to simplify coding of special formats. A new function, scoreFormat(), is now responsible for formatting the string to display in the right half of the status line. scoreFormat() takes the current score and the current turn counter as arguments, and returns a string to display in the right half of the status line. The default implementation in adv.t simply returns a string consisting of the score, a slash (‘/’), and the turn count, which provides the same format that adv.t has traditionally used for the status line.

The older function scoreStatus() calls scoreFormat() to generate the display. In addition, the code in room.statusLine that generates the HTML version of the status line now calls scoreFormat() as well. This makes scoreFormat() the single point in adv.t where the right half of the status line is formatted.

The advantage of this new mechanism is that you can customize the display of the right half of the status line for both text-only and HTML-enabled games simply by replacing the scoreFormat() function.

Of course, HTML-enabled games are not limited to using the traditional status line display; if you want a completely custom status line display when running under an HTML-enabled interpreter, you can replace adv.t's room.statusLine and generate your own <BANNER> display. The scoreFormat() mechanism, however, is convenient when you simply want to customize the right half of the status line, but still use the traditional single-line status format.


turncount: function(parm ): This function can be used as a daemon (normally set up in the init function) to update the turn counter after each turn. This routine increments global.turnsofar, and then calls setscore to update the status line with the new turn count.


addweight: function(list ): Adds the weights of the objects in list and returns the sum. The weight of an object is given by its weight property. This routine includes the weights of all of the contents of each object, and the weights of their contents, and so forth.


addbulk: function(list ): This function returns the sum of the bulks (given by the bulk property) of each object in list. The value returned includes only the bulk of each object in the list, and not of the contents of the objects, as it is assumed that an object does not change in size when something is put inside it. You can easily change this assumption for special objects (such as a bag that stretches as things are put inside) by writing an appropriate bulk method for that object.


incscore: function(amount ): Adds amount to the total score, and updates the status line to reflect the new score. The total score is kept in global.score. Always use this routine rather than changing global.score directly, since this routine ensures that the status line is updated with the new value.


initSearch: function. Initializes the containers of objects with a searchLoc, underLoc, and behindLoc by setting up searchCont, underCont, and behindCont lists, respectively. You should call this function once in your preinit (or init, if you prefer) function to ensure that the underable, behindable, and searchable objects are set up correctly.


reachableList: function(obj) Returns a list of all the objects reachable from a given object. That is, if the object is open or is not an openable, it returns the contents of the object, plus the reachableList result of each object; if the object is closed, it returns an empty list.


visibleList: function(obj, actor) This function is similar to reachableList, but returns the list of objects visible within a given object.


numbered_cleanup: function(obj) This function is used as a fuse to delete objects created by the numberedObject class in reponse to calls to its newNumbered method. Whenever that method creates a new object, it sets up a fuse call to this function to delete the object at the end of the turn in which it created the object.


mainRestore: function(fname) Restore a saved game. Returns true on success, nil on failure. If the game is restored successfully, we’ll update the status line and show the full description of the current location. The restore command uses this function; this can also be used by initRestore (which must be separately defined by the game, since it’s not defined in adv.t).


switchPlayer: function(newPlayer) Switch the player character to a new actor. This function uses the parserSetMe() built-in function to change the parser’s internal record of the player character object, and in addition performs some necessary modifications to the outgoing and incoming player character objects. First, because the player character object is by convention never part of its room’s contents list, we add the outgoing actor to its location’s contents list, and remove the incoming actor from its location’s contents list. Second, we remove the vocabulary words “me” and “myself” from the outgoing object, and add them to the incoming object.


numberedObject: object This class can be added to a class list for an object to allow it to be used as a generic numbered object. You can create a single object with this class, and then the player can refer to that object with any number. For example, you can create a single “button” object that the player can refer to with “button 100” or “button 1000” or any other number. If you want to limit the range of acceptable numbers, override the num_is_valid method so that it displays an appropriate error message and returns nil for invalid numbers. If you want to use a separate object to handle references to the object with a plural (“look at buttons”), override newNumberedPlural to return the object to handle these references; by default, the original object is used to handle plurals.


nestedroom: room. A special kind of room that is inside another room; chairs and some types of vehicles, such as inflatable rafts, fall into this category. Note that a room can be within another room without being a nestedroom, simply by setting its location property to another room. The nestedroom is different from an ordinary room, though, in that it’s an “open” room; that is, when inside it, the actor is still really inside the enclosing room for purposes of descriptions. Hence, the player sees “Laboratory, in the chair.” In addition, a nestedroom is an object in its own right, visible to the player; for example, a chair is an object in a room in addition to being a room itself.

The property statusPrep displays an appropriate preposition for status line displays while the player is in the nested room. The property outOfPrep displays the correct preposition when leaving the nested room. The default values are statusPrep = "in" and outOfPrep = "out of". The class beditem provides default values of "on" and "out of" instead. If you’re defining new subclasses of nestedroom, you can override these properties to provide the most appropriate messages for the subclasses.


chairitem: fixeditem, nestedroom, surface. Acts like a chair: actors can sit on the object. While sitting on the object, an actor can’t go anywhere until standing up, and can only reach objects that are on the chair and in the chair’s reachable list. By default, nothing is in the reachable list. Note that there is no real distinction made between chairs and beds, so you can sit or lie on either; the only difference is the message displayed describing the situation.


beditem: chairitem. This object is the same as a chairitem, except that the player is described as lying on, rather than sitting in, the object.


floatingItem: object This class doesn’t do anything apart from mark an object as having a variable location property. It is necessary to mark all such items by making them a member of this class, so that the objects are added to global.floatingList, which is necessary so that floating objects are included in validDoList and validIoList values (see the deepverb class for a description of these methods).


thing: object. The basic class for objects in a game. The property contents is a list that specifies what is in the object; this property is automatically set up by the system after the game is compiled to contain a list of all objects that have this object as their location property. The contents property is kept consistent with the location properties of referenced objects by the moveInto method; always use moveInto rather than directly setting a location property for this reason. The adesc method displays the name of the object with an indefinite article; the default is to display “a” followed by the sdesc, but objects that need a different indefinite article (such as “an” or “some”) should override this method. Likewise, thedesc displays the name with a definite article; by default, thedesc displays “the” followed by the object’s sdesc.

The sdesc simply displays the object’s name (“short description”) without any articles. The pluraldesc simply adds an “s” to the end of the sdesc property. The pluraldesc property is used by listcont() when multiple equivalent objects are present in a list. (for details, see the information on the changes to listcont() described in the section on indistinguishable objects.) The ldesc is the long description, normally displayed when the object is examined by the player; by default, the ldesc displays “It looks like an ordinary sdesc.” The isIn(object) method returns true if the object’s location is the specified object or the object’s location is an object whose contentsVisible property is true and that object’s isIn(object) method is true. Note that if isIn is true, it doesn’t necessarily mean the object is reachable, because isIn is true if the object is merely visible within the location. The thrudesc method displays a message for when the player looks through the object (objects such as windows would use this property). The moveInto(object) method moves the object to be inside the specified object. To make an object disappear, move it into nil.


item: thing. A basic item which can be picked up by the player. It has no weight (0) and minimal bulk (1). The weight property should be set to a non-zero value for heavy objects. The bulk property should be set to a value greater than 1 for bulky objects, and to zero for objects that are very small and take essentially no effort to hold - or, more precisely, don’t detract at all from the player’s ability to hold other objects (for example, a piece of paper).


lightsource: item. A portable lamp, candle, match, or other source of light. The light source can be turned on and off with the islit property. If islit is true, the object provides light, otherwise it’s just an ordinary object.


hiddenItem: object. This is an object that is hidden with one of the hider classes. A hiddenItem object doesn’t have any special properties in its own right, but all objects hidden with one of the hider classes must be of class hiddenItem so that initSearch can find them.


hider: item. This is a basic class of object that can hide other objects in various ways. The underHider, behindHider, and searchHider classes are examples of hider subclasses. The class defines the method searchObj(actor, list), which is given the list of hidden items contained in the object (for example, this would be the underCont property, in the case of an underHider), and “finds” the object or objects. Its action is dependent upon a couple of other properties of the hider object. The serialSearch property, if true, indicates that items in the list are to be found one at a time; if nil (the default), the entire list is found on the first try. The autoTake property, if true, indicates that the actor automatically takes the item or items found; if nil, the item or items are moved to the actor’s location. The searchObj method returns the list with the found object or objects removed; the caller should assign this returned value back to the appropriate property (for example, underHider will assign the return value to underCont).

Note that because the hider is hiding something, this class overrides the normal verDoSearch method to display the message, “You’ll have to be more specific about how you want to search that.” The reason is that the normal verDoSearch message (“You find nothing of interest”) leads players to believe that the object was exhaustively searched, and we want to avoid misleading the player. On the other hand, we don’t want a general search to be exhaustive for most hider objects. So, we just display a message letting the player know that the search was not enough, but we don’t give away what they have to do instead.

The objects hidden with one of the hider classes must be of class hiddenItem.


underHider: hider. This is an object that can have other objects placed under it. The objects placed under it can only be found by looking under the object; see the description of hider for more information. You should set the underLoc property of each hidden object to point to the underHider.

Note that an underHider doesn’t allow the player to put anything under the object during the game. Instead, it’s to make it easy for the game writer to set up hidden objects while implementing the game. All you need to do to place an object under another object is declare the top object as an underHider, then declare the hidden object normally, except use underLoc rather than location to specify the location of the hidden object. The behindHider and searchHider objects work similarly.

The objects hidden with underHider must be of class hiddenItem.


behindHider: hider. This is just like an underHider, except that objects are hidden behind this object. Objects to be behind this object should have their behindLoc property set to point to this object.

The objects hidden with behindHider must be of class hiddenItem.


searchHider: hider. This is just like an underHider, except that objects are hidden within this object in such a way that the object must be looked in or searched. Objects to be hidden in this object should have their searchLoc property set to point to this object. Note that this is different from a normal container, in that the objects hidden within this object will not show up until the object is explicitly looked in or searched.

The items hidden with searchHider must be of class hiddenItem.


fixeditem: thing. An object that cannot be taken or otherwise moved from its location. Note that a fixeditem is sometimes part of a movable object; this can be done to make one object part of another, ensuring that they cannot be separated. By default, the functions that list a room’s contents do not automatically describe fixeditem objects (because the isListed property is set to nil). Instead, the game author will generally describe the fixeditem objects separately as part of the room’s ldesc.


distantItem: fixeditem. This class is essentially the same as a fixeditem, except that it’s intended to be used for objects that are not actually part of a room, but are visible from the room. For example, the player might be able to see a distant mountain from a certain location, even though the player can’t do anything to the mountain (except look at it). A distantItem object can be inspected, but any other attempts to manipulate the object will receive the response “It's too far away.”


readable: item. An item that can be read. The readdesc property is displayed when the item is read. By default, the readdesc is the same as the ldesc, but the readdesc can be overridden to give a different message.


fooditem: item. An object that can be eaten. When eaten, the object is removed from the game, and global.lastMealTime is decremented by the foodvalue property. By default, the foodvalue property is global.eatTime, which is the time between meals. So, the default fooditem will last for one “nourishment interval.”


dialItem: fixeditem. This class is used for making “dials,” which are controls in your game that can be turned to a range of numbers. You must define the property maxsetting as a number specifying the highest number to which the dial can be turned; the lowest number on the dial is always 1. The setting property is the dial’s current setting, and can be changed by the player by typing the command “turn dial to number.” By default, the ldesc method displays the current setting.


switchItem: fixeditem. This is a class for things that can be turned on and off by the player. The only special property is isActive, which is nil if the switch is turned off and true when turned on. The object accepts the commands “turn it on” and “turn it off,” as well as synonymous constructions, and updates isActive accordingly.


room: thing. A location in the game. By default, the islit property is true, which means that the room is lit (no light source is needed while in the room). You should create a darkroom object rather than a room with islit set to nil if you want a dark room, because other methods are affected as well. The isseen property records whether the player has entered the room before; initially it’s nil, and is set to true the first time the player enters. The roomAction(actor, verb, directObject, preposition, indirectObject) method is activated for each player command; by default, all it does is call the room’s location’s roomAction method if the room is inside another room. The lookAround(verbosity) method displays the room’s description for a given verbosity level; true means a full description, nil means only the short description (just the room name plus a list of the objects present). roomDrop(object) is called when an object is dropped within the room; normally, it just moves the object to the room and displays “Dropped.” The firstseen method is called when isseen is about to be set true for the first time (i.e., when the player first sees the room); by default, this routine does nothing, but it’s a convenient place to put any special code you want to execute when a room is first entered. The firstseen method is called after the room’s description is displayed.


darkroom: room. A dark room. The player must have some object that can act as a light source in order to move about and perform most operations while in this room. Note that the room’s lights can be turned on by setting the room’s lightsOn property to true; do this instead of setting islit, because islit is a method which checks for the presence of a light source.


theFloor: beditem, floatingItem. theFloor is a special item that appears in every room (hence the non-standard location property). This object is included mostly for completeness, so that the player can refer to the floor; otherwise, it doesn’t do much. Dropping an item on the floor, for example, moves it to the current room.


Actor: fixeditem, movableActor. A character in the game. The maxweight property specifies the maximum weight that the character can carry, and the maxbulk property specifies the maximum bulk the character can carry. The actorAction(verb, directObject, preposition, indirectObject) method specifies what happens when the actor is given a command by the player; by default, the actor ignores the command and displays a message to this effect. The isCarrying(object) method returns true if the object is being carried by the actor. The actorDesc method displays a message when the actor is in the current room; this message is displayed along with a room’s description when the room is entered or examined. The verGrab(object) method is called when someone tries to take an object the actor is carrying; by default, an actor won’t let other characters take its possessions.

If you want the player to be able to follow the actor when it leaves the room, you should define a follower object to shadow the character, and set the actor’s myfollower property to the follower object. The follower is then automatically moved around just behind the actor by the actor’s moveInto method.

The isHim property should return true if the actor can be referred to by the player as “him,” and likewise isHer should be set to true if the actor can be referred to as “her.” Note that both or neither can be set; if neither is set, the actor can only be referred to as “it,” and if both are set, any of “him,” “her,” or “it” will be accepted.


movableActor: qcontainer. Just like an Actor object, except that the player can manipulate the actor like an ordinary item. Useful for certain types of actors, such as small animals.


follower: Actor. This is a special object that can “shadow” the movements of a character as it moves from room to room. The purpose of a follower is to allow the player to follow an actor as it leaves a room by typing a “follow” command. Each actor that is to be followed must have its own follower object. The follower object should define all of the same vocabulary words (nouns and adjectives) as the actual actor to which it refers. The follower must also define the myactor property to be the Actor object that the follower follows. The follower will always stay one room behind the character it follows; no commands are effective with a follower except for “follow.”

The follower class’s actorAction method executes an exit statement. In addition, the follower class uses dobjGen and iobjGen to provide sensible responses to most verbs.


basicMe: Actor. A default implementation of the Me object, which is the player character. adv.t defines basicMe instead of Me to allow your game to override parts of the default implementation while still using the rest, and without changing adv.t itself. To use basicMe unchanged as your player character, include this in your game: “Me: basicMe;”.

The basicMe object defines all of the methods and properties required for an actor, with appropriate values for the player character. The nouns “me” and “myself” are defined (“I” is not defined, because it conflicts with the “inventory” command’s minimal abbreviation of “i” in certain circumstances, and is generally not compatible with the syntax of most player commands anyway). The sdesc is “you”; the thedesc and adesc are “yourself,” which is appropriate for most contexts. The maxbulk and maxweight properties are set to 10 each; a more sophisticated Me might include the player’s state of health in determining the maxweight and maxbulk properties.


decoration: fixeditem. An item that doesn’t have any function in the game, apart from having been mentioned in the room description. These items are immovable and can’t be manipulated in any way, but can be referred to and inspected. Liberal use of decoration items can improve a game’s playability by helping the parser recognize all the words the game uses in its descriptions of rooms.


distantItem: fixeditem. This is an item that is too far away to manipulate, but can be seen. The class uses dobjGen and iobjGen to prevent any verbs from being used on the object apart from inspectVerb; using any other verb results in the message “It’s too far away.” Instances of this class should provide the normal item properties: sdesc, ldesc, location, and vocabulary.


buttonitem: fixeditem. A button (the type you push). The individual button’s action method doPush(actor), which must be specified in the button, carries out the function of the button. Note that all buttons have the noun “button” defined.


clothingItem: item. Something that can be worn. By default, the only thing that happens when the item is worn is that its isworn property is set to true. If you want more to happen, override the doWear(actor) property. Note that, when a clothingItem is being worn, certain operations will cause it to be removed (for example, dropping it causes it to be removed). If you want something else to happen, override the checkDrop method; if you want to disallow such actions while the object is worn, use an exit statement in the checkDrop method.


obstacle: object. An obstacle is used in place of a room for a direction property. The destination property specifies the room that is reached if the obstacle is successfully negotiated; when the obstacle is not successfully negotiated, destination should display an appropriate message and return nil.


doorway: fixeditem, obstacle. A doorway is an obstacle that impedes progress when it is closed. When the door is open (isopen is true), the user ends up in the room specified in the doordest property upon going through the door. Since a doorway is an obstacle, use the door object for a direction property of the room containing the door.

If noAutoOpen is not set to true, the door will automatically be opened when the player tries to walk through the door, unless the door is locked (islocked = true). If the door is locked, it can be unlocked simply by typing “unlock door”, unless the mykey property is set, in which case the object specified in mykey must be used to unlock the door. Note that the door can only be relocked by the player under the circumstances that allow unlocking, plus the property islockable must be set to true. By default, the door is closed; set isopen to true if the door is to start out open (and be sure to open the other side as well).

otherside specifies the corresponding doorway object in the destination room (doordest), if any. If otherside is specified, its isopen and islocked properties will be kept in sync automatically.


lockableDoorway: doorway. This is just a normal doorway with the islockable and islocked properties set to true. Fill in the other properties (otherside and doordest) as usual. If the door has a key, set property mykey to the key object.


vehicle: item, nestedroom. This is an object that an actor can board. An actor cannot go anywhere while on board a vehicle (except where the vehicle goes); the actor must get out first.


surface: item. Objects can be placed on a surface. Apart from using the preposition “on” rather than “in” to refer to objects contained by the object, a surface is identical to a container. Note: an object cannot be both a surface and a container, because there is no distinction between the two internally.


qsurface: surface. This is a minor variation of the standard surface that doesn’t list its contents by default when the surface itself is described.


container: item. This object can contain other objects. The iscontainer property is set to true. The default ldesc displays a list of the objects inside the container, if any. The maxbulk property specifies the maximum amount of bulk the container can contain.


openable: container. A container that can be opened and closed. The isopenable property is set to true. The default ldesc displays the contents of the container if the container is open, otherwise a message saying that the object is closed.


qcontainer: container. A “quiet” container: its contents are not listed when it shows up in a room description or inventory list. The isqcontainer property is set to true.


lockable: openable. A container that can be locked and unlocked. The islocked property specifies whether the object can be opened or not. The object can be locked and unlocked without the need for any other object; if you want a key to be involved, use a keyedLockable.


keyedLockable: lockable. This subclass of lockable allows you to create an object that can only be locked and unlocked with a corresponding key. Set the property mykey to the keyItem object that can lock and unlock the object.


keyItem: item. This is an object that can be used as a key for a keyedLockable or lockableDoorway object. It otherwise behaves as an ordinary item.


seethruItem:item. This is a class for objects that the player can look through, and is intended for items such as windows or magnifying glasses. If the player looks through the object (with a command such as “look through the window”), the object calls its thrudesc method to display an appropriate description of what the player sees. You should customize this method to display an appropriate message for each seethruItem you create. The default method displays “You can’t see much through the window,” which obviously won’t always be what you want.

Note that seethruItem is not the same as the transparentItem below. The class transparentItem is for objects whose contents are visible, whereas seethruItem is for objects that the player can look through. Use seethruItem for windows, binoculars, magnifying glasses, and other non-containers. Use transparentItem for glass bottles and other transparent containers.


transparentItem: item. An object whose contents are visible, even when the object is closed. Whether the contents are reachable is decided in the normal fashion. This class is useful for items such as glass bottles, whose contents can be seen when the bottle is closed but cannot be reached.


basicNumObj: object. This object provides a default implementation for numObj. To use this default unchanged in your game, include in your game this line: “numObj: basicNumObj”.


basicStrObj: object. This object provides a default implementation for strObj. To use this default unchanged in your game, include in your game this line: “strObj: basicStrObj”.


deepverb: object. A “verb object” that is referenced by the parser when the player uses an associated vocabulary word. A deepverb contains both the vocabulary of the verb and a description of available syntax. The verb property lists the verb vocabulary words; one word (such as 'take') or a pair (such as 'pick up') can be used. In the latter case, the second word must be a preposition, and may move to the end of the sentence in a player’s command, as in “pick it up.” The action(actor) method specifies what happens when the verb is used without any objects; its absence specifies that the verb cannot be used without an object. The doAction specifies the root of the message names (in single quotes) sent to the direct object when the verb is used with a direct object; its absence means that a single object is not allowed. Likewise, the ioAction(preposition) specifies the root of the message name sent to the direct and indirect objects when the verb is used with both a direct and indirect object; its absence means that this syntax is illegal. Several ioAction properties may be present: one for each preposition that can be used with an indirect object with the verb.

The validDo(actor, object, seqno) method returns true if the indicated object is valid as a direct object for this actor. The validIo(actor, object, seqno) method does likewise for indirect objects. The seqno parameter is a “sequence number,” starting with 1 for the first object tried for a given verb, 2 for the second, and so forth; this parameter is normally ignored, but can be used for some special purposes. For example, askVerb does not distinguish between objects matching vocabulary words, and therefore accepts only the first from a set of ambiguous objects. These methods do not normally need to be changed; by default, they return true if the object is accessible to the actor.

The doDefault(actor, prep, indirectObject) and ioDefault(actor, prep) methods return a list of the default direct and indirect objects, respectively. These lists are used for determining which objects are meant by “all” and which should be used when the player command is missing an object. These normally return a list of all objects that are applicable to the current command.

The validDoList(actor, prep, indirectObject) and validIoList(actor, prep, directObject) methods return a list of all of the objects for which validDo would be true. Remember to include floating objects, which are generally accessible. Note that the objects returned by this list will still be submitted by the parser to validDo, so it’s okay for this routine to return too many objects. In fact, this routine is entirely unnecessary; if you omit it altogether, or make it return nil, the parser will simply submit every object matching the player’s vocabulary words to validDo. The reason to provide this method is that it can significantly improve parsing speed when the game has lots of objects that all have the same vocabulary word, because it cuts down on the number of times that validDo has to be called (each call to validDo is fairly time-consuming).

All of the system verbs in adv.t that use the abort statement have been designed in such a fashion that it’s quite easy to augment their behavior with the modify statement. All of the processing other than the abort is not in the doVerb (or action) method but is elsewhere. For example, the action method in saveVerb looks like this:

  action( actor ) =
    self.saveGame( actor );

The saveGame method in saveVerb performs all of the processing related to the actual save function itself. The benefit of this design is that you can modify the saveGame method, and inherit the standard behavior, without having to worry about an abort statement interfering with the order of operations. For example:

  modify restoreVerb
     restoreGame( actor ) =
        // restore the game, and check for success
        if ( inherited.restoreGame( actor ) )
           // re-randomize the puzzle
           "The carnival hawker flashes a mischievous
           smile at you.  \"There's no use trying to
           guess the answer,\" he says.  \"I changed
           around the shells while you were busy
           puzzle.answer := rand( 100 );


darkVerb: deepverb. Dark verb - a verb that can be used in the dark. Travel verbs are all dark verbs, as are system verbs (quit, save, etc.). In addition, certain special verbs are usable in the dark: for example, you can drop objects you are carrying, and you can turn on light sources you are carrying.


Prep: object. A preposition. The preposition property specifies the vocabulary word.

Verbs in the Adventure Definitions File

In the list below, the alternative vocabulary words for the verb are listed with slashes (/) between them; the alternate syntaxes are listed with commas between. When the verb takes objects, the root of the message the parser generates in shown in parentheses following the syntax description; these are prefaced with do, verDo, io, and verIo, as appropriate. See the section on the parser in chapter 4 for details.

againVerb: again/g

askVerb: ask direct-object about indirect-object (AskAbout)

attachVerb: attach direct-object to indirect-object (AttachTo)

attackVerb: attack/kill/hit direct-object with indirect-object (AttackWith)

boardVerb: get in/get into/board direct-object (Board)

breakVerb: break direct-object (Break)

centerVerb: center direct-object (Center)

cleanVerb: clean direct-object (Clean), clean direct-object with indirect-object (CleanWith)

climbVerb: climb direct-object (Climb)

closeVerb: close direct-object (Close)


detachVerb: detach direct-object from indirect-object (Detach)

digVerb: dig/dig in direct-object with indirect-object (DigWith)

drinkVerb: drink direct-object (Drink)

dropVerb: drop/put down direct-object (Drop), drop/put down direct-object on indirect-object (PutOn)

dVerb: down/d

eatVerb: eat direct-object (Eat)

eVerb: east/e

fastenVerb: fasten direct-object (Fasten)

flipVerb: flip direct-object (Flip)

followVerb: follow direct-object (Follow)

getOutVerb: get out/get out of/get off/get off of direct-object (Unboard)

giveVerb: give/offer direct-object to indirect-object (GiveTo)

gothroughVerb: go through/go thru direct-object (Gothrough)

helloVerb: hello/hi/greetings

inspectVerb: inspect/examine/look at/x direct-object (Inspect)

inVerb: in/go in/enter

itallVerb: i_tall

iVerb: inventory/i

iwideVerb: i_wide

jumpVerb: jump, jump direct-object (Jump)

knockVerb: knock/knock on/knock at direct-object (Knock)

lieVerb: lie/lie on/lie in/lie down/lie down on/lie down in direct-object (Lieon)

lockVerb: lock direct-object (Lock), lock direct-object with indirect-object (LockWith)

lookBehindVerb: look behind direct-object (LookBehind)

lookInVerb: look in direct-object (Lookin)

lookThruVerb: look through/look thru direct-object (Lookthru)

lookUnderVerb: look under/look beneath direct-object (LookUnder)

lookVerb: l/look/look around

moveNVerb: move north/move n/push north/push n direct-object (MoveN)
Note: moveSVerb, moveEVerb, moveWVerb, moveNEVerb, moveNWVerb, moveSEVerb, and moveSWVerb are defined similarly.

moveVerb: move direct-object (Move), move direct-object to indirect-object (MoveTo), move direct-object with indirect-object (MoveWith)

nVerb: north/n

neVerb: northeast/ne

nwVerb: northwest/nw

openVerb: open direct-object (Open)

outVerb: out/go out/exit

plugVerb: plug direct-object into indirect-object (PlugIn)

pokeVerb: poke direct-object (Poke)

pullVerb: pull direct-object (Pull)

pushVerb: push direct-object (Push)

putVerb: put/place direct-object in indirect-object (PutIn), put/place direct-object on indirect-object (PutOn)

quitVerb: quit

readVerb: read direct-object (Read)

removeVerb: take off direct-object (Unwear)

restartVerb: restart

restoreVerb: restore direct-object (Restore)

saveVerb: save direct-object (Save)

sayVerb: say direct-object (Say)

scoreVerb: score/status

scriptVerb: script direct-object (Script)

screwVerb: screw direct-object (Screw), screw direct-object with indirect-object (ScrewWith)

searchVerb: search direct-object (Search)

seVerb: southeast/se

showVerb: show direct-object to indirect-object (ShowTo)

sitVerb: sit on/sit in/sit/sit down/sit down in/sit down on direct-object (Siton)

sleepVerb: sleep

standOnVerb: stand on indirect-object (Standon)

standVerb: stand/stand up/get up

sVerb: south/s

switchVerb: switch direct-object (Switch)

swVerb: southwest/sw

takeVerb: take/pick up/get/remove direct-object (Take), take/pick up/get/remove direct-object out of indirect-object (TakeOut), take/pick up/get/remove direct-object off/off of indirect-object (TakeOff)

tellVerb: tell direct-object about indirect-object (TellAbout)

terseVerb: terse

throwVerb: throw/toss direct-object at indirect-object (ThrowAt)

touchVerb: touch direct-object (Touch)

turnOffVerb: turn off/deactivate/switch off direct-object (Turnoff)

turnOnVerb: activate/turn on/switch on direct-object (Turnon)

turnVerb: turn direct-object (Turn), turn direct-object with indirect-object (TurnWith), turn direct-object to indirect-object (TurnTo)

typeVerb: type direct-object on indirect-object (TypeOn)

undoVerb: undo, undo direct-object (Undo)

unfastenVerb: unfasten/unbuckle direct-object (Unfasten)

unlockVerb: unlock direct-object (Unlock), unlock direct-object with indirect-object (UnlockWith)

unplugVerb: unplug direct-object (Unplug), unplug direct-object from indirect-object (UnplugFrom)

unscrewVerb: unscrew direct-object (Unscrew), unscrew direct-object with indirect-object (UnscrewWith)

unscriptVerb: unscript

uVerb: up/u

verboseVerb: verbose

versionVerb: version

waitVerb: wait/z

wearVerb: wear direct-object (Wear)

wVerb: west/w

yellVerb: yell

Prepositions in the Adventure Definitions

Each preposition is shown with its object, and the list of vocabulary words associated with the object, with slashes between equivalent words. Note that the two-word prepositions, such as “down on,” are actually written as one word, such as “downon,” in the definition file, because the parser collapses two-word prepositions into a single word by removing the intervening space.

aboutPrep: about

aroundPrep: around

atPrep: at

behindPrep: behind

betweenPrep: between/in between

dirPrep: north/south/east/west/up/down/northe/ne/northw/nw/southe/se/southw/sw

inPrep: in/into/in to/down in

fromPrep: from

offPrep: off/off of

onPrep: on/onto/on to/down on/upon

outPrep: out/out of

overPrep: over

thruPrep: through/thru

toPrep: to

withPrep: with

I hate definitions.
BENJAMIN DISRAELI, Vivian Grey (1826)

Chapter Twelve Table of Contents Appendix B