DM4 §A2: Library properties

## §A2 Library properties

The following table lists every library-defined property. The banner headings give the name, what type of value makes sense and the default value (if other than 0). The symbol (+) means “this property is additive” so that inherited values from class definitions pile up into a list, rather than wipe each other out. Recall that `false` is the value 0 and `true` the value 1.

`n_to, s_to, e_to, w_to, ...` | Room, object or routine

For rooms These twelve properties (there are also `ne_to`, `nw_to`, `se_to`, `sw_to`, `in_to`, `out_to`, `u_to` and `d_to`) are the map connections for the room. A value of 0 means “can't go this way”. Otherwise, the value should either be a room or a `door` object: thus, `e_to` might be set to `crystal_bridge` if the direction “east” means “over the crystal bridge”.
Routine returns The room or object the map connects to; or 0 for “can't go this way”; or 1 for “can't go this way; stop and print nothing further”.
Warning Do not confuse the direction properties `n_to` and so on with the twelve direction objects, `n_obj` et al.

`add_to_scope` | List of objects or routine

For objects When this object is in scope (unless it was itself only placed in scope by `PlaceInScope`) so are all those listed, or all those nominated by the routine. A routine given here should call `PlaceInScope(obj)` to put `obj` in scope.
No return value

`after` | Routine `NULL` (+)

