describe an actor as being in/being removed from/being moved into this location

Default preposition to use when an actor is in/on this object (as a nested location), and full prepositional phrase, with no article and with an indefinite article. By default, we use the objInPrep for actors as well.

preposition to use when an actor is being removed from this location

The indefinite-article name for disambiguation prompts. We use the same logic here as in theDisambigName.

Get a list of all of our possible states. For an object that can assume varying states as represented by getState, this should return the list of all possible states that the object can assume.

My name with an indefinite article. By default, we figure out which article to use (a, an, some) automatically.

In rare cases, the automatic determination might get it wrong, since some English spellings defy all of the standard orthographic rules and must simply be handled as special cases; for example, the algorithmic determination doesn't know about silent-h words like "hour". When the automatic determination gets it wrong, simply override this routine to specify the correct article explicitly.

The strength of the light the object is giving off, if indeed it is giving off light. This value should be one of the following:

0: The object is giving off no light at all.

1: The object is self-illuminating, but doesn't give off enough light to illuminate any other objects. This is suitable for something like an LED digital clock.

2: The object gives off dim light. This level is bright enough to illuminate nearby objects, but not enough to go through obscuring media, and not enough for certain activities requiring strong lighting, such as reading.

3: The object gives off medium light. This level is bright enough to illuminate nearby objects, and is enough for most activities, including reading and the like. Traveling through an obscuring medium reduces this level to dim (2).

4: The object gives off strong light. This level is bright enough to illuminate nearby objects, and travel through an obscuring medium reduces it to medium light (3).

Note that the special value -1 is reserved as an invalid level, used to flag certain events (such as the need to recalculate the ambient light level from a new point of view).

Most objects do not give off light at all.

can the player character see/hear/smell/touch me?

Test to see if we can match the pronouns 'him', 'her', 'it', and 'them'. By default, these simply test the corresponding isXxx flags (except 'canMatchThem', which tests 'isPlural' to see if the name has plural usage).

my message indicating that another object x cannot be put into me because I'm already in x

Our collective group. Note - this property is obsolescent; it's supported only for compatibility with old code. New games should use 'collectiveGroups' instead.

My associated "collective group" objects. A collective group is an abstract object, not part of the simulation (i.e, not directly manipulable by characters as a separate object) that can stand in for an entire group of related objects in some actions. For example, we might have a collective "money" object that stands in for any group of coins and paper bills for "examine" commands, so that when the player says something like "look at money" or "count money," we use the single collective money object to handle the command rather than running the command iteratively on each of the individual coins and bills present.

The value is a list because this object can be associated with more than one collective group. For example, a diamond could be in a "treasure" group as well as a "jewelry" group.

The associated collective objects are normally of class CollectiveGroup. By default, if our 'collectiveGroup' property is not nil, our list consists of that one item; otherwise we just use an empty list.

My contents. This is a list of the objects that this object directly contains.

Determine if my contents are to be listed when I'm shown in a listing (in a room description, inventory list, or a description of my container).

Note that this doesn't affect listing my contents when I'm *directly* examined - use contentsListedInExamine to control that.

By default, we'll list our contents in these situations if (1) we have some kind of presence in the description of whatever it is the player is looking at, either by being listed in the ordinary way (that is, isListed is true) or in a custom way (via a specialDesc), and (2) contentsListedInExamine is true. The reasoning behind this default is that if the object itself shows up in the description, then we usually want its contents to be mentioned as well, but if the object itself isn't mentioned, then its contents probably shouldn't be, either. And in any case, if the contents aren't listed even when we *directly* examine the object, then we almost certainly don't want its contents mentioned when we only indirectly mention the object in the course of describing something enclosing it.

Determine if my contents are to be listed when I'm directly examined (with an EXAMINE/LOOK AT command). By default, we *always* list our contents when we're directly examined.

Determine if my contents are listed separately from my own list entry. If this is true, then my contents will be listed in a separate sentence from my own listing; for example, if 'self' is a box, we'll be listed like so:

You are carrying a box. The box contains a key and a book.

By default, this is nil, which means that we list our contents parenthetically after our name:

You are carrying a box (which contains a key and a book).

Using a separate listing is sometimes desirable for an object that will routinely contain listable objects that in turn have listable contents of their own, because it can help break up a long listing that would otherwise use too many nested parentheticals.

Note that this only applies to "wide" listings; "tall" listings will show contents in the indented tree format regardless of this setting.

My "contents lister." This is a Lister object that we use to display the contents of this object for room descriptions, inventories, and the like.

the Lister to use when showing my contents as part of my own description (i.e., for Examine commands)

Flag: I've been desribed. This is nil by default; we set this to true whenever the player explicitly examines the object.

The name of the object, for the purposes of disambiguation prompts to disambiguation among this object and basic equivalents of this object (i.e., objects of the same class marked with isEquivalent=true).

This is used in disambiguation prompts in place of the actual text typed by the user. For example, suppose the user types ">take coin", then we ask for help disambiguating, and the player types ">gold". This narrows things down to, say, three gold coins, but they're in different locations so we need to ask for further disambiguation. Normally, we ask "which gold do you mean", because the player typed "gold" in the input. Once we're down to equivalents, we don't have to rely on the input text any more, which is good because the input text could be fragmentary (as in our present example). Since we have only equivalents, we can use the actual name of the objects (they're all the same, after all). This property gives the name we use.

For English, this is simply the object's ordinary disambiguation name. This property is separate from 'name' and 'disambigName' for the sake of languages that need to use an inflected form in this context.

The name of the object, for the purposes of disambiguation prompts. This should almost always be the object's ordinary name, so we return self.name by default.

In rare cases, it might be desirable to override this. In particular, if a game has two objects that are NOT defined as basic equivalents of one another (which means that the parser will always ask for disambiguation when the two are ambiguous with one another), but the two nonetheless have identical 'name' properties, this property should be overridden for one or both objects to give them different names. This will ensure that we avoid asking questions of the form "which do you mean, the coin, or the coin?". In most cases, non-equivalent objects will have distinct 'name' properties to begin with, so this is not usually an issue.

When overriding this method, take care to override theDisambigName, aDisambigName, countDisambigName, and/or pluralDisambigName as needed. Those routines must be overridden only when the default algorithms for determining articles and plurals fail to work properly for the disambigName (for example, the indefinite article algorithm fails with silent-h words like "hour", so if disambigName is "hour", aDisambigName must be overridden). In most cases, the automatic algorithms will produce acceptable results, so the default implementations of these other routines can be used without customization.

The default "distant" description. If this is defined for an object, then we evaluate it to display the description when an actor explicitly examines this object from a point of view where we have a "distant" sight path to the object.

If this property is left undefined for an object, then we'll describe this object when it's distant in one of two ways. If the object has its 'sightSize' property set to 'large', we'll display the ordinary 'desc', because its large visual size makes its details visible at a distance. If the 'sightSize' is anything else, we'll instead display the default library message indicating that the object is too far away to see any details.

To display a specific description when the object is distant, set this to a double-quoted string, or to a method that displays a message.

The special descriptions to use under obscured and distant viewing conditions. By default, these simply display the normal special description, but these can be overridden if desired to show different messages under these viewing conditions.

Note that if you override these alternative special descriptions, you MUST also provide a base specialDesc. The library figures out whether or not to show any sort of specialDesc first, based on the presence of a non-nil specialDesc; only then does the library figure out which particular variation to use.

Note that remoteSpecialDesc takes precedence over these methods. That is, when 'self' is in a separate top-level room from the point-of-view actor, we'll use remoteSpecialDesc to generate our description, even if the sense path to 'self' is distant or obscured.

My Distinguisher list. This is a list of Distinguisher objects that can be used to distinguish this object from other objects.

Distinguishers are listed in order of priority. The disambiguation process looks for distinguishers capable of telling objects apart, starting with the first in the list. The BasicDistinguisher is generally first in every object's list, because any two objects can be told apart if they come from different classes.

By default, each object has the "basic" distinguisher, which tells objects apart on the basis of the "isEquivalent" property and their superclasses; the ownership distinguisher, which tells objects apart based on ownership; and the location distinguisher, which identifies objects by their immediate containers.

Dummy name - this simply displays nothing; it's used for cases where messageBuilder substitutions want to refer to an object (for internal bookkeeping) without actually showing the name of the object in the output text. This should always simply return an empty string.

Get the effective location of an actor directly within me, for the purposes of a "follow" command. To follow someone, we must have the same effective follow location that the target had when we last observed the target leaving.

For most objects, we simply defer to the location.

The "equivalence key" is the value we use to group equivalent objects. Note that we can only treat objects as equivalent when they're explicitly marked with isEquivalent=true, so the equivalence key is irrelevant for objects not so marked.

Since the main point of equivalence is to allow creation of groups of like-named objects that are interchangeable in listings and in command input, we use the basic disambiguation name as the equivalence key.

Our equivalent item grouper. During initialization, we will create an equivalent grouper and store it in this property for each class object that has instances marked with isEquivalent. Note that this is stored with the class, because we want each of our equivalent instances to share the same grouper object so that they are listed together as a group.

my equivalence grouper class - when we initialize, we'll create a grouper of this class and store it in equivalentGrouper

A static game-wide table of equivalence groups. This has a table of ListGroupEquivalent-derived objects, keyed by equivalence name. Each group of objects with the same equivalence name is listed in the same group and so has the same grouper object.

current explicit visual sense information overriding live value

Get our state - returns a ThingState object describing the state. By default, we don't have varying states, so we simply return nil.

My global parameter name. This is a name that can be used in {xxx} parameters in messages to refer directly to this object. This is nil by default, which means we have no global parameter name. Define this to a single-quoted string to set a global parameter name.

Global parameter names can be especially useful for objects whose names change in the course of the game, such as actors who are known by one name until introduced, after which they're known by another name. It's a little nicer to write "{He/the bob}" than "<<bob.theName>>". We can do this with a global parameter name, because it allows us to use {bob} as a message parameter, even when the actor isn't involved directly in any command.

Note that these parameter names are global, so no two objects are allowed to have the same name. These names are also subordinate to the parameter names in the current Action, so names that the actions define, such as 'dobj' and 'actor', should usually be avoided.

When an actor takes me, the actor will assign me a holding index value, which is simply a serial number indicating the order in which I was picked up. This lets the actor determine which items have been held longest: the item with the lowest holding index has been held the longest.

verb-ending patterns for figuring out which '-s' ending to add

If we define a non-nil initDesc, and the object is in its initial description state (as indicated by isInInitState), then we'll use this property instead of "desc" to describe the object when examined. This can be used to customize the description the player sees in parallel to initSpecialDesc.

Our initial room part location. By default, we set this to nil, which means that we'll use the nominal drop destination of our actual initial location when asked. If desired, this can be set to another part; for example, if a poster is initially described as being "on the north wall," this should set to the default north wall object.

If we define a non-nil initSpecialDesc, this property will be called to describe the object in room listings as long as the object is in its "initial" state (as determined by isInInitState: this is usually true until the object is first moved to a new location). By default, objects don't have initial descriptions.

If this is non-nil, and the object is portable, this will be used (as long as the object is in its initial state) instead of showing the object in an ordinary room-contents listing. This can be used to give the object a special mention in its initial location in the game, rather than letting the ordinary room-contents lister lump it in with all of the other portable object lying around.

my "in-line" contents lister - this is the Lister object that we'll use to display my contents parenthetically as part of my list entry in a second-level contents listing

"Equivalence" flag. If this flag is set, then all objects with the same immediate superclass will be considered interchangeable; such objects will be listed collectively in messages (so we would display "five coins" rather than "a coin, a coin, a coin, a coin, and a coin"), and will be treated as equivalent in resolving noun phrases to objects in user input.

By default, this property is nil, since we want most objects to be treated as unique.

