PlatypusReference to Platypus release 4

Send 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.


  1. Attributes
  2. Properties
  3. Routines
  4. Constants
  5. Global Variables
  6. Entry Points
  7. Objects

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.


If this object is a cog or a floating object, it will not be moved into its gizmo or FloatingHome at startup. This object will not be given known by the library.
This object has a daemon which is running.
This object has a timer which is running.
This object can be spoken to, and can carry and wear items. (Its children without position attributes are considered carried rather than being buried, and are in scope.) Its worn items are listed in room descriptions, as are its carried items if it is transparent.
This object can be worn.
This object is hidden from view.
This object can contain things inside it.
This object can be eaten.
Feminine pronouns are used to describe this object.
This attribute is available for the designer's use. It has no standard purpose.
This object can contain things under it.
This object is inside its parent (which has container).
This object is known to the player. It can be a topic for Ask/Tell/Consult/Answer (and will be put into second if so). If it is a room, it is listed by ##Places whether or not it has been visited.
This object produces light.
This item is locked, and cannot be opened (if openable). If it provides with_key, it can be unlocked using the object specified by that property.
Masculine pronouns are used to describe this object.
This object has been or is being held by the player. The initial message (if any) will no longer be displayed for this object.
Neuter pronouns are used to describe this object.
This object can be opened (and closed).
This object is switched on.
This object is open. Applies to a container or an object with door_to or openable.
Plural pronouns are used to describe this object, and verbs printed for it (them) by the library are conjugated appropriately.
This object has a proper name, which no articles will precede.
This actor's action messages will be printed in the first person.
This object will never be given known by the library.
This object cannot be moved by actors.
This object can hold things upon it.
This object can be turned on and off.
This object can be spoken to.
This object is see-through. If it is a closed container, its inside contents are visible. If it is a hider, its under contents are listed in room descriptions, and an actor under it can see the outside room. If it is an actor, its carried, unworn items will normally be listed in room descriptions.

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.

This object is beneath its parent (which is a hider).
This object is atop its parent (which is a supporter).
This room has been or is being visited by the player. It will be listed in the ##Places listing, and its description will be abbreviated if the game is not in VERBOSE mode.
A temporary attribute used primarily by the library for its internal workings.
Similar to workflag.
This object (which is clothing) is being worn by the actor who is its parent.


adjective (additive)
Expects: dictionary words

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.

add_to_scope (additive)
Expects: routine, or list of objects

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.

Expects: routine
Parameters: upon, inside, or under attribute
Returns: 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().

Expects: routine
Parameters: direction object
Returns: 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.

For: animate objects
Expects: routine
Returns: 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.

Expects: string or routine

The indefinite article for this object, or a routine to print one.

For: Rooms
Expects: string or routine

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.

For: Actors
Expects: number

The maximum number of items that this actor can carry (excluding those worn).

For: Gizmos
Expects: class

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.

daemon (additive)
Expects: routine (or NULL)

This routine will be run each turn while this object has activedaemon.

describe (additive)
Expects: routine (or NULL)
Returns: 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.

Expects: string or routine

The message to be printed when this object is examined, or a routine to print one.

For: Rooms
Expects: array or routine
Parameter (if routine): direction object
Returns: 0 (disallow movement), 1 (disallow and keep silent), string (print if player moving; disallow movement), room or door object

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.

Expects: routine
Parameters: ChooseObjects code
Returns: see description

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.

For: doors
Expects: one or two room objects, a string, or a routine
Returns: room object, 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.

each_turn (additive)
Expects: string or routine (or NULL)

Printed or called every turn, if it is in scope to the player. No meaningful return value.

Expects: list of room objects or routine
Parameter: room
Returns: 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.

For: Rooms
Expects: number

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

For: animate or talkable objects
Expects: routine
Returns: 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.

Expects: routine
Parameters: starting room, ending room, maximum length

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.

For: container objects
Expects: number

The maximum number of objects which can be held inside this object.

For: supporter, container, and hider objects with allow_entry()
Expects: string or routine

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.)

For: takeable object
Expects: routine
Returns: see text below

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.

For: ScopeCogs
Expects: routine
Parameters: object
Returns: 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.

For: ShowobjCogs
Expects: routine
Parameters: property

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

Expects: number, string, or routine
Returns: see text below

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.

For: Actors
Expects: Rooms

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.

meddle_early (additive)
Expects: routine (or NULL)
Returns: 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.)

meddle (additive)
Expects: routine (or NULL)
Returns: 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.

meddle_late (additive)
Expects: routine (or NULL)
Returns: 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.

meddle_late_late (additive)
Expects: routine (or NULL)

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.)

messages (additive)
For: Actors or MessageCogs
Expects: routine
Returns: 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#").

For: floating objects
Expects: routine
Parameters: room object
Returns: 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.

name (additive)
Expects: list of dictionary words

Holds a list of dictionary words which refer to this object. name takes precedence over adjective and descriptors. See also adjective.

Expects: anything

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).

