§A3   Library routines

The Inform library files contain about three hundred routines, almost all of which are “private” in the sense that they are difficult for designers to use, not useful anyway, and subject to change without notice as the library is maintained and rewritten. The routines in this appendix are those which are “open to the public”. Designers are encouraged to make use of them.

Achieved(tasknum)

see §22

Signals to the library that task number tasknum has been achieved, so that points may be awarded if it has not been achieved before.
No return value

AfterRoutines()

see §6

This should be called in the action routine, such as TakeSub, of a group 2 action, such as Take, once the action has taken place but before anything is printed. It runs through the after rules as laid out in §6.
Routine returns   true if the action has been interrupted by some other rule, false if not.

AllowPushDir()

see §15

Used only inside the before rule for a PushDir action, this routine signals to the library that the attempt to push an object from one place to another should be allowed.
No return value

Banner()

see §21

Prints the game banner. Normally unnecessary, but should be used soon after if your game suppresses the banner at the Initialise stage.
No return value

ChangePlayer(obj,flag)

see §21

Cause the player at the keyboard to play as the given object obj, which must provide a number property. If the flag is true, then subsequently print messages like “(as Ford Prefect)” in room description headers. This routine, however, prints nothing itself.
No return value

CommonAncestor(obj1,obj2)

see §3

A routine used internally by the library when working out visibilities, and which might as well be available for public use. Returns the nearest object in the object tree which (directly or indirectly) contains both obj1 and obj2, or else returns nothing if no such object exists. For instance if Bedquilt contains bottle and the player is carrying a lamp, the common ancestor of lamp and bottle is Bedquilt.
Routine returns   The common ancestor or nothing.

DictionaryLookup(word,length)

see §34

Takes the word stored character by character in the array word->0, word->1, …, word->(length-1) and looks it up in the story file's dictionary.
Routine returns   The dictionary value (e.g., 't', 'a', 'k', 'e' will return 'take') or zero if the word isn't in the dictionary.

GetGNAOfObject(obj)

see §37

Determines the gender-number-animation of the short name of the given object obj.
Routine returns   The GNA, which is a number between 0 and 11: see table of GNA values in §34.

HasLightSource(obj)

see §19

Determines whether or not obj “has light”, i.e., casts light outward to objects containing obj: see §19 for a more exact definition.
Routine returns   true or false.

IndirectlyContains(obj1,obj2)

see §3

The condition obj2 in obj1 only tests whether obj2 is directly contained in obj1, so that lamp in player would fail if the lamp were in a rucksack carried by the player. IndirectlyContains(player,lamp) would return true. Formally, the test is whether obj2 is a child of obj1, or is a child of a child of obj1, or … and so on. See also the library routine CommonAncestor above.
Routine returns   true or false.

IsSeeThrough(obj)

see §19

Determines whether or not obj “is see-through”, i.e., allows light to pass through it. An object is see-through if it has transparent, or supporter, or enterable (unless it is also a closed container).
Routine returns   true or false.

Locale(obj,tx1,tx2)

see §26

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.
Routine returns   The number of objects printed in the list, possibly zero.

LoopOverScope(R,actor)

see §32

Calls routine R(obj) for each object obj in scope for the given actor. If no actor is given, the actor is assumed to be the player.
No return value

LTI_Insert(position,character)

see §36

Inserts the given character at the given position in the standard library array buffer used to hold the text typed by the player, moving subsequent text along to make room. (This is protected against overflowing the buffer.)
No return value

MoveFloatingObjects()

see §8

“Floating objects” is Inform library jargon for “objects which use found_in to be present in several locations at once”. This routine adjusts the positions of objects across the whole game, ensuring that they are consistent with the current states of the property found_in and the attribute absent, and should be called after any game event which has changed these states.
No return value

NextWord()

see §28

Finds the next dictionary word in the player's input, that is, the word at position wn in the input, moving the word number wn on by one. (The first word is at position 1.)
Routine returns   The dictionary value, or 0 if the word is not in the dictionary or if the word stream has run out, or the constant THEN1__WD if the “word” was a full stop, or the constant COMMA_WORD if it was a comma.

NextWordStopped()

see §28

Finds the next dictionary word in the player's input, that is, the word at position wn in the input, moving the word number wn on by one. (The first word is at position 1.)
Routine returns   The dictionary value, or 0 if the word is not in the dictionary, or the constant THEN1__WD if the “word” was a full stop, or the constant COMMA_WORD if it was a comma, or −1 if the word stream has run out.

NounDomain(o1,o2,type)

This routine is one of the keystones of the parser, but see also ParseToken below: 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: NOUN_TOKEN, for noun, HELD_TOKEN, for held and CREATURE_TOKEN, for creature. The routine parses the best single object name it can from the current position of wn.
Routine returns   nothing for “no match”, or the object matched for a success, 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 GPR_REPARSE if NounDomain returned REPARSE_CODE, thus passing the buck upwards.

ObjectIsUntouchable(obj,flag)

see §32

Determines whether any solid barrier, that is, any container that is not open, lies between the player and obj. If flag is true, this routine never prints anything; otherwise it prints a message like “You can't, because … is in the way.” if any barrier is found.
Routine returns   true if a barrier is found, false if not.

