Contents
Back
Forward

A6. 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 should return: 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, 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 expected from routine.

(+)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 should return: 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 expected from routine.

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 should return: 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 should return: 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 expected from routine.

capacity -- Number or routine (100)

For objects: Number of objects a container or supporter can hold.


For player objects: 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 (NULL)
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 should return: 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 expected from routine.

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 should return: 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 should return: 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 expected from routine.

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 should return: 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 should return: 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 expected from routine.

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 should return: 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 should return: 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 Section 16, and see also the properties orders and grammar.


Routine should return: 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
\fo 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 should return: Stage 1: False to continue, true not to print the group's list at all.


Routine should return: Stage 2: No return value.

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 Section 16 for how to write orders routines in these cases.


Routine should return: 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.)

(+)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''.


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.


For player objects: Exception: an object to be used as a player-object must provide one of these, and musn't use it for anything.

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 should return: 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 should return: -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 expected from routine.

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 should return: 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 should return: 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 should return: 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 expected from routine.

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 expected from routine.

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 expected from routine.

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 expected from routine.

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).
Contents / Back / Forward
Chapter I / Chapter II / Chapter III / Chapter IV / Chapter V / Chapter VI / Appendix
Mechanically translated to HTML from third edition as revised 16 May 1997. Copyright © Graham Nelson 1993, 1994, 1995, 1996, 1997: all rights reserved.