orders (additive)
For: animate or talkable objects
Expects: routine

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).

Expects: routine

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.

For: Actors
Expects: number
After a successful call to FindPath() for this actor, path_length indicates the number of moves in the path found.
For: Actors
Expects: list of direction objects

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.

For: Actors
Expects: list of 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.

For: Actors
Parameters: action, noun, second

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);
Expects: string or routine

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.)

Expects: number

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

For: Actors or holders
Expects: dictionary words

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.

For: ShowobjCogs
Expects: routine
Parameters: property, value

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

respond_early (additive)
Expects: routine (or NULL)
Returns: 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.

respond_early_indirect (additive)
Expects: routine (or NULL)
Returns: true (stops action) or false

Same as respond_early(), but called for the indirect object (second).

respond (additive)
Expects: routine (or NULL)
Returns: 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.

respond_indirect (additive)
Expects: routine (or NULL)
Returns: true (stops action) or false

Same as respond(), but called for the indirect object (second).

respond_late (additive)
Expects: routine (or NULL)
Returns: 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.

respond_late_indirect (additive)
Expects: routine (or NULL)
Returns: true (stops action) or false

Same as respond_late(), but called for the indirect object (second).

For: Rooms
Expects: list of objects

A list of floating objects to be found in this room.

See also found_in.

Expects: string or routine

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.

Expects: string or routine

If provided, takes the place of short_name when the object is preceded by an indefinite article.

Expects: routine

Called when the game is starting up. Can be used to perform any initialization this object requires.

Expects: number

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.

time_out (additive)
Expects: routine (or NULL)

Called at the end of the turn, when this objects time_left property reaches 0 (so long as the object has activetimer).

For: hider objects
Expects: number

The maximum number of objects which can be held under this object.

For: supporter objects
Expects: number

The maximum number of objects which can be held upon this object.

Expects: object, routine or 0

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.

Expects: Routine
Parameter: dictionary word
Returns: 0, name, or adjective

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.


abs (number)
Returns the absolute value of the given number.
Achieved (task object)
Indicates that the specified task has been completed by the player. If Achieved() has already been called for this task, nothing happens. Otherwise, the task's points are added to score, the player is notified (if score notification is on), and the task will henceforth be listed in the FullScore.
AddWord (array, length)
Used to add words to the game's vocabulary while it is running. You must set the constant RUNTIME_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.

AlphabetizeAll (object[, workflag flag])
Like AlphabetizeIn(), but recurses downward through the object's descendants. If the workflag flag is set, only recurses downward through objects that have workflag.
AlphabetizeIn (object)
Arranges the children of the specified objects in alphabetical order by name. That is, child(object) will be the object that comes first alphabetically, and the siblings will follow in order.
binary (number)
Prints the given value in binary form.
ChangePlayer (Actors object, flag)
Changes the player into the given object. If the flag is set, prints "(as such-and-such)" after the name of the player's location (or Darkness) in room descriptions.
ClearBit (address, bit index)
Clears the given bit, counting from the given address.
Closes the most recently opened (and not yet closed) output (text) buffer. This should replace any instances of "@output_stream -3".

See also OpenBuffer().

CurrentCarryingCapacity (object)
Returns the number of objects an actor is capable of carrying in addition to its current load (worn objects not counted).
CurrentInsideCapacity (object)
Returns the number of additional objects this container can hold inside.
CurrentUnderCapacity (object)
Returns the number of additional objects this hider can hold under.
CurrentUponCapacity (object)
Returns the number of additional objects this supporter can hold upon.
DrawCompass (x-position)
Draws a compass in the status line, which must be at least 3 lines tall. finding_path is set to ExitsSub while DrawCompass() is checking exits, since the compass should reflect the same available exits as the EXITS command.
FindByByte (value, starting address, length in bytes)
Scans the given number of bytes starting from the given address, and returns the index of the first occurrence of the value, or -1 if it is not found.

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.

FindByWord (value, starting address, length in words)
Like FindByByte, but scans for a word (that is, a 16-bit value), and returns a word (-->) index.
FindInTable (value, table)
Like FindByWord, but uses the table's length entry to determine how far to scan.
FindPath (starting room, destination room, actor[, maximum moves])
Finds the shortest route between two Rooms for the given actor. The GuidePath() entry point and the guide_path() property for the actor will be called first. By setting the fpsa of rooms to 0, they can exclude them from consideration (so they won't be allowed in the path).

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)
GreaterOf (number, number)
Returns the greater of the two numbers passed to it (signed).
HasBit (address, bit index)
Returns true if the given bit is set, counting from the given address.

See also ClearBit(), SetBit().

HasVisibleContents (object[, filter bitmap[, attribute]])
Returns a bitmap indicating the position and plurality of any contents of this object. The bits are:
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().

HoldX ()
Redirects text output into the library's print buffer. You must do this if you wish to use print codes (such as "#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().

IndirectlyContains (object1, object2)
Returns 0 if object2 is not a descendant of object1 (unless they are the same; see below). Otherwise, it returns the position of the child of object1 from which object2 is descended. For example:
           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.

