Contents
Back
Forward

A7. Library-defined objects and routines

The library defines the following special objects:

compass
To contain the directions. A direction object provides a door_dir property, and should have the direction attribute. A compass direction with enterable, if there is one (which there usually isn't), will have an Enter action converted to Go.

n_obj, ...
Both the object signifying the abstract concept of 'northness', and the 'north wall' of the current room. (Thus, if a player types "examine the north wall'' then the action Examine n_obj will be generated.) Its door_dir property holds the direction property it corresponds to (n_to). The other such objects are s_obj, e_obj, w_obj, ne_obj, nw_obj, se_obj, sw_obj, u_obj, d_obj, in_obj and out_obj. Note that the parser understands "ceiling'' to refer to u_obj and "floor'' to refer to d_obj. (in_obj and out_obj differ slightly, because "in'' and "out'' are verbs with other effects in some cases; these objects should not be removed from the compass.)

thedark
A pseudo-room representing 'being in darkness'. location is then set to this room, but the player object is not moved to it. Its description can be changed to whatever "It is dark here'' message is desired.

selfobj
The default player-object. Code should never refer directly to selfobj, but only to player, a variable whose value is usually indeed selfobj but which might become green_frog if the player is transformed into one.

InformLibrary
Represents the library. You never need to use it, but it might sometimes be the value of sender when a message is received.

InformParser
Represents the parser.

The following routines are defined in the library and available for public use:

Achieved(task)
Indicate the task is achieved (which only awards score the first time).

AddToScope(obj)
Used in an add_to_scope routine of an object to add another object into scope whenever the first is in scope.

AllowPushDir()
Signal that an attempt to push an object from one place to another should be allowed.

CDefArt(obj)
Print the capitalised definite article and short name of obj. Equivalent to print (The) obj;.

ChangeDefault(p,v)
Changes the default value of property p. (But this won't do anything useful to name.)

ChangePlayer(obj,flag)
Cause the player at the keyboard to play as the given object, which must have a number property supplied. If the flag is set to 1, then subsequently print messages like "(as Ford Prefect)'' in room description headers. This routine, however, prints nothing itself.

DefArt(obj)
Print the definite article and short name of obj. Equivalent to print (the) obj;.

DoMenu(text,R1,R2)
Produce a menu, using the two routines given.

EnglishNumber(x)
Prints out x in English (e.g., "two hundred and seventy-seven").

HasLightSource(obj)
Returns true if obj 'has light'.

InDefArt(obj)
Print the indefinite article and short name of obj. Equivalent to print (a) obj;.

Locale(obj,tx1,tx2)
Prints out the paragraphs of room description which would appear if obj were the room: i.e., prints out descriptions of objects in obj according to the usual rules. After describing the objects which have their own paragraphs, a list is given of the remaining ones. The string tx1 is printed if there were no previous paragraphs, and the string tx2 otherwise. (For instance, you might want "On the ledge you can see'' and "On the ledge you can also see''.) After the list, nothing else is printed (not even a full stop) and the return value is the number of objects in the list (possibly zero).

LoopOverScope(R,actor)
Calls routine R(obj) for each object obj in scope. actor is optional: if it's given, then scope is calculated for the given actor, not the player.

NextWord()
Returns the next dictionary word in the player's input, moving the word number wn on by one. Returns 0 if the word is not in the dictionary or if the word stream has run out.

NextWordStopped()
As NextWord, but returning -1 when the word stream has run out.

NounDomain(o1,o2,type)
This routine is one of the keystones of the parser: the objects given are the domains to search through when parsing (almost always the location and the actor) and the type indicates a token. The only tokens safely usable are: 0:
noun
, 1:
held
and 6:
creature
. The routine parses the best single object name it can from the current position of wn. It returns 0 (no match), an object number or the constant REPARSE_CODE (to indicate that it had to ask a clarifying question: this reconstructed the input drastically and the parser must begin all over again). NounDomain should only be used by general parsing routines and these should always return REPARSE_CODE if it does. Note that all of the usual scope and name-parsing rules apply to the search performed by NounDomain.

ObjectIsUntouchable
Determines whether any solid barrier (that is, any container that is not open) lies between the player and obj. If flag is set, this routine never prints anything; otherwise it prints a message like "You can't, because ... is in the way.'' if any barrier is found. Returns true if a barrier is found, false if not.

OffersLight(obj)
Returns true if obj 'offers light'.

PlaceInScope(obj)
Puts obj into scope for the parser.

PlayerTo(place,flag)
Move the player to place. Unless flag is given and is 1, describe the player's surroundings.

PrintShortName(obj)
Print the short name of obj. (This is protected against obj having a meaningless value.) Equivalent to print (name) obj;.

ScopeWithin(obj)
Puts the contents of obj into scope, recursing downward according to the usual scope rules.

SetTime(time,rate)
Set the game clock (a 24-hour clock) to the given time (in seconds since the start of the day), to run at the given rate r: r=0 means it does not run, if r>0 then r seconds pass every turn, if r<0 then -r turns pass every second.

StartDaemon(obj)
Makes the daemon of obj active, so that its daemon routine will be called every turn.

StartTimer(obj,time)
Starts the timer of obj, set to go off in time turns, at which time its time_out routine will be called (it must provide a time_left property).

StopDaemon(obj)
Makes the daemon of obj inactive, so that its daemon routine is no longer called.

StopTimer(obj)
Stops the timer of obj, so that it won't go off after all.

TestScope(obj,actor)
Returns true if obj is in scope; otherwise false. actor is optional: if it's given, then scope is calculated for the given actor, not the player.

TryNumber(wordnum)
Tries to parse the word at wordnum as a number (recognising decimal numbers and English ones from "one'' to "twenty''), returning -1000 if it fails altogether, or the number. Values exceeding 10000 are rounded down to 10000.

UnsignedCompare(a,b)
Returns 1 if a greater than b, 0 if a equals b and -1 if a less than b, regarding a and b as unsigned numbers between 0 and 65535 (or $ffff). (The usual > condition performs a signed comparison.)

WordAddress(n)
Returns the byte array containing the raw text of the n-th word in the word stream.

WordLength(n)
Returns the length of the raw text of the n-th word in the word stream.

WriteListFrom(obj,s)
Write a list of obj and its siblings, with the style being s (a bitmap of options).

YesOrNo()
Assuming that a question has already been printed, wait for the player to type "yes'' or "no'', returning true or false accordingly.

ZRegion(value)
Works out the type of value, if possible. Returns 1 if it's a valid object number, 2 if a routine address, 3 if a string address and 0 otherwise.

Contents / Back / Forward
Chapter I / Chapter II / Chapter III / Chapter IV / Chapter V / Chapter VI / Appendix
Mechanically translated to HTML from third edition as revised 16 May 1997. Copyright © Graham Nelson 1993, 1994, 1995, 1996, 1997: all rights reserved.