Section A7: Library-defined objects and routines

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.