Receives actions after they have happened, but before the player has been told of them.
For rooms All actions taking place in this room.
For objects All actions for which this object is `noun` (the first object specified in the command); and all fake actions for it.
Routine returns `false` to continue (and tell the player what has happened), `true` to stop here (printing nothing).
The `Search` action is a slightly special case. Here, `after` is called when it is clear that it would be sensible to look inside the object (e.g., it's an open container in a light room) but before the contents are described.

`article` | String or routine `"a"`

For objects Indefinite article for object or routine to print one.
No return value

`articles` | Array of strings

For objects If given, these are the articles used with the object's name. (Provided for non-English languages where irregular nouns may have unusual vowel-contraction rules with articles: e.g., with French non-mute ‘H’.)

`before` | Routine `NULL` (+)

Receives advance warning of actions (or fake actions) about to happen.
For rooms All actions taking place in this room.
For objects All actions for which this object is `noun` (the first object specified in the command); and all fake actions, such as `Receive` and `LetGo` if this object is the container or supporter concerned.
Routine returns `false` to continue with the action, `true` to stop here (printing nothing).

First special case: A vehicle object receives the `Go` action if the player is trying to drive around in it. In this case:
Routine returns 0 to disallow as usual; 1 to allow as usual, moving vehicle and player; 2 to disallow but do (and print) nothing; 3 to allow but do (and print) nothing. If you want to move the vehicle in your own code, return 3, not 2: otherwise the old location may be restored by subsequent workings.
Second special case: in a `PushDir` action, the `before` routine must call `AllowPushDir()` and then return `true` in order to allow the attempt (to push an object from one room to another) to succeed.

`cant_go` | String or routine `"You can't go that way."`

For rooms Message, or routine to print one, when a player tries to go in an impossible direction from this room.
No return value

`capacity` | Number or routine 100

For objects Number of objects a `container` or `supporter` can hold.
For the player-object Number of things the player can carry (when the player is this object); the default player object (`selfobj`) has `capacity` initially set to the constant `MAX_CARRIED`.

`daemon` | Routine

This routine is run each turn, once it has been activated by a call to `StartDaemon`, and until stopped by a call to `StopDaemon`.

`describe` | Routine `NULL` (+)

For objects Called when the object is to be described in a room description, before any paragraph break (i.e., skipped line) has been printed. A sometimes useful trick is to print nothing in this routine and return `true`, which makes an object ‘invisible’.
For rooms Called before a room's long (“look”) description is printed.
Routine returns `false` to describe in the usual way, `true` to stop printing here.

`description` | String or routine

For objects The `Examine` message, or a routine to print one out.
For rooms The long (“look”) description, or a routine to print one out.
No return value

`door_dir` | Direction property or routine

For compass objects When the player tries to go in this direction, e.g., by typing the name of this object, then the map connection tried is the value of this direction property for the current room. For example, the `n_obj` “north” object normally has `door_dir` set to `n_to`.
For objects The direction that this `door` object goes via (for instance, a bridge might run east, in which case this would be set to `e_to`).
Routine returns The direction property to try.

`door_to` | Room or routine

For objects The place this door object leads to. A value of 0 means “leads nowhere”.
Routine returns The room. Again, 0 (or `false`) means “leads nowhere”. Further, 1 (or `true`) means “stop the movement action immediately and print nothing further”.

`each_turn` | String or routine `NULL` (+)

String to print, or routine to run, at the end of each turn in which the object is in scope (after all timers and daemons for that turn have been run).
No return value

`found_in` | List of rooms or routine

This object will be found in all of the listed rooms, or if the routine says so, unless it has the attribute `absent`. If an object in the list is not a room, it means “present in the same room as this object”.
Routine returns `true` to be present, otherwise `false`. The routine can look at the current `location` in order to decide.
Warning This property is only looked at when the player changes rooms.

`grammar` | Routine

For `animate` or `talkable` objects This is called when the parser has worked out that the object in question is being spoken to, and has decided the `verb_word` and `verb_wordnum` (the position of the verb word in the word stream) but hasn't yet tried any grammar. The routine can, if it wishes, parse past some words (provided it moves `verb_wordnum` on by the number of words it wants to eat up).
Routine returns `false` to carry on as usual; `true` to indicate that the routine has parsed the entire command itself, and set up `action`, `noun` and `second` to the appropriate order; or a dictionary value for a verb, such as `'take'`, to indicate “parse the command from this verb's grammar instead”; or minus such a value, e.g. `-'take'`, to indicate “parse from this verb and then parse the usual grammar as well”.

`initial` | String or routine

For objects The description of an object not yet picked up, used when a room is described; or a routine to print one out.
For rooms Printed or run when the room is arrived in, either by ordinary movement or by `PlayerTo`.
Warning If the object is a `door`, or a `container`, or is `switchable`, then use one of the `when_` properties rather than `initial`.
No return value

`inside_description` | String or routine

For objects Printed as part or all of a room description when the player is inside the given object, which must be `enterable`.

`invent` | Routine

This routine is for changing an object's inventory listing. If provided, it's called twice, first with the variable `inventory_stage` set to 1, second with it set to 2. At stage 1, you have an entirely free hand to print a different inventory listing.
Routine returns Stage 1: `false` to continue; `true` to stop here, printing nothing further about the object or its contents.
At stage 2, the object's indefinite article and short name have already been printed, but messages like “ (providing light)” haven't. This is an opportunity to add something like “ (almost empty)".
Routine returns Stage 2: `false` to continue; `true` to stop here, printing nothing further about the object or its contents.

`life` | Routine `NULL` (+)

This routine holds rules about `animate` objects, behaving much like `before` and `after` but only handling the person-to-person events:

`Attack Kiss WakeOther ThrowAt Give Show Ask Tell Answer Order`

See §17, §18 and the properties `orders` and `grammar`.
Routine returns `true` to stop and print nothing, `false` to resume as usual (for example, printing “Miss Gatsby has better things to do.”).

`list_together` | Number, string or routine

For objects Objects with the same `list_together` value are grouped together in object lists (such as inventories, or the miscellany at the end of a room description). If a string such as `"fish"` is given, then such a group will be headed with text such as `"five fish"`.
A routine, if given, is called at two stages in the process (once with the variable `inventory_stage` set to 1, once with it set to 2). These stages occur before and after the group is printed; thus, a preamble or postscript can be printed. Also, such a routine may change the variable `c_style` (which holds the current list style). On entry, the variable `parser_one` holds the first object in the group, and `parser_two` the current depth of recursion in the list. Applying `x=NextEntry(x,parser_two);` moves `x` on from `parser_one` to the next item in the group. Another helpful variable is `listing_together`, set up to the first object of a group being listed (or to 0 whenever no group is being listed).
Routine returns Stage 1: `false` to continue, `true` not to print the group's list at all.
Routine returns Stage 2: No return value.

`name` | List of dictionary words (+)

For objects A list of dictionary words referring to this object.
Warning The `parse_name` property of an object may take precedence over this, if present.
For rooms A list of words which the room understands but which refer to things which “do not need to be referred to in this game”; these are only looked at if all other attempts to understand the player's command have failed.
Warning Uniquely in Inform syntax, these dictionary words are given in double quotes `"thus"`, whereas in all other circumstances they would be `'thus'`. This means they can safely be only one letter long without ambiguity.

`number` | Any value

A general purpose property left free: conventionally holding a number like “number of turns' battery power left”. (Now unnecessary, `number` is a feature left over from earlier versions of Inform where it was less easy to make new properties.)
For compass objects Note that the standard compass objects defined by the library all provide a `number` property, in case this might be useful to the designer.

`orders` | Routine

For `animate` or `talkable` objects This carries out the player's orders (or doesn't, as it sees fit): it looks at `actor`, `action`, `noun` and `second` to do so. Unless this object is the current player, `actor` is irrelevant (it is always the player) and the object is the person being ordered about.
If the player typed an incomprehensible command, like “robot, og sthou”, then the action is `NotUnderstood` and the variable `etype` holds the parser's error number.
If this object is the current player then `actor` is the person being ordered about. `actor` can either be this object — in which case an action is being processed, because the player has typed an ordinary command — or can be some other object, in which case the player has typed an order. See §18 for how to write `orders` routines in these cases.
Routine returns `true` to stop and print nothing further; `false` to continue. (Unless the object is the current player, the `life` routine's `Order` section gets an opportunity to meddle next; after that, Inform gives up.)

`parse_name` | Routine

For objects To parse an object's name (this overrides the `name` but is also used in determining if two objects are describably identical). This routine should try to match as many words as possible in sequence, reading them one at a time by calling `NextWord()`. (It can leave the “word marker” variable `wn` anywhere it likes).
Routine returns 0 if the text didn't make any sense at all, −1 to make the parser resume its usual course (looking at the `name`), or the number of words in a row which successfully matched.
In addition to this, if the text matched seems to be in the plural (for instance, a blind mouse object reading `blind mice`), the routine can set the variable `parser_action` to the value `##PluralFound`. The parser will then match with all of the different objects understood, rather than ask a player which of them is meant.
A `parse_name` routine may also (voluntarily) assist the parser by telling it whether or not two objects which share the same `parse_name` routine are identical. (They may share the same routine if they both inherit it from a class.) If, when it is called, the variable `parser_action` is set to `##TheSame` then this is the reason. It can then decide whether or not the objects `parser_one` and `parser_two` are indistinguishable.

Routine returns −1 if the objects are indistinguishable, −2 if not.

`plural` | String or routine

For objects The plural name of an object (when in the presence of others like it), or routine to print one; for instance, a wax candle might have `plural` set to `"wax candles"`.
No return value

`react_after` | Routine

For objects Acts like an `after` rule, but detects any actions in the vicinity (any actions which take place when this object is in scope).
Routine returns `true` to print nothing further; `false` to carry on.

`react_before` | Routine

For objects Acts like a `before` rule, but detects any actions in the vicinity (any actions which take place when this object is in scope).
Routine returns `true` to stop the action, printing nothing; `false` to carry on.

`short_name` | Routine

For objects The short name of an object (like “brass lamp”), or a routine to print it.

Routine returns `true` to stop here, `false` to carry on by printing the object's ‘real’ short name (the string given at the head of the object's definition). It's sometimes useful to print text like `"half-empty "` and then return `false`.

