appendices/f.rst

   1 ==============================
   2  Appendix F -- Inform library
   3 ==============================
   4
   5 .. |ADD| replace:: **+**
   6
   7 .. The ⊕ symbol doesn't work in LaTeX.
   8
   9 .. default-role:: samp
  10
  11 .. only:: html
  12
  13    .. image:: /images/picL.png
  14       :align: left
  15
  16 .. raw:: latex
  17
  18    \dropcap{l}
  19
  20 ibrary files define Inform's model world, turning a conventional
  21 programming language into a text adventure development system.  Here are
  22 the library constants, variables and routines, the standard object
  23 properties and attributes, the verb grammars and actions.
  24
  25 Library objects
  26 ===============
  27
  28 `compass`
  29   A `container` object holding the twelve direction objects `d_obj e_obj
  30   in_obj n_obj ne_obj nw_obj out_obj s_obj se_obj sw_obj u_obj w_obj`.
  31
  32 `LibraryMessages`
  33   If defined (between Includes of `Parser` and `VerbLib`), changes standard
  34   library messages:
  35
  36   .. only:: html
  37
  38     | `Object LibraryMessages`
  39     |   `with before [;`
  40     |        `{action}: "{string}";`
  41     |        `{action}: "{string}";`
  42     |        `{action}: switch (lm_n) {`
  43     |                `{value}: "{string}";`
  44     |                `{value}: "{string}",`
  45     |                    `(a) lm_o,".";`
  46     |                `...`
  47     |                `}`
  48     |            `...`
  49     |        `];`
  50
  51   .. todo::
  52
  53      Get this to work properly in LaTeX.  Currently get a 'too deeply
  54      nested' error.
  55
  56 `selfobj`
  57   The default player object.  Avoid: use instead the `player` variable,
  58   which usually refers to `selfobj`.
  59
  60 `thedark`
  61   A pseudo-room which becomes the `location` when there is no light
  62   (although the player object is not moved there).
  63
  64 Library constants
  65 =================
  66
  67 In addition to the standard constants `true` (1), `false` (0) and `nothing`
  68 (0), the Library defines `NULL` (-1) for an `{action}`, `{property}` or
  69 `{pronoun}` whose current value is undefined.
  70
  71 `LIBRARY_PARSER`, `LIBRARY_ENGLISH`, `LIBRARY_VERBLIB` and
  72 `LIBRARY_GRAMMAR` are defined to mark the end of inclusion of `Parser.h`,
  73 `English.h`, `VerbLib.h` and `Grammar.h` respectively.
  74
  75 User-defined constants
  76 ======================
  77
  78 Some constants control features rather than represent values.
  79
  80 `AMUSING_PROVIDED`
  81   Activates the `Amusing` entry point.
  82
  83 `COMMENT_CHARACTER = '{char}'`
  84   Introduces a comment line ignored by the parser (default "*").
  85
  86 `DEATH_MENTION_UNDO`
  87   Offers "UNDO the last move" at game end.
  88
  89 `DEBUG`
  90   Activates the debug commands.
  91
  92 `Headline = "{string}"`
  93   **Mandatory**: game style, copyright info, etc.
  94
  95 `MANUAL_PRONOUNS`
  96   Pronouns reflect only objects mentioned by the player.
  97
  98 `MAX_CARRIED = {expr}`
  99   Limit on direct possessions that the player can carry (default 100).
 100
 101 `MAX_SCORE = {expr}`
 102   Maximum game score (default 0).
 103
 104 `MAX_TIMERS = {expr}`
 105   Limit on active timers/daemons (default 32).
 106
 107 `NO_PLACES`
 108   "`OBJECTS`" and "`PLACES`" verbs are barred.
 109
 110 `NO_SCORE`
 111   Game doesn't use scoring.
 112
 113 `NUMBER_TASKS = {expr}`
 114   Number of `scored` tasks (default 1).
 115
 116 `OBJECT_SCORE = {expr}`
 117   For taking a `scored` object for the first time (default 4).
 118
 119 `ROOM_SCORE = {expr}`
 120   For visiting a `scored` room for the first time (default 5).
 121
 122 `SACK_OBJECT = {obj_id}`
 123   A `container` object where the game places held objects.
 124
 125 `START_MOVE = {expr}`
 126   Initial value of turns counter (default 0).
 127
 128 `Story = "{string}"`
 129   **Mandatory**: the name of the story.
 130
 131 `TASKS_PROVIDED`
 132   Activates the task scoring system.
 133
 134 `USE_MODULES`
 135   Activates linking with pre-compiled library modules.
 136
 137 `WITHOUT_DIRECTIONS`
 138   De-activates standard compass directions (bar "`IN`" and "`OUT`").  Place
 139   alternative directions in the `compass`.
 140
 141 Library variables
 142 =================
 143
 144 `action`
 145   The current `{action}`.
 146
 147 `actor`
 148   The target of an instruction: the player, or an NPC.
 149
 150 `deadflag`
 151   Normally 0: 1 indicates a regular death, 2 indicates that the player has
 152   won, 3 or more denotes a user-defined end.
 153
 154 `inventory_stage`
 155   Used by `invent` and `list_together` properties.
 156
 157 `keep_silent`
 158   Normally `false`; `true` makes most :ref:`group 2 actions
 159   <group-2-actions>` silent.
 160
 161 `location`
 162   The player's current room; unless that's dark, when it contains
 163   `thedark`, `real_location` contains the room.
 164
 165 `notify_mode`
 166   Normally `true`: `false` remains silent when score changes.
 167
 168 `noun`
 169   The primary focus object for the current action.
 170
 171 `player`
 172   The object acting on behalf of the human player.
 173
 174 `real_location`
 175   The player's current room when in the dark.
 176
 177 `score`
 178   The current score.
 179
 180 `second`
 181   The secondary focus object for the current action.
 182
 183 `self`
 184   The object which received a message.  (Note: a run-time variable, not a
 185   compile-time constant.)
 186
 187 `sender`
 188   The object which sent a message (or `nothing`).
 189
 190 `task_scores`
 191   A byte array holding scores for the task scoring system.
 192
 193 `the_time`
 194   The game's clock, in minutes 0..1439 since midnight.
 195
 196 `turns`
 197   The game's turn counter.
 198
 199 `wn`
 200   The input stream word number, counting from 1.
 201
 202 .. _library-routines:
 203
 204 Library routines
 205 ================
 206
 207 `Achieved({expr})`
 208   A scored task has been achieved.
 209
 210 `AfterRoutines()`
 211   In a :ref:`group 2 action <group-2-actions>`, controls output of "after"
 212   messages.
 213
 214 `AllowPushDir()`
 215   An object can be pushed from one location to another.
 216
 217 `Banner()`
 218   Prints the game banner.
 219
 220 `ChangePlayer({obj_id,flag})`
 221   Player assumes the persona of the `{obj_id}`.  If the optional `{flag}`
 222   is `true`, room descriptions include "(as `{object}`)".
 223
 224 `CommonAncestor({obj_id1,obj_id2})`
 225   Returns the nearest object which has a parental relationship to both
 226   `{obj_ids}`, or `nothing`.
 227
 228 `DictionaryLookup({byte_array,length})`
 229   Returns address of word in dictionary, or 0 if not found.
 230
 231 `DrawStatusLine()`
 232   Refreshes the status line; happens anyway at end of each turn.
 233
 234 `GetGNAOfObject({obj_id})`
 235   Returns gender-number-animation 0..11 of the `{obj_id}`.
 236
 237 `HasLightSource({obj_id})`
 238   Returns `true` if the `{obj_id}` has light.
 239
 240 `IndirectlyContains({parnt_obj_id,obj_id})`
 241   Returns `true` if `{obj_id}` is currently a child or grand-child or
 242   great-grand-child... of the `{parent_object}`.
 243
 244 `IsSeeThrough({obj_id})`
 245   Returns `true` if light can pass through the `{obj_id}`.
 246
 247 `Locale({obj_id,"string1","string2"})`
 248   Describes the contents of `{obj_id}`, and returns their number.  After
 249   objects with own paragraphs, the rest are listed preceded by `{string1}`
 250   or `{string2}`.
 251
 252 `LoopOverScope({routine_id,actor})`
 253   Calls `{routine_id}({obj_id})` for each `{obj_id}` in scope.  If the
 254   optional `{actor}` is supplied, that defines the scope.
 255
 256 `MoveFloatingObjects()`
 257   Adjusts positions of game's `found_in` objects.
 258
 259 `NextWord()`
 260   Returns the next dictionary word in the input stream, incrementing `wn`
 261   by one.  Returns `false` if the word is not in the dictionary, or if the
 262   input stream is exhausted.
 263
 264 `NextWordStopped()`
 265   Returns the next dictionary word in the input stream, incrementing `wn`
 266   by one.  Returns `false` if the word is not in the dictionary, -1 if the
 267   input stream is exhausted.
 268
 269 `NounDomain({obj_id1,obj_id2,type})`
 270   Performs object parsing; see also `ParseToken()`.
 271
 272 `ObjectIsUntouchable({obj_id,flag})`
 273   Tests whether there is a barrier - a container object which is not open -
 274   between player and `{obj_id}`.  Unless the optional `{flag}` is `true`,
 275   outputs "You can't because ... is in the way".  Returns `true` is a
 276   barrier is found, otherwise `false`.
 277
 278 `OffersLight({obj_id})`
 279   Returns `true` if the `{obj_id}` offers light.
 280
 281 `ParseToken({type,value})`
 282   Performs general parsing; see also `NounDomain()`.
 283
 284 `PlaceInScope({obj_id})`
 285   Used in an `add_to_scope` property or `scope=` token to put the
 286   `{obj_id}` into scope for the parser.
 287
 288 `PlayerTo({obj_id,flag})`
 289   Moves the player to `{obj_id}`.  Prints its description unless optional
 290   `{flag}` is 1 (no description) or 2 (as if walked in).
 291
 292 `PrintOrRun({obj_id,property,flag})`
 293   If `{obj_id.property}` is a string, output it (followed by a newline
 294   unless optional `{flag}` is `true`), and return `true`.  If it's a
 295   routine, run it and return what the routine returns.
 296
 297 `PronounNotice({obj_id})`
 298   Associates an appropriate pronoun with the `{obj_id}`.
 299
 300 `PronounValue('{pronoun}')`
 301   Returns the object to which '`it`' (or '`him`', '`her`', '`them`')
 302   currently refers, or `nothing`.
 303
 304 `ScopeWithin({obj_id})`
 305   Used in an `add_to_scope` property or `scope=` token to put the contents
 306   of the `{obj_id}` in scope for the parser.
 307
 308 `SetPronoun('{pronoun}',{obj_id})`
 309   Defines the `{obj_id}` to which a given pronoun refers.
 310
 311 `SetTime({expr1,expr2})`
 312
 313   Sets `the_time` to `{expr1}` (in mins 0..1439 since midnight), running at
 314   `{expr2}` -
 315
 316   | +ve: `{expr2}` minutes pass each turn;
 317   | -ve: `{-expr2}` turns take one minute;
 318   | zero: time stands still.
 319
 320 `StartDaemon({obj_id})`
 321   Starts the `{obj_id}`\'s daemon.
 322
 323 `StartTimer({obj_id,expr})`
 324   Starts the `{obj_id}`\'s timer, initialising its `time_left` to `{expr}`.
 325   The object's `time_out` property will be called after that number of
 326   turns have elapsed.
 327
 328 `StopDaemon({obj_id})`
 329   Stops the `{obj_id}`\'s daemon.
 330
 331 `StopTimer({obj_id})`
 332   Stops the `{obj_id}`\'s timer.
 333
 334 `TestScope({obj_id,actor})`
 335   Returns `true` if the `{obj_id}` is in scope, otherwise `false`.  If the
 336   optional `{actor}` is supplied, that defines the scope.
 337
 338 `TryNumber({expr})`
 339   Parses word `{expr}` in the input stream as a number, recognising
 340   decimals, also English words one..twenty.  Returns the number 1..10000,
 341   or -1000 if the parse fails.
 342
 343 `UnsignedCompare({expr1,expr2})`
 344   Returns -1 if `{expr1}` is less than `{expr2}`, 0 if `{expr1}` equals
 345   `{expr2}`, and 1 if `{expr1}` is greater than `{expr2}`.  Both
 346   expressions are unsigned, in the range 0..65535.
 347
 348 `WordAddress({expr})`
 349   Returns a byte array containing the raw text of word `{expr}` in the
 350   input stream.
 351
 352 `WordInProperty({word,obj_id,property})`
 353   Returns `true` if the dictionary `{word}` is listed in the `{property}`
 354   values for the `{obj_id}`.
 355
 356 `WordLength({expr})`
 357   Returns the length of word `{expr}` in the input stream.
 358
 359 `WriteListFrom({obj_id,expr})`
 360   Outputs a list of `{obj_id}` and its siblings, in the given style, an
 361   `{expr}` formed by adding any of: `ALWAYS_BIT`, `CONCEAL_BIT`,
 362   `DEFART_BIT`, `ENGLISH_BIT`, `FULLINV_BIT`, `INDENT_BIT`, `ISARE_BIT`,
 363   `NEWLINE_BIT`, `PARTINV_BIT`, `RECURSE_BIT`, `TERSE_BIT`, `WORKFLAG_BIT`.
 364
 365 `YesOrNo()`
 366   Returns `true` if the player types "`YES`", `false` for "`NO`".
 367
 368 `ZRegion({arg})`
 369   Returns the type of its `{arg}` : 3 for a string address, 2 for a routine
 370   address, 1 for an object number, or 0 otherwise.
 371
 372 .. _object-props:
 373
 374 Object properties
 375 =================
 376
 377 Where the `value` of a property can be a routine, several formats are
 378 possible (but remember: embedded "`]`" returns `false`, standalone "`]`"
 379 returns `true`):
 380
 381   | `{property} [; {stmt}; {stmt}; ... ]`
 382   | `{property} [; return {routine_id}(); ]`
 383   | `{property} [; {routine_id}(); ]`
 384   | `{property} {routine_id}`
 385
 386 In this appendix, |ADD| marks an additive property.  Where a `Class` and an
 387 `Object` of that class both define the same property, the value specified
 388 for the `Object` normally overrides the value inherited from the `Class`.
 389 However, if the property is additive then both values apply, with the
 390 Object's value being considered first.
 391
 392 `add_to_scope`
 393   For an object: additional objects which follow it in and out of scope.
 394   The `{value}` can be a space-separated list of `{obj_ids}`, or a routine
 395   which invokes `PlaceInScope()` or `ScopeWithin()` to specify objects.
 396
 397 `after` |ADD|
 398   For an object: receives every `{action}` and `{fake_action}` for which
 399   this is the `{noun}`.  For a room: receives every `{action}` which occurs
 400   here.
 401
 402   The `{value}` is a routine of structure similar to a `switch` statement,
 403   having cases for the appropriate `{actions}` (and an optional `default`
 404   as well); it is invoked after the action has happened, but before the
 405   player has been informed.  The routine should return `false` to continue,
 406   telling the player what has happened, or `true` to stop processing the
 407   action and produce no further output.
 408
 409 `article`
 410   For an object: the object's indefinite article - the default is
 411   automatically "a", "an" or "some".  The `{value}` can be a string, or a
 412   routine which outputs a string.
 413
 414 `articles`
 415   For a non-English object: its definite and indefinite articles.  The
 416   `{value}` is an array of strings.
 417
 418 `before` |ADD|
 419   For an object: receives every `{action}` and `{fake_action}` for which
 420   this is the `{noun}`.  For a room: receives every action which occurs
 421   here.
 422
 423   The `{value}` is a routine invoked before the action has happened.  See
 424   `after`.
 425
 426 `cant_go`
 427   For a room: the message when the player attempts an impossible exit.  The
 428   `{value}` can be a string, or a routine which outputs a string.
 429
 430 `capacity`
 431   For a `container` or `supporter` object: the number of objects which can
 432   be placed in or on it - the default is 100.
 433
 434   For the player: the number which can be carried - `selfobj` has an
 435   initial capacity of `MAX_CARRIED`.
 436
 437   The `{value}` can be a number, or a routine which returns a number.
 438
 439 `d_to`
 440   For a room: a possible exit.  The `{value}` can be
 441
 442   * `false` (the default): not an exit;
 443   * a string: output to explain why this is not an exit;
 444   * a `{room}`: the exit leads to this room;
 445   * a `door` object: the exit leads through this door;
 446   * a routine which should return `false`, a string, a `{room}`, a `door`
 447     object, or `true` to signify "not an exit" and produce no further
 448     output.
 449
 450 `daemon`
 451   The `{value}` is a routine which can be activated by
 452   `StartDaemon({obj_id})` and which then runs once each turn until
 453   deactivated by `StopDaemon({obj_id})`.
 454
 455 `describe` |ADD|
 456   For an object: called before the object's description is output.  For a
 457   room: called before the room's (long) description is output.
 458
 459   The `{value}` is a routine which should return `false` to continue,
 460   outputting the usual description, or `true` to stop processing and
 461   produce no further output.
 462
 463 `description`
 464   For an object: its description (output by `Examine`).
 465
 466   For a room: its long description (output by `Look`).
 467
 468   The `{value}` can be a string, or a routine which outputs a string.
 469
 470 `door_dir`
 471   For a `compass` object (`d_obj`, `e_obj`, ...): the direction in which an
 472   attempt to move to this object actually leads.
 473
 474   For a `door` object: the direction in which this door leads.
 475
 476   The `{value}` can be a directional property (`d_to`, `e_to`, ...), or a
 477   routine which returns such a property.
 478
 479 `door_to`
 480   For a `door` object: where it leads.  The value can be
 481
 482   * `false` (the default): leads nowhere;
 483   * a string: output to explain why door leads nowhere;
 484   * a `{room}`: the door leads to this room;
 485   * a routine which should return `false`, a string, a `{room}`, or `true`
 486     to signify "leads nowhere" without producing any output.
 487
 488 `e_to`
 489   See `d_to`.
 490
 491 `each_turn` |ADD|
 492   Invoked at the end of each turn (after all appropriate daemons and
 493   timers) whenever the object is in scope.  The `{value}` can be a string,
 494   or a routine.
 495
 496 `found_in`
 497   For an object: the rooms where this object can be found, unless it has
 498   the `absent` attribute.  The `{value}` can be
 499
 500   * a space-separated list of `{rooms}` (where this object can be found) or
 501      `{obj_ids}` (whose locations are tracked by this object);
 502   * a routine which should return `true` if this object can be found in the
 503      current location, otherwise `false`.
 504
 505 `grammar`
 506   For an `animate` or `talkable` object: the `{value}` is a routine called
 507   when the parser knows that this object is being addressed, but has yet to
 508   test the grammar.  The routine should return `false` to continue, `true`
 509   to indicate that the routine has parsed the entire command, or a
 510   dictionary word ('`word`' or -'`word`').
 511
 512 `in_to`
 513   See `d_to`.
 514
 515 `initial`
 516   For an object: its description before being picked up.
 517
 518   For a room: its description when the player enters the room.
 519
 520   The `{value}` can be a string, or a routine which outputs a string.
 521
 522 `inside_description`
 523   For an `enterable` object: its description, output as part of the room
 524   description when the player is inside the object.
 525
 526   The `{value}` can be a string, or a routine which outputs a string.
 527
 528 `invent`
 529   For an object: the `{value}` is a routine for outputting the object's
 530   inventory listing, which is called twice.  On the first call nothing has
 531   been output; `inventory_stage` has the value 1, and the routine should
 532   return `false` to continue, or `true` to stop processing and produce no
 533   further output.  On the second call the object's indefinite article and
 534   short name have been output, but not any subsidiary information;
 535   `inventory_stage` has the value 2, and the routine should return `false`
 536   to continue, or `true` to stop processing and produce no further output.
 537
 538 `life` |ADD|
 539   For an `animate` object: receives person-to-person actions (`Answer`,
 540   `Ask`, `Attack`, `Give`, `Kiss`, `Order`, `Show`, `Tell`, `ThrowAt` and
 541   `WakeOther`) for which this is the `{noun}`.  The `{value}` is a routine
 542   of structure similar to a `switch` statement, having cases for the
 543   appropriate `{actions}` (and an optional default as well).  The routine
 544   should return `false` to continue, telling the player what has happened,
 545   or `true` to stop processing the action and produce no further output.
 546
 547 `list_together`
 548
 549   For an object: groups related objects when outputting an inventory or
 550   room contents list.  The `{value}` can be
 551
 552   * a `{number}`: all objects having this value are grouped;
 553   * a `{string}`: all objects having this value are grouped as a count of
 554     the string;
 555   * a routine which is called twice.  On the first call nothing has been
 556     output; `inventory_stage` has the value 1, and the routine should
 557     return `false` to continue, or `true` to stop processing and produce no
 558     further output.  On the second call the list has been output;
 559     `inventory_stage` has the value 2, and there is no test on the return
 560     value.
 561
 562 `n_to`
 563   See `d_to`.
 564
 565 `name` |ADD|
 566   Defines a space-separated list of words which are added to the Inform
 567   dictionary.  Each word can be supplied in apostrophes '...'  or quotes
 568   "..."; in all other cases only words in apostrophes update the
 569   dictionary.
 570
 571   For an object: identifies this object.
 572
 573   For a room: outputs "does not need to be referred to".
 574
 575 `ne_to`
 576   See `d_to`.
 577
 578 `number`
 579   For an object or room: the `{value}` is a general-purpose variable freely
 580   available for use by the program.  A `player` object must provide (but
 581   not use) this variable.
 582
 583 `nw_to`
 584   See `d_to`.
 585
 586 `orders` |ADD|
 587   For an `animate` or `talkable` object: the `{value}` is a routine called
 588   to carry out the player's orders.  The routine should return `false` to
 589   continue, or `true` to stop processing the action and produce no further
 590   output.
 591
 592 `out_to`
 593   See `d_to`.
 594
 595 `parse_name`
 596   For an object: the `{value}` is a routine called to parse an object's
 597   name.  The routine should return zero if the text makes no sense, -1 to
 598   cause the parser to resume, or the positive number of words matched.
 599
 600 `plural`
 601   For an object: its plural form, when in the presence of others like it.
 602   The `{value}` can be a string, or a routine which outputs a string.
 603
 604 `react_after`
 605   For an object: detects nearby actions - those which take place when this
 606   object is in scope.  The `{value}` is a routine invoked after the action
 607   has happened, but before the player has been informed.  See `after`.
 608
 609 `react_before`
 610   For an object: detects nearby actions - those which take place when this
 611   object is in scope.  The `{value}` is a routine invoked before the action
 612   has happened.  See `after`.
 613
 614 `s_to`
 615
 616 `se_to`
 617   See `d_to`.
 618
 619 `short_name`
 620   For an object: an alternative or extended short name.  The `{value}` can
 621   be a string, or a routine which outputs a string.  The routine should
 622   return `false` to continue by outputting the object's *actual* short name
 623   (from the head of the object definition), or `true` to stop processing
 624   the action and produce no further output.
 625
 626 `short_name_indef`
 627   For a non-English object: the short name when preceded by an indefinite
 628   object.  The `{value}` can be a string, or a routine which outputs a
 629   string.
 630
 631 `sw_to`
 632   See `d_to`.
 633
 634 `time_left`
 635   For a timer object: the `{value}` is a variable to hold the number of
 636   turns left until this object's timer - activated and initialised by
 637   `StartTimer({obj_id})` - counts down to zero and invokes the object's
 638   `time_out` property.
 639
 640 `time_out`
 641   For a timer object: the `{value}` is a routine which is run when the
 642   object's `time_left` value - initialised by `StartTimer({obj_id})`, and
 643   not in the meantime cancelled by `StopTimer({obj_id})` - counts down to
 644   zero.
 645
 646 `u_to`
 647
 648 `w_to`
 649   See `d_to`.
 650
 651 `when_closed`
 652
 653 `when_open`
 654   For a `container` or `door` object: used when including this object in a
 655   room's long description.  The `{value}` can be a string, or a routine
 656   which outputs a string.
 657
 658 `when_off`
 659
 660 `when_on`
 661   For a `switchable` object: used when including this object in a room's
 662   long description.  The `{value}` can be a string, or a routine which
 663   outputs a string.
 664
 665 `with_key`
 666   For a `lockable` object: the `{obj_id}` (generally some kind of key)
 667   needed to lock and unlock the object, or `nothing` if no key fits.
 668
 669 .. _object-attrs:
 670
 671 Object attributes
 672 =================
 673
 674 `absent`
 675      For a floating object (one with a `found_in` property, which can
 676      appear in many rooms): is no longer there.
 677
 678 `animate`
 679      For an object: is a living creature.
 680
 681 `clothing`
 682      For an object: can be worn.
 683
 684 `concealed`
 685      For an object: is present but hidden from view.
 686
 687 `container`
 688      For an object: other objects can be put in (but not on) it.
 689
 690 `door`
 691      For an object: is a door or bridge between rooms.
 692
 693 `edible`
 694      For an object: can be eaten.
 695
 696 `enterable`
 697      For an object: can be entered.
 698
 699 `female`
 700      For an `animate` object: is female.
 701
 702 `general`
 703      For an object or room: a general-purpose flag.
 704
 705 `light`
 706      For an object or room: is giving off light.
 707
 708 `lockable`
 709      For an object: can be locked; see the `with_key` property.
 710
 711 `locked`
 712      For an object: can't be opened.
 713
 714 `male`
 715      For an `animate` object: is male.
 716
 717 `moved`
 718      For an object: is being, or has been, taken by the player.
 719
 720 `neuter`
 721      For an `animate` object: is neither male nor female.
 722
 723 `on`
 724      For a `switchable` object: is switched on.
 725
 726 `open`
 727      For a `container` or door object: is open.
 728
 729 `openable`
 730      For a `container` or `door` object: can be opened.
 731
 732 `pluralname`
 733      For an object: is plural.
 734
 735 `proper`
 736      For an object: the short name is a proper noun, therefore not to be
 737      preceded by "The" or "the".
 738
 739 `scenery`
 740      For an object: can't be taken; is not listed in a room description.
 741
 742 `scored`
 743      For an object: awards `OBJECT_SCORE` points when taken for the first
 744      time.  For a room: awards `ROOM_SCORE` points when visited for the
 745      first time.
 746
 747 `static`
 748      For an object: can't be taken.
 749
 750 `supporter`
 751      For an object: other objects can be put on (but not in) it.
 752
 753 `switchable`
 754      For an object: can be switched off or on.
 755
 756 `talkable`
 757      For an object: can be addressed in "object, do this" style.
 758
 759 `transparent`
 760      For a `container` object: objects inside it are visible.
 761
 762 `visited`
 763      For a room: is being, or has been, visited by the player.
 764
 765 `workflag`
 766      Temporary internal flag, also available to the program.
 767
 768 `worn`
 769      For a `clothing` object: is being worn.
 770
 771 .. _entry-points:
 772
 773 Optional entry points
 774 =====================
 775
 776 These routines, if you supply them, are called when shown.
 777
 778 `AfterLife()`
 779   Player has died; `deadflag=0` resurrects.
 780
 781 `AfterPrompt()`
 782   The ">" prompt has been output.
 783
 784 `Amusing()`
 785   Player has won; `AMUSING_PROVIDED` is defined.
 786
 787 `BeforeParsing()`
 788   The parser has input some text, set up the buffer and parse tables, and
 789   initialised `wn` to 1.
 790
 791 `ChooseObjects({object,flag})`
 792   Parser has found "`ALL`" or an ambiguous noun phrase and decided that
 793   `{object}` should be excluded (`flag` is 0), or included (`flag` is 1).
 794   The routine should return 0 to let this stand, 1 to force inclusion, or 2
 795   to force exclusion.  If `flag` is 2, parser is undecided; routine should
 796   return appropriate score 0..9.
 797
 798 `DarkToDark()`
 799   The player has gone from one dark room to another.
 800
 801 `DeathMessage()`
 802   The player has died; `deadflag` is 3 or more.
 803
 804 `GamePostRoutine()`
 805   Called after all actions.
 806
 807 `GamePreRoutine()`
 808   Called before all actions.
 809
 810 `Initialise()`
 811   **Mandatory; note British spelling**: called at start.  Must set
 812   `location`; can return 2 to suppress game banner.
 813
 814 `InScope()`
 815   Called during parsing.
 816
 817 `LookRoutine()`
 818   Called at the end of every `Look` description.
 819
 820 `NewRoom()`
 821   Called when room changes, before description is output.
 822
 823 `ParseNoun({object})`
 824   Called to parse the `{object}`\'s name.
 825
 826 `ParseNumber({byte_array,length})`
 827   Called to parse a number.
 828
 829 `ParserError({number})`
 830   Called to handle an error.
 831
 832 `PrintRank()`
 833   Completes the output of the score.
 834
 835 `PrintTaskName({number})`
 836   Prints the name of the task.
 837
 838 `PrintVerb({addr})`
 839   Called when an unusual verb is printed.
 840
 841 `TimePasses()`
 842   Called after every turn.
 843
 844 `UnknownVerb()`
 845   Called when an unusual verb is encountered.
 846
 847 .. _group-1-actions:
 848
 849 Group 1 actions
 850 ===============
 851
 852 Group 1 actions support the 'meta' verbs.  These are the standard actions
 853 and their triggering verbs.
 854
 855 ==============  =====================================================
 856 `CommandsOff`   "`RECORDING OFF`"
 857 `CommandsOn`    "`RECORDING [ON]`"
 858 `CommandsRead`  "`REPLAY`"
 859 `FullScore`     "`FULLSCORE`", "`FULL [SCORE]`"
 860 `LMode1`        "`BRIEF`", "`NORMAL`"
 861 `LMode2`        "`LONG`", "`VERBOSE`"
 862 `LMode3`        "`SHORT`", "`SUPERBRIEF`"
 863 `NotifyOff`     "`NOTIFY OFF`"
 864 `NotifyOn`      "`NOTIFY [ON]`"
 865 `Objects`       "`OBJECTS`"
 866 `Places`        "`PLACES`"
 867 `Pronouns`      "`[PRO]NOUNS`"
 868 `Quit`          "`DIE`", "`Q[UIT]`"
 869 `Restart`       "`RESTART`"
 870 `Restore`       "`RESTORE`"
 871 `Save`          "`CLOSE`"
 872 `Score`         "`SCORE`"
 873 `ScriptOff`     "`[TRAN]SCRIPT OFF`", "`NOSCRIPT`", "`UNSCRIPT`"
 874 `ScriptOn`      "`[TRAN]SCRIPT [ON]`"
 875 `Verify`        "`VERIFY`"
 876 `Version`       "`VERSION`"
 877 ==============  =====================================================
 878
 879 and the debug tools.
 880
 881 ===============   ===================================================
 882 `ActionsOff`      "`ACTIONS OFF`"
 883 `ActionsOn`       "`ACTIONS [ON]`"
 884 `ChangesOff`      "`CHANGES OFF`"
 885 `ChangesOn`       "`CHANGES [ON]`"
 886 `Gonear`          "`GONEAR`"
 887 `Goto`            "`GOTO`"
 888 `Predictable`     "`RANDOM`"
 889 `RoutinesOff`     "`MESSAGES OFF`", "`ROUTINES OFF`"
 890 `RoutinesOn`      "`MESSAGES [ON]`", "`ROUTINES [ON]`"
 891 `Scope`           "`SCOPE`"
 892 `Showobj`         "`SHOWOBJ`"
 893 `Showverb`        "`SHOWVERB`"
 894 `TimersOff`       "`DAEMONS OFF`", "`TIMERS OFF`"
 895 `TimersOn`        "`DAEMONS [ON]`", "`TIMERS [ON]`"
 896 `TraceLevel`      "`TRACE number`"
 897 `TraceOff`        "`TRACE OFF`"
 898 `TraceOn`         "`TRACE [ON]`"
 899 `XAbstract`       "`ABSTRACT`"
 900 `XPurloin`        "`PURLOIN`"
 901 `XTree`           "`TREE`"
 902 ===============   ===================================================
 903
 904 .. _group-2-actions:
 905
 906 Group 2 actions
 907 ===============
 908
 909 Group 2 actions usually work, given the right circumstances.
 910
 911 .. tabularcolumns:: |l|p{5in}|
 912
 913 =============   =============================================================
 914 `Close`         "`CLOSE [UP]`", "`COVER [UP]`", "`SHUT [UP]`"
 915 `Disrobe`       "`DISROBE`", "`DOFF`", "`REMOVE`", "`SHED`", "`TAKE OFF`"
 916 `Drop`          "`DISCARD`", "`DROP`", "`PUT DOWN`", "`THROW`"
 917 `Eat`           "`EAT`"
 918 `Empty`         "`EMPTY [OUT]`"
 919 `EmptyT`        "`EMPTY IN|INTO|ON|ONTO|TO`"
 920 `Enter`         "`CROSS`", "`ENTER`", "`GET IN|INTO|ON|ONTO`",
 921                 "`GO IN|INSIDE|INTO|THROUGH`",
 922                 "`LEAVE IN|INSIDE|INTO|THROUGH`", "`LIE IN|INSIDE|ON`",
 923                 "`LIE ON TOP OF`",
 924                 "`RUN IN|INSIDE|INTO|THROUGH`", "`SIT IN|INSIDE|ON`",
 925                 "`SIT ON TOP OF`", "`STAND ON`",
 926                 "`WALK IN|INSIDE|INTO|THROUGH`"
 927 `Examine`       "`CHECK,`" "`DESCRIBE`", "`EXAMINE`",
 928                 "`L[OOK] AT`", "`READ`", "`WATCH`", "`X`"
 929 `Exit`          "`EXIT`", "`GET OFF|OUT|UP`",
 930                 "`LEAVE`", "`OUT[SIDE]`", "`STAND [UP]`"
 931 `GetOff`        "`GET OFF`"
 932 `Give`          "`FEED [TO]`", "`GIVE [TO]`", "`OFFER [TO]`", "`PAY [TO]`"
 933 `Go`            "`GO`", "`LEAVE`", "`RUN`", "`WALK`"
 934 `GoIn`          "`CROSS`", "`ENTER`", "`IN[SIDE]`"
 935 `Insert`        "`DISCARD IN|INTO`",
 936                 "`DROP DOWN|IN|INTO`",
 937                 "`INSERT IN|INTO`",
 938                 "`PUT IN|INSIDE|INTO`",
 939                 "`THROW DOWN|IN|INTO`"
 940 `Inv`           "`I[NV]`", "`INVENTORY`", "`TAKE INVENTORY`"
 941 `InvTall`       "`I[NV] TALL`", "`INVENTORY TALL`"
 942 `InvWide`       "`I[NV] WIDE`", "`INVENTORY WIDE`"
 943 `Lock`          "`LOCK WITH`"
 944 `Look`          "`L[OOK]`"
 945 `Open`          "`OPEN`", "`UNCOVER`", "`UNDO`", "`UNWRAP`"
 946 `PutOn`         "`DISCARD ON|ONTO`",
 947                 "`DROP ON|ONTO`",
 948                 "`PUT ON|ONTO`",
 949                 "`THROW ON|ONTO`"
 950 `Remove`        "`GET FROM`", "`REMOVE FROM`", "`TAKE FROM|OFF`"
 951 `Search`        "`L[OOK] IN|INSIDE|INTO|THROUGH`", "`SEARCH`"
 952 `Show`          "`DISPLAY [TO]`", "`PRESENT [TO]`", "`SHOW [TO]`"
 953 `SwitchOff`     "`CLOSE OFF`", "`SCREW OFF`",
 954                 "`SWITCH OFF`", "`TURN OFF`",
 955                 "`TWIST OFF`"
 956 `SwitchOn`      "`SCREW ON`", "`SWITCH ON`",
 957                 "`TURN ON`", "`TWIST ON`"
 958 `Take`          "`CARRY`", "`GET`", "`HOLD`",
 959                 "`PEEL [OFF]`", "`PICK UP`",
 960                 "`REMOVE`", "`TAKE`"
 961 `Transfer`      "`CLEAR TO`", "`MOVE TO`",
 962                 "`PRESS TO`", "`PUSH TO`",
 963                 "`SHIFT TO`", "`TRANSFER TO`"
 964 `Unlock`        "`OPEN WITH`", "`UNDO WITH`",
 965                 "`UNLOCK WITH`"
 966 `VagueGo`       "`GO`", "`LEAVE`", "`RUN`", "`WALK`"
 967 `Wear`          "`DON`", "`PUT ON`", "`WEAR`"
 968 =============   =============================================================
 969
 970 .. _group-3-actions:
 971
 972 Group 3 actions
 973 ===============
 974
 975 Group 3 actions are by default stubs which output a message and stop at the
 976 "before" stage (so there is no "after" stage).
 977
 978 .. tabularcolumns:: |l|p{5in}|
 979
 980 =============   =============================================================
 981 `Answer`        "`ANSWER TO`", "`SAY TO`",
 982                 "`SHOUT TO`", "`SPEAK TO`"
 983 `Ask`           "`ASK ABOUT`"
 984 `AskFor`        "`ASK FOR`"
 985 `Attack`        "`ATTACK`", "`BREAK`", "`CRACK`",
 986                 "`DESTROY`", "`FIGHT`", "`HIT`",
 987                 "`KILL`", "`MURDER`", "`PUNCH`",
 988                 "`SMASH`", "`THUMP`", "`TORTURE`",
 989                 "`WRECK`"
 990 `Blow`          "`BLOW`"
 991 `Burn`          "`BURN [WITH]`", "`LIGHT [WITH]`"
 992 `Buy`           "`BUY`" "`PURCHASE`"
 993 `Climb`         "`CLIMB [OVER|UP]`", "`SCALE`"
 994 `Consult`       "`CONSULT ABOUT|ON`",
 995                 "`LOOK UP IN`",
 996                 "`READ ABOUT IN`", "`READ IN`"
 997 `Cut`           "`CHOP,`" "`CUT`", "`PRUNE`", "`SLICE`"
 998 `Dig`           "`DIG [WITH]`"
 999 `Drink`         "`DRINK`", "`SIP`", "`SWALLOW`"
