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`.
+:obj:`compass`
+ A :attr:`container` object holding the twelve direction objects
+ :obj:`d_obj`, :obj:`e_obj`, :obj:`in_obj`, :obj:`n_obj`, :obj:`ne_obj`,
+ :obj:`nw_obj`, :obj:`out_obj`, :obj:`s_obj`, :obj:`se_obj`,
+ :obj:`sw_obj`, :obj:`u_obj`, :obj:`w_obj`.
-`LibraryMessages`
+:obj:`LibraryMessages`
If defined (between Includes of `Parser` and `VerbLib`), changes standard
library messages:
| `...`
| `];`
-`selfobj`
- The default player object. Avoid: use instead the `player` variable,
- which usually refers to `selfobj`.
+:obj:`selfobj`
+ The default player object. Avoid: use instead the :var:`player`
+ variable, which usually refers to :obj:`selfobj`.
-`thedark`
- A pseudo-room which becomes the `location` when there is no light
+:obj:`thedark`
+ A pseudo-room which becomes the :var:`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.
+In addition to the standard constants :const:`true` (1), :const:`false` (0)
+and :const:`nothing` (0), the Library defines :const:`NULL` (-1) for an
+`{action}`, `{property}` or `{pronoun}` whose current value is undefined.
`LIBRARY_PARSER`, `LIBRARY_ENGLISH`, `LIBRARY_VERBLIB` and
`LIBRARY_GRAMMAR` are defined to mark the end of inclusion of `Parser.h`,
`WITHOUT_DIRECTIONS`
De-activates standard compass directions (bar "`IN`" and "`OUT`"). Place
- alternative directions in the `compass`.
+ alternative directions in the :obj:`compass`.
Library variables
=================
-`action`
+.. index::
+ pair: action; library variable
+
+:var:`action`
The current `{action}`.
-`actor`
+.. index::
+ pair: actor; library variable
+
+:var:`actor`
The target of an instruction: the player, or an NPC.
-`deadflag`
+.. index::
+ pair: deadflag; library variable
+
+:var:`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.
+.. index::
+ pair: inventory_stage; library variable
+
+:var:`inventory_stage`
+ Used by :prop:`invent` and :prop:`list_together` properties.
+
+.. index::
+ pair: keep_silent; library variable
-`keep_silent`
- Normally `false`; `true` makes most :ref:`group 2 actions
+:var:`keep_silent`
+ Normally :const:`false`; :const:`true` makes most :ref:`group 2 actions
<group-2-actions>` silent.
-`location`
+.. index::
+ pair: location; library variable
+
+:var:`location`
The player's current room; unless that's dark, when it contains
- `thedark`, `real_location` contains the room.
+ :obj:`thedark`, :var:`real_location` contains the room.
+
+.. index::
+ pair: notify_mode; library variable
-`notify_mode`
- Normally `true`: `false` remains silent when score changes.
+:var:`notify_mode`
+ Normally :const:`true`: :const:`false` remains silent when score changes.
-`noun`
+.. index::
+ pair: noun; library variable
+
+:var:`noun`
The primary focus object for the current action.
-`player`
+.. index::
+ pair: player; library variable
+
+:var:`player`
The object acting on behalf of the human player.
-`real_location`
+.. index::
+ pair: real_location; library variable
+
+:var:`real_location`
The player's current room when in the dark.
-`score`
+.. index::
+ pair: score; library variable
+
+:var:`score`
The current score.
-`second`
+.. index::
+ pair: second; library variable
+
+:var:`second`
The secondary focus object for the current action.
-`self`
+.. index::
+ pair: self; library variable
+
+:var:`self`
The object which received a message. (Note: a run-time variable, not a
compile-time constant.)
-`sender`
+.. index::
+ pair: sender; library variable
+
+:var:`sender`
The object which sent a message (or `nothing`).
-`task_scores`
+.. index::
+ pair: task_scores; library variable
+
+:var:`task_scores`
A byte array holding scores for the task scoring system.
-`the_time`
+.. index::
+ pair: the_time; library variable
+
+:var:`the_time`
The game's clock, in minutes 0..1439 since midnight.
-`turns`
+.. index::
+ pair: turns; library variable
+
+:var:`turns`
The game's turn counter.
-`wn`
+.. index::
+ pair: wn; library variable
+
+:var:`wn`
The input stream word number, counting from 1.
.. _library-routines:
Library routines
================
+.. index::
+ pair: Achieved; library routine
+
`Achieved({expr})`
A scored task has been achieved.
+.. index::
+ pair: AfterRoutines; library routine
+
`AfterRoutines()`
In a :ref:`group 2 action <group-2-actions>`, controls output of "after"
messages.
+.. index::
+ pair: AllowPushDir; library routine
+
`AllowPushDir()`
An object can be pushed from one location to another.
+.. index::
+ pair: Banner; library routine
+
`Banner()`
Prints the game banner.
+.. index::
+ pair: ChangePlayer; library routine
+
`ChangePlayer({obj_id,flag})`
Player assumes the persona of the `{obj_id}`. If the optional `{flag}`
- is `true`, room descriptions include "(as `{object}`)".
+ is :const:`true`, room descriptions include "(as `{object}`)".
+
+.. index::
+ pair: CommonAncestor; library routine
`CommonAncestor({obj_id1,obj_id2})`
Returns the nearest object which has a parental relationship to both
`{obj_ids}`, or `nothing`.
+.. index::
+ pair: DictionaryLookup; library routine
+
`DictionaryLookup({byte_array,length})`
Returns address of word in dictionary, or 0 if not found.
+.. index::
+ pair: DrawStatusLine; library routine
+
`DrawStatusLine()`
Refreshes the status line; happens anyway at end of each turn.
+.. index::
+ pair: GetGNAOfObject; library routine
+
`GetGNAOfObject({obj_id})`
Returns gender-number-animation 0..11 of the `{obj_id}`.
+.. index::
+ pair: HasLightSource; library routine
+
`HasLightSource({obj_id})`
- Returns `true` if the `{obj_id}` has light.
+ Returns :const:`true` if the `{obj_id}` has light.
+
+.. index::
+ pair: IndirectlyContains; library routine
`IndirectlyContains({parnt_obj_id,obj_id})`
- Returns `true` if `{obj_id}` is currently a child or grand-child or
- great-grand-child... of the `{parent_object}`.
+ Returns :const:`true` if `{obj_id}` is currently a child or grand-child
+ or great-grand-child... of the `{parent_object}`.
+
+.. index::
+ pair: IsSeeThrough; library routine
`IsSeeThrough({obj_id})`
- Returns `true` if light can pass through the `{obj_id}`.
+ Returns :const:`true` if light can pass through the `{obj_id}`.
+
+.. index::
+ pair: Locale; library routine
`Locale({obj_id,"string1","string2"})`
Describes the contents of `{obj_id}`, and returns their number. After
objects with own paragraphs, the rest are listed preceded by `{string1}`
or `{string2}`.
+.. index::
+ pair: LoopOverScope; library routine
+
`LoopOverScope({routine_id,actor})`
Calls `{routine_id}({obj_id})` for each `{obj_id}` in scope. If the
optional `{actor}` is supplied, that defines the scope.
+.. index::
+ pair: MoveFloatingObjects; library routine
+
`MoveFloatingObjects()`
Adjusts positions of game's `found_in` objects.
+.. index::
+ pair: NextWord; library routine
+
`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.
+ Returns the next dictionary word in the input stream, incrementing
+ :var:`wn` by one. Returns :const:`false` if the word is not in the
+ dictionary, or if the input stream is exhausted.
+
+.. index::
+ pair: NextWordStopped; library routine
`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.
+ Returns the next dictionary word in the input stream, incrementing
+ :var:`wn` by one. Returns :const:`false` if the word is not in the
+ dictionary, -1 if the input stream is exhausted.
+
+.. index::
+ pair: NounDomain; library routine
`NounDomain({obj_id1,obj_id2,type})`
Performs object parsing; see also `ParseToken()`.
+.. index::
+ pair: ObjectIsUntouchable; library routine
+
`ObjectIsUntouchable({obj_id,flag})`
Tests whether there is a barrier - a container object which is not open -
- between player and `{obj_id}`. Unless the optional `{flag}` is `true`,
- outputs "You can't because ... is in the way". Returns `true` is a
- barrier is found, otherwise `false`.
+ between player and `{obj_id}`. Unless the optional `{flag}` is
+ :const:`true`, outputs "You can't because ... is in the way". Returns
+ :const:`true` is a barrier is found, otherwise :const:`false`.
+
+.. index::
+ pair: OffersLight; library routine
`OffersLight({obj_id})`
- Returns `true` if the `{obj_id}` offers light.
+ Returns :const:`true` if the `{obj_id}` offers light.
+
+.. index::
+ pair: ParseToken; library routine
`ParseToken({type,value})`
Performs general parsing; see also `NounDomain()`.
+.. index::
+ pair: PlaceInScope; library routine
+
`PlaceInScope({obj_id})`
- Used in an `add_to_scope` property or `scope=` token to put the
+ Used in an :prop:`add_to_scope` property or `scope=` token to put the
`{obj_id}` into scope for the parser.
+.. index::
+ pair: PlayerTo; library routine
+
`PlayerTo({obj_id,flag})`
Moves the player to `{obj_id}`. Prints its description unless optional
`{flag}` is 1 (no description) or 2 (as if walked in).
+.. index::
+ pair: PrintOrRun; library routine
+
`PrintOrRun({obj_id,property,flag})`
If `{obj_id.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.
+ unless optional `{flag}` is :const:`true`), and return :const:`true`. If
+ it's a routine, run it and return what the routine returns.
+
+.. index::
+ pair: PronounNotice; library routine
`PronounNotice({obj_id})`
Associates an appropriate pronoun with the `{obj_id}`.
+.. index::
+ pair: PronounValue; library routine
+
`PronounValue('{pronoun}')`
Returns the object to which '`it`' (or '`him`', '`her`', '`them`')
- currently refers, or `nothing`.
+ currently refers, or :const:`nothing`.
+
+.. index::
+ pair: ScopeWithin; library routine
`ScopeWithin({obj_id})`
- Used in an `add_to_scope` property or `scope=` token to put the contents
- of the `{obj_id}` in scope for the parser.
+ Used in an :prop:`add_to_scope` property or `scope=` token to put the
+ contents of the `{obj_id}` in scope for the parser.
+
+.. index::
+ pair: SetPronoun; library routine
`SetPronoun('{pronoun}',{obj_id})`
Defines the `{obj_id}` to which a given pronoun refers.
-`SetTime({expr1,expr2})`
+.. index::
+ pair: SetTime; library routine
+`SetTime({expr1,expr2})`
Sets `the_time` to `{expr1}` (in mins 0..1439 since midnight), running at
`{expr2}` -
| -ve: `{-expr2}` turns take one minute;
| zero: time stands still.
+.. index::
+ pair: StartDaemon; library routine
+
`StartDaemon({obj_id})`
Starts the `{obj_id}`\'s daemon.
+.. index::
+ pair: StartTimer; library routine
+
`StartTimer({obj_id,expr})`
- Starts the `{obj_id}`\'s timer, initialising its `time_left` to `{expr}`.
- The object's `time_out` property will be called after that number of
- turns have elapsed.
+ Starts the `{obj_id}`\'s timer, initialising its :prop:`time_left` to
+ `{expr}`. The object's :prop:`time_out` property will be called after
+ that number of turns have elapsed.
+
+.. index::
+ pair: StopDaemon; library routine
`StopDaemon({obj_id})`
Stops the `{obj_id}`\'s daemon.
+.. index::
+ pair: StopTimer; library routine
+
`StopTimer({obj_id})`
Stops the `{obj_id}`\'s timer.
+.. index::
+ pair: TestScope; library routine
+
`TestScope({obj_id,actor})`
- Returns `true` if the `{obj_id}` is in scope, otherwise `false`. If the
- optional `{actor}` is supplied, that defines the scope.
+ Returns :const:`true` if the `{obj_id}` is in scope, otherwise
+ :const:`false`. If the optional `{actor}` is supplied, that defines the
+ scope.
+
+.. index::
+ pair: TryNumber; library routine
`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.
+.. index::
+ pair: UnsignedCompare; library routine
+
`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.
+.. index::
+ pair: WordAddress; library routine
+
`WordAddress({expr})`
Returns a byte array containing the raw text of word `{expr}` in the
input stream.
+.. index::
+ pair: WordInProperty; library routine
+
`WordInProperty({word,obj_id,property})`
- Returns `true` if the dictionary `{word}` is listed in the `{property}`
- values for the `{obj_id}`.
+ Returns :const:`true` if the dictionary `{word}` is listed in the
+ `{property}` values for the `{obj_id}`.
+
+.. index::
+ pair: WordLength; library routine
`WordLength({expr})`
Returns the length of word `{expr}` in the input stream.
+.. index::
+ pair: WriteListFrom; library routine
+
`WriteListFrom({obj_id,expr})`
Outputs a list of `{obj_id}` 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`.
+.. index::
+ pair: YesOrNo; library routine
+
`YesOrNo()`
- Returns `true` if the player types "`YES`", `false` for "`NO`".
+ Returns :const:`true` if the player types "`YES`", :const:`false` for
+ "`NO`".
+
+.. index::
+ pair: ZRegion; library routine
`ZRegion({arg})`
Returns the type of its `{arg}` : 3 for a string address, 2 for a routine
=================
Where the `value` of a property can be a routine, several formats are
-possible (but remember: embedded "`]`" returns `false`, standalone "`]`"
-returns `true`):
+possible (but remember: embedded "`]`" returns :const:`false`, standalone
+"`]`" returns :const:`true`):
| `{property} [; {stmt}; {stmt}; ... ]`
| `{property} [; return {routine_id}(); ]`
However, if the property is additive then both values apply, with the
Object's value being considered first.
-`add_to_scope`
+.. index::
+ pair: add_to_scope; library property
+
+:prop:`add_to_scope`
For an object: additional objects which follow it in and out of scope.
The `{value}` can be a space-separated list of `{obj_ids}`, or a routine
which invokes `PlaceInScope()` or `ScopeWithin()` to specify objects.
-`after` |ADD|
+.. index::
+ pair: after; library property
+
+:prop:`after` |ADD|
For an object: receives every `{action}` and `{fake_action}` for which
this is the `{noun}`. For a room: receives every `{action}` which occurs
here.
The `{value}` is a routine of structure similar to a `switch` statement,
having cases for the appropriate `{actions}` (and an optional `default`
as well); it is invoked after the action has happened, but before the
- player has been informed. The routine should return `false` to continue,
- telling the player what has happened, or `true` to stop processing the
- action and produce no further output.
+ player has been informed. The routine should return :const:`false` to
+ continue, telling the player what has happened, or :const:`true` to stop
+ processing the action and produce no further output.
+
+.. index::
+ pair: article; library property
-`article`
+:prop:`article`
For an object: the object's indefinite article - the default is
automatically "a", "an" or "some". The `{value}` can be a string, or a
routine which outputs a string.
-`articles`
+.. index::
+ pair: articles; library property
+
+:prop:`articles`
For a non-English object: its definite and indefinite articles. The
`{value}` is an array of strings.
-`before` |ADD|
+.. index::
+ pair: before; library property
+
+:prop:`before` |ADD|
For an object: receives every `{action}` and `{fake_action}` for which
this is the `{noun}`. For a room: receives every action which occurs
here.
The `{value}` is a routine invoked before the action has happened. See
- `after`.
+ :prop:`after`.
+
+.. index::
+ pair: cant_go; library property
-`cant_go`
+:prop:`cant_go`
For a room: the message when the player attempts an impossible exit. The
`{value}` can be a string, or a routine which outputs a string.
-`capacity`
- For a `container` or `supporter` object: the number of objects which can
- be placed in or on it - the default is 100.
+.. index::
+ pair: capacity; library property
- For the player: the number which can be carried - `selfobj` has an
+:prop:`capacity`
+ For a :attr:`container` or :attr:`supporter` object: the number of
+ objects which can be placed in or on it - the default is 100.
+
+ For the player: the number which can be carried - :obj:`selfobj` has an
initial capacity of `MAX_CARRIED`.
The `{value}` can be a number, or a routine which returns a number.
-`d_to`
+.. index::
+ pair: d_to; library property
+
+:prop:`d_to`
For a room: a possible exit. The `{value}` can be
- * `false` (the default): not an exit;
+ * :const:`false` (the default): not an exit;
* a string: output to explain why this is not an exit;
* a `{room}`: the exit leads to this room;
- * a `door` object: the exit leads through this door;
- * a routine which should return `false`, a string, a `{room}`, a `door`
- object, or `true` to signify "not an exit" and produce no further
- output.
+ * a :obj:`door` object: the exit leads through this door;
+ * a routine which should return :const:`false`, a string, a `{room}`, a
+ :obj:`door` object, or :const:`true` to signify "not an exit" and
+ produce no further output.
-`daemon`
+.. index::
+ pair: daemon; library property
+
+:prop:`daemon`
The `{value}` is a routine which can be activated by
`StartDaemon({obj_id})` and which then runs once each turn until
deactivated by `StopDaemon({obj_id})`.
-`describe` |ADD|
+.. index::
+ pair: describe; library property
+
+:prop:`describe` |ADD|
For an object: called before the object's description is output. For a
room: called before the room's (long) description is output.
- The `{value}` is a routine which should return `false` to continue,
- outputting the usual description, or `true` to stop processing and
+ The `{value}` is a routine which should return :const:`false` to continue,
+ outputting the usual description, or :const:`true` to stop processing and
produce no further output.
-`description`
+.. index::
+ pair: description; library property
+
+:prop:`description`
For an object: its description (output by `Examine`).
For a room: its long description (output by `Look`).
The `{value}` can be a string, or a routine which outputs a string.
-`door_dir`
- For a `compass` object (`d_obj`, `e_obj`, ...): the direction in which an
- attempt to move to this object actually leads.
+.. index::
+ pair: door_dir; library property
+
+:prop:`door_dir`
+ For a :obj:`compass` object (:obj:`d_obj`, :obj:`e_obj`, ...): the
+ direction in which an attempt to move to this object actually leads.
+
+ For a :obj:`door` object: the direction in which this door leads.
- For a `door` object: the direction in which this door leads.
+ The `{value}` can be a directional property (:prop:`d_to`, :prop:`e_to`,
+ \...), or a routine which returns such a property.
- The `{value}` can be a directional property (`d_to`, `e_to`, ...), or a
- routine which returns such a property.
+.. index::
+ pair: door_to; library property
-`door_to`
+:prop:`door_to`
For a `door` object: where it leads. The value can be
- * `false` (the default): leads nowhere;
+ * :const:`false` (the default): leads nowhere;
* a string: output to explain why door leads nowhere;
* a `{room}`: the door leads to this room;
- * a routine which should return `false`, a string, a `{room}`, or `true`
- to signify "leads nowhere" without producing any output.
+ * a routine which should return :const:`false`, a string, a `{room}`, or
+ :const:`true` to signify "leads nowhere" without producing any output.
+
+.. index::
+ pair: e_to; library property
+
+:prop:`e_to`
+ See :prop:`d_to`.
-`e_to`
- See `d_to`.
+.. index::
+ pair: each_turn; library property
-`each_turn` |ADD|
+:prop:`each_turn` |ADD|
Invoked at the end of each turn (after all appropriate daemons and
timers) whenever the object is in scope. The `{value}` can be a string,
or a routine.
-`found_in`
+.. index::
+ pair: found_in; library property
+
+:prop:`found_in`
For an object: the rooms where this object can be found, unless it has
- the `absent` attribute. The `{value}` can be
+ the :attr:`absent` attribute. The `{value}` can be
* a space-separated list of `{rooms}` (where this object can be found) or
`{obj_ids}` (whose locations are tracked by this object);
- * a routine which should return `true` if this object can be found in the
- current location, otherwise `false`.
+ * a routine which should return :const:`true` if this object can be found
+ in the current location, otherwise :const:`false`.
+
+.. index::
+ pair: grammar; library property
+
+:prop:`grammar`
+ For an :attr:`animate` or :attr:`talkable` object: the `{value}` is a
+ routine called when the parser knows that this object is being addressed,
+ but has yet to test the grammar. The routine should return
+ :const:`false` to continue, :const::const:`true` to indicate that the
+ routine has parsed the entire command, or a dictionary word ('`word`' or
+ -'`word`').
+
+.. index::
+ pair: in_to; library property
-`grammar`
- For an `animate` or `talkable` object: the `{value}` is a routine called
- when the parser knows that this object is being addressed, but has yet to
- test the grammar. The routine should return `false` to continue, `true`
- to indicate that the routine has parsed the entire command, or a
- dictionary word ('`word`' or -'`word`').
+:prop:`in_to`
+ See :prop:`d_to`.
-`in_to`
- See `d_to`.
+.. index::
+ pair: initial; library property
-`initial`
+:prop:`initial`
For an object: its description before being picked up.
For a room: its description when the player enters the room.
The `{value}` can be a string, or a routine which outputs a string.
-`inside_description`
+.. index::
+ pair: inside_description; library property
+
+:prop:`inside_description`
For an `enterable` object: its description, output as part of the room
description when the player is inside the object.
The `{value}` can be a string, or a routine which outputs a string.
-`invent`
+.. index::
+ pair: invent; library property
+
+:prop:`invent`
For an object: the `{value}` is a routine for outputting the object's
inventory listing, which is called twice. On the first call nothing has
- been output; `inventory_stage` has the value 1, and the routine should
- return `false` to continue, or `true` to stop processing and produce no
- further output. On the second call the object's indefinite article and
- short name have been output, but not any subsidiary information;
- `inventory_stage` has the value 2, and the routine should return `false`
- to continue, or `true` to stop processing and produce no further output.
-
-`life` |ADD|
+ been output; :var:`inventory_stage` has the value 1, and the routine
+ should return :const:`false` to continue, or :const:`true` to stop
+ processing and produce no further output. On the second call the
+ object's indefinite article and short name have been output, but not any
+ subsidiary information; :var:`inventory_stage` has the value 2, and the
+ routine should return :const:`false` to continue, or :const:`true` to
+ stop processing and produce no further output.
+
+.. index::
+ pair: life; library property
+
+:prop:`life` |ADD|
For an `animate` object: receives person-to-person actions (`Answer`,
`Ask`, `Attack`, `Give`, `Kiss`, `Order`, `Show`, `Tell`, `ThrowAt` and
`WakeOther`) for which this is the `{noun}`. The `{value}` is a routine
of structure similar to a `switch` statement, having cases for the
appropriate `{actions}` (and an optional default as well). The routine
- should return `false` to continue, telling the player what has happened,
- or `true` to stop processing the action and produce no further output.
+ should return :const:`false` to continue, telling the player what has
+ happened, or :const:`true` to stop processing the action and produce no
+ further output.
-`list_together`
+.. index::
+ pair: list_together; library property
+:prop:`list_together`
For an object: groups related objects when outputting an inventory or
room contents list. The `{value}` can be
* a `{string}`: all objects having this value are grouped as a count of
the string;
* a routine which is called twice. On the first call nothing has been
- output; `inventory_stage` has the value 1, and the routine should
- return `false` to continue, or `true` to stop processing and produce no
- further output. On the second call the list has been output;
- `inventory_stage` has the value 2, and there is no test on the return
- value.
+ output; :var:`inventory_stage` has the value 1, and the routine should
+ return :const:`false` to continue, or :const::const:`true` to stop
+ processing and produce no further output. On the second call the list
+ has been output; :var:`inventory_stage` has the value 2, and there is
+ no test on the return value.
+
+.. index::
+ pair: n_to; library property
-`n_to`
- See `d_to`.
+:prop:`n_to`
+ See :prop:`d_to`.
-`name` |ADD|
+.. index::
+ pair: name; library property
+
+:prop:`name` |ADD|
Defines a space-separated list of words which are added to the Inform
dictionary. Each word can be supplied in apostrophes '...' or quotes
"..."; in all other cases only words in apostrophes update the
For a room: outputs "does not need to be referred to".
-`ne_to`
- See `d_to`.
+.. index::
+ pair: ne_to; library property
+
+:prop:`ne_to`
+ See :prop:`d_to`.
-`number`
+.. index::
+ pair: number; library property
+
+:prop:`number`
For an object or room: the `{value}` is a general-purpose variable freely
- available for use by the program. A `player` object must provide (but
- not use) this variable.
+ available for use by the program. A :var:`player` object must provide
+ (but not use) this variable.
+
+.. index::
+ pair: nw_to; library property
+
+:prop:`nw_to`
+ See :prop:`d_to`.
+
+.. index::
+ pair: orders; library property
-`nw_to`
- See `d_to`.
+:prop:`orders` |ADD|
+ For an :attr:`animate` or :attr:`talkable` object: the `{value}` is a
+ routine called to carry out the player's orders. The routine should
+ return :const:`false` to continue, or :const:`true` to stop processing
+ the action and produce no further output.
+
+.. index::
+ pair: out_to; library property
-`orders` |ADD|
- For an `animate` or `talkable` object: the `{value}` is a routine called
- to carry out the player's orders. The routine should return `false` to
- continue, or `true` to stop processing the action and produce no further
- output.
+:prop:`out_to`
+ See :prop:`d_to`.
-`out_to`
- See `d_to`.
+.. index::
+ pair: parse_name; library property
-`parse_name`
+:prop:`parse_name`
For an object: the `{value}` is a routine called to parse an object's
name. The routine should return zero if the text makes no sense, -1 to
cause the parser to resume, or the positive number of words matched.
-`plural`
+.. index::
+ pair: plural; library property
+
+:prop:`plural`
For an object: its plural form, when in the presence of others like it.
The `{value}` can be a string, or a routine which outputs a string.
-`react_after`
+.. index::
+ pair: react_after; library property
+
+:prop:`react_after`
For an object: detects nearby actions - those which take place when this
object is in scope. The `{value}` is a routine invoked after the action
- has happened, but before the player has been informed. See `after`.
+ has happened, but before the player has been informed. See :prop:`after`.
+
+.. index::
+ pair: react_before; library property
-`react_before`
+:prop:`react_before`
For an object: detects nearby actions - those which take place when this
object is in scope. The `{value}` is a routine invoked before the action
- has happened. See `after`.
+ has happened. See :prop:`after`.
-`s_to`
+.. index::
+ pair: s_to; library property
-`se_to`
- See `d_to`.
+:prop:`s_to`
+ See :prop:`d_to`.
-`short_name`
+.. index::
+ pair: se_to; library property
+
+:prop:`se_to`
+ See :prop:`d_to`.
+
+.. index::
+ pair: short_name; library property
+
+:prop:`short_name`
For an object: an alternative or extended short name. The `{value}` can
be a string, or a routine which outputs a string. The routine should
- return `false` to continue by outputting the object's *actual* short name
- (from the head of the object definition), or `true` to stop processing
- the action and produce no further output.
+ return :const:`false` to continue by outputting the object's *actual*
+ short name (from the head of the object definition), or :const:`true` to
+ stop processing the action and produce no further output.
-`short_name_indef`
+.. index::
+ pair: short_name_indef; library property
+
+:prop:`short_name_indef`
For a non-English object: the short name when preceded by an indefinite
object. The `{value}` can be a string, or a routine which outputs a
string.
-`sw_to`
- See `d_to`.
+.. index::
+ pair: sw_to; library property
+
+:prop:`sw_to`
+ See :prop:`d_to`.
+
+.. index::
+ pair: time_left; library property
-`time_left`
+:prop:`time_left`
For a timer object: the `{value}` is a variable to hold the number of
turns left until this object's timer - activated and initialised by
`StartTimer({obj_id})` - counts down to zero and invokes the object's
`time_out` property.
-`time_out`
+.. index::
+ pair: time_out; library property
+
+:prop:`time_out`
For a timer object: the `{value}` is a routine which is run when the
- object's `time_left` value - initialised by `StartTimer({obj_id})`, and
- not in the meantime cancelled by `StopTimer({obj_id})` - counts down to
- zero.
+ object's :prop:`time_left` value - initialised by `StartTimer({obj_id})`,
+ and not in the meantime cancelled by `StopTimer({obj_id})` - counts down
+ to zero.
+
+.. index::
+ pair: u_to; library property
+
+:prop:`u_to`
+ See :prop:`d_to`.
+
+.. index::
+ pair: w_to; library property
+
+:prop:`w_to`
+ See :prop:`d_to`.
+
+.. index::
+ pair: when_closed; library property
-`u_to`
+:prop:`when_closed`
-`w_to`
- See `d_to`.
+.. index::
+ pair: when_open; library property
-`when_closed`
+:prop:`when_open`
+ For a :attr:`container` or :attr:`door` object: used when including this
+ object in a room's long description. The `{value}` can be a string, or a
+ routine which outputs a string.
+
+.. index::
+ pair: when_off; library property
+
+:prop:`when_off`
-`when_open`
- For a `container` or `door` object: used when including this object in a
+.. index::
+ pair: when_on; library property
+
+:prop:`when_on`
+ For a :attr:`switchable` object: used when including this object in a
room's long description. The `{value}` can be a string, or a routine
which outputs a string.
-`when_off`
-
-`when_on`
- For a `switchable` object: used when including this object in a room's
- long description. The `{value}` can be a string, or a routine which
- outputs a string.
+.. index::
+ pair: with_key; library property
-`with_key`
- For a `lockable` object: the `{obj_id}` (generally some kind of key)
- needed to lock and unlock the object, or `nothing` if no key fits.
+:prop:`with_key`
+ For a :attr:`lockable` object: the `{obj_id}` (generally some kind of
+ key) needed to lock and unlock the object, or :const:`nothing` if no key
+ fits.
.. _object-attrs:
Object attributes
=================
-`absent`
- For a floating object (one with a `found_in` property, which can
- appear in many rooms): is no longer there.
+.. index::
+ pair: absent; library attribute
+
+:attr:`absent`
+ For a floating object (one with a :prop:`found_in` property, which can
+ appear in many rooms): is no longer there.
+
+.. index::
+ pair: animate; library attribute
+
+:attr:`animate`
+ For an object: is a living creature.
+
+.. index::
+ pair: clothing; library attribute
+
+:attr:`clothing`
+ For an object: can be worn.
+
+.. index::
+ pair: concealed; library attribute
+
+:attr:`concealed`
+ For an object: is present but hidden from view.
+
+.. index::
+ pair: container; library attribute
+
+:attr:`container`
+ For an object: other objects can be put in (but not on) it.
+
+.. index::
+ pair: door; library attribute
+
+:attr:`door`
+ For an object: is a door or bridge between rooms.
+
+.. index::
+ pair: edible; library attribute
+
+:attr:`edible`
+ For an object: can be eaten.
+
+.. index::
+ pair: enterable; library attribute
+
+:attr:`enterable`
+ For an object: can be entered.
+
+.. index::
+ pair: female; library attribute
+
+:attr:`female`
+ For an :attr:`animate` object: is female.
+
+.. index::
+ pair: general; library attribute
+
+:attr:`general`
+ For an object or room: a general-purpose flag.
+
+.. index::
+ pair: light; library attribute
+
+:attr:`light`
+ For an object or room: is giving off light.
+
+.. index::
+ pair: lockable; library attribute
+
+:attr:`lockable`
+ For an object: can be locked; see the :prop:`with_key` property.
+
+.. index::
+ pair: locked; library attribute
+
+:attr:`locked`
+ For an object: can't be opened.
+
+.. index::
+ pair: male; library attribute
+
+:attr:`male`
+ For an :attr:`animate` object: is male.
+
+.. index::
+ pair: moved; library attribute
+
+:attr:`moved`
+ For an object: is being, or has been, taken by the player.
+
+.. index::
+ pair: neuter; library attribute
+
+:attr:`neuter`
+ For an :attr:`animate` object: is neither male nor female.
-`animate`
- For an object: is a living creature.
+.. index::
+ pair: on; library attribute
-`clothing`
- For an object: can be worn.
+:attr:`on`
+ For a :attr:`switchable` object: is switched on.
-`concealed`
- For an object: is present but hidden from view.
+.. index::
+ pair: open; library attribute
-`container`
- For an object: other objects can be put in (but not on) it.
+:attr:`open`
+ For a :attr:`container` or door object: is open.
-`door`
- For an object: is a door or bridge between rooms.
+.. index::
+ pair: openable; library attribute
-`edible`
- For an object: can be eaten.
+:attr:`openable`
+ For a :attr:`container` or :attr:`door` object: can be opened.
-`enterable`
- For an object: can be entered.
+.. index::
+ pair: pluralname; library attribute
-`female`
- For an `animate` object: is female.
+:attr:`pluralname`
+ For an object: is plural.
-`general`
- For an object or room: a general-purpose flag.
+.. index::
+ pair: proper; library attribute
-`light`
- For an object or room: is giving off light.
+:attr:`proper`
+ For an object: the short name is a proper noun, therefore not to be
+ preceded by "The" or "the".
-`lockable`
- For an object: can be locked; see the `with_key` property.
+.. index::
+ pair: scenery; library attribute
-`locked`
- For an object: can't be opened.
+:attr:`scenery`
+ For an object: can't be taken; is not listed in a room description.
-`male`
- For an `animate` object: is male.
+.. index::
+ pair: scored; library attribute
-`moved`
- For an object: is being, or has been, taken by the player.
+:attr:`scored`
+ For an object: awards `OBJECT_SCORE` points when taken for the first
+ time. For a room: awards `ROOM_SCORE` points when visited for the
+ first time.
-`neuter`
- For an `animate` object: is neither male nor female.
+.. index::
+ pair: static; library attribute
-`on`
- For a `switchable` object: is switched on.
+:attr:`static`
+ For an object: can't be taken.
-`open`
- For a `container` or door object: is open.
+.. index::
+ pair: supporter; library attribute
-`openable`
- For a `container` or `door` object: can be opened.
+:attr:`supporter`
+ For an object: other objects can be put on (but not in) it.
-`pluralname`
- For an object: is plural.
+.. index::
+ pair: switchable; library attribute
-`proper`
- For an object: the short name is a proper noun, therefore not to be
- preceded by "The" or "the".
+:attr:`switchable`
+ For an object: can be switched off or on.
-`scenery`
- For an object: can't be taken; is not listed in a room description.
+.. index::
+ pair: talkable; library attribute
-`scored`
- For an object: awards `OBJECT_SCORE` points when taken for the first
- time. For a room: awards `ROOM_SCORE` points when visited for the
- first time.
+:attr:`talkable`
+ For an object: can be addressed in "object, do this" style.
-`static`
- For an object: can't be taken.
+.. index::
+ pair: transparent; library attribute
-`supporter`
- For an object: other objects can be put on (but not in) it.
+:attr:`transparent`
+ For a :attr:`container` object: objects inside it are visible.
-`switchable`
- For an object: can be switched off or on.
+.. index::
+ pair: visited; library attribute
-`talkable`
- For an object: can be addressed in "object, do this" style.
+:attr:`visited`
+ For a room: is being, or has been, visited by the player.
-`transparent`
- For a `container` object: objects inside it are visible.
+.. index::
+ pair: workflag; library attribute
-`visited`
- For a room: is being, or has been, visited by the player.
+:attr:`workflag`
+ Temporary internal flag, also available to the program.
-`workflag`
- Temporary internal flag, also available to the program.
+.. index::
+ pair: worn; library attribute
-`worn`
- For a `clothing` object: is being worn.
+:attr:`worn`
+ For a :attr:`clothing` object: is being worn.
.. _entry-points:
`BeforeParsing()`
The parser has input some text, set up the buffer and parse tables, and
- initialised `wn` to 1.
+ initialised :var:`wn` to 1.
`ChooseObjects({object,flag})`
Parser has found "`ALL`" or an ambiguous noun phrase and decided that
projects / ibg.git / blobdiff