
Reference to Platypus release 4+
================================

    Send questions, comments, and bug reports to platypushome@yahoo.com.

    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.


Contents:

    Attributes          sec:01
    Properties          sec:02
    Classes             sec:03
    Routines            sec:04
    Constants           sec:05
    Global Variables    sec:06
    Entry Points        sec:07
    Objects             sec:08

    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                                                           sec:01
==============================================================================

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

activedaemon
    This object has a daemon which is running.

activetimer
    This object has a timer which is running.

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

clothing
    This object can be -worn-.

concealed
    This object is hidden from view.

container
    This object can contain things -inside- it.

edible
    This object can be eaten.

female
    Feminine pronouns are used to describe this object.

general
    This attribute is available for the designer's use. It has no standard
    purpose.

hider
    This object can contain things -under- it.

inside
    This object is inside its parent (which has -container-).

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

light
    This object produces light.

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

male
    Masculine pronouns are used to describe this object.

moved
    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
    Neuter pronouns are used to describe this object.

openable
    This object can be opened (and closed).

on
    This object is switched on.

open
    This object is open. Applies to a -container- or an object with
    +door_to+ or -openable-.

pluralname
    Plural pronouns are used to describe this object, and verbs printed for it 
    (them) by the library are conjugated appropriately.

proper
    This object has a proper name, which no articles will precede.

quotedmode
    This actor's action messages will be printed in the first person.

secret
    This object will never be given -known- by the library.

static
    This object cannot be moved by actors.

supporter
    This object can hold things -upon- it.

switchable
    This object can be turned -on- and off.

talkable
    This object can be spoken to.

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

under
    This object is beneath its parent (which is a -hider-).

upon
    This object is atop its parent (which is a -supporter-).

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

workflag
    A temporary attribute used primarily by the library for its internal 
    workings.

workflag2
    Similar to -workflag-.

worn
    This object (which is -clothing-) is being worn by the actor who is its
    parent.


==============================================================================
   Properties                                                           sec:02
==============================================================================

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.

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

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

allow_take
    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=.

article
    Expects: string or routine

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

cant_go
    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].

carrying_capacity
    For: [Actors]
    Expects: number

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

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

description
    Expects: string or routine

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

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

disambiguate
    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 any number to influence the
    decision, a higher number indicating a better choice.
    
    (Note: As of release 4+, the return values from ChooseObjects() and
    +disambiguate()+ are 1000 times less potent, to allow for more precision
    in disambiguation. Multiply by 1000 to keep the same effect as before.)

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

found_in
    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+.

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

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

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

inside_capacity
    For: -container- objects
    Expects: number

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

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

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

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

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

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

location
    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#").

moveYN
    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+.

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

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

path_length
    For: [Actors]
    Expects: number

    After a successful call to FindPath() for this actor, +path_length+
    indicates the number of moves in the path found.

path_moves
    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+.

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

perform
    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);

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

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

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

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

shared
    For: [Rooms]
    Expects: list of objects

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

    See also +found_in+.

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

short_name_indef
    Expects: string or routine

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

startup
    Expects: routine

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

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

under_capacity
    For: -hider- objects
    Expects: number

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

upon_capacity
    For: -supporter- objects
    Expects: number

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

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

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

==============================================================================
   Classes                                                              sec:03
==============================================================================

Actors

    For characters who can carry out actions via +perform()+ and have paths
    determined for them via FindPath().

MessageCogs

    Used to supplement or supersede library messages. See +messages()+.

Rooms

    Used for rooms. Yup.

Sacks

    For containers that [Actors] move stuff to automatically to free space in
    their inventories when taking things. (Takes the place of the SACK_OBJECT
    constant from the standard library.)

ScopeCogs

    Used to add things to scope. See +join_scope()+.

ShowobjCogs

    Used to "teach" ##Showobj how to display properties intelligently. See
    +knows_property()+ and +print_property()+.

==============================================================================
   Routines                                                             sec:04
==============================================================================

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.

CloseBuffer()

    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.

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:

           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.

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)

OpenBuffer(buffer)

    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.

SetDefaultObjectPositions()

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

==============================================================================
   Constants                                                            sec:05
==============================================================================

AMUSING_PROVIDED

    Indicates that an Amusing routine is provided, which will be called if the 
    player enters AMUSING after finishing the game.

DEBUG

    Turns on debugging: causes debugging verbs and routines to be incorporated
    into the game during compilation.

DONT_SCOPE_ROOMS

    If this is defined, an actor's +location+ will only be put in scope for 
    meddle routines and (for the player) ##GoToRoom.

Headline
    Expects: string
    Default: none (must be provided)

    Style of game and copyright message.

INDENT_SIZE
    Expects: number
    Default: 2
    
    Sets the number of spaces per indent degree in object lists.

INFIX

    Turns on the Infix debugging system, along with the traditional debugging 
    commands. (Note that Infix still doesn't work under Glulx, alas.)

MATCH_LIST_SIZE
    Expects: number
    Default: 64
    
    This is the number of objects that the parser can look at when trying to
    interpret a command. In games with a large number of objects in scope at
    once, it may be necessary to increase this.

MAX_CARRIED
    Expects: number
    Default: 100

    Sets the default +carrying_capacity+ for all [Actors].

MAXIMUM_OPEN_BUFFERS
    Expects: number
    Default: 10

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

NO_PLACES

    Disables the PLACES command.

NO_SPECIAL_WARNINGS

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

PLAYER_OBJECT
    Expects: object
    Default: newselfobj

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

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

Story
    Expects: string
    Default: none (must be provided)

    The title (traditionally in all capital letters).

WEAK_ADJECTIVES

    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.

==============================================================================
   Global Variables                                                     sec:06
==============================================================================

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

actor
    Set by: library (usually)

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

finding_path
    Set by: library

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

grammar_line
    Set by: library
    
    Indicates the grammar line matched for the current verb (counting from 1).

invtall_style
    Set by: game (or default)
    
    Sets the listing style for tall inventory lists.
    
invwide_style
    Set by: game (or default)
    
    Sets the listing style for wide inventory lists.

locale_style
    Set by: game (or default)
    
    Sets the listing style for Locale(), which lists the contents of an
    actor's location.

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

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

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

score
    Set by: library (generally)

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

==============================================================================
   Entry Points                                                         sec:07

   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.

ParseNoun(object)

    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.

==============================================================================
   Objects                                                              sec:08
==============================================================================

FloatingHome

    Floating objects must be in this object in order to "float".

Map

    Rooms are kept in this object.
    
Storage

    Floating objects or cogs which are created in this object will not be
    active at startup.