1000 `Fill`          "`FILL`"
1001 `Jump`          "`HOP`", "`JUMP`", "`SKIP`"
1002 `JumpOver`      "`HOP OVER`", "`JUMP OVER`", "`SKIP OVER`"
1003 `Kiss`          "`EMBRACE`", "`HUG`", "`KISS`"
1004 `Listen`        "`HEAR`", "`LISTEN [TO]`"
1005 `LookUnder`     "`LOOK UNDER`"
1006 `Mild`          Various mild swearwords.
1007 `No`            "`NO`"
1008 `Pray`          "`PRAY`"
1009 `Pull`          "`DRAG`" "`PULL`"
1010 `Push`          "`CLEAR`", "`MOVE`", "`PRESS`",
1011                 "`PUSH`", "`SHIFT`"
1012 `PushDir`       "`CLEAR`", "`MOVE`", "`PRESS`",
1013                 "`PUSH`", "`SHIFT`"
1014 `Rub`           "`CLEAN`", "`DUST`", "`POLISH`",
1015                 "`RUB`", "`SCRUB`", "`SHINE`",
1016                 "`SWEEP`", "`WIPE`"
1017 `Set`           "`ADJUST`", "`SET`"
1018 `SetTo`         "`ADJUST TO`", "`SET TO`"
1019 `Sing`          "`SING`"
1020 `Sleep`         "`NAP`", "`SLEEP`"
1021 `Smell`         "`SMELL`", "`SNIFF`"
1022 `Sorry`         "`SORRY`"
1023 `Squeeze`       "`SQUASH`", "`SQUEEZE`"
1024 `Strong`        Various strong swearwords.
1025 `Swim`          "`DIVE`", "`SWIM`"
1026 `Swing`         "`SWING [ON]`"
1027 `Taste`         "`TASTE`"
1028 `Tell`          "`TELL ABOUT`"
1029 `Think`         "`THINK`"
1030 `ThrowAt`       "`THROW AGAINST|AT|ON|ONTO`"
1031 `Tie`           "`ATTACH [TO]`", "`FASTEN [TO]`",
1032                 "`FIX [TO]`", "`TIE [TO]`"
1033 `Touch`         "`FEEL,`" "`FONDLE`", "`GROPE`", "`TOUCH`"
1034 `Turn`          "`ROTATE`", "`SCREW`", "`TURN`",
1035                 "`TWIST`", "`UNSCREW`"
1036 `Wait`          "`WAIT`" "`Z`"
1037 `Wake`          "`AWAKE[N]`", "`WAKE [UP]`"
1038 `WakeOther`     "`AWAKE[N]`", "`WAKE [UP]`"
1039 `Wave`          "`WAVE`"
1040 `WaveHands`     "`WAVE`"
1041 `Yes`           "`Y[ES]`"
1042 =============   =============================================================
1043
1044 Fake actions
1045 ============
1046
1047 Fake actions handle some special cases, or represent "real" actions from
1048 the viewpoint of the second object.
1049
1050 .. tabularcolumns:: |l|p{5in}|
1051
1052 ================   ========================================================
1053 `LetGo`            Generated by `Remove`.
1054 `ListMiscellany`   Outputs a range of inventory messages.
1055 `Miscellany`       Outputs a range of utility messages.
1056 `NotUnderstood`    Generated when parser fails to interpret some `orders`.
1057 `Order`            Receives things not handled by `orders`.
1058 `PluralFound`      Tells the parser that `parse_name()` has identified a
1059                    plural object.
1060 `Prompt`           Outputs the prompt, normally ">".
1061 `Receive`          Generated by `Insert` and `PutOn`.
1062 `TheSame`          Generated when parser can't distinguish between two
1063                    objects.
1064 `ThrownAt`         Generated by `ThrowAt`.
1065 ================   ========================================================