InsertAfter (object1, object2)
Makes object 2 the sibling() of object1.
InsertBefore (object1, object2)
Makes object 2 the elder of object1.
InsertLast (object1, object2)
Makes object 2 the last child of object1, that is, the child with no sibling().
LesserOf (number, number)
Returns the lesser of the two values passed to it (signed).
LMRaw (action[, number[, object]])
Prints a library message without processing #...# codes. Necessary to avoid garbled output when printing a library message from within a library message (for instance, in a short_name() routine).
MoveTo (object, destination object[, position attribute[, look flag]])
Moves the object to the destination object, and clears the object's upon, inside, and under attributes. If no position attribute is supplied (or it is 0), it calls SetDefaultPosition() for the object. (Otherwise the given attribute is set.)

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)
Begins capturing all printed text in the specified buffer (array). This should replace any instances of "@output_stream 3 buffer". If a buffer was already open when this routine is called, the previous buffer will resume capturing text once this one is closed. Up to 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().

PositionOf (object)
Returns upon, inside, or under, to signify the object's position in its parent, or 0 if none of these apply.
PrintX ([string[, object]])
Outputs the text stored in the library's print buffer, that is, text printed after a call to HoldX(). Substitutes the appropriate strings or object names for print codes (such as "#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().

rootof (object)
Returns the "ultimate parent" of the object, that is, the ancestor of the object which is parentless. (For example, this is used to set an actor's location.)
SetBit (address, bit index)
Sets the given bit, counting from the given address.
Calls SetDefaultPosition() (see below) for all objects in the game. Primarily intended to be called during initialization.
SetDefaultPosition (object)
Sets the upon, inside, or under attribute for the object, as appropriate to its parent.

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.

TestScope (object1[, object2])
Determines whether object1 is in scope to object2. If object2 is omitted, it defaults to the current actor.
Transmogrify (object1, object2[, print player glag] )
Can be called whenever something in the game changes in such a way that it is necessary or expedient to use a different object to represent it. Object1 will be removed from play and replaced with object2, resetting any pronouns that were pointing to object1, etc.

The flag works just like the flag for ChangePlayer(). It has no effect unless object1 is the player.


Indicates that an Amusing routine is provided, which will be called if the player enters AMUSING after finishing the game.
Turns on debugging: causes debugging verbs and routines to be incorporated into the game during compilation.
If this is defined, an actor's location will only be put in scope for meddle routines and (for the player) ##GoToRoom.
Expects: string
Default: none (must be provided)

Style of game and copyright message.

Expects: number
Default: 2

Sets the number of spaces per indent degree in object lists.

Turns on the Infix debugging system, along with the traditional debugging commands.
Expects: number
Default: 100

Sets the default carrying_capacity for all Actors.

Expects: number
Default: 10

The maximum number of nested calls allowed to OpenBuffer().

Disables the PLACES command.
Disables the compile-time warnings that Platypus otherwise issues if certain obsolete property names have been defined. (These are intended to warn a designer who may have accidentally used react_before instead of meddle_early, for example.)
Expects: object
Default: newselfobj

Can be used to set the initial value of player. If set, prevents the standard player object from being created.

Expects: number
Default: none

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

Expects: string
Default: none (must be provided)

The title (traditionally in all capital letters).

If this constant is defined, the player must type at least one name in order to specify an object. In other words, identifying an object only by words in its adjective property will not work.

PlatypusGlobal Variables

Set by: library

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).

Set by: library (usually)

During parsing, indicates the creature being ordered by the player. During an action, indicates the Actors object performing the action.

Set by: library Is automatically set to the object (usually an actor) for whom a path is being searched out by FindPath().
Set by: library

Indicates the grammar line matched for the current verb (counting from 1).

Set by: game (or default)

Sets the listing style for tall inventory lists.

Set by: game (or default)

Sets the listing style for wide inventory lists.

Set by: game (or default)

Sets the listing style for Locale(), which lists the contents of an actor's location.

Set by: library or game

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.

Set by: library

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.

parser_action, parser_one, parser_two
Set by: library (mostly)

See the entry for parse_name().

Set by: game (or default)

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.

Set by: library (generally)

The player's current score, as displayed by SCORE and (possibly) the status line.

PlatypusEntry Points

Note: Many entry points work the same as in the standard library, and are not listed here.

GuidePath(object, start, finish, maximum steps)
If provided, this routine works just like guide_path(), except that it is called for any object for which FindPath() is called.
This works exactly like parse_name(), except that it must be a freestanding routine which accepts the object to be matched as a parameter.

ParseNoun() will never be called for an object with a parse_name(), unless the parse_name() returns -1.


Floating objects must be in this object in order to "float".
Rooms are kept in this object.
Floating objects or cogs which are created in this object will not be active at startup.

-- Anson Turner
(formatted by John G. Wood)

This page originally found at
Last updated: 14 March 2002

Notices & Disclaimers


Interactive Fiction

Platypus Index