`short_name_indef` | Routine

For objects If set, this form of the short name is used when the name is prefaced by an indefinite article. (This is not useful in English-language games, but in other languages adjectival parts of names agree with the definiteness of the article.)

`time_left` | Number

Number of turns left until the timer for this object (if set, which must be done using `StartTimer`) goes off. Its initial value is of no significance, as `StartTimer` will write over this, but a timer object must provide the property. If the timer is currently set, the value 0 means “will go off at the end of the current turn”, the value 1 means “… at the end of next turn” and so on.

`time_out` | Routine `NULL` (+)

Routine to run when the timer for this object goes off (having been set by `StartTimer` and not in the mean time stopped by `StopTimer`).
Warning A timer object must also provide a `time_left` property.

`when_closed` | String or routine

For objects Description, or routine to print one, of something closed (a `door` or `container`) in a room's long description.
No return value

`when_open` | String or routine

For objects Description, or routine to print one, of something open (a `door` or `container`) in a room's long description.
No return value

`when_on` | String or routine

For objects Description, or routine to print one, of a `switchable` object which is currently switched on, in a room's long description.
No return value

`when_off` | String or routine

For objects Description, or routine to print one, of a `switchable` object which is currently switched off, in a room's long description.
No return value

`with_key` | Object `nothing`

The key object needed to lock or unlock this `lockable` object. A player must explicitly name it as the key being used and be holding it at the time. The value `nothing`, or 0, means that no key fits (though this is not made clear to the player, who can try as many as he likes).