Reference to Platypus release 4Reference to Platypus release 4Send questions, comments, and bug reports to Anson Turner.
Conventions followed in this document:
| Attribute: | light |
| Class, or member: | Rooms |
| Global variables: | actor |
| Obsolete: | lockable |
| Property: | description |
| Property routine: | parse_name() |
| Routine: | InDark() |
| Balrog: | B |
[Square brackets] also indicate optional parameters in routine calls.
Note: Most descriptions of items found in the Inform standard library are adapted from The Inform Designer's Manual by Graham Nelson, or some antiquated version thereof.
These lists do not comprise an exhaustive inventory of the library, but attempt to define those elements that are externally useful.
Attributes##Places whether or not it has been visited.
All of a transparent object's children are in scope when the object is, unless they have illegal position attributes set. A child with no position attribute will not be listed in the room description (unless this object is a room or an actor), but will still be in scope.
##Places listing, and its description will be abbreviated
if the game is not in VERBOSE mode.
Properties
Holds a list of words describing this object. Adjectives rank below names
but above descriptors. That is, if the player enters GET ORANGE, and there
are two objects nearby, one a fruit with 'orange' as a name, and another
an orange widget with 'orange' as an adjective, the parser will assume
that the fruit is the item referred to. See constant WEAK_ADJECTIVES.
Whenever this object is in scope, those objects listed will also be
brought into scope. If a routine is given here, it should call
PlaceInScope(object) to put objects in scope.
true (to allow the object to be entered in the specified way)
or false
Should look at the attribute given and return true if the object can be
entered by Actors in that way. Excluding specific actors is better
done via respond().
true (to allow the object to be pushed) or false
Should return true to allow the current actor to push this object out
of this location in the specified direction.
true (to allow the object to be taken) or false
This method should return true to allow this animate to be picked up
by the current actor.
The indefinite article for this object, or a routine to print one.
A message, or a routine to print one, which is displayed when an actor tries to Go in a direction for which the dirs property yielded 0. If a string is given here, it is only printed for the player, not for other Actors.
The maximum number of items that this actor can carry (excluding those worn).
The class connected to this Gizmos object. All objects of this class will be moved into this object at startup, except those that have absent.
This routine will be run each turn while this object has activedaemon.
true (stop printing here) or false
Called when this object is to be described in a room description. If this
object is a room, called before its description is printed. If
describe() returns true, does not mention the object further, nor are
its contents listed.
The message to be printed when this object is examined, or a routine to print one.
dirs is responsible for determining what is connected to a room in each direction, that is, where an actor winds up upon exiting the room in that direction. It can take two forms: array and routine.
As an array, dirs contains a list of one or more direction objects (ndir, sedir, outdir, etc.), followed by the room object in that direction (or a door or a string to print when the player tries to go that way). You can list more than one direction before the destination. In the following example, going either southwest or down would lead to In_Sloping_Corridor:
dirs nedir CrossRicketyBridge
swdir ddir In_Sloping_Corridor;
As a routine, dirs() is called with one parameter, a direction object,
and returns the room (or door) the room connects to in that direction.
If it returns 0, the movement is blocked (with the cant_go or default
message printed, if it is the player trying to move). If it returns 1,
movement is blocked, but nothing is printed by the library. If it
returns a string, movement is prevented, and the string will be printed
only if the player is trying to move.
This property should look at the global finding_path to see if it is
being called by FindPath() (and should never print anything or change
the game state if so). finding_path will be set to ExitsSub if it is
being called due to the Exits command, or because the compass is being
drawn.
It may also wish to look at moving_player, which is set to true if the
player is being moved along a path by the GoToRoom command. And of course
actor, to see who is moving.
Works like ChooseObjects(), for this object only. Takes one parameter, equivalent to the code passed to ChooseObjects: 0 means the parser is leaning toward excluding the object from an "all", 1 means it is to be included. The method can return 0 to play no part in the decision (it will go to ChooseObjects() next), 1 to force the object to be included, or 2 to force it to be excluded.
If code is 2, the parser is trying to choose one best object to match the player's input. disambiguate() can return a number from 0 to 9 to influence the decision, a higher number indicating a better choice.
false (to block movement),
true (to block movement and print nothing)
Holds the destination(s) of this door object, or a routine which returns one.
If door_to contains one room object, that is the destination that the door leads to. If it contains an array of two room objects, entering the door from one will lead to the other. If the door does not also have a found_in property, it will automatically be treated as a floating object present in both locations.
If it contains a string, it will be printed if the player is trying to pass through. (The door will not lead anywhere.)
If it is a routine, it takes the location from which it is being entered
as a parameter. If it returns false, the door leads nowhere. If it returns
true, the door leads nowhere, but the message saying so will not be
printed.
Printed or called every turn, if it is in scope to the player. No meaningful return value.
true (if present at actor.location) or false
This object is present (in scope) at all locations listed in this
property. If found_in is a routine, it is called with a room as a
parameter, and should return true if the object should be found in that
room.
This property only works while the object is in FloatingHome.
See also shared.
This is used by FindPath() to aid it in finding the shortest path between rooms. The GuidePath() entry point, or a guide_path() property can set a room's fpsa to 0 to prevent it from being allowed on the path being searched for. See the entry for guide_path().
false, true (to indicate command has been fully parsed),
or a dictionary word verb
This routine is called when the object is being spoken to, and the parser has set verb_word and verb_wordnum, but has not yet tried any grammar. The routine can parse past some words, if it increases verb_wordnum accordingly.
If this returns false, the parser continues parsing as usual. If it
returns true, it means that it has set action, noun, and second
itself. If it returns a dictionary word verb, the parser will parse the
command using that verb's grammar instead. If it returns a negative
dictionary word verb (such as -'take'), the parser will parse using that
verb's grammar, and then try the usual grammar as well.
This routine is called by FindPath() when it is searching for a path for this object (usually ofclass Actors). It is passed three Parameters: the starting room for the path, the ending room, and the maximum length allowed for the path. By setting a room's fpsa property, it can determine the maximum number of moves FindPath is allowed to make to reach that room. Thus, by setting a room's fpsa to 0, that room will not be allowed on the path at all.
If this routine returns true, FindPath() will not attempt to find the path
at all.
The maximum number of objects which can be held inside this object.
Printed as all or part of the room description for an actor who is a child of this object. (It is the whole description if the actor is inside a closed container or under a hider, assuming non-transparency in each case.)
This is used to change an object's inventory listing. It is called twice, first with variable inventory_stage set to 1, then with it set to 2.
At stage 1, if this returns true, the library prints nothing about the
object or its contents.
At stage 2, the library has already printed the object's name, but not
messages such as " (providing light)". This is an opportunity to add
something like " (humble and true)". If this returns true, nothing further
is printed about the object or its contents.
true (to put this object in scope) or false
This method is called with one parameter, an object (usually an actor) for
which scope is being determined. It can use PlaceInScope(object) to add
things to scope, and if it returns true, this cog itself is also put into
scope.
This method takes a single parameter, a property, and should return true
if this ShowobjCogs object knows how to display the property's value(s).
See also print_property().
Objects with the same list_together value are grouped together in object
lists (such as inventories). If a string such as "corknuts" is given, the
group will be headed with text such as "forty-two corknuts".
If a routine is given, it is called twice, first with inventory_stage
set to 1, then with it set to 2. These stages occur before and after the
group is printed, so a preamble or postscript can be printed. If it
returns true at stage one, the group is not listed at all.
The routine may change c_style, which holds the current listing style. At stage one, parser_one is set to the first object in the group, and parser_two is set to the current depth of recursion in the list. NextEntry(obj, parser_two) will return the next object in the group, after obj. listing_together holds the first object of a group being listed, or 0 when no group is being listed.
Indicates the room that this actor is in. You should never set this manually, except at startup. After startup, use
MoveTo(actor, place[, position])
to move actors, where place is a Rooms object or a supporter, container, or hider with an appropriate allow_entry() routine, and the (optional) position is upon, inside, or under.
true (stops action) or false
Called when any action begins within scope of this object. Always called
for the actor's location, whether the room is in scope or not. If this
returns true, the action is cancelled. (Equivalent to standard library
react_before.)
true (stops action) or false
Called when any action within scope of this object has passed the
verification stage and is about to actually happen. Always called for the
actor's location. If this returns true, the action is cancelled.
true (stops action message) or false
Called after an action within scope of this object has occurred, but
before the normal message for the action has been printed. Always called
for the actor's location. If this returns true, the standard message
for the action is not printed.
This is called after an action is completely finished and the library has printed the outcome text. It is called even if the action failed or was interrupted at an earlier stage. Thus, this property can be used to allow characters to react to or comment on actions after the fact. (Look at action_failed to determine whether the action was completed.)
true or false (prints default message)
For Actors, the messages to be printed when the actor performs actions. For MessageCogs, the messages to be printed when any actor performs actions which are not trapped by the actor's messages property.
This property should look at lm_n to determine the number of the message
to be printed. It may also need to look at noun, second, and lm_o
(the object that was passed to ActionMessages()), but action message codes
may be used instead (e.g. "#obj#").
true (to allow this object to be moved) or false
If provided, this method can decide whether or not to allow this object to be moved into the specified room, which has this object listed in its shared or sharedx property.
Holds a list of dictionary words which refer to this object. name takes precedence over adjective and descriptors. See also adjective.
This is a general-purpose property with no library function. However, it does have special meaning for tasks and footnotes (see section 7 of the Summary).
Called when the player issues a command to this object. The routine can
look at action, noun, and second to determine what to do. If the
command was not understood by the parser, action is ##NotUnderstood (and
etype holds the parser's error number).
If this returns false, the command is then converted into an ##Answer
action (which may be trapped by respond() properties, etc.). If it
returns true, the library does nothing further with the command.
This property is called for the player for every order issued, and in that case, actor is set to the object the order is directed at (which may be the player).
This is used to parse an object's name, by calling NextWord() and matching as many words as possible. It returns 0 to signify that the text does not match the object at all, -1 to have the parser resume its normal course (parsing name, adjective, etc.), or the number of words that were matched (as names). It can also specify that some of the words should be treated as adjectives rather than names, by multiplying them by 100 before adding them to the return value. For example, a return value of 201 means that the method matched 2 adjectives and 1 name, for a total of 3 words matched.
It can set parser_action to ##PluralFound to indicate that a name given
was in the plural, and should refer to all matching objects.
Note that parse_name() may be called more than once when the parser is attempting to match a given object. If the parser is attempting to match THE OPEN BOX, for example, and the box has a parse_name(), it will first be called while wn is at THE. If it returns 0, the parser will then identify THE as a descriptor and the method will be called again at OPEN. If it returns 0 again, and the box has open, then OPEN will also be matched as a descriptor, and the method will be called a third time at BOX.
You can put an end to the process by adding 10000 to the return value. The parser will then make no further attempts to match descriptors (which also means that the method will not be called again for the current token, since it will presumably have matched as many words as it is going to.) If you instead add 20000, it will also stop the parser from trying to match a positional description, as IN THE RUCKSACK in the command EXAMINE THE OPEN BOX IN THE RUCKSACK.
If the routine is called with parser_action set to ##TheSame, the parser
wants to know if two objects with the same parse_name() routine can be
distinguished from each other. It should then return -2 if the objects
parser_one and parser_two can be distinguished, or -1 if not.
After a successful call to FindPath() for this actor, path_moves will contain the moves in the path, in the form of direction objects (ndir, etc.).
See also path_length, path_rooms.
After a successful call to FindPath() for this actor, path_rooms will contain the rooms in the path which result from travelling in the directions specified in path_moves. For example, if the first room is Kitchen, and the first direction object is ndir, then FindPath() first went into the Kitchen by travelling north from the starting room. This property is used to verify that the path is still valid while the actor is moving along it.
See also path_length, path_moves.
Used to cause an actor to perform an action. This method is inherited from the Actors class, and should not normally be provided for an individual actor. Usage Example:
Fred.perform(##Insert, square_peg, round_hole);
The plural name for this object (or a routine to print one). For example,
a banana might have plural set to "bananas". If this property is not
provided, the objects will all be listed separately (e.g. "a banana, a
banana, a banana" etc.)
The number of points to be awarded to the player. For Rooms, points are awarded when the player first enters. For takeable objects, points are awarded when the player first holds the object. For tasks, points are awarded when the task is Achieved().
Holds a list of words which describe objects carried by this actor.
Examples: 'fred^s', 'girl^s'. The player can use these words when
referring to objects: EXAMINE FRED'S GRANOLA.
Takes two parameters, a property and a value for that property, and should print the value in a format appropriate to the property. For example, if the property normally holds dictionary words, it should print the value as a dictionary word.
See also knows_property().
true (stops action) or false
Called as soon as any action begins which is directed at this object,
before any verification takes place. If it returns true, the action is
cancelled immediately.
true (stops action) or false
Same as respond_early(), but called for the indirect object (second).
true (stops action) or false
Called when an action directed at this object has passed the verification
stage and is just about to actually happen. For instance, if the action is
##Take, respond is called immediately before the object is moved into the
actor's possession. If this returns true, the action is cancelled.
true (stops action) or false
Same as respond(), but called for the indirect object (second).
true (stops action message) or false
Called after an action directed at this object has been performed, but
before the success message is printed. If this returns true, the success
message will not be printed.
true (stops action) or false
Same as respond_late(), but called for the indirect object (second).
A list of floating objects to be found in this room.
See also found_in.
The printed name of this object (e.g. "phone booth") or a routine to print
one. If the routine returns false, the name given in the object's header
(after the object's identifier) is printed.
If provided, takes the place of short_name when the object is preceded by an indefinite article.
Called when the game is starting up. Can be used to perform any initialization this object requires.
The number of turns before this object's time_out() property is called.
This is decremented by 1 every turn if this object has activetimer. When
it reaches 0, the object's time_out() property is called at the end of
the current turn. StartTimer(object, time left) will give the object
activetimer and set this property to the given value.
Called at the end of the turn, when this objects time_left property reaches 0 (so long as the object has activetimer).
The maximum number of objects which can be held under this object.
The maximum number of objects which can be held upon this object.
The (key) object needed to unlock this object. If 0, no object can unlock
this. If a routine, takes an object as a parameter and returns true if
that object can be used to unlock it.
Is sent a dictionary word by the library and should return name if it is a name matching the object, adjective if it is an adjective, or 0 if it does not match the object at all. If provided, this property supersedes name and adjective - an object should not normally have both.
RoutinesRUNTIME_DICTIONARY_MAX_WORDS at the start of the program
to the maximum number of words you will add to the vocabulary in order to
use this. Put the characters comprising the word into an array, then call
this routine with the array and the length of the word. For example:
Array new_word -> 'g' 'l' 'k';
x = AddWord(new_word, 3);
Would cause 'glk' to become a new word recognized by the parser. x would
then contain the address of the new word, unless there was no room left in
the Runtime Dictionary, in which case AddWord() return false (0). If you
try to add a word already in the dictionary, AddWord() returns the address
of the existing word.
AddWord() is used by "nameable.h" to allow the player to name objects.
child(object) will be the object that comes first
alphabetically, and the siblings will follow in order.
@output_stream -3".
See also OpenBuffer().
Thus, if the Values array contains: 4 0 3 9 12, a call to FindByByte(9, Values, 5) will return 3, because Values->3 == 9.
If FindPath() returns false, no path could be found. Otherwise, the
direction objects indicating the path will be stored in the actor's
path_moves and the rooms those directions lead to are stored in the
actor's path_rooms. The number of moves in the path is stored in
path_length.
While FindPath() is running, finding_path is set to the actor for whom the path is being found. It is essential to look at this before printing anything or changing the game state in a dirs() method. For example, if trying to go through a particular exit causes a trap to go off, you must check the finding_path global to make sure the trap is not triggered by FindPath(). Examples:
FindPath(bedroom, kitchen, player)
FindPath(boy.location, player.location, boy, 3)
true if the given bit is set, counting from the given address.
See also ClearBit(), SetBit().
| ONE_UPON | Has one object upon it. |
| MULTI_UPON | Has multiple objects upon it. |
| ONE_INSIDE | Has one object inside it. |
| MULTI_INSIDE | Has multiple object inside it. |
| ONE_UNDER | Has one object under it (but set only if object has transparent). |
| MULTI_UNDER | Has multiple objects under it (but set only if object has transparent). |
| ONE_WORN | Is wearing one object. |
| MULTI_WORN | Is wearing multiple objects. |
| ONE_HELD | Is carrying one object (but only if this actor has transparent). |
| MULTI_HELD | Is carrying multiple objects (but only if this actor has transparent). |
The remaining bits are redundant, but provided for convenience:
| ANY_UPON | Has one or more objects upon it. |
| ANY_INSIDE | Has one or more objects inside it. |
| ANY_UNDER | Has one or more objects under it (but set only if object has transparent). |
| ANY_WORN | I'm sure you have the idea by now... |
| ANY_HELD | Etc... |
The filter bitmap can include the CONCEAL_BIT and/or ALWAYS_BIT from
WriteListFrom(). The attribute is a filter; objects without it will not be
counted.
Note that this routine judges visibility based on the current actor.
Thus, if the object is not open or transparent, its inside contents will
not be considered visible, unless the actor is also inside, in which
case those are the only contents that are visible. However, with
ALWAYS_BIT set, all non-concealed contents are counted, except those with
illegal position attributes. If CONCEAL_BIT is set, then concealed items
are counted as well.
Also note that items under a non-transparent hider are not considered
visible (unless the actor is also under), though they are in scope,
because they are omitted from room descriptions. They can, in fact, be
seen by way of ##LookUnder.
See also HasVisibleContentsFiltered().
#Actor#") in text other than in
messages. Most likely, this would be used in one of the respond or
meddle property routines.
See also PrintX().
table
!-----------------------!
book (upon) box (under)
!
kitten (inside)
Then IndirectlyContains(table, kitten) == under.
If the child of object1 has no position attribute, or object1 and object2 are the same, then the return value is -1.
#...# codes. Necessary to
avoid garbled output when printing a library message from within a library
message (for instance, in a short_name() routine).
If the object is ofclass Actors, its location is set.
If the object is the player, a Look will normally take place. If the look flag is provided and is 1, no Look will take place. If it is 2, the usual description the player would get upon walking into the room (which may be shortened if the room has visited) is printed. Examples:
MoveTo(wand, player.location)
MoveTo(player, bed, upon, 1)
MAXIMUM_OPEN_BUFFERS buffers
can be open at once, but only the most recently opened one will be
capturing output at any given time.
This routine should not be called for any buffer which is already open.
See also CloseBuffer().
#obj#"). Print codes are covered in
section 4i of the Summary.
If a string is supplied, calls HoldX() and prints the string before doing
the above. If an object is also supplied, temporarily uses that object
for the #object# code.
See also HoldX().
If the object already has any of those attributes (or worn), or if the parent is ofclass Class, Rooms, or Gizmos, this routine does nothing. Otherwise, it will set the first applicable attribute in this order: upon, inside, under.
The flag works just like the flag for ChangePlayer(). It has no effect unless object1 is the player.
Constants##GoToRoom.
Style of game and copyright message.
Sets the number of spaces per indent degree in object lists.
Sets the default carrying_capacity for all Actors.
The maximum number of nested calls allowed to OpenBuffer().
Can be used to set the initial value of player. If set, prevents the standard player object from being created.
Sets the maximum number of words that can be added to the game's dictionary (via AddWord()) during play. Must be declared in order to make use of AddWord().
The title (traditionally in all capital letters).
Global Variables
Is automatically set to true if the last action attempted was interrupted
at the early or middle (meddle(), respond()) stage, and therefore was
not carried out (at least not by the library).
In future releases, this variable may be used to indicate the reason for
the failure. Any non-zero value should be treated as true. I.e., use
(action_failed ~= 0), not (action_failed == 1).
During parsing, indicates the creature being ordered by the player. During an action, indicates the Actors object performing the action.
Indicates the grammar line matched for the current verb (counting from 1).
Sets the listing style for tall inventory lists.
Sets the listing style for wide inventory lists.
Sets the listing style for Locale(), which lists the contents of an actor's location.
The maximum possible score in this game, displayed when the player uses the SCORE command. This is initialized at startup by totaling all points properties with positive values, but may be set to any value by your Initialise() or startup() routines.
Is automatically set to player when the player is being moved automatically due to the use of a GO TO <room> command (i.e., by GoToRoomSub). Setting this to 0 terminates movement.
See the entry for parse_name().
May be set to FIRST_PERSON, SECOND_PERSON, or THIRD_PERSON (or 1, 2, or
3), to determine the pronouns and verb endings used for the player.
Defaults to SECOND_PERSON.
The player's current score, as displayed by SCORE and (possibly) the status line.
Entry PointsNote: Many entry points work the same as in the standard library, and are not listed here.
ParseNoun() will never be called for an object with a parse_name(), unless the parse_name() returns -1.
Objects
-- Anson Turner
(formatted by John G. Wood)
This page originally found at http://www.elvwood.org/InteractiveFiction/Platypus/Ref.html
Last updated: 14 March 2002
