inflibqr/inflibqr.md

   1 % InfoLib At Your Fingertips
   2 % Roger Firth <roger@firthworks.com>
   3
   4 A quick reference to the Inform Library.
   5
   6 Copyright © 2002 Roger Firth <roger@firthworks.com>. Copying and
   7 distribution, with or without modification, are permitted in any
   8 medium without royalty provided the copyright notice and this notice
   9 are preserved.
  10
  11 <http://www.firthworks.com/roger/>
  12
  13 Version 1.5 (March 2002)
  14
  15 The road to brevity is via solecism and imprecision.
  16
  17 Library objects
  18 ---------------
  19
  20 `compass` - A `container` object holding the twelve direction objects
  21 `d_obj` `e_obj` `in_obj` `n_obj` `ne_obj` `nw_obj` `out_obj` `s_obj`
  22 `se_obj` `sw_obj` `u_obj` `w_obj`.
  23
  24 `LibraryMessages` - If defined (between Includes of `Parser` and
  25 `VerbLib`), changes standard library messages:
  26
  27     Object  LibraryMessages
  28       with  before [;
  29                 action : "string";
  30                 action : "string";
  31                 action : switch (lm_n) {
  32                     value : "string";
  33                     value : "string ",(a) lm_o,".";
  34                     ...
  35                     }
  36                 ...
  37                 ];
  38
  39 `selfobj` - The default player object. Avoid: use instead the `player`
  40 variable, which usually refers to `selfobj`.
  41
  42 `thedark` - A pseudo-room which becomes the `location` when there is
  43 no light (although the player object is not moved there).
  44
  45 Library constants
  46 -----------------
  47
  48 In addition to the standard constants `true` (1), `false` (0) and
  49 `nothing` (0), the Library defines `NULL` (-1) for an action, property
  50 or pronoun whose current value is undefined.
  51
  52 User-defined constants
  53 ----------------------
  54
  55 Some constants control features rather than represent values.
  56
  57 AMUSING_PROVIDED - Activates the `Amusing` entry_point.
  58
  59 DEATH_MENTION_UNDO - Offers "UNDO the last move" when the game is
  60 over.
  61
  62 DEBUG - Activates the debug commands.
  63
  64 Headline = "*string*" - **Mandatory**: the game style, copyright
  65 information, etc.
  66
  67 MANUAL_PRONOUNS - Pronouns reflect only objects mentioned by the
  68 player.
  69
  70 MAX_CARRIED = *expr* - Maximum number of direct possessions that the
  71 player can carry (default 100).
  72
  73 MAX_SCORE = *expr* - Maximum game score (default 0).
  74
  75 MAX_TIMERS = *expr* - Maximum number of active timers/daemons
  76 (default 32).
  77
  78 NO_PLACES - The "`OBJECTS`" and "`PLACES`" verbs are not allowed.
  79
  80 NUMBER_TASKS = *expr* - Number of `scored` tasks to be performed
  81 (default 1).
  82
  83 OBJECT_SCORE = *expr* - For taking a `scored` object for the first
  84 time (default 4).
  85
  86 ROOM_SCORE = *expr* - For visiting a `scored` room for the first time
  87 (default 5).
  88
  89 SACK_OBJECT = *object* - A `container` object where the game places
  90 held objects.
  91
  92 Story = "*string*" - **Mandatory**: the name of the story.
  93
  94 TASKS_PROVIDED - Activates the task scoring system.
  95
  96 USE_MODULES - Activates linking with pre-compiled library modules.
  97
  98 WITHOUT_DIRECTIONS - De-activates standard compass directions (bar
  99 "IN" and "OUT"). Place alternative directions in the compass.
 100
 101 Library variables
 102 -----------------
 103
 104 action - The current *action*.
 105
 106 actor - The target of an instruction: the player, or an NPC.
 107
 108 deadflag - Normally 0: 1 indicates a regular death, 2 indicates that
 109 the player has won, 3 or more denotes a user-defined end.
 110
 111 inventory_stage - Used by `invent` and `list_together` properties.
 112
 113 keep_silent - Normally false; true makes most group 2 actions silent.
 114
 115 location - The player's current room; unless that's dark, when it
 116 contains `thedark`, `real_location` contains the room.
 117
 118 notify_mode - Normally `true`: `false` remains silent when score
 119 changes.
 120
 121 noun - The primary focus object for the current action.
 122
 123 player - The object acting on behalf of the human player.
 124
 125 real_location -The player's current room when in the dark.
 126
 127 score - The current score.
 128
 129 second - The secondary focus object for the current action.
 130
 131 self - The object which received a message. (Note: a run-time
 132 variable, not a compile-time constant.)
 133
 134 sender - The object which sent a message (or `nothing`).
 135
 136 task_scores - A byte array holding scores for the task scoring
 137 system.
 138
 139 the_time - The game's clock, in minutes 0..1439 since midnight.
 140
 141 turns - The game's turn counter.
 142
 143 wn - The input stream word number, counting from 1.
 144
 145 Library routines
 146 ----------------
 147
 148 Achieved(*expr*) - A scored task has been achieved.
 149
 150 AfterRoutines() - In a group 2 action, controls output of 'after'
 151 messages.
 152
 153 AllowPushDir() - An object can be pushed from one location to another.
 154
 155 Banner() - Prints the game banner.
 156
 157 ChangePlayer(*object*,*flag*) - Player assumes the persona of the
 158 *object*. If the optional *flag* is *true*, room descriptions include
 159 "(as *object*)".
 160
 161 CommonAncestor(*object1*,*object2*) - Returns the nearest object which
 162 a parental relationship to both *objects*, or `nothing`.
 163
 164 DictionaryLookup(*byte_array*,*length*) - Returns address of word in
 165 dictionary, or 0 if not found.
 166
 167 DrawStatusLine() - Refreshes the status line.
 168
 169 GetGNAOfObject(*object*) - Returns gender-number-animation 0..11 of
 170 the *object*.
 171
 172 HasLightSource(*object*) - Returns `true` if the *object* has light.
 173
 174 IndirectlyContains(*parent_object*,*object*) - Returns true if object
 175 is currently a child or grand-child or great-grand-child... of the
 176 *parent_object*.
 177
 178 IsSeeThrough(*object*) - Returns `true` if light can pass through the
 179 *object*.
 180
 181 Locale(*object*,"*string1*","*string2*") - Describes the contents of
 182 object, and returns their number. After objects with own paragraphs,
 183 the rest are listed preceded by *string1* or *string2*.
 184
 185 LoopOverScope(*routine*,*actor*) - Calls *routine*(*object*) for each
 186 *object* in scope. If the optional *actor* is supplied, that defines
 187 the scope.
 188
 189 MoveFloatingObjects() - Adjusts positions of game's `found_in`
 190 objects.
 191
 192 NextWord() - Returns the next dictionary word in the input stream,
 193 incrementing *wn* by one. Returns `false` if the word is not in the
 194 dictionary, or if the input stream is exhausted.
 195
 196 NextWordStopped() - Returns the next dictionary word in the input
 197 stream, incrementing `wn` by one. Returns `false` if the word is not
 198 in the dictionary, -1 if the input stream is exhausted.
 199
 200 NounDomain(*object1*,*object2*,*type*) - Performs object parsing; see
 201 also ParseToken().
 202
 203 ObjectIsUntouchable(*object*,*flag*) - Tests if there is a barrier - a
 204 container object which is not open - between player and object. Unless
 205 the optional flag is true, outputs "You can't because ... is in the
 206 way". Returns true is a barrier is found, otherwise false.
 207
 208 OffersLight(*object*) - Returns `true` if the object offers light.
 209
 210 ParseToken(*type*,*value*) - Performs general parsing; see also
 211 `NounDomain()`.
 212
 213 PlaceInScope(*object*) - Used in an `add_to_scope` property or
 214 `scope=` token to put the *object* into scope for the parser.
 215
 216 PlayerTo(*object*,*flag*) - Moves the player to *object*. Prints its
 217 description unless optional *flag* is 1 (no description) or 2 (as if
 218 walked in).
 219
 220 PrintOrRun(object,property,flag) - If *object.property* is a string,
 221 output it (followed by a newline unless optional flag is true), and
 222 return *true*. If it's a routine, run it and return what the routine
 223 returns.
 224
 225 PronounNotice(*object*) - Associates an appropriate pronoun with the
 226 *object*.
 227
 228 PronounValue('*pronoun*') - Returns the object to which '`it`' (or
 229 '`him`', '`her`', '`them`') currently refers, or `nothing`.
 230
 231 ScopeWithin(*object*) - Used in an `add_to_scope` property or `scope=`
 232 token to put the contents of the object in scope for the parser.
 233
 234 SetPronoun('*pronoun*',*object) - Defines the *object* to which a
 235 given *pronoun* refers.
 236
 237 SetTime(*expr1*,*expr2*) - Sets `the_time` to *expr1* (in mins 0..1439
 238 since midnight), running at *expr2* (positive: expr2 minutes pass each
 239 turn; negative: expr2 turns take one minute; zero: time stands still).
 240
 241 StartDaemon(*object*) - Starts the *object*'s daemon.
 242
 243 StartTimer(*object*,*expr*) - Starts the *object*'s timer,
 244 initialising its `time_left` to *expr. The object's `time_out`
 245 property will be called after that number of turns have elapsed.
 246
 247 StopDaemon(*object*) - Stops the *object*'s daemon.
 248
 249 StopTimer(object) - Stops the *object*'s timer.
 250
 251 TestScope(*object*,*actor*) - Returns `true` if the object is in
 252 scope, otherwise `false`. If the optional *actor* is supplied, that
 253 defines the scope.
 254
 255 TryNumber(*expr*) - Parses word *expr* in the input stream as a
 256 number, recognising decimals, also English words one..twenty. Returns
 257 the number 1..10000, or -1000 if the parse fails.
 258
 259 UnsignedCompare(*expr1*,*expr2*) - Returns -1 if *expr1* is less than
 260 *expr2*, 0 if *expr1* equals *expr2*, and 1 if *expr1* is greater than
 261 *expr2*. Both expressions are unsigned, in the range 0..65535.
 262
 263 WordAddress(*expr*) - Returns a byte array contains the raw text of
 264 word *expr* in the input stream.
 265
 266 WordInProperty(word,object,property) - Returns `true` if the
 267 dictionary *word* is listed in the *property* values for the *object*.
 268
 269 WordLength(*expr*) - Returns the length of word *expr* in the input
 270 stream.
 271
 272 WriteListFrom(*object*,*expr*) - Outputs a list of *object* and its
 273 siblings, in the given style, an *expr* formed by adding any of:
 274 `ALWAYS_BIT`, `CONCEAL_BIT`, `DEFART_BIT`, `ENGLISH_BIT`,
 275 `FULLINV_BIT`, `INDENT_BIT`, `ISARE_BIT`, `NEWLINE_BIT`,
 276 `PARTINV_BIT`, `RECURSE_BIT`, `TERSE_BIT`, `WORKFLAG_BIT`.
 277
 278 YesOrNo() - Returns `true` if the player types "YES", false for "NO".
 279
 280 ZRegion(*arg*) - Returns the type of its *arg*: 3 for a string
 281 address, 2 for a routine address, 1 for an object number, or 0
 282 otherwise.