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