The Pianosa Reference
Version 1.0
(c) 1999-2000 John McCall (TenthStone)
tenthstone@hotmail.com
Warning: this is a reference, not a primer. Any attempt to learn
Pianosa should be accompanied by a copy of the library and any
Pianosa source code that happens to exist. Any attempt to learn
TADS directly with Pianosa is unadvisable at this time.
Introduction
I suppose anyone reading this paragraph is wondering why I wrote an
alternate library for TADS. Well, here goes an attempt to explain.
My problem with adv.t is that too often I find myself fighting against
the library, trying to get some basic effect but lacking any good tools
to that end. I don't mind hacking a library -- my work in progress
has required me to modify Pianosa a good bit, and the more generally
useful of those modifications, like doorwayframe, I've permanently
placed in the library. But my old adv.t sources were riddled with
hacks and out-and-out replacements -- and that's where I draw the line,
when it's no longer worthwhile to keep patching the old system.
My problem with WorldClass is that I can't figure out how to extend it.
The library tends to work via long, complicated procedures without
any escape hatches; the fact that it works on a higher level than adv.t
serves only to make the inevitable adjustments that much more difficult
to handle -- see, for example, the monstrosity that is listcontentsX.
I haven't looked very hard at Kevin Forchione's Alt library yet, although
that's something I've been meaning to do. (Pianosa predated the
unification of Alt by a few months; since then, I've had three major
IF projects (Pianosa, Finch (a library for TADS3), and my work-in-progress
(WIP)), so my IF programming time has been mostly devoted to those).
Why should someone convert to Pianosa? They shouldn't. Unless their
work is still far from complete (programming-wise, not writing-wise),
or unless they're absolutely frustrated in their current library, it's
not really worth the effort to actually convert a work in progress.
Why should someone use Pianosa? Because it's a hacker's library. Because
I've painstakingly opened as many processes as I could think of to easy
adjustment. Because it is my hope that that person never need to wage war
against the library again.
Because it's a powerful library, with a large number of features and
options that can fiddle down to the smallest technicality. Because it's
a simple library, with very few direct requirements if one's willing to
accept the defaults. Because moving from one extreme towards the other has
been made as painless as I think it can be without sacrificing some of
the power underneath.
Because it's an intelligent library, with a large amount of code devoted
to avoiding unnecessary duplication, while preserving the capability of
fine dinstinctions.
Because it's a creative library, engineered to make it as easy as possible
to write the damn game and stop fiddling with the controls already.
Because it's here. Because it's good. Because it's time.
Past, present, future. What will come of Pianosa in the age of TADS 3?
That's a good question, and the answer depends largely upon whether
TADS 3 becomes widely accepted in the IF community. I'm not going to
stop supporting it regardless, but if TADS 3 catches on I doubt many
will spend much time on an alternative library for an outmoded old system.
That's all I've got to say about that.
-- TenthStone
Pittsburgh 8-28-2000
Table of Contents
Searching this document for the text in the first column should browse
instantly to that section of the reference.
Chapter 1 Quick Start
1.0. The very quick start
1.1. The quick start
Chapter 2 TADS Programming (not found)
Chapter 3 The Pianosa Classes
3.1.0. thing
3.1.1. room
3.1.2. container, cover, mask, surface
3.1.2.3.0. movableActor
3.1.3. other gameworld classes
3.1.3.12. Verb
3.2. Pianosa defined objects
3.3. Inheritance hierarchy
Chapter 4 The Pianosa Functions
4.1. Pianosa defined functions
4.2. General functions
4.3. External functions
Chapter 5 The Pianosa Procedures (not found)
Chapter 6 Supplemental Files
6.1. ts_codes.t
6.2. ts_funcs.t
6.3. ts_grid.t
6.4. ts_menu.t
6.5. ts_sense.t
6.6. ts_std.t
Chapter 1
Quick Start
1.0. The very quick start
I'm going to assume you know how to compile a file, so open ts_basic.t
and compile it. It should work -- that's all it takes.
And that's the very quick start.
Note that our pathetically bare game is already close to 100KB even
when compiled without debugging symbols. We'd better add something
to it to make it worthwhile, since all we've got in the world is
a default description which doesn't even make sense.
I'll take you through a quick sample game, but understand this:
the majority of adv.t-designed code will still work in Pianosa, and
most of what doesn't work will work with a quick name-change. adv.t
method is very sound there, and I've taken care not to disturb it.
Where Pianosa has a marked difference, and where changing libraries
will be hardest, is advanced code, where you're not merely defining
something but where you're trying to achieve something. That's not
the sort of problem I can guide you through in this kind of reference.
You should first look at the appropriate class's entry here; if the
information you need isn't there, check its superclass(es); if you
still need help, please feel free to contact me at tenthstone@hotmail.com
or better yet, on the newsgroup rec.arts.int-fiction (remember to
put [TADS][Pianosa] in the subject line). I'm always open to
suggestions, and I always give credit when I remember to.
Anyway, on to the sample game.
1.1. The quick start
Let's look at what we've got in here already. #including ts_std.t
gives us Pianosa and the standard definitions package. version holds
information about the game; commence() prints startup messages;
startroom is the room we're in.
First, let's annoy all the auteurs and pick our title before we write
our game. How about, "The House of Locked Doors". It's nicely
mysterious, yet kitschy enough to qualify for a programming reference.
Besides, I've changed it anyway; it used to be "The Hidden Button."
Looking up the version object in this reference (try searching for
"version:"), we find that version.sdesc holds the name of the work.
Filling in a little, we have
version: object
sdesc = "Is Road Like Wish So Empty?"
bdesc = "<< sdesc >>, unrelease 1 (5 September, 2000)"
ldesc = "<< sdesc >>
\nAn interactive English in Three and Twenty Easy Steps for
native Ashwen speakers, copyright (c) A.D. 2000.
\n<< versionVerb.ldesc >>"
;
Now we need a commence() function. Searching here for it gives us one
reference: it's called by init(). In fact, commence() is responsible for
all the introductory text printed by the game except for the initial
room description (and if you're using random numbers, you might want to
throw in a randomize() call as well).
commence: function {
"\H+\b
\bOh by the village winds, there he goes again. Rising over the
walls of the night's camp is another of his damned green bubbles.
Some little girl from the nearby town -- Brinson-on-Gere, is it? --
comes out to look after the flocks, and Faraj the Great has to
show off his little magic tricks.
\bAh, but as long as it amuses the children, you ought not to
complain. There's precious little to cheer one in an age like
this. You smile softly to yourself, lean on your sword, and
dream of your own family, safe far from these troubled borderlands.
\bWipe that insipid grin off your face, Brac. That sharp crack
could only be Mirane's voice, and you open your eyes. There she is
again, the newest member of your party, only an hour after she left
to check on the road ahead.
\bYou look in Mirane's eyes and see no anxiety; the road, then, must
be clear. But why has she returned so quickly? Her smile is a trace
more smug than usual; perhaps she's found something interesting.
You search for a subtle way to coax the information out while still
allowing her her moment in the sun -- and then you've got it, you
know exactly what to say, you open your mouth, and you say,
\bIs road like wish so empty?
\b
\b
\b<< version.ldesc >>
\b
\b
\b";
}
Now on to the third required entry, startroom. In fact, the code requiring
startroom is in std.t, so if we were working directly with Pianosa, we
wouldn't need startroom at all. But that's all irrelevent.
Technically speaking, we could use .roomdesc and .statusdesc instead of
.ldesc and .sdesc, respectively; however, I've gotten into the habit of
using the adv.t conventions, and I only use the Pianosa equivalents
when there's a need to differentiate between the two, as in when the
room object is a physical world object (e.g. a vehicle).
startroom: room
sdesc = "
BOOKMARK: The example game here is not complete
;
Chapter 3
The Pianosa Classes
The core of any TADS library is its classes. I could go on and explain why,
but there's really no point so I won't, subject to later revisions of this
paragraph.
In Pianosa, there are five core classes, representing the five core groups
of gameworld ideas. A thing is a basic inanimate object. A container class
object is to meant to hold other objects. A character can perform actions.
A room is meant to hold characters. Actions define the player's interface
with the gameworld. This categorisation will never be mentioned again.
There will be no test.
Partially because of this idea of core classes, but mostly because it makes
organisation simpler, the library is not ordered purely by inheritance and
alphabetisation. There are three general sets -- thing-derived,
container-class-derived, and other-base-classes.
3.1. Class reference.
3.1.0. thing
class thing: object
thing is the central class to the adv.t archiecture, from which Pianosa
derives. Every phsyical object in the gameworld inherits from thing. It
is therefore somewhat appropriate that most of our time will be spent with
thing. Other classes which may inherit much, if not all, of their behavior
from thing have properties more specific to themselves described in their
entries.
There is probably no reason to inherit directly from thing in actual game
code, although there's certainly no reason not to. Movable objects which
can be picked up and carried with the player should be defined as item;
other objects are as like to be fixedthing or a more specific class.
Attributes
.adesc Displays the name of self preceded by the indefinite article.
Defined.
.adjective Vocabulary attribute; should be an unbracketed list of single
quoted strings.
.bdesc Displays a brief description of objects listed seperately
(see .describealone). Defined, but better redefined.
.behind Defines the location of self. Only one of the following
properties is applicable at any one time; priority is in the
following order: .in, .on, .under, .behind, etc. Should
point to a valid container class object. These properties
are not updated after preinitialization.
.bulk Defines the bulk (size) of an object. Container-class objects
can set maximum bulks which they can carry.
.cdesc Displays a cursory description of an object when it is picked
up (via a "take" or "put in/on/etc." command). Returns true
to abort the pick-up.
.circularmessage( object ) Displays a message forbidding a circular object
scenario (where A is in B which is in A, or even more complex);
called on the object being moved.
.dart Displays the correct definite article. Defined by .isproper.
.describealone Defines whether self should be listed alone instead of in
a standard inventory. If so, .bdesc is called after the
standard inventory is concluded.
.Dropped( actor ) Displays a message saying that self has been
successfully dropped by actor.
.followlist List of all objects which should be sent a follow message
when this object moves by .moveInto.
.grammarperson Determines which grammatical "person" this object should
be conjugated by; used in association with .isplural. Defined
as THIRD_PERSON; other options are FIRST_PERSON, SECOND_PERSON.
.iart Displays the correct indefinite article. Defined by .isproper
and .isThem.
.idesc Displays the name of self as for an inventory listing, with
.specialdesc appended. Defined.
.in See .behind.
.isdesc Displays self's .sdesc followed by a conjugated form of to be.
Defined.
.isfixed Flag determining whether self is fixed or not. If it is,
.putInto checks with .Fail before continuing.
.isfollowable Flag determining whether self can be followed or not;
referenced only by the doFollow routine itself, and not by the
actual following routines.
.isher Flag allowing this object to be referred to as "her".
.ishidden Flag for an object which should not be listed until it is taken
by an actor.
.ishim Flag allowing this object to be referred to as "him".
.ispasttense Flag marking whether verbs conjugated with self as subject
should be placed in the past tense or not. Defined as
parserGetMe().ispasttense.
.isplural Flag marking whether verbs conjugated with self as subject
should be placed in one of the plural forms.
.isproper Flag marking whether self's .sdesc is a proper noun.
.istaken Flag marking whether self has been taken by the player as of yet.
Objects getting their .istaken attribute set true also have the
.FirstTake message called.
.isthem Flag allowing this object to be referred to as "them". Defined
as self.isplural.
.ldesc Displays a long description of the object, as displayed when
examined. Defined, but better redefined.
.locdesc Displays a description of self's location.
Defined as self.locate.posdesc( self.position ).
.Movearound Displays a message stating what happens when the object is
moved (e.g. north). An error message, not a handling method.
.multisdesc Displays the name of self as it should appear before the
colon when multiple objects are referenced in one command.
Defined as .sdesc. Once a parser mainstay, now only used as
referenced by .prefixdesc. Example:
>Take all.
red hat: Taken.
blue scarf: Taken.
.noun Vocabulary attribute; should be an unbracketed list of single
quoted strings.
.objcount Defines the number of objects referenced by self. Roughly defined
such that if .isThem is true, .objcount is more than one.
Otherwise, one. Such is sufficient.
.on See .behind.
.plural Vocabulary attribute; should be an unbracketed list of single
quoted strings. .plural allows groups of objects to be referred
to at once; it should consist of plural nouns which can then be
used in this fashion.
.pluraldesc Displays a plural form of .sdesc by appending .pluralizer.
Defined.
.pluralidesc Displays a plural form of .idesc. Defined.
.pluralizer Displays what to add to self's .sdesc to make it plural.
Defined as "s" when self isn't already plural.
.predthedesc Displays a short description of self, considering that
it is a predicate object in some sentence. Defined as .thedesc.
.prefixdesc Displays a short description of self before executing it in
a multiple-object command. Defaults to .sdesc.
.Put( actor, position, object ) Displays a message stating that the object
has been successfully put in a position around object; called by
the doPutX routines.
.readdesc Displays what can be seen when self is read (although verDoRead
must be cleared)
.sdesc Displays a short description of the object, i.e. a noun phrase
without article.
.specialdesc Displays additional information on self to be included in
a standard inventory. Defined for clothing and lamps.
.subjthedesc Displays a short description of self, considering that it
is the subject of some sentence (should be lowercase). Defined
as .thedesc.
.Taken( actor ) Displays a message stating that the object has been succesfully
taken by actor.
.thatdesc Displays a reference to self as an indefinite pronoun
(`that'/'those' ). Defined.
.thedesc Displays the name of self preceded by the definite article.
Defined.
.thrudesc Displays what can seen when self is looked through.
.uberlocate List determining the location of self, in the form
[ position object ].
.under See .behind.
.isdesc Displays self's .sdesc followed by a conjugated form of to be,
but in the past tense. Defined.
.weight Defines the weight of an object. Container-class objects can set
maximum weights which they can carry.
Methods
.addadjective( word )
Adds a word (or list of words) to self's set of adjectives. Words should
be single quoted strings.
.addnoun( word )
Adds a word (or list of words) to self's set of nouns. Words should be
single quoted strings.
.addplural( word )
Adds a word (or list of words) to self's set of plurals. Words should be
single quoted strings.
.cantreach( actor )
Displays a message stating that while self is visible, it is not reachable.
.checkdrop
Checks with the object to see if anything special should be done before
the object is moved. For instance, clothing should be taken off. It is
usually called by direct-object movement routines such as .doPutIn and
.doDrop, but it is not called by .putInto.
.clearloc
Resets .uberlocate to [ nil nil ].
.deladjective( word )
Removes a word (or list of words) from self's set of adjectives. Words
should be single quoted strings.
.delnoun( word )
Removes a word (or list of words) from self's set of nouns. Words should
be single quoted strings.
.delplural( word )
Removes a word (or list of words) from self's set of plurals. Words should
be single quoted strings.
.distinguish( object )
Returns whether self can be distinguished from object. Called by
contListing(), which considers two items indistinguishable only if
.isequivalent is true on both and both .distinguish routines return nil.
By default, calls isIndistinguishable().
.Fail
Checks whether a fixed object (.isfixed = true) can be moved; if it cannot,
should display a message and return true.
.Follow( object, destination, position )
Displays statement that self is following object into a certain position
around destination.
.hasclass( class )
Determines whether self has a certain class or not. I never can remember
whether it's isclass( object, class ) (it is) or the other way around.
.isaddressable( actor )
Determines whether self is addressable by actor. Defaults to .isVisible.
.isheldbyactor
Determines whether self is being ultimately held by an actor or not.
.isin( object {, position} )
Determines whether self is located, but not necessarily visible, around
an object. If a position is given, either self or some ultimate container
of self must be held in that position around object. Compare .isvisiblyin.
.islisted
Determines whether self should be listed in the standard inventory or not.
.isreachable( actor )
Determines whether self is reachable by actor.
.isvisible( vantage )
Determines whether self is visible from vantage.
.isvisiblyin( object {, position} )
Determines whether self is visible around an object. If a position is
given, either self or some ultimate container of self must be held in that
position around object. Compare .isin.
.Leaving( actor )
Message sent to self when actor leaves a room. Returns true to be removed
from .leavelist.
.locate
Determines the location of self.
.locatetree
Determines the location tree of self, in form [ self, self.position,
self.locate, self.locate.position, self.locate.locate, ... ]. Recursive.
.Move( target )
Message sent to self by .putInto to verify movement to target. Returns
true to abort movement.
.position
Determines the position of self relative to .locate.
.sameloc( object )
Determines whether self is in the same location and position as object.
.Say( actor )
Displays how actor would refer to self.
.totalweight
Determines the total weight of this object and all of its contents.
.totalbulk
Determines the total bulk of this object and all of its contents.
.ultimatelocate
Determines the ultimate (typically, ultimate visible) location of self.
.verifyremove( actor )
Verification routine which calls .verGrab all the way up the contents tree
until it reaches either the actor or nil. Called by direct-object movement
verification routines.
Actions
.dropFrom( object {, position {, jostle}} )
Drops self from a certain object and position (default = In) according to
.dropping.
.follow( object, desitination {, position} )
Causes self to follow object into a position (default = In) around
destination if possible.
.forceInto( object {, position } )
Moves self into a certain position (default = In) around object (or nil)
by calling .forceRelease on self's location (if exists) and .forceAccept
on the target (if exists).
.hearNoise( type )
Responds to a sound of a certain type.
.jostle( jostle )
Jostles this object and everything in it. By default, runs through the
contents calling the same level of jostle.
.listen( sound, specificity )
Responds to a speech-sound of a certain type, either directed at self or
not.
.mixWith( list )
Mixes self with every object in the list. Should return true if it moves
any of the objects.
.moveInto( object {, position} )
Moves self into a certain position (default = In) around object (or nil),
first notifying containers via .Grab messages and followers via .follow
messages and then calling .forceInto.
.putInto( target {, position {, jostle }} )
Moves self into a certain position (default = In) around object, verifying
the movement with self (see .routePutInto) and the target (see
.routebehind), checking for weight and bulk overload, and then one last
time checking with the source (see .Drop), self (see .Move), jostling
effects (see .jostle), and the target (see .Take) before calling .moveInto.
Returns true upon a routing halt or completion; returns nil for failure.
.routePutInto( target, position, jostle )
Routes wheres self, being put into a certain position around target,
should really go. If it should abort the movement, this should return
true.
.sayTo( actor, sound, specificity )
Responds to a speech-sound of a certain type, either directed at self or
not, usually by calling .listen.
.speak( sound )
Displays a message on how self would cause sound to be emitted. Returns
true to abort.
- thing subclasses
3.1.0.0. dialthing
class dialthing: thing
dialthings are gameworld objects which happen to have dials upon them which
can be set anywhere from .minsetting to .maxsetting, or to strings
corresponding to labels upon the dial. Unlike most other subclasses,
dialthing supplies its own .ldesc supplying information on the dial's
settings.
Attributes
.maxsetting Number of the maximum setting on the dial.
.minsetting Number of the minimum setting on the dial.
.setting Number of the current setting on the dial.
.settings List of valid labels on the dial.
.settingsvalues List of valid settings on the dial corresponding to
entries in .settings.
.settingsonly Flag determining whether numbers can be used for the dial
(nil). Defaults to nil.
Methods
.validsetting( number_or_string )
Determines whether the given setting is valid on the dial.
3.1.0.1. fixedthing
class fixedthing: thing
fixedthings are gameworld objects which happen to be fixed (perhaps
temporarily) within a location. The default behaviour has .isfixed set true
and .Fail set to return true -- aborting any attempt at movement.
fixedthings are typically important enough to warrant their own
descriptions, so .describealone is set to true. If tied to a room, they
would also usually be described in the room's description -- so .ishidden
is set true as well to suppress the individual description.
-- fixedthing subclasses
3.1.0.1.0. buttonthing
class buttonthing: fixedthing
buttonthings are fixed gameworld objects which may be pushed. By default,
pushing the button toggles .isactive on and off.
Attributes
.isactive Flag determining whether self is on or off. Defaults to
nil (off).
.routebutton Object to modify the .isactive properties for. Defaults
to nil, meaning self.
Actions
.turnOn
Sets .isactive true and displays a message.
.turnOff
Sets .isactive nil and displays a message.
3.1.0.1.1. decoration
class decoration: fixedthing
decorations are fixed gameworld objects which may be examined and nothing
else. To add another possible action, adding the appropriate verification
routine to the object definition will let it pass through -- but really,
adding other actions is not advisable as seasoned IF players have grown
accustomed to not being able to do anything at all to a decorative object.
While decorations should be added for every object listed in or implied
by the room description, it is often a nice touch to define such objects
as real gameworld objects that may be fairly interacted with. Any object
of any importance at all should definitely not be declared a decoration.
You've been warned.
Attribute
.Error Message to the effect that this object is not important.
3.1.0.1.2. distantthing
class distantthing: fixedthing
distantthings are gameworld objects that are not really present in this
room, but instead are simply visible from here. Any attempt at interaction
with the object fails.
Attribute
.Error Message to the effect that self is too far away to be dealt
with like that.
3.1.0.2. foodthing
class foodthing: thing
foodthings are gameworld objects which happen to be edible.
Attributes
.Eat Displays message upon consumption. Returning true aborts the
action.
.foodvalue Number specifying how many extra turns the player can last on
the basis of self.
.meal Number specifying how many meals can be made of self.
3.1.0.3. item
class item: thing
items are normal gameworld objects which can be moved around at ease. There
is no special code within the class definition; in fact, there is no code
whatsoever. item is a marker class.
-- item subclasses
3.1.0.3.0. clothingitem
class clothingitem: item
clothingitems are normal gameworld objects which can be worn by an actor.
The act of wearing is summed up like this: self is held by the wearer
and .isworn is true.
Attribute
.isworn Flag determining whether the object is being worn or not.
Defaults nil.
Actions
.remove
Removes self by setting .isworn nil.
.wear
Wears self by setting .isworn true.
3.1.0.3.1. keyitem
class keyitem: item
keyitems are gameworld objects which can be carried around and used to
unlock things. What they can unlock is not up to the key: it's up to the
door, or the chest, or whatever. keyitem is an enabler class, simply
defining the verb actions and leaving all the work to the door.
3.1.0.4. lightsource
class lightsource: thing
lightsources are gameworld objects which can supply light to a darkened room.
The class supplies code in the .doTurnon routine for turning on the lights,
but that is all.
Attributes
.isactive Flag determining whether the light is on or not.
.islamp Flag determining whether the object is a lamp. All objects with
this attribute set true at preinit() are assembled into
global.lampList.
.islit Alias to .isactive.
3.1.0.5. liquid
class liquid: thing
liquids are gameworld objects which are liquid in nature. They can be poured
onto random objects, mixed with other liquids, and spilled if the player
isn't careful. They can (as defined in Pianosa) be put only in
liquidcontainers. For all these reasons, liquids can be a pain to put in IF.
Ofttimes, liquid objects can simply be instances of a type of liquid. This
type is defined in an object called the liquidclass which contains rules about
how the liquid functions; for single instances, this object should probably
just be the object itself.
Attributes
.isliquid Flag declaring for all the world to know that this is, indeed,
a liquid.
.liquidtype Determines the liquidclass for self.
Actions
.mixWith( list )
Mixes self with every object on the list. Reduces each object to its
liquidclass, if applicable, and calls .mix on the liquidclass. Returns
true if the contents are altered.
.mix( instance, reactant_liquidclass, reactant )
Mixes self with a reactant. Should return true if contents are altered.
.spill( jostlelevel )
Causes self to spill out of its container and by default disappear.
3.1.0.6. readable
class readable: thing
readables are gameworld objects which happen to be readable. All this class
does is overwrite thing's verDoRead definition. The text can be put in
.readdesc.
3.1.0.7. switchablething
class switchablething: thing
switchablethings are gameworld objects which happen to be turnable on and
off. They can also be switched (toggled). They can be turned on in the
dark as long as the .verDarkSwitch property does not display a message.
Attributes
.isactive Flag determining whether self is switched on or off.
.routeswitch Defines whether self should be switched (returns nil), or
whether another object should be (returns that object).
Methods
.verDarkSwitch( actor )
Verification routine called when the actor's location is dark
(.islit = nil).
Actions
.turnOff
Sets .isactive nil and displays a message.
.turnOn
Sets .isactive true and displays a message.
3.1.1. room
class room: thing
A room is an object meant to contain actors such as the player character.
Rooms set the maxweight and maxbulk properties nil for In and On. The
In position describes a state of floating above the floor; the On
position describes a state of lying on the floor.
Direction properties are also tied to the room; they are defined by
the .dirTravel attribute of the Direction objects. Unlike in Adv.t, these
are meant to be straight objects and not contain code. Any code related with
traveling in a certain direction is in the Go direction property
(.dirGoDirProp on the Direction), which is called with one argument, the
actor doing the traveling. Although Pianosa does not define any Directions,
ts_std.t includes the standard twelve (compass rose, up/down, enter/exit).
The nomenclature used by that file, although not binding, follows the form
of &north and &goNorth.
Attributes
.ambientlist String/string list of ambient sound resource names.
.bgambientlist String/string list of background ambient sound resource names.
.darkdesc Displays an error message saying that it's too dark to do that.
.darkroomdesc Displays the long description of the room in the dark.
.darkstatusdesc Displays the short description of the room in the dark.
.doesecho Flag determining whether .echonoise is called in this room instead
of .hearnoise. Defaults to nil.
.Exitless Displays a message stating that there is no exit in the intended
direction.
.exitlist Property list of the standard exits.
.flooradesc Displays the short description of the floor, preceded by the
indefinite article.
.floorldesc Displays the long description of the floor.
.floorsdesc Displays the short description of the floor.
.floorthedesc Displays the short description of the floor, preceded by
the definite article.
.genadesc Displays a short epithet for the room, preceded by the indefinite
article.
.gensdesc Displays a short epithet for the room, such as "area" or "room".
.genthedesc Displays a short epithet for the room, preceded by the
definite article.
.hasambient Flag determining whether self has ambient sounds or not.
.hasbgambient Flag determining whether self has background ambient sounds
or not.
.hasfloor Flag determining whether self has a floor or not.
.hasmusic Flag determining whether self has background music or not.
.incontdesc( c ) See container classes.
.isinside Flag determining whether self is inside or outside.
.isroom Flag specifying that yes, this is a room.
.isseen Flag determining whether self has been entered by the player
character or not.
.issleepable( actor, position ) Flag determining whether actor may
comfortably sleep here; if not, displays a message.
.killoldambient Flag determining whether ambient sounds currently queued
should be removed upon entrance into self. Defaults to true.
.killoldbgambient Flag determining whether background ambient sounds
currently queued should be removed upon entrance into self.
Defaults to nil.
.killoldmusic Flag determining whether background music currently queued
should be removed upon entrance into self. Defaults to nil.
.leavelist List of objects to be given a .leaving message when an actor
leaves self.
.lightson Flag determining whether the room's lighting is on or not.
Defaults true.
.musiclist String/string list of background music resource names.
.notfollowroom Flag determining whether followers shouldn't follow their
targets into self.
.incontdesc( c ) See container classes.
.reachable List of objects which are specifically reachable from self.
.repeatambient Number of times ambient sounds should repeat or true for
continual repeat.
.repeatbgambient Number of times background ambient sounds should repeat
or true for continual repeat.
.repeatmusic Number of times background music should repeat or true for
continual repeat.
.roomdesc Displays the long description of the room. Defaults to .ldesc.
.roomdescafter Displays whatever after the .roomdesc and .bdescs, but before
the inventories. Defaults to "\n\t".
.scoredesc Displays the score description (on the right in the default
status line) in HTML mode.
.sequenceambient String value for "sequence" attribute in ambient sound
definition. Can be `random', `cycle', or `replace'. Defaults
to `random'.
.sequencebgambient See .sequenceAmbient.
.sequencemusic See .sequenceAmbient.
.sitloc Object to be sat in if the command is just "sit"; defaults
to nil (meaning the floor).
.statusdesc Displays the short status-line description of the room.
Default to .sdesc.
.statusLine Displays the status-line text or, in HTML mode, configures
the status-line banner.
.tagdesc The status-line text; defaults to .statusdesc or .darkstatusdesc
apropos.
.Wait( actor ) Displays a message when the player types "wait".
Methods
.actorlist( actor )
Finds all actors within the room, the given actor excluded, verifies them
via .inEveryone, and returns them in a list.
.addleavelist( object )
Adds the given object to .leavelist.
.cantexit
Displays a message stating that movement is impossible, either because
it is blocked in the specified direction (.Exitless) or because it is
too dark (stumble()).
.cantreachfrom( actor, object )
Displays a message stating that an object cannot be reached from self by
actor. Called by .cantreach.
.Enter
Displays a message associated with entering self.
.enterRoom( actor, verbosity )
Does tasks associated with actor's entering self. verbosity equaling nil
means that passive messages (like describing the room) should be
suppressed. If actor is the player character, calls .Enter, .initSound,
.lookAround (if verbosity is true), and .firstseen (if .isseen is nil).
.firstseen
Displays a message associated with entering self for the first time.
.initAmbient
Initiates ambient sounds for self. See .hasAmbient, .ambientList,
.repeatAmbient, .seqenceAmbient, and .killOldAmbient.
.initBGAmbient
Initiates background ambient sounds for self. See .hasBGAmbient,
.bgambientList, .repeatBGAmbient, .seqenceBGAmbient, and .killOldBGAmbient.
.initMusic
Initiates background music for self. See .hasMusic, .musicList,
.repeatMusic, .seqenceMusic, and .killOldMusic.
.initSound
Initiates all sound for self by calling .initMusic, .initBGAmbient, and
.initAmbient. Called from .enterRoom.
.islit
Determines whether the room is lit or not. Checks .lightson, and if that
fails then checks every object in global.lampList to see if it's on and
visible from self, and if that fails checks for a parent room and sees
whether that room's lights are on.
.leaveRoom( actor, verbosity )
Notification to room that an actor is leaving. Sends .Leaving messages
to all objects in .leavelist. verbosity equaling nil usually means that
this is a nested room to parent room movement.
.lookAround( verbosity )
Displays a description of the room according to the given verbosity. By
default, displays the tagline and then calls .nrmLookAround or
.darkroomdesc as appropriate.
.notifyPreactors( actor, verbobject, directobject_object, prepositionobject,
indirectobject_object)
Sends .preactorAction messages to all objects of class Preactor visible
within self. Called by .roomAction.
.notifyReactors( actor, verbobject, directobject_object, prepositionobject,
indirectobject_object)
Sends .reactorAction messages to all objects of class Reactor visible
within self. Called by reactorDaemon.
.nrmLookAround( verbosity )
Describes self with a given verbosity. By default nil verbosity means
to display only a standard inventory of self's contents and true verbosity
means to display the long description (.roomdesc), list the .describealone
objects, and then display the standard inventory.
.orderPreactorList( list )
Allows modification and ordering of the list of Preactors for
.notifyPreactors
.orderReactorList( list )
Allows modification and ordering of the list of Reactors for
.notifyReactors.
.roomAction( actor, verbobject, directobject_object, prepositionobject,
indirectobject_object)
Action routine for the actor's location.
.roomCheck( verbobject )
Determines whether verbobject is a valid verb within self; called by
the parser. Should display a message if returning nil.
Actions
.darkTravel( actor, dir )
Handles movement in a darkened room. By default, replicates the .travel
experience except that it requires that the destination be lit.
.echoNoise( type )
Causes a noise of a certain type to be echoed within self. The default
procedure is to call .hearnoise in self and then call .hearnoise in all
adjoining rooms (with no option for echo) and any existant parent room.
.hearNoise( type )
Causes a noise of a certain type to be heard by all objects of class
hearer within self; .hearnoise is called on all of said objects.
.jump( actor )
Causes actor to jump within self. The default version displays a
"witty" response and jostles the actor's contents.
.makeNoise( type )
Causes a noise of a certain type to be made within self. The default
procedure is to call .hearnoise in self, call .echonoise in an adjoining
room if said room has .doesecho set true (otherwise, call .hearnoise),
and then call .makenoise in any existing parent room.
.sitDown( actor )
Causes actor to sit down within self. The default version checks for
a .sitloc on self and if none is found calls .Sitdown on actor.
.standUp( actor )
Causes actor to stand up within self. The default version calls
.Standup on actor.
.travel( actor, direction_property )
Causes actor to attempt travel in the given direction. Calls .darkTravel
if the room is not lit, verifies the movement via the .go property
(see .goDown), checks to see that direction leads somewhere (if not,
calls .cantexit), and then calls .travelTo on actor if all checks out.
-- room subclasses
3.1.1.0. nestedroom
class nestedroom: room
nestedrooms are rooms designed to be within other rooms; however, the code
their definition adds is mostly veneer. .lookAround messages are passed
to parent locations and .statusdesc is set to show that this room is
really just a location within a location. Followers, for the most part,
should not follow their quarries into these locations (.isfollowroom is
nil); articles dropped here should really fall into other places
(.isdroploc is nil).
Attributes
.statusPrep Displays the preposition to be used in the status line:
"Cellar, in the comfy chair".
.outOfPrep Displays the preposition to be used when leaving: "You get
out of the car.".
--- nestedroom subclasses
3.1.1.0.0. bednested
class bednested: fixedthing, nestedroom, surface
bednesteds are gameworld objects which can either be sat upon or lied
down upon. Objects put into the chair are instead put onto the chair.
The definition changes .standup to move the standing actor into the parent
room.
Attributes
.autoExit Flag determining whether self should be automatically left when
the sitting actor attempts to leave the parent room. Defaults
to nil.
Methods
.removePrepPosture( posture )
Displays the preposition for removing oneself from the bed when one
is in a given posture.
3.1.1.0.1. chairnested
class chairnested: fixedthing, nestedroom, surface
chairnesteds are gameworld objects meant to be sat in like a chair. They
are identical to bednesteds except that they do not allow actors to lie
upon them, their exit prepositions are slightly different, and .autoExit
has a different default. chairnesteds have the infrastructure to be lied
upon, so if a sofa or futon is desired, simply copying bednested code
into the object's definition should be enough.
Attributes
.autoExit Flag determining whether self should be automatically left when
the sitting actor attempts to leave the parent room. Defaults
to true.
Methods
.removePrepPosture( posture )
Displays the preposition for removing oneself from the chair when one
is in a given posture.
(the roomfloor object is found here in the Pianosa library file)
3.1.1.0.2. vehicle
class vehicle: nestedroom
vehicles are gameworld objects which are meant to convey actors from one
place to another. They can either be "open" or "closed"; if closed
(.isopen is nil), they are (or should be) in their own little world, with
the whole of the outside inaccessible. Some vehicles can also be taken;
this case is provided for within the definition. Furthermore, many actions
are forbidden to be done to the vehicle while inside it; because this is
done with .dobjGen and .iobjGen, it is possible to allow further actions
(than examine, put in/on, and leave) by making sure that the proper
verification routine is defined specifically within the object's code.
Atributes
.Error Displays a message that the action is not possible from
within the vehicle.
.isvehicle Flag specifying that yes indeed, this is a vehicle.
.reachable List of objects accessible from within vehicle. If adding
anything to this, make sure the list 1) includes self and
2) takes into account openness, if that feature is being used.
3.1.2. container, cover, mask, surface
class container: thing
class cover: thing
class mask: thing
class surface: thing
A container is an object meant to contain other objects within it. A cover
is an object meant to contain other objects beneath it. A mask is an
object meant to contain other objects behind it. A surface is an object
meant to contain other objects on top of it.
These are the four default position-holders in Pianosa. Properties dealing
with the duties of having contents will be dealt with here, including the
contents-listing methods.
There are four companion classes: qcontainer, qcover, qmask, and qsurface.
These classes simply set their respective .isq attributes true.
Attributes
.behindcont List of all objects held directly behind self. Set up
automatically.
.behindcontdesc( c ) Displays an introductory message for an inventory
listing; if this returns true a form of "to be" will be
conjugated (according to the number of objects to be listed)
directly after the message. c is the number of objects
(invCount) in the list.
.behindcontreachable Flag determining whether objects held behind self
are generally accessible. Defaults to .behindcontvisible.
.behindcontvisible Flag determining whether objects held behind self are
generally visible. Defaults to true.
.behinddesc Displays a description of what's behind self. Defaults to
nothing.
.emptybehind Displays a message stating that there is nothing (visible)
behind self.
.emptyin See .emptybehind.
.emptyon See .emptybehind.
.emptyunder See .emptybehind.
.excessbulk( object, position ) Displays a message stating that object
will not fit in position because it is too large.
.excessweight( object, position ) Displays a message stating that object
will not fit in position because it is too heavy.
.incont See .behindcont.
.incontdesc( c ) See .behindcontdesc.
.incontreachable See .behindcontreachable. Also, defined to check .isopen.
.incontvisible See .behindcontvisible. Also, defined to check .isopen
and .istransparent.
.indesc See .behinddesc.
.iscontainer Flag specifying that yes, good sir, this is a container.
.iscover Flag specifying that indeed, this is a most verifiable cover.
.isdroploc Flag determining whether dropping an object here should cause it
to stay here or fall further. Default true for rooms, nil for
everything else.
.ismask Flag specifying that in fact, this is a certified mask.
.isqcontainer Flag determining whether a container will list its contents
in room listings and inventories. Default nil.
.isqcover See .isqcontainer.
.isqmask See .isqcontainer.
.isqsurface See .isqcontainer.
.issurface Flag specifying that this is truly a surface to have things laid
upon.
.istransparent Flag determining whether, when closed, the contents of self
can be seen anyway.
.listcontoninspect Flag determining whether .listallcontents will be called
when an object is looked at. Default is true.
.maxbulkbehind Bulk limit for the Behind position. Set nil for no limit.
Default is 10.
.maxbulkin See .maxbulkbehind.
.maxbulkon See .maxbulkbehind.
.maxbulkunder See .maxbulkbehind.
.maxweightbehind Weight limit for the Behind position. Set nil for no
limit. Default is 10.
.maxweightin See .maxweightbehind.
.maxweighton See .maxweightbehind.
.maxweightunder See .maxweightbehind.
.oncont See .behindcont.
.oncontdesc( c ) See .behindcontdesc.
.oncontreachable See .behindcontreachable.
.oncontvisible See .behindcontvisible.
.ondesc See .behinddesc.
.outOfPrep Displays the preposition for actors getting off of/out of a
nestedroom like a chair or a bed. Compare .removePrep.
.posdesc( position ) Displays how to refer to an object being held in a
certain position relative to self.
Example: desk.posdesc( Under ) displays "under the desk"
.posPrep( position ) Displays the preposition to describe being in a
certain position relative to self.
Example: desk.posPrep( Under ) displays "under"
.removePrep( position ) Displays the preposition to describe being taken
out from a certain position relative to self.
Example: desk.removeProp( Under ) displays "out from under"
.statusPrep Displays the preposition for actors within a nestedroom like
a chair or a bed. Compare .posPrep.
.undercont See .behindcont.
.undercontdesc( c ) See .behindcontdesc.
.undercontreachable See .behindcontreachable.
.undercontvisible See .behindcontvisible.
.underdesc See .behinddesc.
Methods
.bulkbehind
Determines the total extra bulk added by objects within the Behind
position. Defaults to returning 0 regardless, because most containers
are fixed.
.bulkin
Determines the total extra bulk added by objects within the In position.
If self has .isflexiblecontainer set true, it actually sums this up;
otherwise, it simply returns 0.
.bulkon
See .bulkbehind.
.bulkunder
See .bulkbehind.
.contents
An alias to .allcont.
.Drop( object, target )
Message sent to self by .putInto to verify letting go of object being
moved to target. Returns true to abort movement.
.dropall( {position, {, dontDropWornObjects {, jostle }}} )
Causes all objects in a position (default In) to be dropped from self
(excepting objects with .isworn set true unless the first argument is nil)
according to .dropFrom.
.dropping( object, position )
Returns a list in the format [ object position ] specifying where an
object, dropping from a certain position around self, should fall.
By default, if .isdroploc is set nil then .dropping is called on self's
location with the position On.
.endPutInto( object, position )
Notification by .putInto that object has been successfully put into
position around self. By default, calls .mixCont.
.gaca( class {, property {, value {, argument }}} )
Gets all contents of a certain class in any position around self. Loops
through the positions calling the appropriate gac-class property on self.
If property exists, that property must equal value (default = true) on an
object for it to be included in the list; if argument exists, it will be
passed to the property.
.gacb( class {, property {, value {, argument }}} )
Gets all contents of a certain class behind self. Calls .gacva on every
object behind self and adds those objects as well. For the last three
parameters, see .gaca.
.gaci( class {, property {, value {, argument }}} )
See .gacb.
.gaco( class {, property {, value {, argument }}} )
See .gacb.
.gacu( class {, property {, value {, argument }}} )
See .gacb.
.gacva( class {, property {, value {, argument }}} )
Gets all contents of a certain class in any visible position around self.
See .gaca.
.Grab( object, position )
Notification by .moveInto that object is being removed from a certain
position around self (or from an object in a certain position around
self); if this returns non-nil the movement is canceled.
.listallalonecontents( {depth} )
Lists all describe-alone contents in all non-quiet, visible positions
around self at a certain inventory depth (default = 1). Calls
aloneContListing , which calls .bdesc.
.listallcontcontents( {depth, {verbosity_type }} )
Lists all non-quiet, visible contents positions of objects held in
non-quiet, visible positions around self at a certain inventory depth
(default = 2) and with a certain verbosity type. Calls innerContListing,
which in turn calls .listallcontents on the contents items.
.listallcontents( {depth, {verbosity_type}} )
Lists all non-quiet, visible contents positions on self at a
certain inventory depth (default = 1) and with a certain verbosity type.
Calls the specific contents-listing properties (see .listbehindcont) and
then .listallcontcontents.
.listbehindcont( depth, verbosity_type )
See .listXcont.
.listincont( depth, verbosity_type )
See .listXcont.
.listoncont( depth, verbosity_type )
See .listXcont.
.listundercont( depth, verbosity_type )
See .listXcont.
.listXcont( position, depth, verbosity_type )
Lists objects in a certain position relative to self, provided that the
objects there are visible (see .behindcontvisible). Passing true as
depth forces a wide-inventory display; otherwise, depth just specifies
indentation. Displays the appropriate introduction message (see
.behindcontdesc) if there are to-be-listed contents or the verbosity
type is 0, then calls contListing.
.reachList( actor )
Determines the list of all objects reachable by actor around self.
.routebehind( object, jostle )
Routes where a certain object, being put behind self, should go. To
abort the movement, this should return nil.
.routein( object, jostle )
See .routebehind.
.routeon( object, jostle )
See .routebehind.
.routeunder( object, jostle )
See .routebehind.
.speakList( actor )
Determines the list of all objects speakable to by actor around self.
Defaults to .visList.
.Take( object, position )
Message sent to self by .putInto to verify accepting object being moved
to a position around self. Returns true to abort movement.
.verGrab( object, position )
Verification routine checking whether object can be removed from a
certain position around self (or from an object in a certain position
around self). Shows displeasure by diplaying a message, should not
otherwise.
.visList( actor )
Determines the list of all objects visible by actor from self.
.weightbehind
Determines the total extra weight added by objects within the Behind
position. Defaults to 0.
.weightin
Determines the total extra weight added by objects within the In position.
.weighton
See .weightin.
.weightunder
See .weightbehind.
Actions
.forceAccept( object {, position } )
Causes object to be moved into a certain position (default = In) relative
to self. By default, does this by setting the appropriate location
property on object to self and adding object to the appropriate contents
list on self.
.forceRelease( object )
Causes object to be removed from around self. By default, does this by
removing object from the appropriate contents list of self and then
clearing all location properties of object (by calling .clearloc).
.mixCont( position )
Causes contents in a certain position to be suddenly mixed. Loops through
the contents list, calling .mixwith on each object with every other object
in the loop.
-- container class subclasses
3.1.2.0. coverer
class coverer: qcover
coverers are covers which do not have a real-world Under position counterpart
per se, but instead are capable of hiding things underneath them until they
are moved. The class defines a special .Move, so any other code there should
include or pass to the library code. It also defines .verDoMove and .doMove
routines which enable that command to cause covered items to be revealed.
3.1.2.1. liquidcontainer
class liquidcontainer: qcontainer
liquidcontainers are containers designed to hold liquids. They can either
service only liquids (.liquidsonly set true) or function as general containers.
Whether they are qcontainers or not depends upon whether they hold liquids
or not, because they alter .specialdesc to include what they contain if it's
a liquid. This class overrides .Take.
Attributes
.liquidsonly Flag determining whether other objects can be placed in self
beside liquids.
.oneliquidonly Flag determining whether more than one liquid may be placed in
self at a time.
.spillsafe Determines what jostle level must be exceeded to cause liquids
inside to spill; true if self is completely spillsafe.
Methods
.holdsliquid
Determines whether self holds a liquid or not.
.liquiddesc
Describes the liquid within self.
3.1.2.2. openable
class openable: container
openables are containers which can be opened (if .isopenable is true) and
shut (if .iscloseable is true) at will. If transparent (.istransparent is
true), their contents can be seen from without.
Attributes
.Close( actor ) Displays a message upon closing self.
.iscloseable Flag determining whether self is closeable or not.
Defaults true.
.isopen Flag determining whether self is currently open or not.
Defaults true.
.isopenable Flag determining whether self is openable or not.
Defaults true.
.istransparent Flag determining whether self is transparent or not.
Defaults nil.
.Open( actor ) Displays a message upon opening self.
Actions
.close( actor )
Closes self.
.open( actor )
Opens self.
--- openable subclass
3.1.2.2.0. lockable
class lockable: openable, Lockcode
lockables are openables which can be locked and unlocked as well (if
.islockable and .isunlockable are set true). Most of their functional code
is in the Lockcode class.
Attributes
.autoUnlock Flag determining whether attemping to open self should
automatically unlock self if possible.
.Close( actor ) Displays a message upon closing self.
.iscloseable Flag determining whether self is closeable or not.
Defaults true.
.islockable Flag determining whether self is lockable or not.
Defaults nil.
.isopen Flag determining whether self is currently open or not.
Defaults true.
.isopenable Flag determining whether self is openable or not.
Defaults true.
.istransparent Flag determining whether self is transparent or not.
Defaults nil.
.isunlockable Flag determining whether self is unlockable or not.
Defaults true.
.Lock( actor, key ) Displays a message upon locking self.
.mykey Object or object list of valid keys for self. nil means no key
is necessary.
.mykeyKnown Flag determining whether a correct key for self is known
to the player.
.Open( actor ) Displays a message upon opening self.
.Unlock( actor, key ) Displays a message upon unlocking self.
Methods
.keyHeldBy( object )
Checks whether a defaultable key is being held by object.
.keyIsValid( object )
Checks whether object is a valid key for self.
Actions
.close( actor )
Closes self.
.lock( actor, key )
Locks self.
.open( actor )
Opens self.
.unlock( actor, key )
Unlocks self.
3.1.2.3. qcontainer, qcover, qmask, qsurface
class qcontainer: container
class qcover: cover
class qmask: mask
class qsurface: surface
These four classes are enabler classes, merely setting their respective
q-properties true.
--- qcontainer subclass
3.1.2.3.0. movableActor
class movableActor: qcontainer
movableActors are NPCs which can be picked up and taken with the player.
All characters in the game inherit from movableActor.
Attributes
.actorname The name of the actor. Referenced by sdesc.
.bdesc Message briefly describing self to everything else in the room.
.disavow Message saying that self knows nothing about what was asked of
self.
.Hungerwarning Message notifying self that if self doesn't eat almost
immediately, self is going to die.
.Hungerwatch Message notifying self that if self doesn't eat "soon", self
is going to die.
.hasfollower Flag determining whether self can be followed.
.hashunger Flag determining whether self must eat to survive.
.hassleep Flag determining whether self must occaisionally sleep.
.hungerTime Number determining how long self can live without dying.
.hungryTime Number determining how long self has gone without eating.
.inEveryone Flag determining whether self is included in Everyone.
Defaults true.
.iPos Determines the inventory position for self.
.isactor Flag specifying the fact that self is an actor, and thus can be
given commands.
.isasleep Flag determining whether self is asleep or not.
.possessive Displays the possessive, e.g. "your" or "