% InfoLib At Your Fingertips % Roger Firth A quick reference to the Inform Library. Copyright © 2002 Roger Firth . Copying and distribution, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. Version 1.5 (March 2002) The road to brevity is via solecism and imprecision. Library objects --------------- `compass` - A `container` object holding the twelve direction objects `d_obj` `e_obj` `in_obj` `n_obj` `ne_obj` `nw_obj` `out_obj` `s_obj` `se_obj` `sw_obj` `u_obj` `w_obj`. `LibraryMessages` - If defined (between Includes of `Parser` and `VerbLib`), changes standard library messages: Object LibraryMessages with before [; action : "string"; action : "string"; action : switch (lm_n) { value : "string"; value : "string ",(a) lm_o,"."; ... } ... ]; `selfobj` - The default player object. Avoid: use instead the `player` variable, which usually refers to `selfobj`. `thedark` - A pseudo-room which becomes the `location` when there is no light (although the player object is not moved there). Library constants ----------------- In addition to the standard constants `true` (1), `false` (0) and `nothing` (0), the Library defines `NULL` (-1) for an action, property or pronoun whose current value is undefined. User-defined constants ---------------------- Some constants control features rather than represent values. AMUSING_PROVIDED - Activates the `Amusing` entry_point. DEATH_MENTION_UNDO - Offers "UNDO the last move" when the game is over. DEBUG - Activates the debug commands. Headline = "*string*" - **Mandatory**: the game style, copyright information, etc. MANUAL_PRONOUNS - Pronouns reflect only objects mentioned by the player. MAX_CARRIED = *expr* - Maximum number of direct possessions that the player can carry (default 100). MAX_SCORE = *expr* - Maximum game score (default 0). MAX_TIMERS = *expr* - Maximum number of active timers/daemons (default 32). NO_PLACES - The "`OBJECTS`" and "`PLACES`" verbs are not allowed. NUMBER_TASKS = *expr* - Number of `scored` tasks to be performed (default 1). OBJECT_SCORE = *expr* - For taking a `scored` object for the first time (default 4). ROOM_SCORE = *expr* - For visiting a `scored` room for the first time (default 5). SACK_OBJECT = *object* - A `container` object where the game places held objects. Story = "*string*" - **Mandatory**: the name of the story. TASKS_PROVIDED - Activates the task scoring system. USE_MODULES - Activates linking with pre-compiled library modules. WITHOUT_DIRECTIONS - De-activates standard compass directions (bar "IN" and "OUT"). Place alternative directions in the compass. Library variables ----------------- action - The current *action*. actor - The target of an instruction: the player, or an NPC. deadflag - Normally 0: 1 indicates a regular death, 2 indicates that the player has won, 3 or more denotes a user-defined end. inventory_stage - Used by `invent` and `list_together` properties. keep_silent - Normally false; true makes most group 2 actions silent. location - The player's current room; unless that's dark, when it contains `thedark`, `real_location` contains the room. notify_mode - Normally `true`: `false` remains silent when score changes. noun - The primary focus object for the current action. player - The object acting on behalf of the human player. real_location -The player's current room when in the dark. score - The current score. second - The secondary focus object for the current action. self - The object which received a message. (Note: a run-time variable, not a compile-time constant.) sender - The object which sent a message (or `nothing`). task_scores - A byte array holding scores for the task scoring system. the_time - The game's clock, in minutes 0..1439 since midnight. turns - The game's turn counter. wn - The input stream word number, counting from 1. Library routines ---------------- Achieved(*expr*) - A scored task has been achieved. AfterRoutines() - In a group 2 action, controls output of 'after' messages. AllowPushDir() - An object can be pushed from one location to another. Banner() - Prints the game banner. ChangePlayer(*object*,*flag*) - Player assumes the persona of the *object*. If the optional *flag* is *true*, room descriptions include "(as *object*)". CommonAncestor(*object1*,*object2*) - Returns the nearest object which a parental relationship to both *objects*, or `nothing`. DictionaryLookup(*byte_array*,*length*) - Returns address of word in dictionary, or 0 if not found. DrawStatusLine() - Refreshes the status line. GetGNAOfObject(*object*) - Returns gender-number-animation 0..11 of the *object*. HasLightSource(*object*) - Returns `true` if the *object* has light. IndirectlyContains(*parent_object*,*object*) - Returns true if object is currently a child or grand-child or great-grand-child... of the *parent_object*. IsSeeThrough(*object*) - Returns `true` if light can pass through the *object*. Locale(*object*,"*string1*","*string2*") - Describes the contents of object, and returns their number. After objects with own paragraphs, the rest are listed preceded by *string1* or *string2*. LoopOverScope(*routine*,*actor*) - Calls *routine*(*object*) for each *object* in scope. If the optional *actor* is supplied, that defines the scope. MoveFloatingObjects() - Adjusts positions of game's `found_in` objects. NextWord() - Returns the next dictionary word in the input stream, incrementing *wn* by one. Returns `false` if the word is not in the dictionary, or if the input stream is exhausted. NextWordStopped() - Returns the next dictionary word in the input stream, incrementing `wn` by one. Returns `false` if the word is not in the dictionary, -1 if the input stream is exhausted. NounDomain(*object1*,*object2*,*type*) - Performs object parsing; see also ParseToken(). ObjectIsUntouchable(*object*,*flag*) - Tests if there is a barrier - a container object which is not open - between player and object. Unless the optional flag is true, outputs "You can't because ... is in the way". Returns true is a barrier is found, otherwise false. OffersLight(*object*) - Returns `true` if the object offers light. ParseToken(*type*,*value*) - Performs general parsing; see also `NounDomain()`. PlaceInScope(*object*) - Used in an `add_to_scope` property or `scope=` token to put the *object* into scope for the parser. PlayerTo(*object*,*flag*) - Moves the player to *object*. Prints its description unless optional *flag* is 1 (no description) or 2 (as if walked in). PrintOrRun(object,property,flag) - If *object.property* is a string, output it (followed by a newline unless optional flag is true), and return *true*. If it's a routine, run it and return what the routine returns. PronounNotice(*object*) - Associates an appropriate pronoun with the *object*. PronounValue('*pronoun*') - Returns the object to which '`it`' (or '`him`', '`her`', '`them`') currently refers, or `nothing`. ScopeWithin(*object*) - Used in an `add_to_scope` property or `scope=` token to put the contents of the object in scope for the parser. SetPronoun('*pronoun*',*object) - Defines the *object* to which a given *pronoun* refers. SetTime(*expr1*,*expr2*) - Sets `the_time` to *expr1* (in mins 0..1439 since midnight), running at *expr2* (positive: expr2 minutes pass each turn; negative: expr2 turns take one minute; zero: time stands still). StartDaemon(*object*) - Starts the *object*'s daemon. StartTimer(*object*,*expr*) - Starts the *object*'s timer, initialising its `time_left` to *expr. The object's `time_out` property will be called after that number of turns have elapsed. StopDaemon(*object*) - Stops the *object*'s daemon. StopTimer(object) - Stops the *object*'s timer. TestScope(*object*,*actor*) - Returns `true` if the object is in scope, otherwise `false`. If the optional *actor* is supplied, that defines the scope. TryNumber(*expr*) - Parses word *expr* in the input stream as a number, recognising decimals, also English words one..twenty. Returns the number 1..10000, or -1000 if the parse fails. UnsignedCompare(*expr1*,*expr2*) - Returns -1 if *expr1* is less than *expr2*, 0 if *expr1* equals *expr2*, and 1 if *expr1* is greater than *expr2*. Both expressions are unsigned, in the range 0..65535. WordAddress(*expr*) - Returns a byte array contains the raw text of word *expr* in the input stream. WordInProperty(word,object,property) - Returns `true` if the dictionary *word* is listed in the *property* values for the *object*. WordLength(*expr*) - Returns the length of word *expr* in the input stream. WriteListFrom(*object*,*expr*) - Outputs a list of *object* and its siblings, in the given style, an *expr* formed by adding any of: `ALWAYS_BIT`, `CONCEAL_BIT`, `DEFART_BIT`, `ENGLISH_BIT`, `FULLINV_BIT`, `INDENT_BIT`, `ISARE_BIT`, `NEWLINE_BIT`, `PARTINV_BIT`, `RECURSE_BIT`, `TERSE_BIT`, `WORKFLAG_BIT`. YesOrNo() - Returns `true` if the player types "YES", false for "NO". ZRegion(*arg*) - Returns the type of its *arg*: 3 for a string address, 2 for a routine address, 1 for an object number, or 0 otherwise.