Flags indicating that the object should be referred to with gendered pronouns (such as 'he' or 'she' rather than 'it').

Note that these flags aren't mutually exclusive, so it's legal for the object to have both masculine and feminine usage. This can be useful when creating collective objects that represent more than one individual, for example.

Am I in my "initial state"? This is used to determine if we should show the initial special description (initSpecialDesc) and initial examine description (initDesc) when describing the object. By default, we consider the object to be in its initial state until the first time it's moved.

You can override this to achieve other effects. For example, if you want to use the initial description only the first time the object is examined, and then revert to the ordinary description, you could override this to return (!described).

Flag: this object is explicitly "known" to actors in the game, even if it's never been seen. This allows the object to be resolved as a topic in ASK ABOUT commands and the like. Sometimes, actors know about an object even before it's been seen - they might simply know about it from background knowledge, or they might hear about it from another character, for example.

Like the 'seen' property, this is merely the DEFAULT 'known' property that we use for actors. Each actor can individually use a separate property to track its own knowledge if it prefers; it can do this simply by overriding its isKnownProp property.

by default, most objects are not logical targets for commands

by default, regular objects are not listed when they arrive aboard vehicles (only actors are normally listed in this fashion)

Flag that this is object's name is a "mass noun" - that is, a noun denoting a continuous (effectively infinitely divisible) substance or material, such as water, wood, or popcorn; and certain abstract concepts, such as knowledge or beauty. Mass nouns are never rendered in the plural, and use different determiners than ordinary ("count") nouns: "some popcorn" vs "a kernel", for example.

Flag that this object's name is rendered as a plural (this applies to both a singular noun with plural usage, such as "pants" or "scissors," and an object used in the world model to represent a collection of real-world objects, such as "shrubs").

Proper name flag. This indicates that the 'name' property is the name of a person or place. We consider proper names to be fully qualified, so we don't add articles for variations on the name such as 'theName'.

Qualified name flag. This indicates that the object name, as given by the 'name' property, is already fully qualified, so doesn't need qualification by an article like "the" or "a" when it appears in a sentence. By default, a name is considered qualified if it's a proper name, but this can be overridden to mark a non-proper name as qualified when needed.

Have we been through Thing.construct() yet for this object? Note that this will only be set for dynamically created instances (i.e., objects created with 'new').

Is this a "top-level" location? A top-level location is an object which doesn't have another container, so its 'location' property is nil, but which is part of the game universe anyway. In most cases, a top-level location is simply a Room, since the network of rooms makes up the game's map.

If an object has no location and is not itself a top-level location, then the object is not part of the game world. It's sometimes useful to remove objects from the game world, such as when they're destroyed within the context of the game.

Single-item listing description. This is used to display the item when it appears as a single (non-grouped) item in a list. By default, we just show the indefinite article description.

"List Group" objects. This specifies a list of ListGroup objects that we use to list this object in object listings, such as inventory lists and room contents lists.

An object can be grouped in more than one way. When multiple groups are specified here, the order is significant:

- To the extent two groups entirely overlap, which is to say that one of the pair entirely contains the other (for example, if every coin is a kind of money, then the "money" listing group would contain every object in the "coin" group, plus other objects as well: the coin group is a subset of the money group), the groups must be listed from most general to most specific (for our money/coin example, then, money would come before coin in the group list).

- When two groups do not overlap, then the earlier one in our list is given higher priority.

By default, we return an empty list.

Every Thing has a location, which is the Thing that contains this object. A Thing's location can only be a simple object reference, or nil; it cannot be a list, and it cannot be a method.

If the location is nil, the object does not exist anywhere in the simulation's physical model. A nil location can be used to remove an object from the game world, temporarily or permanently.

In general, the 'location' property should be declared for each statically defined object (explicitly or implicitly via the '+' syntax). 'location' is a private property - it should never be evaluated or changed by any subclass or by any other object. Only Thing methods may evaluate or change the 'location' property. So, you can declare a 'location' property when defining an object, but you should essentially never refer to 'location' directly in any other context; instead, use the location and containment methods (isIn, etc) when you want to know an object's containment relationship to another object.

the Lister to use when showing my contents in response to a LookIn command

Flag: I've been moved out of my initial location. Whenever we move the object to a new location, we'll set this to true.

The name of the object - this is a string giving the object's short description, for constructing sentences that refer to the object by name. Each instance should override this to define the name of the object. This string should not contain any articles; we use this string as the root to generate various forms of the object's name for use in different places in sentences.

explain the reason isActorTravelReady() returned nil

our list of registered notification items

Default preposition to use when an object is in/on this object. By default, we use 'in' as the preposition; subclasses can override to use others (such as 'on' for a surface).

The initial descriptions to use under obscured and distant viewing conditions. By default, these simply show the plain initSpecialDesc; these can be overridden, if desired, to show alternative messages when viewing conditions are less than ideal.

Note that in order for one of these alternative initial descriptions to be shown, the regular initSpecialDesc MUST be defined, even if it's never actually used. We make the decision to display these other descriptions based on the existence of a non-nil initSpecialDesc, so always define initSpecialDesc whenever these are defined.

My explicit owner. By default, objects do not have explicit owners, which means that the owner at any given time is determined by the object's location - my innermost container that can own me is my owner.

However, in some cases, an object is inherently owned by a particular other object (usually an actor), and this is invariant even when the object moves to a new location not within the owner. For such cases, this property can be set to the explicit owner object, which will cause self.isOwnedBy(obj) to return true if and only if obj == self.owner.

some pre-compiled patterns for pluralName

pre-compile some regular expressions for aName

The plural name for disambiguation prompts. We use the same logic here as in theDisambigName.

Get the default plural name. By default, we'll use the algorithmic plural determination, which is based on the spelling of the name.

The algorithm won't always get it right, since some English plurals are irregular ("men", "children", "Attorneys General"). When the name doesn't fit the regular spelling patterns for plurals, the object should simply override this routine to return the correct plural name string.

Get the 'pronoun selector' for the various pronoun methods. This returns:

- singular neuter = 1
- singular masculine = 2
- singular feminine = 3
- plural = 4

our interior room name when we're in the dark

Get my "room location." If 'self' is capable of holding actors, this should return 'self'; otherwise, it should return the nearest enclosing container that's a room location. By default, we simply return our location's room location.

Our interior room name. This is the status line name we display when an actor is within this object and can't see out to the enclosing room. Since we can't rely on the enclosing room's status line name if we can't see the enclosing room, we must provide one of our own.

By default, we'll use our regular name.

Flag: I've been seen by the player character. This is nil by default; we set this to true whenever we show a room description from the player character's perspective, and the object is visible. The object doesn't actually have to be mentioned in the room description to be marked as seen - it merely has to be visible to the player character.

Note that this is only the DEFAULT 'seen' property, which all Actor objects use by default. The ACTUAL property that a given Actor uses depends on the actor's seenProp, which allows a game to keep track separately of what each actor has seen by using different 'seen' properties for different actors.

Determine whether or not the object has a "presence" in each sense. An object has a presence in a sense if an actor immediately adjacent to the object could detect the object by the sense alone. For example, an object has a "hearing presence" if it is making some kind of noise, and does not if it is silent.

Presence in a given sense is an intrinsic (which does not imply unchanging) property of the object, in that presence is independent of the relationship to any given actor. If an alarm clock is ringing, it has a hearing presence, unconditionally; it doesn't matter if the alarm clock is sealed inside a sound-proof box, because whether or not a given actor has a sense path to the object is a matter for a different computation.

Note that presence doesn't control access: an actor might have access to an object for a sense even if the object has no presence in the sense. Presence indicates whether or not the object is actively emitting sensory data that would make an actor aware of the object without specifically trying to apply the sense to the object.

By default, an object is visible and touchable, but does not emit any sound or odor.

Sense sizes of the object. Each object has an individual size for each sense. By default, objects are medium for all senses; this allows them to be sensed from a distance or through an obscuring medium, but doesn't allow their details to be sensed.

My "special" contents lister. This is the Lister to use to display the special descriptions for objects that have special descriptions when we're showing a room description for this object.

"Special" description. This is the generic place to put a description of the object that should appear in the containing room's full description. If the object defines a special description, the object is NOT listed in the basic contents list of the room, because listing it with the contents would be redundant with the special description.

By default, we have no special description. If a special description is desired, define this to a double-quoted string containing the special description, or to a method that displays the special description.

Special description phase. We list special descriptions for a room's full description in two phases: one phase before we show the room's portable contents list, and another phase after we show the contents list. This property controls the phase in which we show this item's special description. This only affects special descriptions that are shown with room descriptions; in other cases, such as "examine" descriptions of objects, all of the special descriptions are usually shown together.

By default, we show our special description (if any) before the room's contents listing, because most special descriptions act like extensions of the room's main description and thus should be grouped directly with the room's descriptive text. Objects with special descriptions that are meant to indicate more ephemeral properties of the location can override this to be listed after the room's portable contents.

One situation where you usually will want to list a special description after contents is when the special description applies to an item that's contained in a portable item. Since the container will be listed with the room contents, as it's portable, we'll usually want the special description of this child item to show up after the contents listing, so that it shows up after its container is mentioned.

Note that the specialDescOrder is secondary to this phase grouping, because we essentially list special items in two separate groups.

Get the list group for my special description. This works like the ordinary listWith, but is used to group me with other objects showing special descriptions, rather than in ordinary listings.

List order for the special description. Whenever there's more than one object showing a specialDesc at the same time (in a single room description, for example), we'll use this to order the specialDesc displays. We'll display in ascending order of this value. By default, we use the same value for everything, so listing order is arbitrary; when one specialDesc should appear before or after another, this property can be used to control the relative ordering.

Our "special" room part location. By default, we set this to nil, which means that we'll use the nominal drop destination of our actual current location when asked.

