1 ==============================
2 Appendix F -- Inform library
3 ==============================
5 .. |ADD| replace:: **(+)**
7 .. The ⊕ symbol doesn't work in LaTeX.
13 .. image:: /images/picL.png
16 |L|\ibrary files define Inform's model world, turning a conventional
17 programming language into a text adventure development system. Here are
18 the library constants, variables and routines, the standard object
19 properties and attributes, the verb grammars and actions.
25 pair: compass; library object
28 A :attr:`container` object holding the twelve direction objects
29 :obj:`d_obj`, :obj:`e_obj`, :obj:`in_obj`, :obj:`n_obj`, :obj:`ne_obj`,
30 :obj:`nw_obj`, :obj:`out_obj`, :obj:`s_obj`, :obj:`se_obj`,
31 :obj:`sw_obj`, :obj:`u_obj`, :obj:`w_obj`.
34 pair: LibraryMessages; library object
36 :obj:`LibraryMessages`
37 If defined (between Includes of `Parser` and `VerbLib`), changes standard
40 | `Object LibraryMessages`
42 | `{action}: "{string}";`
43 | `{action}: "{string}";`
44 | `{action}: switch (lm_n) {`
45 | `{value}: "{string}";`
46 | `{value}: "{string}",`
54 pair: selfobj; library object
57 The default player object. Avoid: use instead the :var:`player`
58 variable, which usually refers to :obj:`selfobj`.
61 pair: thedark; library object
64 A pseudo-room which becomes the :var:`location` when there is no light
65 (although the player object is not moved there).
70 In addition to the standard constants :const:`true` (1), :const:`false` (0)
71 and :const:`nothing` (0), the Library defines :const:`NULL` (-1) for an
72 `{action}`, `{property}` or `{pronoun}` whose current value is undefined.
74 `LIBRARY_PARSER`, `LIBRARY_ENGLISH`, `LIBRARY_VERBLIB` and
75 `LIBRARY_GRAMMAR` are defined to mark the end of inclusion of `Parser.h`,
76 `English.h`, `VerbLib.h` and `Grammar.h` respectively.
78 User-defined constants
79 ======================
81 Some constants control features rather than represent values.
84 Activates the `Amusing` entry point.
86 `COMMENT_CHARACTER = '{char}'`
87 Introduces a comment line ignored by the parser (default "*").
90 Offers "UNDO the last move" at game end.
93 Activates the debug commands.
95 `Headline = "{string}"`
96 **Mandatory**: game style, copyright info, etc.
99 Pronouns reflect only objects mentioned by the player.
101 `MAX_CARRIED = {expr}`
102 Limit on direct possessions that the player can carry (default 100).
105 Maximum game score (default 0).
107 `MAX_TIMERS = {expr}`
108 Limit on active timers/daemons (default 32).
111 "`OBJECTS`" and "`PLACES`" verbs are barred.
114 Game doesn't use scoring.
116 `NUMBER_TASKS = {expr}`
117 Number of `scored` tasks (default 1).
119 `OBJECT_SCORE = {expr}`
120 For taking a `scored` object for the first time (default 4).
122 `ROOM_SCORE = {expr}`
123 For visiting a `scored` room for the first time (default 5).
125 `SACK_OBJECT = {obj_id}`
126 A `container` object where the game places held objects.
128 `START_MOVE = {expr}`
129 Initial value of turns counter (default 0).
132 **Mandatory**: the name of the story.
135 Activates the task scoring system.
138 Activates linking with pre-compiled library modules.
141 De-activates standard compass directions (bar "`IN`" and "`OUT`"). Place
142 alternative directions in the :obj:`compass`.
148 pair: action; library variable
151 The current `{action}`.
154 pair: actor; library variable
157 The target of an instruction: the player, or an NPC.
160 pair: deadflag; library variable
163 Normally 0: 1 indicates a regular death, 2 indicates that the player has
164 won, 3 or more denotes a user-defined end.
167 pair: inventory_stage; library variable
169 :var:`inventory_stage`
170 Used by :prop:`invent` and :prop:`list_together` properties.
173 pair: keep_silent; library variable
176 Normally :const:`false`; :const:`true` makes most :ref:`group 2 actions
177 <group-2-actions>` silent.
180 pair: location; library variable
183 The player's current room; unless that's dark, when it contains
184 :obj:`thedark`, :var:`real_location` contains the room.
187 pair: notify_mode; library variable
190 Normally :const:`true`: :const:`false` remains silent when score changes.
193 pair: noun; library variable
196 The primary focus object for the current action.
199 pair: player; library variable
202 The object acting on behalf of the human player.
205 pair: real_location; library variable
208 The player's current room when in the dark.
211 pair: score; library variable
217 pair: second; library variable
220 The secondary focus object for the current action.
223 pair: self; library variable
226 The object which received a message. (Note: a run-time variable, not a
227 compile-time constant.)
230 pair: sender; library variable
233 The object which sent a message (or `nothing`).
236 pair: task_scores; library variable
239 A byte array holding scores for the task scoring system.
242 pair: the_time; library variable
245 The game's clock, in minutes 0..1439 since midnight.
248 pair: turns; library variable
251 The game's turn counter.
254 pair: wn; library variable
257 The input stream word number, counting from 1.
259 .. _library-routines:
265 pair: Achieved; library routine
268 A scored task has been achieved.
271 pair: AfterRoutines; library routine
274 In a :ref:`group 2 action <group-2-actions>`, controls output of "after"
278 pair: AllowPushDir; library routine
281 An object can be pushed from one location to another.
284 pair: Banner; library routine
287 Prints the game banner.
290 pair: ChangePlayer; library routine
292 `ChangePlayer({obj_id,flag})`
293 Player assumes the persona of the `{obj_id}`. If the optional `{flag}`
294 is :const:`true`, room descriptions include "(as `{object}`)".
297 pair: CommonAncestor; library routine
299 `CommonAncestor({obj_id1,obj_id2})`
300 Returns the nearest object which has a parental relationship to both
301 `{obj_ids}`, or `nothing`.
304 pair: DictionaryLookup; library routine
306 `DictionaryLookup({byte_array,length})`
307 Returns address of word in dictionary, or 0 if not found.
310 pair: DrawStatusLine; library routine
313 Refreshes the status line; happens anyway at end of each turn.
316 pair: GetGNAOfObject; library routine
318 `GetGNAOfObject({obj_id})`
319 Returns gender-number-animation 0..11 of the `{obj_id}`.
322 pair: HasLightSource; library routine
324 `HasLightSource({obj_id})`
325 Returns :const:`true` if the `{obj_id}` has light.
328 pair: IndirectlyContains; library routine
330 `IndirectlyContains({parnt_obj_id,obj_id})`
331 Returns :const:`true` if `{obj_id}` is currently a child or grand-child
332 or great-grand-child... of the `{parent_object}`.
335 pair: IsSeeThrough; library routine
337 `IsSeeThrough({obj_id})`
338 Returns :const:`true` if light can pass through the `{obj_id}`.
341 pair: Locale; library routine
343 `Locale({obj_id,"string1","string2"})`
344 Describes the contents of `{obj_id}`, and returns their number. After
345 objects with own paragraphs, the rest are listed preceded by `{string1}`
349 pair: LoopOverScope; library routine
351 `LoopOverScope({routine_id,actor})`
352 Calls `{routine_id}({obj_id})` for each `{obj_id}` in scope. If the
353 optional `{actor}` is supplied, that defines the scope.
356 pair: MoveFloatingObjects; library routine
358 `MoveFloatingObjects()`
359 Adjusts positions of game's :prop:`found_in` objects.
362 pair: NextWord; library routine
365 Returns the next dictionary word in the input stream, incrementing
366 :var:`wn` by one. Returns :const:`false` if the word is not in the
367 dictionary, or if the input stream is exhausted.
370 pair: NextWordStopped; library routine
373 Returns the next dictionary word in the input stream, incrementing
374 :var:`wn` by one. Returns :const:`false` if the word is not in the
375 dictionary, -1 if the input stream is exhausted.
378 pair: NounDomain; library routine
380 `NounDomain({obj_id1,obj_id2,type})`
381 Performs object parsing; see also `ParseToken()`.
384 pair: ObjectIsUntouchable; library routine
386 `ObjectIsUntouchable({obj_id,flag})`
387 Tests whether there is a barrier - a container object which is not open -
388 between player and `{obj_id}`. Unless the optional `{flag}` is
389 :const:`true`, outputs "You can't because ... is in the way". Returns
390 :const:`true` is a barrier is found, otherwise :const:`false`.
393 pair: OffersLight; library routine
395 `OffersLight({obj_id})`
396 Returns :const:`true` if the `{obj_id}` offers light.
399 pair: ParseToken; library routine
401 `ParseToken({type,value})`
402 Performs general parsing; see also `NounDomain()`.
405 pair: PlaceInScope; library routine
407 `PlaceInScope({obj_id})`
408 Used in an :prop:`add_to_scope` property or `scope=` token to put the
409 `{obj_id}` into scope for the parser.
412 pair: PlayerTo; library routine
414 `PlayerTo({obj_id,flag})`
415 Moves the player to `{obj_id}`. Prints its description unless optional
416 `{flag}` is 1 (no description) or 2 (as if walked in).
419 pair: PrintOrRun; library routine
421 `PrintOrRun({obj_id,property,flag})`
422 If `{obj_id.property}` is a string, output it (followed by a newline
423 unless optional `{flag}` is :const:`true`), and return :const:`true`. If
424 it's a routine, run it and return what the routine returns.
427 pair: PronounNotice; library routine
429 `PronounNotice({obj_id})`
430 Associates an appropriate pronoun with the `{obj_id}`.
433 pair: PronounValue; library routine
435 `PronounValue('{pronoun}')`
436 Returns the object to which '`it`' (or '`him`', '`her`', '`them`')
437 currently refers, or :const:`nothing`.
440 pair: ScopeWithin; library routine
442 `ScopeWithin({obj_id})`
443 Used in an :prop:`add_to_scope` property or `scope=` token to put the
444 contents of the `{obj_id}` in scope for the parser.
447 pair: SetPronoun; library routine
449 `SetPronoun('{pronoun}',{obj_id})`
450 Defines the `{obj_id}` to which a given pronoun refers.
453 pair: SetTime; library routine
455 `SetTime({expr1,expr2})`
456 Sets `the_time` to `{expr1}` (in mins 0..1439 since midnight), running at
459 | +ve: `{expr2}` minutes pass each turn;
460 | -ve: `{-expr2}` turns take one minute;
461 | zero: time stands still.
464 pair: StartDaemon; library routine
466 `StartDaemon({obj_id})`
467 Starts the `{obj_id}`\'s daemon.
470 pair: StartTimer; library routine
472 `StartTimer({obj_id,expr})`
473 Starts the `{obj_id}`\'s timer, initialising its :prop:`time_left` to
474 `{expr}`. The object's :prop:`time_out` property will be called after
475 that number of turns have elapsed.
478 pair: StopDaemon; library routine
480 `StopDaemon({obj_id})`
481 Stops the `{obj_id}`\'s daemon.
484 pair: StopTimer; library routine
486 `StopTimer({obj_id})`
487 Stops the `{obj_id}`\'s timer.
490 pair: TestScope; library routine
492 `TestScope({obj_id,actor})`
493 Returns :const:`true` if the `{obj_id}` is in scope, otherwise
494 :const:`false`. If the optional `{actor}` is supplied, that defines the
498 pair: TryNumber; library routine
501 Parses word `{expr}` in the input stream as a number, recognising
502 decimals, also English words one..twenty. Returns the number 1..10000,
503 or -1000 if the parse fails.
506 pair: UnsignedCompare; library routine
508 `UnsignedCompare({expr1,expr2})`
509 Returns -1 if `{expr1}` is less than `{expr2}`, 0 if `{expr1}` equals
510 `{expr2}`, and 1 if `{expr1}` is greater than `{expr2}`. Both
511 expressions are unsigned, in the range 0..65535.
514 pair: WordAddress; library routine
516 `WordAddress({expr})`
517 Returns a byte array containing the raw text of word `{expr}` in the
521 pair: WordInProperty; library routine
523 `WordInProperty({word,obj_id,property})`
524 Returns :const:`true` if the dictionary `{word}` is listed in the
525 `{property}` values for the `{obj_id}`.
528 pair: WordLength; library routine
531 Returns the length of word `{expr}` in the input stream.
534 pair: WriteListFrom; library routine
536 `WriteListFrom({obj_id,expr})`
537 Outputs a list of `{obj_id}` and its siblings, in the given style, an
538 `{expr}` formed by adding any of: `ALWAYS_BIT`, `CONCEAL_BIT`,
539 `DEFART_BIT`, `ENGLISH_BIT`, `FULLINV_BIT`, `INDENT_BIT`, `ISARE_BIT`,
540 `NEWLINE_BIT`, `PARTINV_BIT`, `RECURSE_BIT`, `TERSE_BIT`, `WORKFLAG_BIT`.
543 pair: YesOrNo; library routine
546 Returns :const:`true` if the player types "`YES`", :const:`false` for
550 pair: ZRegion; library routine
553 Returns the type of its `{arg}` : 3 for a string address, 2 for a routine
554 address, 1 for an object number, or 0 otherwise.
561 Where the `value` of a property can be a routine, several formats are
562 possible (but remember: embedded "`]`" returns :const:`false`, standalone
563 "`]`" returns :const:`true`):
565 | `{property} [; {stmt}; {stmt}; ... ]`
566 | `{property} [; return {routine_id}(); ]`
567 | `{property} [; {routine_id}(); ]`
568 | `{property} {routine_id}`
570 In this appendix, |ADD| marks an additive property. Where a `Class` and an
571 `Object` of that class both define the same property, the value specified
572 for the `Object` normally overrides the value inherited from the `Class`.
573 However, if the property is additive then both values apply, with the
574 Object's value being considered first.
577 pair: add_to_scope; library property
580 For an object: additional objects which follow it in and out of scope.
581 The `{value}` can be a space-separated list of `{obj_ids}`, or a routine
582 which invokes `PlaceInScope()` or `ScopeWithin()` to specify objects.
585 pair: after; library property
588 For an object: receives every `{action}` and `{fake_action}` for which
589 this is the `{noun}`. For a room: receives every `{action}` which occurs
592 The `{value}` is a routine of structure similar to a `switch` statement,
593 having cases for the appropriate `{actions}` (and an optional `default`
594 as well); it is invoked after the action has happened, but before the
595 player has been informed. The routine should return :const:`false` to
596 continue, telling the player what has happened, or :const:`true` to stop
597 processing the action and produce no further output.
600 pair: article; library property
603 For an object: the object's indefinite article - the default is
604 automatically "a", "an" or "some". The `{value}` can be a string, or a
605 routine which outputs a string.
608 pair: articles; library property
611 For a non-English object: its definite and indefinite articles. The
612 `{value}` is an array of strings.
615 pair: before; library property
618 For an object: receives every `{action}` and `{fake_action}` for which
619 this is the `{noun}`. For a room: receives every action which occurs
622 The `{value}` is a routine invoked before the action has happened. See
626 pair: cant_go; library property
629 For a room: the message when the player attempts an impossible exit. The
630 `{value}` can be a string, or a routine which outputs a string.
633 pair: capacity; library property
636 For a :attr:`container` or :attr:`supporter` object: the number of
637 objects which can be placed in or on it - the default is 100.
639 For the player: the number which can be carried - :obj:`selfobj` has an
640 initial capacity of `MAX_CARRIED`.
642 The `{value}` can be a number, or a routine which returns a number.
645 pair: d_to; library property
648 For a room: a possible exit. The `{value}` can be
650 * :const:`false` (the default): not an exit;
651 * a string: output to explain why this is not an exit;
652 * a `{room}`: the exit leads to this room;
653 * a :obj:`door` object: the exit leads through this door;
654 * a routine which should return :const:`false`, a string, a `{room}`, a
655 :obj:`door` object, or :const:`true` to signify "not an exit" and
656 produce no further output.
659 pair: daemon; library property
662 The `{value}` is a routine which can be activated by
663 `StartDaemon({obj_id})` and which then runs once each turn until
664 deactivated by `StopDaemon({obj_id})`.
667 pair: describe; library property
669 :prop:`describe` |ADD|
670 For an object: called before the object's description is output. For a
671 room: called before the room's (long) description is output.
673 The `{value}` is a routine which should return :const:`false` to continue,
674 outputting the usual description, or :const:`true` to stop processing and
675 produce no further output.
678 pair: description; library property
681 For an object: its description (output by :act:`Examine`).
683 For a room: its long description (output by :act:`Look`).
685 The `{value}` can be a string, or a routine which outputs a string.
688 pair: door_dir; library property
691 For a :obj:`compass` object (:obj:`d_obj`, :obj:`e_obj`, ...): the
692 direction in which an attempt to move to this object actually leads.
694 For a :obj:`door` object: the direction in which this door leads.
696 The `{value}` can be a directional property (:prop:`d_to`, :prop:`e_to`,
697 \...), or a routine which returns such a property.
700 pair: door_to; library property
703 For a `door` object: where it leads. The value can be
705 * :const:`false` (the default): leads nowhere;
706 * a string: output to explain why door leads nowhere;
707 * a `{room}`: the door leads to this room;
708 * a routine which should return :const:`false`, a string, a `{room}`, or
709 :const:`true` to signify "leads nowhere" without producing any output.
712 pair: e_to; library property
718 pair: each_turn; library property
720 :prop:`each_turn` |ADD|
721 Invoked at the end of each turn (after all appropriate daemons and
722 timers) whenever the object is in scope. The `{value}` can be a string,
726 pair: found_in; library property
729 For an object: the rooms where this object can be found, unless it has
730 the :attr:`absent` attribute. The `{value}` can be
732 * a space-separated list of `{rooms}` (where this object can be found) or
733 `{obj_ids}` (whose locations are tracked by this object);
734 * a routine which should return :const:`true` if this object can be found
735 in the current location, otherwise :const:`false`.
738 pair: grammar; library property
741 For an :attr:`animate` or :attr:`talkable` object: the `{value}` is a
742 routine called when the parser knows that this object is being addressed,
743 but has yet to test the grammar. The routine should return
744 :const:`false` to continue, :const::const:`true` to indicate that the
745 routine has parsed the entire command, or a dictionary word ('`word`' or
749 pair: in_to; library property
755 pair: initial; library property
758 For an object: its description before being picked up.
760 For a room: its description when the player enters the room.
762 The `{value}` can be a string, or a routine which outputs a string.
765 pair: inside_description; library property
767 :prop:`inside_description`
768 For an :prop:`enterable` object: its description, output as part of the
769 room description when the player is inside the object.
771 The `{value}` can be a string, or a routine which outputs a string.
774 pair: invent; library property
777 For an object: the `{value}` is a routine for outputting the object's
778 inventory listing, which is called twice. On the first call nothing has
779 been output; :var:`inventory_stage` has the value 1, and the routine
780 should return :const:`false` to continue, or :const:`true` to stop
781 processing and produce no further output. On the second call the
782 object's indefinite article and short name have been output, but not any
783 subsidiary information; :var:`inventory_stage` has the value 2, and the
784 routine should return :const:`false` to continue, or :const:`true` to
785 stop processing and produce no further output.
788 pair: life; library property
791 For an :prop:`animate` object: receives person-to-person actions
792 (:act:`Answer`, :act:`Ask`, :act:`Attack`, :act:`Give`, :act:`Kiss`,
793 :act:`Order`, :act:`Show`, :act:`Tell`, :act:`ThrowAt` and
794 :act:`WakeOther`) for which this is the `{noun}`. The `{value}` is a
795 routine of structure similar to a `switch` statement, having cases for
796 the appropriate `{actions}` (and an optional default as well). The
797 routine should return :const:`false` to continue, telling the player what
798 has happened, or :const:`true` to stop processing the action and produce
802 pair: list_together; library property
804 :prop:`list_together`
805 For an object: groups related objects when outputting an inventory or
806 room contents list. The `{value}` can be
808 * a `{number}`: all objects having this value are grouped;
809 * a `{string}`: all objects having this value are grouped as a count of
811 * a routine which is called twice. On the first call nothing has been
812 output; :var:`inventory_stage` has the value 1, and the routine should
813 return :const:`false` to continue, or :const:`true` to stop processing
814 and produce no further output. On the second call the list has been
815 output; :var:`inventory_stage` has the value 2, and there is no test on
819 pair: n_to; library property
825 pair: name; library property
828 Defines a space-separated list of words which are added to the Inform
829 dictionary. Each word can be supplied in apostrophes '...' or quotes
830 "..."; in all other cases only words in apostrophes update the
833 For an object: identifies this object.
835 For a room: outputs "does not need to be referred to".
838 pair: ne_to; library property
844 pair: number; library property
847 For an object or room: the `{value}` is a general-purpose variable freely
848 available for use by the program. A :var:`player` object must provide
849 (but not use) this variable.
852 pair: nw_to; library property
858 pair: orders; library property
861 For an :attr:`animate` or :attr:`talkable` object: the `{value}` is a
862 routine called to carry out the player's orders. The routine should
863 return :const:`false` to continue, or :const:`true` to stop processing
864 the action and produce no further output.
867 pair: out_to; library property
873 pair: parse_name; library property
876 For an object: the `{value}` is a routine called to parse an object's
877 name. The routine should return zero if the text makes no sense, -1 to
878 cause the parser to resume, or the positive number of words matched.
881 pair: plural; library property
884 For an object: its plural form, when in the presence of others like it.
885 The `{value}` can be a string, or a routine which outputs a string.
888 pair: react_after; library property
891 For an object: detects nearby actions - those which take place when this
892 object is in scope. The `{value}` is a routine invoked after the action
893 has happened, but before the player has been informed. See :prop:`after`.
896 pair: react_before; library property
899 For an object: detects nearby actions - those which take place when this
900 object is in scope. The `{value}` is a routine invoked before the action
901 has happened. See :prop:`after`.
904 pair: s_to; library property
910 pair: se_to; library property
916 pair: short_name; library property
919 For an object: an alternative or extended short name. The `{value}` can
920 be a string, or a routine which outputs a string. The routine should
921 return :const:`false` to continue by outputting the object's *actual*
922 short name (from the head of the object definition), or :const:`true` to
923 stop processing the action and produce no further output.
926 pair: short_name_indef; library property
928 :prop:`short_name_indef`
929 For a non-English object: the short name when preceded by an indefinite
930 object. The `{value}` can be a string, or a routine which outputs a
934 pair: sw_to; library property
940 pair: time_left; library property
943 For a timer object: the `{value}` is a variable to hold the number of
944 turns left until this object's timer - activated and initialised by
945 `StartTimer({obj_id})` - counts down to zero and invokes the object's
949 pair: time_out; library property
952 For a timer object: the `{value}` is a routine which is run when the
953 object's :prop:`time_left` value - initialised by `StartTimer({obj_id})`,
954 and not in the meantime cancelled by `StopTimer({obj_id})` - counts down
958 pair: u_to; library property
959 pair: w_to; library property
968 pair: when_closed; library property
969 pair: when_open; library property
974 For a :attr:`container` or :attr:`door` object: used when including this
975 object in a room's long description. The `{value}` can be a string, or a
976 routine which outputs a string.
979 pair: when_off; library property
980 pair: when_on; library property
985 For a :attr:`switchable` object: used when including this object in a
986 room's long description. The `{value}` can be a string, or a routine
987 which outputs a string.
990 pair: with_key; library property
993 For a :attr:`lockable` object: the `{obj_id}` (generally some kind of
994 key) needed to lock and unlock the object, or :const:`nothing` if no key
1003 pair: absent; library attribute
1006 For a floating object (one with a :prop:`found_in` property, which can
1007 appear in many rooms): is no longer there.
1010 pair: animate; library attribute
1013 For an object: is a living creature.
1016 pair: clothing; library attribute
1019 For an object: can be worn.
1022 pair: concealed; library attribute
1025 For an object: is present but hidden from view.
1028 pair: container; library attribute
1031 For an object: other objects can be put in (but not on) it.
1034 pair: door; library attribute
1037 For an object: is a door or bridge between rooms.
1040 pair: edible; library attribute
1043 For an object: can be eaten.
1046 pair: enterable; library attribute
1049 For an object: can be entered.
1052 pair: female; library attribute
1055 For an :attr:`animate` object: is female.
1058 pair: general; library attribute
1061 For an object or room: a general-purpose flag.
1064 pair: light; library attribute
1067 For an object or room: is giving off light.
1070 pair: lockable; library attribute
1073 For an object: can be locked; see the :prop:`with_key` property.
1076 pair: locked; library attribute
1079 For an object: can't be opened.
1082 pair: male; library attribute
1085 For an :attr:`animate` object: is male.
1088 pair: moved; library attribute
1091 For an object: is being, or has been, taken by the player.
1094 pair: neuter; library attribute
1097 For an :attr:`animate` object: is neither male nor female.
1100 pair: on; library attribute
1103 For a :attr:`switchable` object: is switched on.
1106 pair: open; library attribute
1109 For a :attr:`container` or door object: is open.
1112 pair: openable; library attribute
1115 For a :attr:`container` or :attr:`door` object: can be opened.
1118 pair: pluralname; library attribute
1121 For an object: is plural.
1124 pair: proper; library attribute
1127 For an object: the short name is a proper noun, therefore not to be
1128 preceded by "The" or "the".
1131 pair: scenery; library attribute
1134 For an object: can't be taken; is not listed in a room description.
1137 pair: scored; library attribute
1140 For an object: awards `OBJECT_SCORE` points when taken for the first
1141 time. For a room: awards `ROOM_SCORE` points when visited for the
1145 pair: static; library attribute
1148 For an object: can't be taken.
1151 pair: supporter; library attribute
1154 For an object: other objects can be put on (but not in) it.
1157 pair: switchable; library attribute
1160 For an object: can be switched off or on.
1163 pair: talkable; library attribute
1166 For an object: can be addressed in "object, do this" style.
1169 pair: transparent; library attribute
1172 For a :attr:`container` object: objects inside it are visible.
1175 pair: visited; library attribute
1178 For a room: is being, or has been, visited by the player.
1181 pair: workflag; library attribute
1184 Temporary internal flag, also available to the program.
1187 pair: worn; library attribute
1190 For a :attr:`clothing` object: is being worn.
1194 Optional entry points
1195 =====================
1197 These routines, if you supply them, are called when shown.
1200 Player has died; `deadflag=0` resurrects.
1203 The ">" prompt has been output.
1206 Player has won; `AMUSING_PROVIDED` is defined.
1209 The parser has input some text, set up the buffer and parse tables, and
1210 initialised :var:`wn` to 1.
1212 `ChooseObjects({object,flag})`
1213 Parser has found "`ALL`" or an ambiguous noun phrase and decided that
1214 `{object}` should be excluded (`flag` is 0), or included (`flag` is 1).
1215 The routine should return 0 to let this stand, 1 to force inclusion, or 2
1216 to force exclusion. If `flag` is 2, parser is undecided; routine should
1217 return appropriate score 0..9.
1220 The player has gone from one dark room to another.
1223 The player has died; :var:`deadflag` is 3 or more.
1226 Called after all actions.
1229 Called before all actions.
1232 **Mandatory; note British spelling**: called at start. Must set
1233 `location`; can return 2 to suppress game banner.
1236 Called during parsing.
1239 Called at the end of every :act:`Look` description.
1242 Called when room changes, before description is output.
1244 `ParseNoun({object})`
1245 Called to parse the `{object}`\'s name.
1247 `ParseNumber({byte_array,length})`
1248 Called to parse a number.
1250 `ParserError({number})`
1251 Called to handle an error.
1254 Completes the output of the score.
1256 `PrintTaskName({number})`
1257 Prints the name of the task.
1260 Called when an unusual verb is printed.
1263 Called after every turn.
1266 Called when an unusual verb is encountered.
1268 .. _group-1-actions:
1273 Group 1 actions support the 'meta' verbs. These are the standard actions
1274 and their triggering verbs.
1276 =================== ==================================================
1277 :act:`CommandsOff` "`RECORDING OFF`"
1278 :act:`CommandsOn` "`RECORDING [ON]`"
1279 :act:`CommandsRead` "`REPLAY`"
1280 :act:`FullScore` "`FULLSCORE`", "`FULL [SCORE]`"
1281 :act:`LMode1` "`BRIEF`", "`NORMAL`"
1282 :act:`LMode2` "`LONG`", "`VERBOSE`"
1283 :act:`LMode3` "`SHORT`", "`SUPERBRIEF`"
1284 :act:`NotifyOff` "`NOTIFY OFF`"
1285 :act:`NotifyOn` "`NOTIFY [ON]`"
1286 :act:`Objects` "`OBJECTS`"
1287 :act:`Places` "`PLACES`"
1288 :act:`Pronouns` "`[PRO]NOUNS`"
1289 :act:`Quit` "`DIE`", "`Q[UIT]`"
1290 :act:`Restart` "`RESTART`"
1291 :act:`Restore` "`RESTORE`"
1292 :act:`Save` "`CLOSE`"
1293 :act:`Score` "`SCORE`"
1294 :act:`ScriptOff` "`[TRAN]SCRIPT OFF`", "`NOSCRIPT`", "`UNSCRIPT`"
1295 :act:`ScriptOn` "`[TRAN]SCRIPT [ON]`"
1296 :act:`Verify` "`VERIFY`"
1297 :act:`Version` "`VERSION`"
1298 =================== ==================================================
1300 and the debug tools.
1302 ================== ===================================================
1303 :act:`ActionsOff` "`ACTIONS OFF`"
1304 :act:`ActionsOn` "`ACTIONS [ON]`"
1305 :act:`ChangesOff` "`CHANGES OFF`"
1306 :act:`ChangesOn` "`CHANGES [ON]`"
1307 :act:`Gonear` "`GONEAR`"
1308 :act:`Goto` "`GOTO`"
1309 :act:`Predictable` "`RANDOM`"
1310 :act:`RoutinesOff` "`MESSAGES OFF`", "`ROUTINES OFF`"
1311 :act:`RoutinesOn` "`MESSAGES [ON]`", "`ROUTINES [ON]`"
1312 :act:`Scope` "`SCOPE`"
1313 :act:`Showobj` "`SHOWOBJ`"
1314 :act:`Showverb` "`SHOWVERB`"
1315 :act:`TimersOff` "`DAEMONS OFF`", "`TIMERS OFF`"
1316 :act:`TimersOn` "`DAEMONS [ON]`", "`TIMERS [ON]`"
1317 :act:`TraceLevel` "`TRACE number`"
1318 :act:`TraceOff` "`TRACE OFF`"
1319 :act:`TraceOn` "`TRACE [ON]`"
1320 :act:`XAbstract` "`ABSTRACT`"
1321 :act:`XPurloin` "`PURLOIN`"
1322 :act:`XTree` "`TREE`"
1323 ================== ===================================================
1325 .. _group-2-actions:
1330 Group 2 actions usually work, given the right circumstances.
1332 .. tabularcolumns:: |l|p{5in}|
1334 ================ ===========================================================
1335 :act:`Close` "`CLOSE [UP]`", "`COVER [UP]`", "`SHUT [UP]`"
1336 :act:`Disrobe` "`DISROBE`", "`DOFF`", "`REMOVE`", "`SHED`", "`TAKE OFF`"
1337 :act:`Drop` "`DISCARD`", "`DROP`", "`PUT DOWN`", "`THROW`"
1339 :act:`Empty` "`EMPTY [OUT]`"
1340 :act:`EmptyT` "`EMPTY IN|INTO|ON|ONTO|TO`"
1341 :act:`Enter` "`CROSS`", "`ENTER`", "`GET IN|INTO|ON|ONTO`",
1342 "`GO IN|INSIDE|INTO|THROUGH`",
1343 "`LEAVE IN|INSIDE|INTO|THROUGH`", "`LIE IN|INSIDE|ON`",
1345 "`RUN IN|INSIDE|INTO|THROUGH`", "`SIT IN|INSIDE|ON`",
1346 "`SIT ON TOP OF`", "`STAND ON`",
1347 "`WALK IN|INSIDE|INTO|THROUGH`"
1348 :act:`Examine` "`CHECK`", "`DESCRIBE`", "`EXAMINE`",
1349 "`L[OOK] AT`", "`READ`", "`WATCH`", "`X`"
1350 :act:`Exit` "`EXIT`", "`GET OFF|OUT|UP`",
1351 "`LEAVE`", "`OUT[SIDE]`", "`STAND [UP]`"
1352 :act:`GetOff` "`GET OFF`"
1353 :act:`Give` "`FEED [TO]`", "`GIVE [TO]`", "`OFFER [TO]`", "`PAY [TO]`"
1354 :act:`Go` "`GO`", "`LEAVE`", "`RUN`", "`WALK`"
1355 :act:`GoIn` "`CROSS`", "`ENTER`", "`IN[SIDE]`"
1356 :act:`Insert` "`DISCARD IN|INTO`",
1357 "`DROP DOWN|IN|INTO`",
1359 "`PUT IN|INSIDE|INTO`",
1360 "`THROW DOWN|IN|INTO`"
1361 :act:`Inv` "`I[NV]`", "`INVENTORY`", "`TAKE INVENTORY`"
1362 :act:`InvTall` "`I[NV] TALL`", "`INVENTORY TALL`"
1363 :act:`InvWide` "`I[NV] WIDE`", "`INVENTORY WIDE`"
1364 :act:`Lock` "`LOCK WITH`"
1365 :act:`Look` "`L[OOK]`"
1366 :act:`Open` "`OPEN`", "`UNCOVER`", "`UNDO`", "`UNWRAP`"
1367 :act:`PutOn` "`DISCARD ON|ONTO`",
1371 :act:`Remove` "`GET FROM`", "`REMOVE FROM`", "`TAKE FROM|OFF`"
1372 :act:`Search` "`L[OOK] IN|INSIDE|INTO|THROUGH`", "`SEARCH`"
1373 :act:`Show` "`DISPLAY [TO]`", "`PRESENT [TO]`", "`SHOW [TO]`"
1374 :act:`SwitchOff` "`CLOSE OFF`", "`SCREW OFF`", "`SWITCH OFF`",
1375 "`TURN OFF`", "`TWIST OFF`"
1376 :act:`SwitchOn` "`SCREW ON`", "`SWITCH ON`",
1377 "`TURN ON`", "`TWIST ON`"
1378 :act:`Take` "`CARRY`", "`GET`", "`HOLD`",
1379 "`PEEL [OFF]`", "`PICK UP`",
1380 "`REMOVE`", "`TAKE`"
1381 :act:`Transfer` "`CLEAR TO`", "`MOVE TO`",
1382 "`PRESS TO`", "`PUSH TO`",
1383 "`SHIFT TO`", "`TRANSFER TO`"
1384 :act:`Unlock` "`OPEN WITH`", "`UNDO WITH`",
1386 :act:`VagueGo` "`GO`", "`LEAVE`", "`RUN`", "`WALK`"
1387 :act:`Wear` "`DON`", "`PUT ON`", "`WEAR`"
1388 ================ ===========================================================
1390 .. _group-3-actions:
1395 Group 3 actions are by default stubs which output a message and stop at the
1396 "before" stage (so there is no "after" stage).
1398 .. tabularcolumns:: |l|p{5in}|
1400 ================ ==========================================================
1401 :act:`Answer` "`ANSWER TO`", "`SAY TO`",
1402 "`SHOUT TO`", "`SPEAK TO`"
1403 :act:`Ask` "`ASK ABOUT`"
1404 :act:`AskFor` "`ASK FOR`"
1405 :act:`Attack` "`ATTACK`", "`BREAK`", "`CRACK`",
1406 "`DESTROY`", "`FIGHT`", "`HIT`",
1407 "`KILL`", "`MURDER`", "`PUNCH`",
1408 "`SMASH`", "`THUMP`", "`TORTURE`",
1410 :act:`Blow` "`BLOW`"
1411 :act:`Burn` "`BURN [WITH]`", "`LIGHT [WITH]`"
1412 :act:`Buy` "`BUY`" "`PURCHASE`"
1413 :act:`Climb` "`CLIMB [OVER|UP]`", "`SCALE`"
1414 :act:`Consult` "`CONSULT ABOUT|ON`",
1416 "`READ ABOUT IN`", "`READ IN`"
1417 :act:`Cut` "`CHOP`", "`CUT`", "`PRUNE`", "`SLICE`"
1418 :act:`Dig` "`DIG [WITH]`"
1419 :act:`Drink` "`DRINK`", "`SIP`", "`SWALLOW`"
1420 :act:`Fill` "`FILL`"
1421 :act:`Jump` "`HOP`", "`JUMP`", "`SKIP`"
1422 :act:`JumpOver` "`HOP OVER`", "`JUMP OVER`", "`SKIP OVER`"
1423 :act:`Kiss` "`EMBRACE`", "`HUG`", "`KISS`"
1424 :act:`Listen` "`HEAR`", "`LISTEN [TO]`"
1425 :act:`LookUnder` "`LOOK UNDER`"
1426 :act:`Mild` Various mild swearwords.
1428 :act:`Pray` "`PRAY`"
1429 :act:`Pull` "`DRAG`" "`PULL`"
1430 :act:`Push` "`CLEAR`", "`MOVE`", "`PRESS`",
1432 :act:`PushDir` "`CLEAR`", "`MOVE`", "`PRESS`",
1434 :act:`Rub` "`CLEAN`", "`DUST`", "`POLISH`",
1435 "`RUB`", "`SCRUB`", "`SHINE`",
1437 :act:`Set` "`ADJUST`", "`SET`"
1438 :act:`SetTo` "`ADJUST TO`", "`SET TO`"
1439 :act:`Sing` "`SING`"
1440 :act:`Sleep` "`NAP`", "`SLEEP`"
1441 :act:`Smell` "`SMELL`", "`SNIFF`"
1442 :act:`Sorry` "`SORRY`"
1443 :act:`Squeeze` "`SQUASH`", "`SQUEEZE`"
1444 :act:`Strong` Various strong swearwords.
1445 :act:`Swim` "`DIVE`", "`SWIM`"
1446 :act:`Swing` "`SWING [ON]`"
1447 :act:`Taste` "`TASTE`"
1448 :act:`Tell` "`TELL ABOUT`"
1449 :act:`Think` "`THINK`"
1450 :act:`ThrowAt` "`THROW AGAINST|AT|ON|ONTO`"
1451 :act:`Tie` "`ATTACH [TO]`", "`FASTEN [TO]`",
1452 "`FIX [TO]`", "`TIE [TO]`"
1453 :act:`Touch` "`FEEL`", "`FONDLE`", "`GROPE`", "`TOUCH`"
1454 :act:`Turn` "`ROTATE`", "`SCREW`", "`TURN`",
1455 "`TWIST`", "`UNSCREW`"
1456 :act:`Wait` "`WAIT`" "`Z`"
1457 :act:`Wake` "`AWAKE[N]`", "`WAKE [UP]`"
1458 :act:`WakeOther` "`AWAKE[N]`", "`WAKE [UP]`"
1459 :act:`Wave` "`WAVE`"
1460 :act:`WaveHands` "`WAVE`"
1461 :act:`Yes` "`Y[ES]`"
1462 ================ ==========================================================
1467 Fake actions handle some special cases, or represent "real" actions from
1468 the viewpoint of the second object.
1470 .. tabularcolumns:: |l|p{5in}|
1472 ===================== ======================================================
1473 :act:`LetGo` Generated by :act:`Remove`.
1474 :act:`ListMiscellany` Outputs a range of inventory messages.
1475 :act:`Miscellany` Outputs a range of utility messages.
1476 :act:`NotUnderstood` Generated when parser fails to interpret some
1478 :act:`Order` Receives things not handled by :prop:`orders`.
1479 :act:`PluralFound` Tells the parser that `parse_name()` has identified a
1481 :act:`Prompt` Outputs the prompt, normally ">".
1482 :act:`Receive` Generated by :act:`Insert` and :act:`PutOn`.
1483 :act:`TheSame` Generated when parser can't distinguish between two
1485 :act:`ThrownAt` Generated by :act:`ThrowAt`.
1486 ===================== ======================================================