OffersLight(obj)

see §19

Determines whether or not obj “offers light”, i.e., contains light so that its contents are visible to each other: see §19 for a more exact definition.
Routine returns   true or false.

ParseToken(tokentype,tokendata)

see §31

This is the library's own “general parsing routine”, and parses the word stream against the specified token. Because some of these tokens require too much setting-up work to parse, and anyway are not very useful, only two token types are open to the public. If tokentype is ELEMENTARY_TT, then tokendata must have one of the following values: NOUN_TOKEN, HELD_TOKEN, MULTI_TOKEN, MULTIHELD_TOKEN, MULTIEXCEPT_TOKEN, MULTIINSIDE_TOKEN, CREATURE_TOKEN and NUMBER_TOKEN. Alternatively, tokentype can be SCOPE_TT and tokendata must then be a “scope routine”.
Routine returns   GPR_FAIL if parsing fails; GPR_PREPOSITION if a match is made but results in no data; GPR_NUMBER if a match is made, resulting in a number; GPR_MULTIPLE if a match is made, resulting in a multiple object; GPR_REPARSE if the parser has had to rewrite the text being parsed and would now like parsing to begin again from scratch; otherwise, an object which the parser has matched against the text.

PlaceInScope(obj)

see §32

Used in “scope routines” (only) when scope_stage is set to 2 (only). Places obj in scope for the token currently being parsed. No other objects are placed in scope as a result of this, unlike the case of ScopeWithin.
No return value

PlayerTo(obj,flag)

see §21

Moves the player to obj, which can either be a location or something enterable. If flag is false, then run a Look action to print out a room description: but if flag is true, print nothing, and if flag is 2, print a room description but abbreviate it if the room has been visited before.
No return value

PronounNotice(obj)

see §33

Resets the pronouns to the object obj. This means that all pronouns which can match against the object are set equal to it: for instance, “Aunt Jemima” would match 'her' but not 'it', “the grapes” would match 'them' and so on.
No return value

PronounValue(pronoun)

see §33

Finds the current setting of pronoun, which has to be the dictionary value of a legal pronoun in the current language: in the case of English, that means 'it', 'him', 'her' or 'them'.
Routine returns   The setting, or nothing if it is unset.

ScopeWithin(obj)

see §32

Used in “scope routines” (only) when scope_stage is set to 2 (only). Places the contents of obj in scope for the token currently being parsed, and applies the rules of scope recursively so that contents of see-through objects are also in scope, as is anything added to scope.
No return value

SetPronoun(pronoun,obj)

see §33

Changes the current setting of pronoun, which has to be the dictionary value of a legal pronoun in the current language: in the case of English, that means 'it', 'him', 'her' or 'them'.
No return value

SetTime(time,rate)

see §20

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.
No return value

StartDaemon(obj)

see §20

Makes the daemon of the object obj active, so that its daemon routine will be called at the end of every turn.
No return value

StartTimer(obj,period)

see §20

Makes the timer of the object obj active. Its time_left property is set initially to period, then decreased by 1 at the end of every turn in which it was positive. At the end of the turn when it was zero, the timer is stopped and the object's time_out property is called.
No return value

StopDaemon(obj)

see §20

Makes the daemon of the object obj no longer active, so that its daemon routine will no longer be called at the end of every turn.
No return value

StopTimer(obj)

see §20

Makes the timer of the object obj no longer active, so that its time_left routine will no longer be decreased and time_out will not be called as originally scheduled.
No return value

TestScope(obj,actor)

see §32

Tests whether the object obj is in scope to the given actor. If no actor is given, the actor is assumed to be the player.
Routine returns   true or false.

TryNumber(wordnum)

see §28

Tries to parse the word at wordnum as a non-negative number, recognising decimal numbers and English ones from “one” to “twenty”.
Routine returns   −1000 if it fails altogether, or the number, except that values exceeding 10000 are rounded down to 10000.

UnsignedCompare(a,b)

The usual > condition performs a signed comparison, and occasionally, usually when comparing addresses in memory of routines or strings, you need an unsigned comparison.
Routine returns   Returns 1 if a > b, 0 if a = b and −1 if a < b, regarding a and b as unsigned numbers between 0 and 65535. (That is, regarding -1 as 65535, -2 as 65534, …, -32768 as 32768.)

WordAddress(wordnum)

see §28

Find where word number wordnum from what the player typed is stored.
Routine returns   The -> array holding the text of the word.

WordInProperty(word,obj,prop)

see §34

Tests whether word is one of the dictionary values listed in the array given as the property prop of object obj. (Most often used to see if a given dictionary word is one of the name values.)
Routine returns   true or false.

WordLength(wordnum)

see §28

Find the length (number of letters) of the word numbered wordnum from what the player typed.
Routine returns   The length.

WriteListFrom(obj,st)

see §27

Write a list of obj and its siblings, with the style being st. To list all the objects inside X, list from child(X). The style is made up by adding together some of the following constants:

YesOrNo()

Assuming that a question has already been printed, wait for the player to type “yes”, “y”, “no” or “n”.
Routine returns   true for “yes” or “y”, false for “no” or “n”.