This property has a function similar to initNominalRoomPartLocation, but is used to describe the nominal room part container of the object has been moved (and even before it's been moved, if initNominalRoomPartLocation is nil).

It's rare for an object to have a special room part location after it's been moved, because most games simply don't provide commands for things like re-attaching a poster to a wall or re-hanging a fan from the ceiling. When it is possible to move an object to a new special location, though, this property can be used to flag its new special location.

Flag: suppress the automatic setting of the "seen" status for this object in room and object descriptions. Normally, we'll automatically mark every visible object as seen (by calling gActor.setHasSeen()) whenever we do a LOOK AROUND. We'll also automatically mark as seen every visible object within an object examined explicitly (such as with EXAMINE, LOOK IN, LOOK ON, or OPEN). This property can override this automatic status change: when this property is true, we will NOT mark this object as seen in any of these cases. When this property is true, the game must explicitly mark the object as seen, if and when desired, by calling actor.setHasSeen().

Sometimes, an object is not meant to be immediately obvious. For example, a puzzle box might have a hidden button that can't be seen on casual examination. In these cases, you can use suppressAutoSeen to ensure that the object won't be marked as seen merely by virtue of its being visible at the time of a LOOK AROUND or EXAMINE command.

Note that this property does NOT affect the object's actual visibility or other sensory attributes. This property merely controls the automatic setting of the "seen" status of the object.

general message for "take from" when an object isn't in me

The definite-article name for disambiguation prompts.

By default, if the disambiguation name is identical to the regular name (i.e, the string returned by self.disambigName is the same as the string returned by self.name), then we simply return self.theName. Since the base name is the same in either case, presumably the definite article names should be the same as well. This way, if the object overrides theName to do something special, then we'll use the same definite-article name for disambiguation prompts.

If the disambigName isn't the same as the regular name, then we'll apply the same algorithm to the base disambigName that we normally do to the regular name to produce the theName. This way, if the disambigName is overridden, we'll use the overridden disambigName to produce the definite-article version, using the standard definite-article algorithm.

Note that there's an aspect of this conditional approach that might not be obvious. It might look as though the test is redundant: if name == disambigName, after all, and the default theName returns theNameFrom(name), then this ought to be identical to returning theNameFrom(disambigName). The subtlety is that theName could be overridden to produce a custom result, in which case returning theNameFrom(disambigName) would return something different, which probably wouldn't be correct: the whole reason theName would be overridden is that the algorithmic determination (theNameFrom) gets it wrong. So, by calling theName directly when disambigName is the same as name, we are assured that we pick up any override in theName.

Note that in rare cases, neither of these default approaches will produce the right result; this will happen if the object uses a custom disambigName, but that name doesn't fit the normal algorithmic pattern for applying a definite article. In these cases, the object should simply override this method to specify the custom name.

Get the name with a definite article ("the box"). By default, we use our standard definite article algorithm to apply an article to self.name.

The name returned must be in the nominative case (which makes no difference unless the name is a pronoun, since in English ordinary nouns don't vary according to how they're used in a sentence).

TheName as a possessive noun (that is Bob's, that is yours). We simply return the possessive adjective name, since the two forms are usually identical in English (except for pronouns, where they sometimes differ: "her" for the adjective vs "hers" for the noun).

Scratch-pad for calculating ambient energy level - valid only after calcAmbience and until the game state changes in any way. This is for internal use within the sense propagation methods only.

Last fill material traversed by the ambient sense energy in tmpAmbient_. We must keep track of this so that we can treat consecutive traversals of the same fill material as equivalent to a single traversal.

Scratch-pads for the ambient level, best transparency, and obstructor to our *interior* surface. We keep track of these separately from the exterior data so that we can tell what we look like from the persepctive of an object within us.

My fill medium. We cache this during each sense path calculation, since the fill medium calculation often requires traversing several containment levels.

Scratch-pad for the obstructor that contributed to a non-transparent path to this object in tmpTrans_.

Scratch-pad for the sense path direction at this object. If this is true, the sense path is pointing inward - that is, the path from the source object to here is entering from outside me. Otherwise, the sense path is pointing outward.

Scrach-pad for the best transparency level to this object from the current point of view. This is used during cacheSenseInfo to keep track of the sense path to this object.

A few common irregular verbs and name-plus-verb constructs, defined for convenience.

An object has "weight" and "bulk" specifying how heavy and how large the object is. These are in arbitrary units, and by default everything has a weight of 1 and a bulk of 1.

by default, objects don't accept commands

add myself and all of my contents, recursively including contents of contents, to a vector

Add this item and its direct containment connections to the lookup table. This must recursively add all connected objects that aren't already in the table.

Add an item to our registered notification list for actions involving this object as the direct object, indirect object, and so on.

Items can be added here if they must be notified of actions involving this object regardless of the physical proximity of this item and the notification item.

Add an object to my contents.

Note that this should NOT be overridden to cause side effects - if side effects are desired when inserting a new object into my contents, use notifyInsert(). This routine is not allowed to cause side effects because it is sometimes necessary to bypass side effects when moving an item.

Add myself to a sense info table. This is called by senseInfoTable() for each object connected by containment to the source object 'src', after we've fully traversed the containment tree to initialize our current-sense properties (tmpAmbient_, tmpTrans_, etc).

Our job is to figure out if 'src' can sense us, and add a SenseInfo entry to the LookupTable 'tab' (which is keyed by object, hence our key is simply 'self') if 'src' can indeed sense us.

Note that an object that wants to set up its own special sensory data can do so by overriding this. This routine will only be called on objects connected to 'src' by containment, though, so if an object overrides this in order to implement a special sensory system that's outside of the normal containment model, it must somehow ensure that it gets included in the containment connection table in the first place.

Adjust the sense table a "look around" command. This is called after we calculate the sense info table, but before we start describing any of the room's contents, to give us a chance to remove any items we don't want described (or, conceivably, to add any items we do want described but which won't show up with the normal sense calculations).

By default, we simply remove the point-of-view object from the list, to ensure that it's not included among the objects mentioned as being in the room. We don't want to mention the point of view because the POV object because a POV isn't normally in its own field of view.

Adjust a drop destination chosen in a THROW. This is called on the object that was chosen as the preliminary landing location for the thrown object, as calculated by getHitFallDestination(), to give the preliminary destination a chance to redirect the landing to another object. For example, if the preliminary destination simply isn't a suitable surface or container where a projectile could land, or it's not big enough to hold the projectile, the preliminary destination could override this method to redirect the landing to a more suitable object.

By default, we don't need to make any adjustment, so we simply return 'self' to indicate that this can be used as the actual destination.

Receive notification that a command has just been performed. This is called by the same rules as beforeAction(), but under the conditions prevailing after the command has been completed.

Receive notification that a traveler has just arrived via travelerTravelTo(). This notification is sent to each object connected to the traveler by containment, in its new location, just after the travel completes.

Get a vector of all of my contents, recursively including contents of contents.

Apply an indefinite article ("a box", "an orange", "some lint") to the given name. We'll try to figure out which indefinite article to use based on what kind of noun phrase we use for our name (singular, plural, or a "mass noun" like "lint"), and our spelling.

By default, we'll use the article "a" if the name starts with a consonant, or "an" if it starts with a vowel.

If the name starts with a "y", we'll look at the second letter; if it's a consonant, we'll use "an", otherwise "a" (hence "an yttrium block" but "a yellow brick").

If the object is marked as having plural usage, we will use "some" as the article ("some pants" or "some shrubs").

Some objects will want to override the default behavior, because the lexical rules about when to use "a" and "an" are not without exception. For example, silent-"h" words ("honor") are written with "an", and "h" words with a pronounced but weakly stressed initial "h" are sometimes used with "an" ("an historian"). Also, some 'y' words might not follow the generic 'y' rule.

'U' words are especially likely not to follow any lexical rule - any 'u' word that sounds like it starts with 'y' should use 'a' rather than 'an', but there's no good way to figure that out just looking at the spelling (consider "a universal symbol" and "an unimportant word", or "a unanimous decision" and "an unassuming man"). We simply always use 'an' for a word starting with 'u', but this will have to be overridden when the 'u' sounds like 'y'.

the indefinite-article name in the objective case

Get my name (in various forms) distinguished by my owner or location.

If the object has an owner, and either we're giving priority to the owner or our immediate location is the same as the owner, we'll show using a possessive form with the owner ("bob's flashlight"). Otherwise, we'll show the name distinguished by our immediate container ("the flashlight in the backpack").

These are used by the ownership and location distinguishers to list objects according to owners in disambiguation lists. The ownership distinguisher gives priority to naming by ownership, regardless of the containment relationship between owner and self; the location distinguisher gives priority to naming by location, showing the owner only if the owner is the same as the location.

We will presume that objects with proper names are never indistinguishable from other objects with proper names, so we won't worry about cases like "Bob's Bill". This leaves us free to use appropriate articles in all cases.

Announce myself as a default object for an action. By default, we'll show the standard library message announcing a default.

Add to a vector all of my contents that are directly held when I'm being directly held. This is used to add the direct contents of an item to scope when the item itself is being directly held.

In most cases, we do nothing. Certain types of objects override this because they consider their contents to be held if they're held. For example, a keyring considers all of its keys to be held if the keyring itself is held, because the keys are attached to the keyring rather than contained within it.

Our room atmospheric message list. This can be set to an EventList that provides messages to be displayed while the player character is within this object.

By default, if our container is visible to us, we'll use our container's atmospheric messages. This can be overridden to provide our own atmosphere list when the player character is in this object.

Base moveInto - this is the low-level containment changer; this routine does not send any notifications to any containers, and does not mark the object as moved. This form should be used only for internal library-initiated state changes, since it bypasses all of the normal side effects of moving an object to a new container.

Perform the basic 'examine' action. This shows either the normal or initial long description (the latter only if the object hasn't been moved yet, and it has a special initial examine description), and marks the object as having been described at least once.

Basic examination of an object for touch. As with the basic taste examination, we don't use an emanation object or distinguish transparency levels, because feeling an object requires direct physical contact.

Basic examination of the object for sound. If the object has an associated noise object, we'll describe it.

If 'explicit' is true, we'll show our soundDesc if we have no associated Noise object; otherwise, we'll show nothing at all unless we have a Noise object.

Basic examination of the object for odor. If the object has an associated odor object, we'll describe it.

Basic examination of an object for taste. Unlike the smell/listen examination routines, we don't bother using a separate sensory emanation object for tasting, as tasting is always an explicit action, never passive. Furthermore, since tasting requires direct physical contact with the object, we don't differentiate levels of transparency or distance.

Receive notification that a command is about to be performed. This is called on each object connected by containment with the actor performing the command, and on any objects explicitly registered with the actor, the actor's location and its locations up to the outermost container, or the directly involved objects.

Receive notification that a traveler (an actor or a vehicle, for example) is about to depart via travelerTravelTo(), OR that an actor is about to move among nested locations via travelWithin(). This notification is sent to each object connected to the traveler by containment, just before the traveler departs.

If the traveler is traveling between top-level locations, 'connector' is the TravelConnector object being traversed. If an actor is merely moving between nested locations, 'connector' will be nil.

Service routine for getAllPathsTo: build a vector of the containment paths starting with this object.

Cache the ambient energy level at each object in the table. The list must include everything connected by containment.

Cache sensory information for all objects in the given list from the point of view of self. This caches the ambient energy level at each object, if the sense uses ambient energy, and the transparency and obstructor on the best path in the sense to the object. 'objs' is the connection table, as generated by connectionTable().

Cache the sense path for each object reachable from this point of view. Fills in tmpTrans_ and tmpObstructor_ for each object with the best transparency path from the object to me.

can the given actor see/hear/smell/touch me?

Determine if I can be sensed under the given conditions. Returns true if the object can be sensed, nil if not. If this method returns nil, this object will not be considered in scope for the current conditions.

By default, we return nil if the ambient energy level for the object is zero. If the ambient level is non-zero, we'll return true in 'transparent' conditions, nil for 'opaque', and we'll let the sense decide via its canObjBeSensed() method for any other transparency conditions. Note that 'ambient' as given here is the ambient level *at the object*, not as seen along my sense path - so this should NOT be given as the ambient value from a SenseInfo, which has already been adjusted for the sense path.

Determine if I can be sensed IN DETAIL in the given sense, with the given SenseInfo description. By default, an object's details can be sensed if the sense path is 'transparent' or 'attenuated', OR the object's scale in the sense is 'large'.

can we match the given PronounXxx pronoun type specifier?

Determine if we can traverse this object for moving the given object via a path. Calls checkMoveViaPath(), and returns true if checkMoveViaPath() indicates success, nil if it indicates failure.

Note that this method should generally not be overridden; only checkMoveViaPath() should usually need to be overridden.

show a list of exits as part of failed travel - defer to location

Display a message explaining why we are obstructing a sense path to the given object.

explain why we cannot see the source of an odor

Display a message explaining that the source of a sound cannot be seen because I am visually obstructing it. By default, we show nothing at all; subclasses can override this to provide a better explanation when possible.

Can I own the given object? By default, objects cannot own other objects. This can be overridden when ownership is desired.

This doesn't determine that we *do* own the given object, but only that we *can* own the given object.

Can I see/hear/smell the given object? By default, an object can "see" (or "hear", etc) another if there's a clear path in the corresponding basic sense to the other object. Note that actors override this, because they have a subjective view of the senses: an actor might see in a special infrared vision sense rather than (or in addition to) the normal 'sight' sense, for example.

determine if we can throw an object via this path

Determine if I can touch the given object. By default, we can always touch our immediate container; otherwise, we can touch anything with a touch path that we can traverse.

determine if we can reach out and touch an object via this path

Check, using pre-condition rules, that the actor is removed from this nested location and moved to its exit destination.

This is called when the actor is attempting to move to an object outside of this object while the actor is within this object (for example, if we have a platform containing a box containing a chair, 'self' is the box, and the actor is in the chair, an attempt to move to the platform will trigger a call to box.checkActorOutOfNested).

By default, we're not a nested location, but we could *contain* nested locations. So what we need to do is defer to the child object that actually contains the actor, to let it figure out what it means to move the actor out of itself.

Check a proposed change in my bulk. When this is called, the new bulk should already be in effect (the best way to do this when just making a check is via whatIf).

This routine can be called during the 'check' or 'action' stages of processing a command to determine if a change in my bulk would cause a problem. If so, we'll add a failure report and exit the command.

By default, notify our immediate container of the change to see if there's any objection. A change in an object's bulk typically only aaffects its container or containers.

The usual way to invoke this routine in a 'check' or 'action' routine is with something like this:

whatIf({: checkBulkChange()}, &inflated, true);

This checks to see if the change in my bulk implied by changing self.inflated to true would present a problem for my container, terminating with a reportFailure+exit if so.

Check a bulk change of one of my direct contents, given by obj. When this is called, 'obj' will be (tentatively) set to reflect its proposed new bulk; if this routine doesn't like the new bulk, it should issue a failure report and exit the command, which will cancel the command that would have caused the change and will prevent the proposed change from taking effect.

By default, we'll do nothing; subclasses that are sensitive to the bulks of their contents should override this.

Determine if we can traverse self for moving the given object in the given manner. This is used to determine if a containment connection path can be used to move an object to a new location. Returns a CheckStatus object indicating success if we can traverse self, failure if not.

By default, we'll simply return a success indicator. Subclasses might want to override this for particular conditions. For example, containers would normally override this to return nil when attempting to move an object in or out of a closed container. Some special containers might also want to override this to allow moving an object in or out only if the object is below a certain size threshold, for example.

'obj' is the object being moved, and 'dest' is the destination of the move.

'op' is one of the pathXxx operations - PathIn, PathOut, PathPeer - specifying what kind of movement is being attempted. PathIn indicates that we're moving 'obj' from outside self to inside self; PathOut indicates the opposite. PathPeer indicates that we're moving 'obj' entirely within self - this normally means that we've moved the object out of one of our contents and will move it into another of our contents.

Determine if I'm a valid staging location for the given nested room destination 'dest'. This is called when the actor is attempting to enter the nested room 'dest', and the travel handlers find that we're the staging location for the room. (A "staging location" is the location the actor is required to occupy immediately before moving into the destination.)

If this object is a valid staging location, the routine should simply do nothing. If this object isn't valid as a staging location, this routine should display an appropriate message and terminate the command with 'exit'.

An arbitrary object can't be a staging location, simply because an actor can't enter an arbitrary object. So, by default, we'll explain that we can't enter this object. If the destination is contained within us, we'll provide a more specific explanation indicating that the problem is that the destination is within us.

Determine if we can traverse this object for throwing the given object in the given manner. By default, this returns the same thing as canMoveViaPath, since throwing is in most cases the same as ordinary movement. Objects can override this when throwing an object through this path element should be treated differently from ordinary movement.

Determine if we can traverse self in the given manner for the purposes of 'obj' touching another object. 'obj' is usually an actor; this determines if 'obj' is allowed to reach through this path element on the way to touching another object.

By default, this returns the same thing as canMoveViaPath, since touching is in most cases the same as ordinary movement of an object from one location to another. Objects can overridet his when touching an object through this path element should be treated differently from moving an object.

Check that a traveler is directly in this room. By default, a Thing is not a room, so a connector within a Thing actually requires the traveler to be in the Thing's container, not in the Thing itself. So, defer to our container.

Get a description of an object within this object, describing the object's location as this object. By default, we'll append "in <theName>" to the given object name.

Base routine for generating childInName and related names. Takes the name to use for the child and the name to use for me, and combines them appropriately.

In most cases, this is the only one of the various childInName methods that needs to be overridden per subclass, since the others are defined in terms of this one. Note also that if the only thing you need to do is change the preposition from 'in' to something else, you can just override objInPrep instead.

Get a description of an object within this object, showing the owner of this object. This is similar to childInName, but explicitly shows the owner of the containing object, if any: "the flashlight in bob's backpack".

get a description of an object within this object, as seen from a remote location

Clear the sensory scratch-pad properties, in preparation for a sensory calculation pass.

Create a clone for inclusion in MultiInstance contents. We'll recursively clone our own contents.

Clone this object for inclusion in a MultiInstance's contents tree. When we clone an instance object for a MultiInstance, we'll also clone its contents, and their contents, and so on. This routine creates a private copy of all of our contents.

Conjugate a regular verb in the present or past tense for our person and number.

In the present tense, this is pretty easy: we add an 's' for the third person singular, and leave the verb unchanged for plural (it asks, they ask). The only complication is that we must check some special cases to add the -s suffix: -y -> -ies (it carries), -o -> -oes (it goes).

In the past tense, we can equally easily figure out when to use -d, -ed, or -ied. However, we have a more serious problem: for some verbs, the last consonant of the verb stem should be repeated (as in deter -> deterred), and for others it shouldn't (as in gather -> gathered). To figure out which rule applies, we would sometimes need to know whether the last syllable is stressed, and unfortunately there is no easy way to determine that programmatically.

Therefore, we do *not* handle the case where the last consonant is repeated in the past tense. You shouldn't use this method for this case; instead, treat it as you would handle an irregular verb, by explicitly specifying the correct past tense form via the tSel macro. For example, to generate the properly conjugated form of the verb "deter" for an object named "thing", you could use an expression such as:

'deter' + tSel(thing.verbEndingS, 'red')

This would correctly generate "deter", "deters", or "deterred" depending on the number of the object named "thing" and on the current narrative tense.

Generate a lookup table of all of the objects connected by containment to this object. This table includes all containment connections, even through closed containers and the like.

The table is keyed by object; the associated values are meaningless, as all that matters is whether or not an object is in the table.

on constructing a new Thing, initialize it as we would a statically instantiated Thing

Are my contents within a fixed item that is within the given location? By default, we return nil because we are not ourselves fixed.

The counted name for disambiguation prompts. We use the same logic here as in theDisambigName.

Single-item counted listing description. This is used to display an item with a count of equivalent items ("four gold coins"). 'info' is the sense information from the current point of view for 'self', which we take to be representative of the sense information for all of the equivalent items.

Return a string giving the "counted name" of the object - that is, a phrase describing the given number of the object. For example, for a red book, and a count of 5, we might return "five red books". By default, we use countNameFrom() to construct a phrase from the count and either our regular (singular) 'name' property or our 'pluralName' property, according to whether count is 1 or more than 1.

Returns a string giving a count applied to the name string. The name must be given in both singular and plural forms.

we have no owner - show as "the item in the location"

Get my dark room contents lister - this is the Lister object we'll use to display the room's self-illuminating contents when the room is dark.

the default distant description

the default obscured description

The default long description, which is displayed in response to an explicit player request to examine the object. We'll use a generic library message; most objects should override this to customize the object's desription.

Note that we show this as a "default descriptive report," because this default message indicates merely that there's nothing special to say about the object. If we generate any additional description messages, such as status reports ("it's open" or "it contains a gold key") or special descriptions for things inside, we clearly *do* have something special to say about the object, so we'll want to suppress the nothing-special message. To accomplish this suppression, all we have to do is report our generic description as a default descriptive report, and the transcript will automatically filter it out if there are any other reports for this same action.

Note that any time this is overridden by an object with any sort of actual description, the override should NOT use defaultDescReport. Instead, simply set this to display the descriptive message directly:

desc = "It's a big green box. "

Find a direction linked to a given connector, for travel by the given actor. Returns the first direction (as a Direction object) we find linked to the connector, or nil if we don't find any direction linked to it.

distant smell description

distant sound description

"Ask about" action

"Ask for" action

Vague "ask" and "tell" - these are for syntactically incorrect ASK and TELL phrasings, so that we can provide better error feedback.

"AttachTo" action

"Attack" action.

"Attack with" action - attack with (presumably) a weapon.

"Board" action

"Break" action

"Burn". By default, we ask for something to use to burn the object, since most objects are not self-igniting.

"Burn with"

"Clean" action

"CleanWith" action

"Climb", "climb up", and "climb down" actions

"Close" action

"Consult" action

"Cut with" action

"Detach" action

"DetachFrom" action

"Dig" action - by default, simply re-reoute to dig-with, since we generally need a digging implement to dig in anything. Some objects might want to override this to allow digging without any implement; a sandy beach, for example, might allow digging in the sand without a shovel.

"DigWith" action

"Doff" action

"Drink" action

"Drop" verb processing

"Eat" action

"Enter"

"Enter on" action

"Examine" action

"Extinguish"

"Fasten" action

"Fasten to" action

"Feel"

"Flip" action

"Follow" action

"Get off of" action

"Get out of" (unboard) action

"Give to" action

"Go through"

"jump off"

"jump over"

"Kiss"

"LieOn" action

"Light" action. By default, we treat this as equivalent to "burn".

"Listen to"

"Lock" action

"LockWith" action

"Look behind"

"Look in"

"Look through"

"Look under"

"Move" action

"MoveTo" action

"MoveWith" action

"Open" action

"PlugIn" action

"PlugInto" action

"Pour"

"Pour into"

"Pour onto"

"Pull" action

"Push" action

Push in Direction action - this is for commands like "push boulder north" or "drag sled into cave".

"PutBehind" action

"Put In" verb processing. Default objects cannot contain other objects, but they can be put in arbitrary containers.

"Put On" processing. Default objects cannot have other objects put on them, but they can be put on surfaces.

"PutUnder" action

"Read"

"Remove" processing. We'll treat "remove dobj" as meaning "take dobj from <something>", where <something> is elided and must be determined.

This should be overridden in certain cases. For clothing, "remove dobj" should be the same as "doff dobj". For removable components, this should imply removing the component from its container.

"Screw" action

"ScrewWith" action

"Search". By default, we make "search obj" do the same thing as "look in obj".

"Set" action

"SetTo" action

"Show to" action

"SitOn" action

"Smell"

"StandOn" action

For the most part, "strike" has the same meaning as "hit", so define this as a synonym for "attack" most objects. There are a few English idioms where "strike" means something different, as in "strike match" or "strike tent."

"Switch" action

"Take" action

"Take from" processing

"Talk to"

"Taste"

"Tell about" action

"Throw" action. By default, we'll simply re-route this to a "throw at" action. Objects that can meaningfully be thrown without any specific target can override this.

Note that we don't apply an preconditions or verification, since we don't really do anything with the action ourselves. If an object overrides this, it should add any preconditions and verifications that are appropriate.

"Throw at" action

"Throw <direction>". By default, we simply reject this and explain that the command to use is THROW AT. With one exception: we treat THROW <down> as equivalent to THROW AT FLOOR, and use the default library message for that command instead.

"Throw to" action

"Turn" action

"TurnOff" action

"TurnOn" action

"Turn to" action

"TurnWith" action

"Type <literal> on" action

"Type on" action

"Unfasten" action

"Unfasten from" action

"Unlock" action

"UnlockWith" action

"Unplug" action

"UnplugFrom" action

"Unscrew" action

"UnscrewWith" action

"Wear" action

List my contents as part of Examine processing. We'll recursively list contents of contents; this will ensure that even if we have no listable contents, we'll list any listable contents of our contents.

list my contents for an "examine", using the given lister

Show the special descriptions of any contents. We'll run through the visible information list for the location; for any visible item inside me that is using its special description, we'll display the special description as a separate paragraph.

Show any status associated with the object as part of the full description. This is shown after the basicExamine() message, and is only displayed if we can see full details of the object according to the viewing conditions.

By default, we simply show our contents. Even though this base class isn't set up as a container from the player's perspective, we could contain components which are themselves containers. So, to ensure that we properly describe any contents of our contents, we need to list our children.

Generic "check" failure routine. This displays the given failure message, then performs an 'exit' to cancel the current command. 'msg' is the message to display - it can be a single-quoted string with the message text, or a property pointer. If 'msg' is a property pointer, any necessary message parameters can be supplied as additional 'params' arguments.

The "feel description," which is the description displayed when an actor explicitly feels the object. As with taste, we don't distinguish transparency or distance.

Get my "fill medium." This is an object of class FillMedium that permeates our interior, such as fog or smoke. This object affects the transmission of senses from one of our children to another, or between our interior and exterior.

Note that the FillMedium object is usually a regular object in scope, so that the player can refer to the fill medium. For example, if a room is filled with fog, the player might want to be able to refer to the fog in a command.

By default, our medium is the same as our parent's medium, on the assumption that fill media diffuse throughout the location's interior. Note, though, that Container overrides this so that a closed Container is isolated from its parent's fill medium - think of a closed bottle within a room filled with smoke. However, a fill medium doesn't expand from a child into its containers - it only diffuses into nested containers, never out.

An object at the outermost containment level has no fill medium by default, so we return nil if our location is nil.

Note that, unlike the "surface" material, the fill medium is assumed to be isotropic - that is, it has the same sense-passing characteristics regardless of the direction in which the energy is traversing the medium. Since we don't have any information in our containment model about the positions of our objects relative to one another, we have no way to express anisotropy in the fill medium among our children anyway.

Note further that energy going in or out of this object must traverse both the fill medium and the surface of the object itself. Since we have no other information on the relative positions of our contents, we can only assume that they're uniformly distributed through our interior, so it is necessary to traverse the same amount of fill material to go from one child to any other or from a child to our inner surface.

As a sense is transmitted, several consecutive traversals of a single fill material (i.e., a single object reference) will be treated as a single traversal of the material. Since we don't have a notion of distance in our containment model, we can't assume that we cover a certain amount of distance just because we traverse a certain number of containment levels. So, if we have three nested containment levels all inheriting a single fill material from their outermost parent, traversing from the inner container to the outer container will count as a single traversal of the material.

Find an opaque obstructor. This can be called immediately after calling senseObj() when senseObj() indicates that the object is opaquely obscured. We will find the nearest (by containment) object where the sense status is non-opaque, and we'll return that object.

senseObj() by itself does not determine the obstructor when the sense path is opaque, because doing so requires extra work. The sense path calculator that senseObj() uses cuts off its search whenever it reaches an opaque point, because beyond that point nothing can be sensed.

This can only be called immediately after calling senseObj() because we re-use the same cached sense path information that senseObj() uses.

Find the object that prevents us from touching the given object.

Call a function on each *connected* container. For most objects, this is the same as forEachContainer, but objects that don't connect their containers for sense purposes would do nothing here.

Call a function on each container. If we have no location, we won't invoke the function at all. We'll invoke the function as follows:

(func)(location, args...)

Call a method on this object from the given point of view. We'll push the current point of view, call the method, then restore the enclosing point of view.

Get a list of objects suitable for matching ALL in TAKE ALL FROM <self>. By default, this simply returns the list of everything in scope that's directly inside 'self'.

Build a vector containing all of the possible paths we can traverse to get from me to the given object. The return value is a vector of paths; each path is a list of containment operations needed to get from here to there.

Each path item in the vector is a list arranged like so:

[obj, op, obj, op, obj]

Each 'obj' is an object, and each 'op' is an operation enum (PathIn, PathOut, PathPeer) that specifies how to get from the preceding object to the next object. The first object in the list is always the starting object (i.e., self), and the last is always the target object ('obj').

Get the distinguisher to use for printing this object's name in an action announcement (such as a multi-object, default object, or vague-match announcement). We check the global option setting to see if we should actually use distinguishers for this; if so, we call getInScopeDistinguisher() to find the correct distinguisher, otherwise we use the "null" distinguisher, which simply lists objects by their base names.

'lst' is the list of other objects from which we're trying to differentiate 'self'. The reason 'lst' is given is that it lets us choose the simplest name for each object that usefully distinguishes it; to do this, we need to know exactly what we're distinguishing it from.

Get "bag of holding" affinities for the given list of objects. For each item in the list, we'll get the item's bulk, and get each bag's affinity for containing the item. We'll note the bag with the highest affinity. Once we have the list, we'll put it in descending order of affinity, and return the result as a vector.

Find all of the bags of holding contained within this object and add them to the given vector. By default, we'll simply recurse into our children so they can add their bags of holding.

Get a distinguisher that differentiates me from all of the other objects in the given list, if possible, or from as many of the other objects as possible.

Calculate my total bulk. Most objects have a fixed external shape (and thus bulk) that doesn't vary as contents are added or removed, so our default implementation simply returns our intrinsic bulk without considering any contents.

Some objects do change shape as contents are added. Such objects can override this routine to provide the appropriate behavior. (We don't try to provide a parameterized total bulk calculator here because there are too many possible ways a container's bulk could be affected by its contents or by other factors.)

If an object's bulk depends on its contents, the object should override notifyInsert() so that it calls checkBulkChange() - this will ensure that an object won't suddenly become too large for its container (or holding actor).

Calculate the bulk contained within this object. By default, we'll simply add up the bulks of all of our contents.

Get the carrying actor. This is the nearest enclosing location that's an actor.

Get the container (direct or indirect) we have in common with the object, if any.

Get the direct container we have in common with the given object, if any. Returns at most one common container. Returns nil if there is no common location.

Get a list of all of my connected containers. This simply returns the list that forEachConnectedContainer() iterates over.

Search our direction list for a connector that will lead the given actor to the given destination.

Get the listed contents in a direct examination of this object. By default, this simply returns a list of all of our direct contents that are included in the info table.

get my "destination name," for travel purposes; by default, we simply defer to our location, if we have one

Get the destination for an object dropped within me. Ordinary objects can't contain actors, so an actor can't directly drop something within a regular Thing, but the same effect could occur if an actor throws a projectile, since the projectile might reach either the target or an intermediate obstruction, then bounce off and land in whatever contains the object hit.

By default, objects dropped within us won't stay within us, but will land in our container's drop destination.

'obj' is the object being dropped. In some cases, the drop destination might differ according to the object; for example, if the floor is a metal grating, a large object might land on the grating when dropped, but a small object such as a coin might drop through the grating to the room below. Note that 'obj' can be nil, if the caller simply wants to determine the generic destination where a *typical* object would land if dropped - this routine must therefore not assume that 'obj' is non-nil.

'path' is the sense path (as returned by selectPathTo and the like) traversed by the operation that's seeking the drop destination. For ordinary single-location objects, the path is irrelevant, but this information is sometimes useful for multi-location objects to let them know which "side" we approached them from. Note that the path can be nil, so this routine must not depend upon a path being supplied; if the path is nil, the routine should assume that the ordinary "touch" sense path from the current actor to 'self' is to be used, because the actor is effectively reaching out and placing an object on self. This means that when calling this routine, you can supply a nil path any time the actor is simply dropping an object.

Calculate the amount of bulk that this object contributes towards encumbering an actor directly holding the item. By default, this simply returns my total bulk.

Some types of objects will override this to cause the object to contribute more or less bulk to an actor holding the object. For example, an article of clothing being worn by an actor typically contributes no bulk at all to the actor's encumbrance, because an actor wearing an item typically doesn't also have to hold on to the item. Or, a small animal might encumber an actor more than its normal bulk because it's squirming around trying to get free.

Calculate the amount of weight that this object contributes towards encumbering an actor directly holding the item. By default, this simply returns my total weight.

Note that we don't recursively sum the encumbering weights of our contents - we simply sum the actual weights. We do it this way because items within a container aren't being directly held by the actor, so any difference between the encumbering and actual weights should not apply, even though the actor is indirectly holding the items. If a subclass does want the sum of the encumbering weights, it should override this to make that calculation.

Get my extra scope items. This is a list of any items that we want to add to command scope (i.e., the set of all items to which an actor is allowed to refer with noun phrases) when we are ourselves in the command scope. Returns a list of the items to add (or just [] if there are no items to add).

By default, we add nothing.

Get the "hit-and-fall" destination for a thrown object. This is called when we interrupt a thrown object's trajectory because we're in the way of its trajectory.

For example, if the actor is inside a cage, and tries to throw a projectile at an object outside the cage, and the cage blocks the projectile's passage, then this routine is called on the cage to determine where the projectile ends up. The projectile's ultimate destination is the hit-and-fall destination for the cage: it's where the project ends up when it hits me and then falls to the ground, its trajectory cut short.

'thrownObj' is the projectile thrown, 'self' is the target object, and 'path' is the path the projectile took to reach us. The path is of the form returned by getThrowPathTo(). Note that the path could extend beyond 'self', because the original target might have been a different object - we could simply have interrupted the projectile's course.

Get our "identity" object. This is the object that we appear to be an inseparable part of.

In most cases, an object is its own identity object. However, there are times when the object that a player sees isn't the same as the object that the parser resolves, because we're modeling a single physical object with several programming objects. For example, a complex container has one or more secret internal program objects representing the different sub-containers; as far as the player is concerned, all of the sub-containers are just aspects of the parent complex container, not separate object, so the sub-containers all have the identity of the parent complex container.

By default, this is simply 'self'. Objects that take their effective identities from other objects must override this accordingly.

Get a distinguisher that differentiates me from all of the other objects in scope, if possible, or at least from some of the other objects in scope.

Get my listed contents for recursive object descriptions. This returns the list of the direct contents that we'll mention when we're examining our container's container, a further enclosing container, or the enclosing room.

By default, we'll return the same list we'll display on direct examination of this object.

Get the "location push traveler" - this is the object that's going to travel for a push-travel action performed by a traveler within this location. This is called by a traveler within this location to find out if the location wants to be involved in the travel, as a vehicle might be. By default, we let our location handle it, if we have one.

Get the location traveler - this is the object that's actually going to change location when a traveler within this location performs a travel command to travel via the given connector. By default, we'll indicate what our containing room indicates. (The enclosing room might be a vehicle or an ordinary room; in any case, it'll know what to do, so we merely have to ask it.)

We defer to our enclosing room by default because this allows for things like a seat in a car: the actor is sitting in the seat and starts traveling in the car, so the seat calls the enclosing room, which is the car, and the car returns itself, since it's the car that will be traveling.

Get the path for moving this object from its present location to the given new container.

Get my associated noise object. By default, this looks for an item of class Noise directly within me.

Get the nominal destination for an object dropped into this object. This is used to report where an object ends up when the object is moved into me by some indirect route, such as throwing the object.

By default, most objects simply return themselves, so we'll report something like "obj lands {in/on} self". Some objects might want to report a different object as the destination; for example, an indoor room might want to report objects as falling onto the floor.

Get the "nominal owner" of this object. This is the owner that we report for the object if asked to distinguish this object from another via the OwnershipDistinguisher. Note that the nominal owner is not necessarily the only owner, because an object can have multiple owners in some cases; however, the nominal owner must always be an owner, in that isOwnedBy(getNominalOwner()) should always return true.

By default, if we have an explicit owner, we'll return that. Otherwise, if our immediate container can own us, we'll return our immediate container. Otherwise, we'll return our immediate container's nominal owner. Note that this last case means that a dollar bill inside Bob's wallet will be Bob's dollar bill, even if Bob's wallet is currently being carried by another actor.

Get my notification list - this is a list of objects on which we must call beforeAction and afterAction when this object is involved in a command as the direct object, indirect object, or any addition object (other than as the actor performing the command).

The general notification mechanism always includes in the notification list all of the objects connected by containment to the actor; this method allows for explicit registration of additional objects that must be notified when commands are performed on this object even when the other objects are nowhere nearby.

Get my associated odor object. By default, this looks for an item of class Odor directly within me.

Get the outermost containing room. We return our container, if we have one, or self if not.

get the outermost room that's visible from the given point of view

Get the notification list actions performed by actors within this object. Ordinary objects don't have room notification lists, but we might be part of a nested set of objects that includes rooms, so simply look to our container for the notification list.

Get the apparent location of one of our room parts (the floor, the ceiling, etc). By default, we'll simply ask our container about it, since a nested room by default doesn't have any of the standard room parts.

Get the "listing state" of the object, given the visual sense information for the object from the point of view for which we're generating the listing. This returns a ThingState object describing the object's state for the purposes of listings. This should return nil if the object doesn't have varying states for listings.

By default, we return a list state if the visual sense path is transparent or attenuated, or we have large visual scale. In other cases, we assume that the details of the object are not visible under the current sense conditions; since the list state is normally a detail of the object, we don't return a list state when the details of the object are not visible.

get the status line exit lister height - defer to our location

Get the path for throwing this object from its present location to the given target object.

Get the path for this object reaching out and touching the given object. This can be used to determine whether or not an actor can touch the given object.

Get the travel connector from this location in the given direction.

Map all of the directional connections to their values in the enclosing location, except for any explicitly defined in this object. (In most cases, ordinary objects won't define any directional connectors directly, since those connections usually apply only to top-level rooms.)

If 'actor' is non-nil, we'll limit our search to enclosing locations that the actor can currently see. If 'actor' is nil, we'll consider any connector in any enclosing location, whether the actor can see the enclosing location or not. It's useful to pass in a nil actor in cases where we're interested in the structure of the map and not actual travel, such as when constructing an automatic map or computing possible courses between locations.

Get the visual sense information for this object from the current global point of view. If we have explicit sense information set with setSenseInfo, we'll return that; otherwise, we'll calculate the current sense information for the given point of view. Returns a SenseInfo object giving the information.

Calculate my total weight. Weight is generally inclusive of the weights of contents or components, because anything inside an object normally contributes to the object's total weight.

Are we associated with the given collective group? We do if it's in our collectiveGroups list.

Hide from 'all' for a given action. If this returns true, this object will never be included in 'all' lists for the given action class. This should generally be set only for objects that serve some sort of internal purpose and don't represent physical objects in the model world. By default, objects are not hidden from 'all' lists.

Note that returning nil doesn't put the object into an 'all' list. Rather, it simply *leaves* it in any 'all' list it should happen to be in. Each action controls its own selection criteria for 'all', and different verbs use different criteria. No matter how an action chooses its 'all' list, though, an item will always be excluded if hideFromAll() returns true for the item.

Hide from defaulting for a given action. By default, we're hidden from being used as a default object for a given action if we're hidden from the action for 'all'.

Initialize this class object for listing its instances that are marked with isEquivalent. We'll initialize a list group that lists our equivalent instances as a group.

Objects are grouped by their equivalence key - each set of objects with the same key is part of the same group. The key is determined by the language module, but is usually just the basic disambiguation name (the 'disambigName' property in English, for example).

Initialize my location's contents list - add myself to my container during initialization

General initialization - this will be called during preinit so that we can set up the initial values of any derived internal properties.

A prepositional phrase that can be used to describe things that are in this room as seen from a remote point of view. This should be something along the lines of "in the airlock", "at the end of the alley", or "on the lawn".

'pov' is the point of view from which we're seeing this room; this might be

We use this phrase in cases where we need to describe things in this room when viewed from a point of view outside of the room (i.e., in a different top-level room). By default, we'll use our actorInName.

it makes as much sense to attack any object as any other, but by default attacking an object has no effect

inherit any further processing

verify the transfer

verify the transfer

The actor performing the showing must also be visible to the indirect object, otherwise the actor wouldn't be able to attract the indirect object's attention to do the showing.

we've passed our checks, so process it as a regular "take"

process a 'throw' operation, finishing with hitting the target if we get that far

process a 'throw' operation, finishing with the target trying to catch the object if we get that far

Determine if the current gActor, who is directly in this location, is "travel ready." This means that the actor is ready, as far as this location is concerned, to traverse the given connector. By default, we'll defer to our location.

Note that if you override this to return nil, you should also provide a custom 'notTravelReadyMsg' property that explains the objection.

Am I a component of the given object? The base Thing is not a component of anything, so we'll simply return nil.

Determine if I'm directly inside another Thing. Returns true if this object is contained directly within obj. Returns nil if this object isn't directly within obj, even if it is indirectly in obj (i.e., its container is directly or indirectly in obj).

Determine if I'm "held" by an actor, for the purposes of being manipulated in an action. In most cases, an object is considered held by an actor if it's directly within the actor's inventory, because the actor's direct inventory represents the contents of the actors hands (or equivalent).

Some classes might override this to change the definition of "held" to include things not directly in the actor's inventory or exclude things directly in the inventory. For example, an item being worn is generally not considered held even though it might be in the direct inventory, and a key on a keyring is considered held if the keyring is being held.

Determine if I'm is inside another Thing. Returns true if this object is contained within 'obj', directly or indirectly (that is, this returns true if my immediate container is 'obj', OR my immediate container is in 'obj', recursively defined).

isIn(nil) returns true if this object is "outside" the game world, which means that the object is not reachable from anywhere in the game map and is thus not part of the simulation. This is the case if our outermost container is NOT a top-level object, as indicated by its isTopLevel property. If we're inside an object marked as a top-level object, or we're inside an object that's inside a top-level object (and so on), then we're part of the game world, so isIn(nil) will return nil. If our outermost container is has a nil isTopLevel property, isIn(nil) will return true.

Note that our notion of "in" is not limited to enclosing containment, because the same containment hierarchy is used to represent all types of containment relationships, including things being "on" other things and part of other things.

Determine if this object is contained within an item fixed in place within the given location. We'll check our container to see if its contents are within an object fixed in place in the given location.

This is a rather specific check that might seem a bit odd, but for some purposes it's useful to treat objects within fixed containers in a location as though they were in the location itself, because fixtures of a location are to some extent parts of the location.

Determine if I'm to be listed at all in my room's description, and in descriptions of objects containing my container.

Most objects should be listed normally, but some types of objects should be suppressed from the normal room listing. For example, fixed-in-place scenery objects are generally described in the custom message for the containing room, so these are normally omitted from the listing of the room's contents.

By default, we'll return the same thing as isListedInContents - that is, if this object is to be listed when its *direct* container is examined, it'll also be listed by default when any further enclosing container (including the enclosing room) is described. Individual objects can override this to use different rules.

Why would we want to be able to list an object when examining in its direct container, but not when examining an enclosing container, or the enclosing room? The most common reason is to control the level of detail, to avoid overloading the broad description of the room and the main things in it with every detail of every deeply-nested container.

Determine if I'm listed in explicit "examine" and "look in" descriptions of my direct container.

By default, we return true as long as we're not using our special description in this particular context. Examining or looking in a container will normally show special message for any contents of the container, so we don't want to list the items with special descriptions in the ordinary list as well.

Determine if I'm listed in inventory listings. By default, we include every item in an inventory list.

Determine if I'm listed as being located in the given room part. We'll first check to make sure the object is nominally contained in the room part; if not, it's not listed in the room part. We'll then ask the room part itself to make the final determination.

Are we the "look around ceiling"? If so, it means that a LOOK AROUND for an actor within this location (or from a point of view within this location) will use our own interior description, via lookAroundWithin(). If we're not the ceiling, then we defer to our location, letting it describe its interior.

By default, we're the ceiling if we're a top-level room (that is, we have no enclosing location), OR it's not possible to see out to our location. In either of these cases, we can't see anything outside of this room, so we have to generate our own interior description. However, if we do have a location that we can see, then we'll assume that this object just represents a facet of its enclosing location, so the enclosing location provides the room interior description.

In some cases, a room might want to provide its own LOOK AROUND interior description directly even if its location is visible. For example, if the player's inside a wooden booth with a small window that can see out to the enclosing location, LOOK AROUND should probably describe the interior of the booth rather than the enclosing location: even though the exterior is technically visible, the booth clearly dominates the view, from the player's perspective. In this case, we'd want to override this routine to indicate that we're the LOOK AROUND ceiling, despite our location's visibility.

Determine if I'm "nominally" inside the given Thing. Returns true if the object is actually within the given object, OR the object is a room part and I'm nominally in the room part.

Determine if we're nominally in the given room part (floor, ceiling, wall, etc). This returns true if we *appear* to be located directly in/on the given room part object.

In most cases, a portable object might start out with a special initial room part location, but once moved and then dropped somewhere, ends up nominally in the nominal drop destination of the location where it was dropped. For example, a poster might start out being nominally attached to a wall, or a light bulb might be nominally hanging from the ceiling; if these objects are taken and then dropped somewhere, they'll simply end up on the floor.

Our default behavior models this. If we've never been moved, we'll indicate that we're in our initial room part location, given by initNominalRoomPartLocation. Once we've been moved (or if our initNominalRoomPartLocation is nil), we'll figure out what the nominal drop destination is for our current container, and then see if we appear to be in that nominal drop destination.

Am I occluded by the given Occluder when viewed in the given sense from the given point of view? The default Occluder implementation calls this on each object involved in the sense path to determine if it should occlude the object. Returns true if we're occluded by the given Occluder, nil if not. By default, we simply return nil to indicate that we're not occluded.

Am I either inside 'obj', or equal to 'obj'?

Determine if I'm "owned" by another object. By default, if we have an explicit owner, then we are owned by 'obj' if and only if 'obj' is our explicit owner; otherwise, if 'obj' is our immediate location, and our immediate location can own us (as reported by obj.canOwn(self)), then 'obj' owns us; otherwise, 'obj' owns us if our immediate location CANNOT own us AND our immediate location is owned by 'obj'. This last case is tricky: it means that if we're inside something other than 'obj' that can own us, such as another actor, then 'obj' doesn't own us because our immediate location does; it also means that if we're inside an object that has an explicit owner rather than an owner based on location, we have the same explicit owner, so a dollar bill inside Bob's wallet which is in turn being carried by Charlie is owned by Bob, not Charlie.

This is used to determine ownership for the purpose of possessives in commands. Ownership is not always exclusive: it is possible for a given object to have multiple owners in some cases. For example, if Bob and Bill are both sitting on a couch, the couch could be referred to as "bob's couch" or "bill's couch", so the couch is owned by both Bob and Bill. It is also possible for an object to be unowned.

In most cases, ownership is a function of location (possession is nine-tenths of the law, as they say), but not always; in some cases, an object has a particular owner regardless of its location, such as "bob's wallet". This default implementation allows for ownership by location, as well as explicit ownership, with explicit ownership (as indicated by the self.owner property) taking precedence.

Are we aboard a ship? By default, we'll return our location's setting for this property; if we have no location, we'll return nil. In general, this should be overridden in shipboard rooms to return true.

The purpose of this property is to indicate to the travel system that shipboard directions (fore, aft, port, starboard) make sense here. When this returns true, and an actor attempts travel in a shipboard direction that doesn't allow travel here, we'll use the standard noTravel message. When this returns nil, attempting to move in a shipboard direction will show a different response that indicates that such directions are not meaningful when not aboard a ship of some kind.

Note that we look to our location unconditionally - we don't bother to check to see if we're open, transparent, or anything like that, so we'll check with our location even if the actor can't see the location. The idea is that, no matter how nested within opaque containers we are, we should still know that we're aboard a ship. This might not always be appropriate; if the actor is magically transported into an opaque container that happens to be aboard a ship somewhere, the actor probably shouldn't think of the location as shipboard until escaping the container, unless they'd know because of the rocking of the ship or some other sensory factor that would come through the opaque container. When the shipboard nature of an interior location should not be known to the actor, this should simply be overridden to return nil.

Determine if I'm equivalent, for the purposes of command vocabulary, to given object.

We'll run through our list of distinguishers and check with each one to see if it can tell us apart from the other object. If we can find at least one distinguisher that can tell us apart, we're not equivalent. If we have no distinguisher that can tell us apart from the other object, we're equivalent.

get a string with the appropriate pronoun for the object plus the correct conjugation of 'to be'

get a string with the appropriate pronoun for the object for the nominative case, objective case, possessive adjective, possessive noun

get a string with the appropriate pronoun for the object plus the correct conjugation of the given regular verb for the appropriate person

The grammatical cardinality of this item when it appears in a list. This is used to ensure verb agreement when mentioning the item in a list of items. ("Cardinality" is a fancy word for "how many items does this look like").

English only distinguishes two degrees of cardinality in its grammar: one, or many. That is, when constructing a sentence, the only thing the grammar cares about is whether an object is singular or plural: IT IS on the table, THEY ARE on the table. Since English only distinguishes these two degrees, two is the same as a hundred is the same as a million for grammatical purposes, so we'll consider our cardinality to be 2 if we're plural, 1 otherwise.

Some languages don't express cardinality at all in their grammar, and others distinguish cardinality in greater detail than just singular-vs-plural, which is why this method has to be in the language-specific part of the library.

Find the "local" direction link from this object to the given travel connector. We'll only consider our own local direction links; we won't consider enclosing objects.

Look around from the point of view of this object and on behalf of the given actor. This can be used to generate a description as seen from this object by the given actor, and is suitable for cases where the actor can use this object as a sensing device. We simply pass this through to lookAroundPov(), passing 'self' as the point-of-view object.

'verbose' is a combination of LookXxx flags (defined in adv3.h) indicating what style of description we want. This can also be 'true', in which case we'll show the standard verbose listing (LookRoomName | LookRoomDesc | LookListSpecials | LookListPortables); or 'nil', in which case we'll use the standard terse listing (LookRoomName | LookListSpecials | LookListPortables).

Look around from within this object, looking from the given point of view and on behalf of the given actor.

'actor' is the actor doing the looking, and 'pov' is the point of view of the description. These are usually the same, but need not be. For example, an actor could be looking at a room through a hole in the wall, in which case the POV would be the object representing the "side" of the hole in the room being described. Or, the actor could be observing a remote room via a closed-circuit television system, in which case the POV would be the camera in the remote room. (The POV is the physical object receiving the photons in the location being described, so it's the camera, not the TV monitor that the actor's looking at.)

'verbose' has the same meaning as it does in lookAround().

This routine checks to see if 'self' is the "look-around ceiling," which is for most purposes the outermost visible container of this object; see isLookAroundCeiling() for more. If this object is the look-around ceiling, then we'll call lookAroundWithin() to generate the description of the interior of 'self'; otherwise, we'll recursively defer to our immediate container so that it can make the same test. In most cases, the outermost visible container that actually generates the description will be a Room or a NestedRoom.

Provide a "room description" of the interior of this object. This routine is primarily intended as a subroutine of lookAround() and lookAroundPov() - most game code shouldn't need to call this routine directly. Note that if you *do* call this routine directly, you *must* set the global point-of-view variables, which you can do most easily by calling this routine indirectly through the fromPOV() method.

The library calls this method when an actor performs a "look around" command, and the actor is within this object, and the actor can't see anything outside of this object; this can happen simply because we're a top-level room, but it can also happen when we're a closed opaque container or there's not enough light to see the enclosing location.

The parameters have the same meaning as they do in lookAroundPov().

Note that this method must be overridden if a room overrides the standard mechanism for representing its contents list (i.e., it doesn't store its complete set of direct contents in its 'contents' list property).

In most cases, this routine will only be called in Room and NestedRoom objects, because actors can normally only enter those types of objects. However, it is possible to try to describe the interior of other types of objects if (1) the game allows actors to enter other types of objects, or (2) the game provides a non-actor point-of-view object, such as a video camera, that can be placed in ordinary containers and which transmit what they see for remote viewing.

Show my room contents for a "look around" description within this object.

Show our "look around" long description. This is used to display the location's full description when we're providing the room description - that is, when the actor doing the looking is inside me. This displays only the room-specific portion of the room's description; it does not display the status line or anything about the room's dynamic contents.

Show my name for a "look around" command. This is used to display the location name when we're providing the room description. 'illum' is the ambient visual sense level at the point of view.

By default, we show our interior room name or interior dark room name, as appropriate to the ambient light level at the point of view.

Add to the room description a list of things we notice through a specific sense. This is used to add things we can hear and smell to a room description.

Show the exits from this room as part of a description of the room, if applicable. By default, if we have an exit lister object, we'll invoke it to show the exits.

Our LOOK IN description. This is shown when we explicitly LOOK IN the object. By default, we just report that there's nothing unusual inside.

Main examination processing. This is called with the current global POV set to the actor performing the 'examine' command.

Main moveInto - this is the mid-level containment changer; this routine sends notifications to the old and new container, but doesn't notify anything along the connecting sense path.

For all of the two-object forms, map these using our general push-travel mapping. We do all of this mapping here, rather than in the action definition, so that individual objects can change the meanings of these verbs for special cases as appropriate.

Are we being held by the given actor for the purposes of the objHeld precondition? By default, and in almost all cases, this simply returns isHeldBy(). In some rare cases, it might make sense to consider an object to meet the objHeld condition even if isHeldBy returns nil; for example, an actor's hands and other body parts can't be considered to be held, but they also don't need to be for any command operating on them.

Merge two SenseInfo items. Chooses the "better" of the two items and returns it, where "better" is defined as more transparent, or, transparencies being equal, brighter in ambient energy.

Merge two senseInfoTable tables. Merges the second table into the first. If an object appears only in the first table, the entry is left unchanged; if an object appears only in the second table, the entry is added to the first table. If an object appears in both tables, we'll keep the one with better detail or brightness, adding it to the first table if it's the one in the second table.

Move this object to a new container. Before the move is actually performed, we notify the items in the movement path of the change, then we send notifyRemove and notifyInsert messages to the old and new containment trees, respectively.

All notifications are sent before the object is actually moved. This means that the current game state at the time of the notifications reflects the state before the move.

Move this object to a new container as part of travel. This is almost the same as the regular moveInto(), but does not attempt to calculate and notify the sense path to the new location. We omit the path notification because travel is done via travel connections, which are not necessarily the same as sense connections.

Notify each element of the move path of a moveInto operation.

Report a failure of the condition that tryMovingObjInto tries to bring into effect. By default, this simply says that the object must be in 'self'. Some objects might want to override this when they describe containment specially; for example, an actor might want to say that the actor "must be carrying" the object.

get my name plus a being verb ("the box is")

get my name plus a negative being verb ("the box isn't")

My name with the given regular verb in agreement: in the present tense, if my name has singular usage, we'll add 's' to the verb, otherwise we won't. In the past tense, we'll add 'd' (or 'ed'). This can't be used with irregular verbs, or with regular verbs that have the last consonant repeated before the past -ed ending, such as "deter".

"Normalize" a containment path to remove redundant containment traversals.

First, we expand any sequence of in+out operations that take us out of one root-level containment tree and into another to include a "through" operation for the multi-location object being traversed. For example, if 'a' and 'c' do not share a common container, then we will turn this:

[a PathIn b PathOut c]

into this:

[a PathIn b PathThrough b PathOut c]

This will ensure that when we traverse the path, we will explicitly traverse through the connector material of 'b'.

Second, we replace any sequence of out+in operations through a common container with "peer" operations across the container's contents directly. For example, a path that looks like this

[a PathOut b PathIn c]

will be normalized to this:

[a PathPeer c]

This means that we go directly from a to c, traversing through the fill medium of their common container 'b' but not actually traversing out of 'b' and back into it.

Note that I'm being used in a disambiguation prompt by owner/location. If we're showing the owner, we'll set the antecedent for the owner's pronoun, if the owner is a 'him' or 'her'; this allows the player to refer back to our prompt text with appropriate pronouns.

Note that we're being used in a prompt question with our possessive adjective. If we're a 'him' or a 'her', set our pronoun antecedent so that the player's response to the prompt question can refer back to the prompt text by pronoun.

Note that I've been seen by the given actor, setting the given "seen" property. This routine notifies the object that it's just been observed by the given actor, allowing it to take any special action it wants to take in such cases.

Receive notification that we are about to insert a new object into this container. 'obj' is the object being moved, and 'newCont' is the new direct container (which might be a child of ours). This is normally called during the action() phase.

During moveInto(), this is called on the new container tree after notifyRemove has been called on the old container tree. This routine can cancel the move by displaying an explanatory message and calling 'exit'.

Receive notification that I'm about to be moved to a new container. By default, we do nothing; subclasses can override this to do any special processing when this object is moved. This is normally called during the action() phase.

During moveInto(), this routine is called after notifyRemove() and notifyInsert() have been called on the old and new container trees (respectively). This routine can cancel the move by displaying an explanatory message and calling 'exit'.

This routine is the last in the notification sequence, so if this routine doesn't cancel the move, then the move will definitely happen (at least to the extent that we'll definitely call baseMoveInto() to carry out the move).

Check moving an object through this container via a path. This method is called during moveInto to notify each element along a move path that the movement is about to occur. We call checkMoveViaPath(); if it indicates failure, we'll report the failure encoded in the status object and terminate the command with 'exit'.

Note that this method should generally not be overridden; only checkMoveViaPath() should usually need to be overridden.

Receive notification that we are about to remove an object from this container. This is normally called during the action() phase.

When an object is about to be moved via moveInto(), the library calls notifyRemove on the old container tree, then notifyInsert on the new container tree, then notifyMoveInto on the object being moved. Any of these routines can cancel the operation by displaying an explanatory message and calling 'exit'.

The "obscured" description. If this is defined for an object, then we call it to display the description when an actor explicitly examines this object from a point of view where we have an "obscured" sight path to the object.

If this property is left undefined for an object, then we'll describe this object when it's obscured in one of two ways. If the object has its 'sightSize' property set to 'large', we'll display the ordinary 'desc', because its large visual size makes its details visible even when the object is obscured. If the 'sightSize' is anything else, we'll instead display the default library message indicating that the object is too obscured to see any details.

To display a specific description when the object is visually obscured, override this to a method that displays your message. 'obs' is the object that's obstructing the view - this will be something on our sense path, such as a dirty window, that the actor has to look through to see 'self'.

obscured smell description

obscured sound description

Get the plural form of the given name string. If the name ends in anything other than 'y', we'll add an 's'; otherwise we'll replace the 'y' with 'ies'. We also handle abbreviations and individual letters specially.

This can only deal with simple adjective-noun forms. For more complicated forms, particularly for compound words, it must be overridden (e.g., "Attorney General" -> "Attorneys General", "man-of-war" -> "men-of-war"). Likewise, names with irregular plurals ('child' -> 'children', 'man' -> 'men') must be handled with overrides.

Process a 'throw' command. This is common handling that can be used for any sort of throwing (throw at, throw to, throw in, etc). The projectile is self, and 'target' is the thing we're throwing at or to. 'hitProp' is the property to call on 'target' if we reach the target.

Determine if one property on this object effectively "hides" another. This is a sort of override check for two distinct properties.

We look at the object to determine where prop1 and prop2 are defined in the class hierarchy. If prop1 isn't defined, it definitely doesn't hide prop2. If prop2 isn't defined, prop1 definitely hides it. If both are defined, then prop1 hides prop2 if and only if it is defined at a point in the class hierarchy that is "more specialized" than prop2. That is, for prop1 to hide prop2, the class that defines prop1 must either be the same as the class that defines prop2, or the class where prop1 is defined must inherit from the class that defines prop2, or the class where prop1 is defined must be earlier in a multiple inheritance list than the class defining prop2.

Invoke a property (with an optional argument list) on this object while temporarily switching to the present tense, and return the result.

Provide the prepositional phrase for an object being put into me. For a container, for example, this would say "into the box"; for a surface, it would say "onto the table." By default, we return our library message given by our putDestMessage property; this default is suitable for most cases, but individual objects can customize as needed. When customizing this, be sure to make the phrase suitable for use in sentences like "You put the book <<putInName>>" and "The book falls <<putInName>>" - the phrase should be suitable for a verb indicating active motion by the object being received.

Receive a dropped object. This is called when we are the actual (not nominal) drop destination for an object being dropped, thrown, or otherwise discarded. This routine is responsible for carrying out the drop operation, and reporting the result of the command.

'desc' is a "drop descriptor": an object of class DropType, which describes how the object is being discarded. This can be a DropTypeDrop for a DROP command, a DropTypeThrow for a THROW command, or custom types defined by the game or by library extensions.

In most cases, the actual *result* of dropping the object will always be the same for a given location, regardless of which command initiated the drop, so this routine won't usually have to look at 'desc' at all to figure out what happens.

However, the *message* we generate does usually vary according to the drop type, because this is the report for the entire command. There are three main ways of handling this variation.

- First, you can check what kind of descriptor it is (using ofKind, for example), and generate a custom message for each kind of descriptor. Be aware that any library extensions you're using might have added new DropType subclasses.

- Second, experienced programmers might prefer the arguably cleaner OO "visitor" pattern: treat 'desc' as a visitor, calling a single method that you define for your custom message. You'll have to define that custom method in each DropType subclass, of course.

- Third, you can build a custom message by combining the standard "message fragment" prefix provided by the drop descriptor with your own suffix. The prefix will always be the start of a sentence describing what the player did: "You drop the box", "The ball hits the wall and bounces off", and so on. Since the fragment always has the form of the start of a sentence, you can always add your own suffix: ", and falls to the floor", for example, or ", and falls into the chasm". Note that if you're using one of the other approaches above, you'll probably want to combine that approach with this one to handle cases where you don't recognize the drop descriptor type.

By default, we simply move the object into self and display the standard message using the descriptor (we use the "visitor" pattern to display that standard message). This can be overridden in cases where it's necessary to move the object to a different location, or to invoke a side effect.

The "remote" description. If this is defined for an object, then we call it to display the description when an actor explicitly examines this object from a separate top-level location. That is, when the actor's outermost enclosing room is different from our own outermost enclosing room, we'll use this description.

If this property is left undefined, then we'll describe this object when it's distant as though it were in the same room. So, we'll select the obscured, distant, or ordinary description, according to the sense path.

the initial remote special description

Get my lister for the contents of the given remote room. A remote room is a separate top-level room that an actor can see from its current location; for example, if two top-level rooms are connected by a window, so that an actor standing in one room can see into the other room, then the other room is the remote room, from the actor's perspective.

This is called on the actor's outermost room to get the lister for objects visible in the given remote room. This lets each room customize the way it describes the objects in adjoining rooms as seen from its point of view.

We provide a simple default lister that yields decent results in most cases. However, it's often desirable to customize this, to be more specific about how we see the items: "Through the window, you see..." or "Further down the hall, you see...". An easy way to provide such custom listings is to return a new CustomRoomLister, supplying the prefix and suffix strings as parameters:

return new CustomRoomLister(
'Further down the hall, {you/he} see{s}', '.');

The "remote" special description. This is the special description that will be used when this object is not in the point-of-view actor's current top-level room, but is visible in a connected room. For example, if two top-level rooms are connected by a window, so that an actor in one room can see the objects in the other room, this method will be used to generate the description of the object when the actor is in the other room, viewing this object through the window.

By default, we just use the special description. It's usually better to customize this to describe the object from the given point of view. 'actor' is the point-of-view actor.

Remove an object from my contents.

Do NOT override this routine to cause side effects. If side effects are desired when removing an object, use notifyRemove().

remove an item from the registered notification list

Restore a previously saved location. Does not trigger any side effects.

Describe an actor in this location either from the point of view of a separate top-level room, or at a distance. This is called when we're showing a room description (for LOOK AROUND), and the given actor is in a remote room or at a distance visually from the actor doing the looking, and the given actor is contained within this room.

By default, if we have a location, and the actor doing the looking can see out into the enclosing room, we'll defer to the location. Otherwise, we'll show a default library message ("The actor is nearby").

Get my lighted room contents lister - this is the Lister object that we use to display the room's contents when the room is lit. We'll return the default library room lister.

By default, an object containing the player character will forward the roomDaemon() call up to the container.

show our interior description in the dark

Show our interior description. We use this to generate the long "look" description for the room when an actor is within this object and cannot see the enclosing room.

Note that this is used ONLY when the actor cannot see the enclosing room - when the enclosing room is visible (because the nested room is something like a chair that doesn't enclose the actor, or can enclose the actor but is open or transparent), then we'll simply use the description of the enclosing room instead, adding a note to the short name shown at the start of the room description indicating that the actor is in the nested room.

By default, we'll show the appropriate "actor here" description for the posture, so we'll say something like "You are sitting on the red chair" or "You are in the phone booth." Instances can override this to customize the description with something more detailed, if desired.

Show our first-time room description. This is the description we show when the actor is seeing our interior description for the first time. By default, we just show the ordinary room description, but this can be overridden to provide a special description the first time the actor sees the room.

Show our remote viewing description. This is used when we show a description of a room, via lookAroundWithin, and the actor who's viewing the room is remote. Note that the library never does this itself, since there's no command in the basic library that lets a player view a remote room. However, a game might want to generate such a description to handle a command like LOOK THROUGH KEYHOLE, so we provide this extra description method for the game's use.

By default, we simply show the normal room description. You'll probably want to override this any time you actually use it, though, to describe what the actor sees from the remote point of view.

Get the travel preconditions for an actor in this location. For ordinary objects, we'll just defer to our container, if we have one.

Save my location for later restoration. Returns a value suitable for passing to restoreLocation.

Choose a path from this object to a given object. If no paths are available, returns nil. If any paths exist, we'll find the shortest usable one, calling the given property on each object in the path to determine if the traversals are allowed.

If we can find a path, but there are no good paths, we'll return the shortest unusable path. This can be useful for explaining why the traversal is impossible.

Send the given notification to each direct parent, each of their direct parents, and so forth, stopping when we reach parents that we have in common with our new location. We don't notify parents in common with new location (or their parents).

This should always be called *before* a change of location is actually put into effect, so that we will still be in our old container when this is called. 'obj' is the object being inserted, and 'newCont' is the new direct container.

Send the given notification to each direct parent, each of their direct parents, and so forth, stopping when we reach parents that we have in common with our new location. We don't notify parents in common with new location (or their parents) because we're not actually removing the object from the common parents.

Determine the highest ambient sense level at this object for any of the given senses.

Note that this method changes certain global variables used during sense and scope calculations. Because of this, be careful not to call this method *during* sense or scope calculations. In particular, don't call this from an object's canBeSensed() method or anything it calls. For example, don't call this from a Hidden.discovered method.

Build a list of full information on all of the objects reachable from me through the given sense, along with full information for each object's sense characteristics.

We return a lookup table of each object that can be sensed (in the given sense) from the point of view of 'self'. The key for each entry in the table is an object, and the corresponding value is a SenseInfo object describing the sense conditions for the object.

Determine how well I can sense the given object. Returns a SenseInfo object describing the sense path from my point of view to the object.

Note that, because 'distant', 'attenuated', and 'obscured' transparency levels always compound (with one another and with themselves) to opaque, there will never be more than a single obstructor in a path, because any path with two or more obstructors would be an opaque path, and hence not a path at all.

Build a path from an object within me.

Build a path from an object immediately containing me.

Build a sense path to my contents

Build a path to my location or locations

Build a list of the objects reachable from me through the given sense and with a presence in the sense.

Mark everything visible as having been seen. 'infoTab' is a LookupTable of sight information, as returned by visibleInfoTable(). We'll mark everything visible in the table as having been seen by the actor, EXCEPT objects that have suppressAutoSeen set to true.

Mark all visible contents of 'self' as having been seen. 'infoTab' is a LookupTable of sight information, as returned by visibleInfoTable(). This should be called any time an object is examined in such a way that its contents should be considered to have been seen.

We will NOT mark as seen any objects that have suppressAutoSeen set to true.

Set the global parameter name dynamically. If you need to add a new global parameter name at run-time, call this rather than setting the property directly, to ensure that the name is added to the message builder's name table. You can also use this to delete an object's global parameter name, by passing nil for the new name.

(You only need to use this method if you want to add or change a name dynamically at run-time, because the library automatically initializes the table for objects with globalParamName settings defined at compile-time.)

Set the explicit visual sense information; if this is not nil, getVisualSenseInfo() will return this rather than calculating the live value. Returns the old value, which is a SenseInfo or nil.

Transmit ambient energy from an object within me. This transmits to my outer surface, and also to my own immediate children - in other words, to the peers of the child shining on us. We need to transmit to the source's peers right now, because it might degrade the ambient energy to go out through our surface.

Transmit ambient energy from an object immediately containing me.

Shine ambient energy at my surface onto my contents.

Transmit ambient energy to my location or locations.

show the special description under distant viewing conditions

Show the contents of this object as part of an inventory listing. By default, we simply use the same listing we do for the normal contents listing.

Show this item as part of an inventory list. By default, we'll show the regular list item name.

show the item, using the inventory state name

Show this item as part of a list. 'options' is a combination of ListXxx flags indicating the type of listing. 'infoTab' is a lookup table of SenseInfo objects giving the sense information for the point of view.

Show this item as part of a list, grouped with a count of list-equivalent items.

General routine to show this item as part of a list, grouped with a count of list-equivalent items. 'stateNameProp' is the property of any list state object that we should use to obtain the name of the listing state.

General routine to show the item as part of a list. 'stateNameProp' is the property to use in any listing state object to obtain the state name.

Show the contents of this object, as part of a recursive listing generated as part of the description of our container, our container's container, or any further enclosing container.

If the object has any contents, we'll display a listing of the contents. This is used to display the object's contents as part of the description of a room ("look around"), of an object ("examine box"), or of an object's contents ("look in box").

'options' is the set of flags that we'll pass to showList(), and has the same meaning as for that function.

'infoTab' is a lookup table of SenseInfo objects for the objects that the actor to whom we're showing the contents listing can see via the sight-like senses.

This method should be overridden by any object that doesn't store its contents using a simple 'contents' list property.

show the special description under obscured viewing conditions

show the remote special description

Show the special description, if we have one. If we are using our initial description, we'll show that; otherwise, if we have a specialDesc property, we'll show that.

Note that the initial description overrides the specialDesc property whenever useInitSpecialDesc() returns true. This allows an object to have both an initial description that is used until the object is moved, and a separate special description used thereafter.

Show the special description in contents listings under various sense conditions. By default, we'll use the corresponding special descriptions for full room descriptions. These can be overridden to show special versions of the description when we're examining particular containers, if desired. 'actor' is the actor doing the looking.

Show our special description as part of a parent's full description.

Show my special description, given a SenseInfo object for the visual sense path from the point of view of the description.

show exits in the statusline - defer to our location

Show this item as part of a list of items being worn.

show the item, using the worn-listing state name

The "smell description," which is the description displayed when an actor explicitly smells the object. This is used when we have a transparent sense path to the object, and we have no "emanation" object; when we have an associated emanation object, we use its description instead of this one.

Show the smell/sound description for the object as part of a room description. These are displayed when the object is in the room and it has a presence in the corresponding sense. By default, these show nothing.

In most cases, regular objects don't override these, because most regular objects have no direct sensory presence of their own. Instead, a Noise or Odor is created and added to the object's direct contents, and the Noise or Odor provides the object's sense presence.