Appendix A

The TADS run-time system 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.

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.)

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.

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.

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.

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.

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.

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.

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 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.

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.

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."

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.

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.

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.

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.

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)

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)

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)

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

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

helloVerb: hello/hi/greetings

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

inVerb: in/go in/enter

iVerb: inventory/i

jumpVerb: jump, jump direct-object (Jump)

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)

standOnVerb: stand on indirect-object (Standon)

standVerb: stand/stand up/get up

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)

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

sVerb: south/s

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

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

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