tads3/lib/adv3/changes.htm

<html>
<title>Recent Changes to the TADS 3 Library</title>

<style type="text/css">
<!--
body {
    font: 10pt/14pt Verdana, Arial, Helvetica, Sans-Serif;
}
h1 {
    font: 18pt/24pt Georgia, Times New Roman, New York, Times, Serif;
    color: #400060;
}
h2 {
    font: 14pt/18pt Georgia, Times New Roman, New York, Times, Serif;
    color: #600060;
}
h3 {
    background: #f0f0f0;
    border-top: 1px solid #d8d8d8;
    margin-top: 2.5em;
    padding: 1ex 1ex 1ex 1ex;
    font: 12pt/14pt Georgia, Times New Roman, New York, Times, Serif;
    color: #600060;
}
li {
    margin-top: 0.75em;
    margin-bottom: 0.75em;
}
li ul {
    margin-top: 0.75em;
}
li li {
    margin-top: 0.25em;
    margin-bottom: 0.25em;
}
li p {
    margin-top: 0.5em;
    margin-bottom: 0.5em;
}
ul.toc li {
    margin: 0;
}

div.sepbar {
    width: 100%;
    background: #f0f0f0;
    border-top: 1px solid #d8d8d8;
    margin-top: 2.5em;
    padding: 1ex 1ex 1ex 1ex;
    font: 12pt/14pt Georgia, Times New Roman, New York, Times, Serif;
    color: #600060;
}

div.firstentry {
   padding: 0em .5ex 1em .5ex;
   margin: 0px .5ex 0px .5ex;
   border-top: none;
}

div.entry {
   padding: 1em .5ex 1em .5ex;
   margin: 0px .5ex 0px .5ex;
   border-top: 1px solid #c0c0c0;
}

#versionIndex {
   height: 0px;
   overflow: hidden;
   transition: height .5s;
   -webkit-transition: height .5s;
}
#versionIndexBtn {
   margin-top: 1em;
}

//-->
</style>

<body>

<h1>Recent Changes to the TADS 3 Library</h1>

<p>This is a history of changes to Adv3, the TADS 3 adventure game
library.  Changes are listed in reverse chronological order (the most
recent changes are first).

<div id="versionIndexBtn">
<a href="#" onclick="javascript:return toggleVersionIndex(this);">Show version index</a>
</div>
<script type="text/javascript">
function toggleVersionIndex(a)
{
    var i = document.getElementById("versionIndex");
    if (i.clientHeight > 0) {
        i.style.height = "0px";
        a.innerHTML = "Show version index";
    } else {
        i.style.height = i.querySelector("ul").clientHeight + "px";
        a.innerHTML = "Hide version index";
    }
}
</script>
<div id="versionIndex">
<ul class=toc>
<li><a href='#313'>3.1.3</a>
<li><a href='#312'>3.1.2</a>
<li><a href='#311'>3.1.1</a>
<li><a href='#310'>3.1.0</a>
<li><a href='#3018a'>3.0.18.1</a>
<li><a href='#3018'>3.0.18</a>
<li><a href='#3017a'>3.0.17.1</a>
<li><a href='#3017'>3.0.17</a>
<li><a href='#3016'>3.0.16</a>
<li><a href='#3015c'>3.0.15.3</a>
<li><a href='#3015b'>3.0.15.2</a>
<li><a href='#3015a'>3.0.15.1</a>
<li><a href='#3015'>3.0.15</a>
<li><a href='#3014'>3.0.14</a>
<li><a href='#3013'>3.0.13</a>
<li><a href='#3012'>3.0.12</a>
<li><a href='#3011'>3.0.11</a>
<li><a href='#3010'>3.0.10</a>
<li><a href='#309'>3.0.9</a>
<li><a href='#308'>3.0.8</a>
<li><a href='#307'>3.0.7</a>
<li><a href='#306q'>3.0.6q</a>
<li><a href='#306p'>3.0.6p</a>
<li><a href='#306o'>3.0.6o</a>
<li><a href='#306n'>3.0.6n</a>
<li><a href='#306m'>3.0.6m</a>
<li><a href='#306l'>3.0.6l</a>
<li><a href='#306k'>3.0.6k</a>
<li><a href='#306j'>3.0.6j</a>
<li><a href='#306i'>3.0.6i</a>
<li><a href='#306h'>3.0.6h</a>
<li><a href='#306g'>3.0.6g</a>
<li><a href='#306f'>3.0.6f</a>
<li><a href='#306ae'>3.0.6a-e</a>
<li><a href='#305'>3.0.5</a>
<li><a href='#304'>3.0.4 and earlier</a>
</ul>
</div>

<!------------------------------- 3.1.3 --------------------------------->
<div class="sepbar"><a name='313'></a>3.1.3</div>
<p><b><i>Released May 16, 2013</i></b>
<p>

<!------------------->
<div class=firstentry>

A bug in the parser caused a run-time error when a player attempted to
traverse an AskConnector.  This is now fixed.

(<a href="http://bugdb.tads.org/view.php?id=0000169">bugdb.tads.org #0000169</a>)

</div>

<!------------------->
<div class=entry>

For conversational commands such as HELLO, GOODBYE, YES, and NO, the
parser now sets the sense context to the issuing actor (that is, the
actor who issued a command, which is usually the player character)
rather than the target actor (the target in BOB, GOODBYE is Bob).  For
most commands, the target actor is the one who's meant to carry out
the command - BOB, GO NORTH asks Bob to go north - so it's appropriate
to execute most actions in the sense context of the target actor.  In
the past, the parser did just this, unconditionally for all types of
actions.  However, this isn't appropriate for conversational commands,
because the meaning of the target actor is different in these
commands; the target specifies the person being addressed in the
conversation rather than the actor carrying out the command.  BOB,
HELLO doesn't tell Bob to say hello, but rather tells the player
character to say hello to Bob.  In these types of commands, then, the
actor actually carrying out the command is the issuer, not the target,
so the sense context should remain with the issuer.  The parser now
makes this distinction when setting the sense context.

(<a href="http://bugdb.tads.org/view.php?id=0000190">bugdb.tads.org #0000190</a>)

</div>

<!------------------->
<div class=entry>

A parser bug caused the same object to be matched multiple times in a
disambiguation query under certain circumstances.  If an object
defined multiple 'noun' words that all had a common prefix up to the
truncation limit, and there were two or more objects with the same
list of similar nouns, and the player entered a noun phrase that
matched the common leading substring, a normal disambiguation question
would be triggered.  If the player then answered this question with
ALL, the parser matched each object multiple times, equal to the
number of matching (truncated) nouns per object.

<p>The key element to triggering the bug is multiple noun synonyms
that share a common prefix that's longer than the truncation limit.
It's rare to find examples of this in English games, but it's common
in inflected languages where nouns have multiple forms with different
endings (the bug was discovered in a Czech translation).  Here's a
somewhat contrived English example.  The kind of compass you use to
inscribe circles can be called a COMPASS or COMPASSES - it's one of
those odd English words like "scissors" or "pants" where the plural
noun form can be used for the singular object, but (unlike scissors or pants)
the singular form can be used interchangeably.  If you set the TADS
truncation limit to 6 characters, and then create a red compass and a
blue compass with COMPASS and COMPASSES as noun synonyms, the bug
would have caused the following odd interaction:

<pre>
&gt;x compas
Which compas do you mean, the red compass or the blue compass?

&gt;all
red compass: It's an ordinary red compass.
blue compass: It's an ordinary blue compass.
blue compass: It's an ordinary blue compass.
red compass: It's an ordinary red compass.
</pre>

<p>This is now fixed.

(<a href="http://bugdb.tads.org/view.php?id=0000188">bugdb.tads.org #0000188</a>)

</div>

<!------------------->
<div class=entry>

The library showed the wrong default message for the THROW DOWN
command (that is, the ThrowDir action, when the direction is Down).
The message used to be the rather non sequitur "You're not carrying
that"; the message now says "You should just put it down instead."

</div>


<!------------------------------- 3.1.2 --------------------------------->
<div class="sepbar"><a name='312'></a>3.1.2</div>
<p><b><i>Released August 20, 2012</i></b>
<p>

<!------------------->
<div class=firstentry>

In the past, atmosphere messages (via the Room atmosphereList
property) didn't display a paragraph separator before the message, so
if whatever item happened to be displayed just before an atmosphere
message didn't add a paragraph separator at the end, the atmosphere
message was shown as a continuation of the preceding paragraph.
Room.roomDaemon() now explicitly adds a &lt;.commandsep&gt; before
each atmosphere message to ensure that a paragraph break is displayed.

(<a href="http://bugdb.tads.org/view.php?id=0000161">bugdb.tads.org #0000161</a>)


</div>


<!------------------------------- 3.1.1 --------------------------------->
<div class="sepbar"><a name='311'></a>3.1.1</div>
<p><b><i>Released July 14, 2012</i></b>
<p>

<!------------------->
<div class=firstentry>

The "inventory tall" lister incorrectly listed the contents of
contentsListedSeparately containers both in-line and separately.
This has been fixed, so that only the separate contents list is shown.

(<a href="http://bugdb.tads.org/view.php?id=0000116">bugdb.tads.org #0000116</a>)


</div>

<!------------------->
<div class=entry>

The Thing methods for LOOK and EXAMINE that generate listings of contents
now pass an additional named parameter, "examinee:", to the list methods.
This is occasionally useful when one of the listing-related methods on
one of the contents objects needs to know exactly what the context of
the listing is.

<p>The specific situation that motivated this change was a problem
involving MultiLoc items with special descriptions, as described in
the next item.

</div>

<!------------------->
<div class=entry>

In the past, a MultiLoc with a special description was incorrectly
included in the miscellaneous object list portion of a LOOK
description for its room, or an EXAMINE description of its container.
A special description is supposed to supersede inclusion in the
ordinary list, since it provides the same information.  This
now works correctly.

<p>The reason for the double listing was that the method that decides
whether or not to include an object in the ordinary list,
isListedInContents, didn't deal properly with MultiLoc objects.  In
fact, it couldn't deal with them properly, because it didn't have
enough information, namely the identity of the object being
examined.

<p>For an ordinary Thing, the examinee is implicit in the call to
isListedInContents, because this method is called only on direct
children of the examinee; a Thing has only one direct container, so
the examinee is implicitly the Thing's location.  This logic doesn't
work for a MultiLoc, though, because a MultiLoc can have multiple
direct containers.  So, to work properly, this method needed to know
the examinee.  This information is now available to the method via
the new "examinee:" named parameter that the various Thing methods
for LOOK and EXAMINE now supply.  A new BaseMultiLoc.isListedInContents
method uses the "examinee:" parameter to get the correct listing
information.

(<a href="http://bugdb.tads.org/view.php?id=0000119">bugdb.tads.org #0000119</a>)

</div>

<!------------------->
<div class=entry>

openableContentsLister has been renamed to openableDescContentsLister,
because the original name was inconsistent with the corresponding
listers for other classes.  xxxContentsLister is supposed to be the
lister assigned to the 'contentsLister' property for class xxx, and
xxxDescContentsLister is the one for 'descContentsLister'.
('contentsLister' is the lister used for descriptions of objects
<i>containing</i> the xxx, such as the enclosing room description;
'descContentsLister' is for EXAMINE descriptions of the xxx itself.)
There isn't (and never was) a separate 'contentsLister' for Openable;
the former openableContentsLister was always its 'descContentsLister',
but unfortunately wasn't named accordingly.

<p>To minimize the impact on existing code, adv3.h provides a #define
that maps the old name to the new name.  In the case of Openable,
there's no need for a specialized 'contentsLister' at all, so there's
no practical need to distinguish the two names, allowing us to create
the mapping for the sake of compatibility.  Existing code shouldn't
notice the difference unless it defined an openableDescContentsLister
object of its own, which seems unlikely given that
openableContentsLister already filled the role implied by that name.

</div>

<!------------------->
<div class=entry>

The dobjFor() and iobjFor() macros in adv3.h now have some special
code that catches handler definitions for non-existent Actions.  If
the Action named in the dobjFor() or iobjFor() doesn't exist, the
compiler will report an "undefined symbol" error naming the Action
object.  This only happens in debug builds (e.g., using the "-d"
option for the command-line compiler), since it generates some extra
code to create a reference to the action object.  The warning can be
helpful for catching typos (misspelled action names) or references to
actions you intended to define but never got around to.

(<a href="http://bugdb.tads.org/view.php?id=0000135">bugdb.tads.org #0000135</a>)


</div>

<!------------------->
<div class=entry>

The English parser is a little more nuanced about the way it handles
queries for missing direct objects for verbs with prepositional phrasing
for the direct object.  For example:

<p>
<pre>&gt;DIG
What do you want to dig in?

&gt;IN THE DIRT
</pre>

<p>In the past, the parser treated the reply "IN THE DIRT" as a new
command meaning ENTER DIRT.  The assumption was that if the reply
matched the phrasing of a new command, it must in fact be a new
command rather than a reply to the missing object query.  In many
cases where there's this kind of ambiguity, the parser would have to
be able to read the user's mind to know what was intended, but in this
particular case the parallel phrasing of the query ("...dig in?") and
the reply ("in <i>noun</i>") suggests pretty strongly that the user
did indeed intend the input as a reply to the query rather than as a
new command.

<p>To address this, the parser has a new method for production
matches, isSpecialResponseMatch.  This new method returns true if the
production matches special phrasing that makes it more likely to be a
query response than a new command, otherwise nil.  The English parser
uses this for the various prepositional response phrasings, such as
inSingleNoun and forSingleNoun; these are all subclasses of
PrepSingleNounProd.  When one of these productions matches input that
starts with its preposition, it will return true from
isSpecialResponseMatch, causing the missing object query processor to
treat the match as a reply to the query rather than as a new command,
even when the phrasing could also be interpreted as a new command.

(<a href="http://bugdb.tads.org/view.php?id=0000147">bugdb.tads.org #0000147</a>)


</div>

<!------------------->
<div class=entry>

A bug in the parser caused the wrong message to be displayed when a
command was directed to an actor, and the predicate portion of the
command contained an unknown word, and the noun phrase wording for the
actor portion matched at least one grammatical structure phrasing that
could only refer to an out-of-scope object.  In such a case, the
parser reported "You see no <i>actor</i> here" rather than "The word
<i>word</i> is not necessary in this story".  This was obviously the
wrong message when an actor matching the noun phrase actually was in
scope, but was also inconsistent with the "unknown word" message shown
in other similar cases that didn't meet all of the bug conditions.
This has now been fixed so that the "unknown word" message is used.

(<a href="http://bugdb.tads.org/view.php?id=0000149">bugdb.tads.org #0000149</a>)

</div>


<!------------------->
<div class=entry>

In the past, the library incorrectly called breakTopicTie() on each
matching topic with the topic object as the first argument, instead of
passing the whole list of matching topics as advertised.  This has
been corrected.

(<a href="http://bugdb.tads.org/view.php?id=0000138">bugdb.tads.org #0000138</a>)

</div>

<!------------------------------- 3.1.0 --------------------------------->
<div class="sepbar"><a name='310'></a>3.1.0</div>
<p><b><i>Released 12/21/2011</i></b>
<p>

<!------------------->
<div class=firstentry>

The on-again, off-again <a
href='#getInScopeDistinguisher'>detailed-naming scheme</a> is now on
again, this time with enhancements that will (hopefully) make it here
to stay.  This feature was first introduced in version 3.0.10, then
disabled by default in 3.0.11 due to rough edges in that first
attempt.  It's reinstated in this release, with improvements.  This
improved version has been separately available for some time in an
extension called newNames.t, so it's seen some testing and we think
it'll provide good results.

<p>The problem with the 3.0.10 implementation was that it made the
object-name announcements unnaturally verbose - it added an excess of
qualifiers to object names compared to what a human speaker would use.
The new version tries to be smarter about adding only useful detail,
by using more contextual information.  For a multi-object
announcement, for example, the new version only adds enough detail to
distinguish the objects being announced from one another (rather than
from everything else in scope), and also considers the context at a
fixed point in time.  The new version also uses the ordinary name for
an object whenever that's enough to distinguish it; it only uses the
(usually more verbose) disambig name when it's needed.

<p>If you find that the new version still produces awkward
announcements, or if you just prefer the original style, you can
disable this feature: just set
gameMain.useDistinguishersInAnnouncements = nil.  This makes the
parser revert to the basic object names in announcements.

<p>Note that this change makes the newNames.t extension superfluous,
since the library now incorporates it in its entirety.

</div>

<!------------------->
<div class=entry>

It's now possible for a game to provide custom code to break ties in
topic matches, when more than one topic matches the player's input
with the same score.  In the past, the parser just chose a matching
topic entry arbitrarily.  In some cases, it's possible for the game to
make a smarter choice based on the exact input text.  In addition, the
parser now automatically filters tie lists by selecting exact text
matches over truncated text matches.

<p>To add a custom tie-breaker, you add the method breakTopicTie to
one or more of your TopicEntry objects.  This method receives as
arguments the list of tied TopicEntry objects, the original
ResolvedTopic object from the parser, the atcor, and the original
input token list.  When a topic tie occurs, the parser calls this
method on each tied TopicEntry object in turn, in in arbitrary order.
This method can either select the tie-breaker or do nothing.  If it
selects the tie-breaker, the selection process ends immediately with
the selected winner; otherwise, the parser continues calling
breakTopicTie on the remaining TopicEntry objects in the list of ties.

<p>This method was added to address a situation where two topics
happened to match the same input due to vocabulary truncation.
Suppose we have a game object that matches the vocabulary "elephant",
and another that matches "elephants".  If the player enters ASK ABOUT
ELEPHANT, the word ELEPHANT in the input will match both game objects,
since the parser allows the user to abbreviate words by truncating to
the first six characters only.  Now suppose we have separate topic
entries for these two objects, and that both topics are active at the
same time and have the same match score.  This results in a topic tie,
triggering the new tie-breaking code.

<p>For the sake of this example, let's suppose that you want to
distinguish between ASK ABOUT ELEPHANT and ASK ABOUT ELEPHANTS (which
stands to reason, as you probably wouldn't have created both topic
entries otherwise).  In the past, since we have a tie between the two
topic entries, the parser simply chose one arbitrarily.  You can now
specifically select one or the other for a given entry, by writing a
breakTopicTie method.  Since we want ASK ABOUT ELEPHANT to match the
singular version of the topic, here's how the method would look:

<p>
<pre>
    breakTopicTie(matches, topic, actor, toks)
    {
        if (toks[1].toLower() == 'elephant')
            return self;
        return nil;
    }
</pre>

<p>You can add this method to either TopicEntry object, but it really
belongs conceptually with the singular version of the topic.

<p>The default handling for breakTopicTie() is simply to return nil,
which defers to other objects in the list to make the selection.

<p>For the specific case of truncation matching, you actually don't
have to write a breakTopicTie() method after all, since the parser now
<b>also</b> uses vocabulary truncation to break ties on its own.  It
does this <b>after</b> applying any custom breakTopicTie() results.
That is, if breakTopicTie() fails to break the tie, because none of
the TopicEntry objects return a non-nil result for the method, the
parser tries to break the tie on its own by comparing vocabulary
truncation flags.  If one topic entry matched with truncation, and
another didn't, the parser will select the one that matched without
truncation.

<p>The parser selects by truncation because this is probably the most
common basis for selection.  But it's certainly not the only basis.
Other selection criteria could include word order, and the presence or
absence of certain words.  Those sorts of criteria would be very
difficult to encode into a general framework, thus breakTopicTie()
leaves it to the game to make the selection.

<p>This feature addresses <a
href="http://bugdb.tads.org/view.php?id=78">bugdb.tads.org #0000078</a>.

</div>

<!------------------->
<div class=entry>

The scheme that selects which message to display for a reportFailure()
or similar message call had a problem when a verb had both a direct
and an indirect object, <i>and</i> both of those objects had overrides
for the same message.  The message generator always gave priority to
the direct object when both objects had overrides, which was wrong if
the message was due to a condition relating to the indirect object.
For example, given an Underside and a Container, both with limited
bulk, "PUT Underside IN Container" showed the Underside's bulk error
message ("The Container won't fit under the Underside"), since the
Underside is the direct object.

<p>The message generator now gives priority to the <i>calling</i>
object.  The generator looks in the stack trace for a "self" object in
the source list, and gives priority to the first source object it
finds.  This is the source object whose method is actually generating
the message; this will usually be a verify(), check(), or action()
method to process a verb, so presumably it's the object to which the
error condition applies.

<p>(It's certainly valid to generate messages from other places than
the verify(), check(), and action() methods, or indeed from an object
that's not one of the message sources.  But the source priority
shouldn't matter in those cases, because the message presumably has no
particular object affiliation anyway if it's not being generated by
code attached to one of the source objects.)

<p>(<a href="http://bugdb.tads.org/view.php?id=61">bugdb.tads.org #0000061</a>)

</div>

<!------------------->
<div class=entry>

The new TAction methods getDobjTokens() and getDobjWords() make it easier
to retrieve the original text entered by the player to refer to the current
direct object.  These work only when there's an active direct object
(a non-nil object in gDobj).

<p>The corresponding new TIAction methods getIobjTokens() and getIobjWords()
retrieve the original text of the current indirect object.

<p>The token lists returned generally contain the full phrase that the
player entered, including qualifiers like articles ("the") and possessives.
When the player enters a list ("take book, bell, and candle"), the
token list will only include the phrase for the current object, not
the whole list.

<p>Original text isn't always available even when there's a valid
direct/indirect object in play.  For example, text isn't generally
available when the action is a nested or implied action, since these
actions are synthesized internally within the game rather than being
parsed from user input.  The new methods return nil when there's no
original text available for the corresponding objects.

</div>

<!------------------->
<div class=entry>

In the past, the getOrigTokenList() method on a noun phrase that had
been manually disambiguated ("which book do you mean...") returned
only the tokens of the user's last answer.  For example, if the player
typed "take book", and answered the "which book" question with "blue",
then getOrigTokenList() on the resulting noun phrase returned just the
"blue" token.

<p>The parser now builds a token list that has the complete original
noun phrase plus the disambiguation answer (or answers, if multiple
questions were needed to narrow the list sufficiently).  The naive way
to do this (at least in English) might be to simply prepend the
disambiguation answer to the original noun phrase, on the assumption
that the answer is simply an adjective modifying the original phrase;
this would work for the "blue book" example above.  One problem with
this is that some names include prepositional phrases, such as "stack
of bills"; we'd want a "which one?" answer of "$20" to turn this into
"stack of $20 bills" instead of "$20 stack of bills", since that would
mean something rather different.  The bigger problem is that the
parser accepts a number of answer formats that aren't mere adjectives,
such as "the blue one", "both", "any of them", and "2" or "second" or
"the second one" to pick the second item listed in the parser's "which
book" question.  These obviously would produce nonsense using the
naive algorithm.

<p>The parser's solution is to append each new answer parenthetically
to the end of the original phrase.  This produces a result that's at
least comprehensible (and usually pretty good) for any answer format,
because it parallels the way the phrase was actually built, as a
series of post hoc clarifications: "book (the blue one)" or "tea (Earl
Gray) (hot)".  Further, if there's a need to display the phrase to the
player, it should make sense to the player because it parrots back
what they just typed, retaining the same word order and grouping.

</div>

<!------------------->
<div class=entry>

SenseConnector now overrides checkThrowViaPath(), to handle throwing
objects across the connector independently of "move" and "reach"
operations.  In the past, throwing was handled as equivalent to
moving, but this caused an unintended change of behavior when
DistanceConnector was recently changed (in 3.0.16) to allow moving
objects across a distance.

<p>SenseConnector also defines a new method, checkThrowThrough().
This method is the "throw" equivalent of the existing methods
checkMoveThrough() and checkTouchThrough().  The default definition of
the new method returns a failure indication, parallel to the
corresponding existing methods for "move" and "reach".

<p>Finally, DistanceConnector overrides checkThrowThrough() in
parallel to its corresponding overrides for "move" and "reach".

<p>This change (a) restores the pre-3.0.16 behavior for throwing
across a distance, by disallowing it, and (b) makes it possible to
define independent move, reach, and throw handling for sense
connectors.


</div>

<!------------------->
<div class=entry>

The English parser now accepts "LOOK <i>thing</i>" and "L
<i>think</i>" as synonyms for "LOOK AT <i>thing</i>", since it's been
observed that many novice players use this syntax.

<p>(<a href="http://bugdb.tads.org/view.php?id=91">bugdb.tads.org #0000091</a>)

</div>


<!------------------->
<div class=entry>

Thing.addToContents() now skips adding the child object to the
'contents' list if it's already there.  In the past, it was possible
to cause an item to added to its parent's contents list twice, by
explicitly using moveInto() in an initializeThing() override; this
caused strange behavior, such as listing the child item twice in
contents list messages.  The extra check avoids this unintended
duplication.

<p>(<a href="http://bugdb.tads.org/view.php?id=67">bugdb.tads.org #0000067</a>)

</div>

<!------------------->
<div class=entry>

Using a RoomPart as a regular contents item in a room (rather than as
an element of a roomParts list) caused a run-time error on LOOK AROUND
in some cases.  This has been corrected.

<p>(<a href="http://bugdb.tads.org/view.php?id=76">bugdb.tads.org #0000076</a>)

</div>

<!------------------->
<div class=entry>

In the past, if you put one StretchyContainer inside another, the library
didn't properly enforce the bulkCapacity of the outer container when adding
new contents to the inner container.  (Since the inner container is itself
a StretchyContainer, its bulk can increase when a new item is added, which
can make it too large for the outer container.)  This has been corrected.

<p>(<a href="http://bugdb.tads.org/view.php?id=68">bugdb.tads.org #0000068</a>)

</div>

<!------------------->
<div class=entry>

ASK ABOUT and other topic verbs sometimes didn't work properly when
plural words were used in the topic phrase.  This has been corrected.

<p>(<a href="http://bugdb.tads.org/view.php?id=69">bugdb.tads.org #0000069</a>)


</div>

<!------------------->
<div class=entry>

The English command grammar now allows "the" as an article in
possessive phrases, as in "the orc's axe".  In the past, possessive
phrases didn't allow any article qualifier (the library took the
overly narrow view that possessives are usually proper names, as in
"Bob's book").

<p>In addition, plural possessives, signified by an apostrophe at the
end of a plural word, are now accepted.  For example, "the Smiths'
house" would be accepted if "Smiths" is defined as a plural word.
(<a href="http://bugdb.tads.org/view.php?id=77">bugdb.tads.org #0000077</a>)

</div>

<!------------------->
<div class=entry>

The Lister had a bug involving list groups with minimum group sizes.
If there weren't enough candidate items to list with a group,
according to the group's minGroupSize property, but there were more
than one item, the list builder incorrectly included only one of the
items in the final list, omitting the others.  This has been corrected
- the list builder now includes moves all of the candidate items to
the "singles" list, so they all show up in the final list.
(<a href="http://bugdb.tads.org/view.php?id=83">bugdb.tads.org #0000083</a>)


</div>

<!------------------->
<div class=entry>

In the past, if a command contained a noun phrase of the form THE ONE
IN <i>CONTAINER</i>, and the phrase required interactive
disambiguation, the parser incorrectly acted as though the player
answered the "which one do you mean?" prompt with ALL.  This was due
to a parser bug; it's now fixed.

(<a href="http://bugdb.tads.org/view.php?id=95">bugdb.tads.org #0000095</a>)

</div>

<!------------------->
<div class=entry>

The parser now gives priority to a possessive-phrase interpretation of
a noun phrase that doesn't match anything in scope, in cases where the
same words could be interpreted as a plain noun phrase without any
possessive qualifiers.  For example, in the library sample game, we
have an object defined with vocabulary words including "Bob's fish
cleaner", which means that "Bob's" is defined as an adjective in the
dictionary.  "Bob" also is the name of an actor in the game, so the
word "Bob's" in player input can be interpreted in two ways: as an
adjective, or as a possessive qualifier.  If the player enters a noun
phrase such as "Bob's desk", the same phrase can be interpreted with
two very different grammatical structures: the possessive qualifier
"Bob's" modifying an underlying noun phrase "desk", or the noun phrase
"Bob's desk", where the first word is a simple adjective from the
dictionary.  In the past, the parser considered the two phrasings be
equally strong at the structural level.  If one phrasing has a valid
resolution (i.e., it could be mapped to in-scope objects) and the
other doesn't, the structural equivalence doesn't matter, because the
parser always picks the phrase that has the best resolution to game
objects.  However, in cases where neither phrasing has a resolution -
because there's no desk in scope at all, say - the parser picks the
interpretation based on structural strength.  Since the two phrasings
were equally strong, the parser picked one arbitrarily.  If the winner
happened to be the adjective interpretation, this produced the odd
error message "You see no bob's desk here."  Now, with this change,
the parser gives priority to the possessive interpretation in cases
where other things are equal, so the error will be "You see no desk
here."  This is a better message because the unmatched object really
is simply "desk", regardless of whose desk it is; reporting that
"bob's desk" is the missing object seems overly literal.

(<a href="http://bugdb.tads.org/view.php?id=96">bugdb.tads.org #0000096</a>)


</div>

<!------------------->
<div class=entry>

Room now provides a suitable message for cases where objects are
thrown within the room, but there's no floor object among the room
part list for the room.  In the past, this caused a run-time error,
because there was no message defined for this situation.

<p>When an object is thrown, the library's default handling is simply
to drop the object into the room, as though the player had typed DROP
<i>PROJECTILE</i>.  The default message, though, describes the object
as "falling <i>to the floor</i>", where <i>to the floor</i> is
replaced by a message that depends on the "nominal drop destination"
for the location - i.e., the object where things are <i>described</i>
as landing when dropped in the room.  The standard nominal drop is the
room's floor, which is to say the Floor object in the room's roomParts
list.  If there's no floor object, though, the fallback is the Room
itself.  The run-time error occurred because Room didn't have the
associated message property for this situation.  The <i>to the
floor</i> phrase in the message is obtained via the putDestMessage
property, which Room didn't define.  Room now defines this property as
the message property pointer &amp;putDestRoom.  libMessages in the
English library in turn defines putDestRoom to display "into <i>the
room</i>".  The result is that THROW PROJECTILE AT WALL in a room
without a floor now properly replies "...and falls into <i>the
room</i>", instead of causing a run-time error.

<p>(<a href="http://bugdb.tads.org/view.php?id=78">bugdb.tads.org #0000078</a>)

</div>

<!------------------->
<div class=entry>

Using replaceAction with GiveTo sometimes caused a run-time error.
(This was due a complex interaction with the giveMeToAskFor global
remapping.  AskFor is a "topic" action, but GiveTo isn't; the remapping
tried to resolve the GiveTo direct object as a topic for AskFor, but
within the context of the GiveTo verb, which didn't provide one of
the required resolver methods, createTopicQualifierResolver.  This
method is now defined for the base Action class, since this situation
creates a dependency on it even for ordinary non-topic action types.)

<p>(<a href="http://bugdb.tads.org/view.php?id=103">bugdb.tads.org #0000103</a>)


</div>

<!------------------->
<div class=entry>

The English library message for an empty topic inventory has been reworded
slightly for the past-tense version, replacing "right now" with "just then".

</div>


<!------------------------------- 3.0.18.1 --------------------------------->
<div class="sepbar"><a name='3018a'></a>3.0.18.1</div>
<p><b><i>Released 5/5/2009</i></b>
<p>

<!------------------->
<div class=firstentry>

A typo in the English message for refuseCommand has been fixed.

</div>


<!------------------------------- 3.0.18 --------------------------------->
<div class="sepbar"><a name='3018'></a>3.0.18</div>
<p><b><i>Released 4/28/2009</i></b>
<p>

<!------------------->
<div class=firstentry>

More of the lister classes have been reorganized along the same lines
as the BaseContentsLister refactoring in version 3.0.17.  In particular:

<ul>
   <li>surfaceLookInLister, undersideLookUnderLister, and rearLookBehindLister
   are now trivial classes based on the new class LookWhereContentsLister.
   For consistency, thingLookInLister is based on the new class as well,
   but is non-trivial due to its different wording.

   <li>surfaceInlineContentsLister, undersideInlineContentsLister, and
   rearInlineContentsLister are now trivial classes based on the new class
   BaseInlineContentsLister.  For consistency, inlineContentsLister
   is also based on the new base class, but is non-trivial due to
   its different wording.

</ul>

</div>

<!------------------->
<div class=entry>

When an action remapping is inherited from a base class, a subclass or
instance can now define a verify() method for the original action.  In
the past, only the <b>new</b> action's verify() was called - the
remapping bypassed any dobjFor() or iobjFor() definitions for the
old action.  This made it impossible to tweak the subclass handling
for verbs that were remapped in base classes.

<p>With this change, the verify() for the <b>new and old</b> actions
are <b>both</b> called, <b>if</b> there's a verify() for the old
action defined on a subclass of the class where the remap() itself is
defined.  In other words, if the verify() "overrides" the remap(), the
subclassed verify() is invoked.

<p>Because the verify() methods for both the old and new actions are
called, you can't actually override the new action's verify() call.
But verify() results are cumulative, so you <i>can</i> use it to
adjust the logicalness of the action, or to make the action illogical.

</div>

<!------------------->
<div class=entry>

The parser can now has an option to generate more descriptive messages
when noun phrases are disambiguated using the logicalness rules.

<p>Disambiguation occurs when the player uses a noun phrase that
matches more than one in-scope object.  For example, if the current
room contains a red door and a blue door, and the player types OPEN
DOOR, the noun phrase DOOR could refer to either of the two door
objects.  The parser must decide which of the two objects the player
is referring to; this process is called disambiguation.  The parser
does this by applying the various logical, logicalRank, illogicalNow,
illogicalAlready, and related rules defined on the matching objects in
the library and in your game code.

<p>There are two kinds of disambiguation results: "clear" and
"unclear".  When exactly one of the objects involved is logical, it's
a clear disambiguation result: we consider it safe to assume that the
player was referring to that exact object, since the other choices
simply don't make sense.  When more than one object is logical,
though, the parser can sometimes still pick one automatically (i.e.,
without generating an extra question asking the player to specify
which one she intended) based on the "likelihood" rankings given by
logicalRank rules.  A pick based on likelihood rankings is an unclear
result, because the player could plausibly have been referring to one
of the other logical matches.

<p>For unclear results, the parser has always generated a
parenthetical announcement saying which object it chose.  This is to
alert the player to the parser's choice, so that any misunderstanding
is immediately apparent.

<p>However, in past versions, the parser didn't say anything to
explicate clear disambiguation results.  In practice, even clear
results can sometimes disagree with the player's intentions, for the
simple reason that the player sometimes misunderstands the current
state of the objects.  So some authors have found that it's better to
make some kind of object announcement in every case, regardless of how
clear the parser thinks the resolution is.

<p>The parser now provides two new modes, in addition to the
traditional mode, for announcing clear disambiguation results.  These
new modes are selected via the new gameMain property ambigAnnounceMode.
You can set this in your gameMain object to select the behavior you
prefer.  The settings are:

<ul>

   <li>AnnounceUnclear: The parser makes a parenthetical announcement
   (such as "(the red door)") only when a disambiguation result is
   unclear.  It doesn't make any announcements for clear disambiguation
   results, or when only one in-scope object matches a noun phrase.
   This is the traditional behavior that the library used before the
   new options were added.

   <li>AnnounceClear: The parser makes a parenthetical announcement
   for <i>any</i> disambiguation result, whether clear or unclear.
   No announcement is generated when there's no disambiguation, though
   (that is, the noun phrase itself matches only one in-scope object).

   <li>DescribeClear: For unclear disambiguation, the parser makes the
   traditional parenthetical announcement.  For clear disambiguation,
   the parser skips the parenthetical announcement, but it uses more
   detailed default reply messages in lieu of the ultra-terse defaults,
   such as "Taken" or "Dropped".  For example, instead of just "Taken",
   the parser replies "You take the dusty old tome."  The longer messages
   mention the objects involved by name, so they provide the same
   information as the parenthetical announcements, but in a somewhat
   less conspicuous and mechanistic way.

</ul>

<p>Note that the new default behavior differs from the old behavior
from before this feature was added.  If you prefer the old behavior,
you must explicitly set gameMain.ambigAnnounceMode to AnnounceUnclear.

<p>The short-vs-long message selection for the DescribeClear option is
done through a couple of new MessageHelper methods, shortTMsg() and
shortTIMsg().  If you're adding new messages of your own, you can use
these methods to do the same type of selection.

</div>

<!------------------->
<div class=entry>

The parser can now accept short-hand replies to disambiguation queries
involving a locational qualifier, using nothing more than an adjective
or noun from one of the location names.  For example:

<p><pre>
&gt;take torch
Which torch do you mean, the torch in the left sconce, or the torch in
the right sconce?

&gt;left
Taken.
</pre>

<p>In the past, it was necessary for the response to be explicit about
the location qualification: THE TORCH IN THE LEFT SCONCE, THE ONE IN
THE LEFT, etc.  In particular, the response had to actually use the
locational phrasing to refer to the distinguishing location.  This is
no longer necessary; a player can now simply name one of the
locations, and can even abbreviate to a single distinguishing word
from the location name.

<p>To support this change, the DisambigResolver now keeps track of the
Distinguisher that was used to generate the question (the prompting
message - "Which torch do you mean...?").  This lets the resolver look
for qualifying phrases relevant to the distinguishing characteristic
called out in the prompt.

<p>The Distinguisher, meanwhile, has a couple of new methods that let
it provide the added information: objInScope() lets the distinguisher
add qualifying objects to the scope list, and matchName() lets the
distinguisher recognize qualifying objects in addition to the original
ambiguous objects.  The locational and ownership distinguishers
defined in the library provide suitable definitions for these new
methods.  Games that define their own custom Distinguisher subclasses
might want to add these methods if they also make use of ancillary
qualifier objects.

</div>

<!------------------->
<div class=entry>

In the English library, PathPassage adjusts the logicalness of
the verbs Enter and Go Through downward (to logical rank 50).  These
verbs aren't usually used with path-like objects in English;
this logicalness adjustment tells the parser to pick other objects
first in cases of ambiguity.

</div>

<!------------------->
<div class=entry>

The new conversationManager method setRevealed(key) adds the given key
to the revealed topic table.  The library now calls this method any
time it needs to add a key to the table (whereas it used to manipulate
the table directly).

<p>These changes don't affect any existing behavior - existing code
will continue to work unchanged.  The purpose of the changes is to
provide a single point for overriding the default library behavior via
'modify'.  In particular, you can override setRevealed() to store
additional information about the revealed topic in its table entry,
beyond the mere fact of the revelation.  You could, for example, store
the location where the key was revealed, or a time stamp marking when
it was revealed.

</div>

<!------------------->
<div class=entry>

A new ConvNode method, noteActiveReason(reason), extends the older
noteActive() method by providing information on why the node is being
activated.  The 'reason' parameter is a string indicating what
triggered the node change:

<ul>
   <li>'convnode' - processing a &lt;.convnode&gt; tag
   <li>'convend' - processing a &lt;.convend&gt; tag
   <li>'initiateConversation' - a call to Actor.initiateConversation()
   <li>'endConversation' - a call to Actor.endConversation()
</ul>

<p>By default, this new method simply ignores the reason code and
calls the noteActive() method.  This ensures that existing code will
work unchanged.

<p>If you need the reason information when activating the node,
override noteActiveReason().  Otherwise, you can override noteActive()
as in the past.

<p>The new reason code information is supplied when the caller changes
the node by calling the new Actor method setConvNodeReason().  This is
essentially an extended version of the existing setConvNode() method.
The new method takes an additional argument giving the reason code,
which it passes to noteActiveReason().

<p>Note that the reason code will be nil if the node change is
initiated by calling Actor.setConvNode() directly.  All of the library
calls to setConvNode() have been replaced by calls to
setConvNodeReason(), so unless your game code is calling setConvNode()
directly, the reason code will always be set properly.  For
compatibility with existing code, setConvNode() can still be called;
it works as before, simply passing a nil reason code.

</div>

<!------------------->
<div class=entry>

<a name="3018-byetopic-convnode"></a>In the past, when an actor used
conversational states (ConversationReadyState, InConversationState),
terminating the conversation didn't take into account any ByeTopic
objects in the current ConvNode within the conversation.  This was
because the conversation states have some special transition handling
that overrides the usual code where the ConvNode ByeTopic would be
found.  The conversation states now take care to check the ConvNode
in effect at the end of the conversation, so ByeTopic objects within
a ConvNode should now interact properly with conversation states.

</div>

<!------------------->
<div class=entry>

The transformation from "X, GIVE ME Y" to "ASK X FOR Y" that was
introduced in 3.0.17 caused a run-time error if "Y" was a valid word
but didn't resolve to an object.  This has been corrected.
(<a href="http://bugdb.tads.org/view.php?id=0000021">bugdb.tads.org #0000021</a>)


</div>

<!------------------->
<div class=entry>

In the past, when EXAMINE was used with ItemizingCollectiveGroup, the
output omitted any object that wasn't listable through the room
contents lister.  This was a problem for objects such as Fixtures,
which normally aren't displayed in a room listing.

<p>ItemizingCollectiveGroup now calls a new method on self,
examineUnlisted(x), to list each object <i>x</i> that isn't listed
via the room contents lister.  By default, this new method performs
a nested EXAMINE command on the unlisted object to show its full
description.

</div>

<!------------------->
<div class=entry>

In Settable, the message routing properties have been changed
slightly.  In the past, the message properties okaySetToMsg and
setToInvalidMsg were doubly redirected: okaySetToMsg had the value
&amp;okaySetToMsg, and setToInvalidMsg had the value
&amp;setToInvalidMsg.  The TurnTo action handler that used these
messages evaluated the properties directly, to get the property
pointers, which the library then processed in the usual way.

<p>The point of this arrangement was that subclasses of Settable (Dial
in particular) could easily redirect these messages to different
library messages, just by overriding the properties.  However, this
was inconsistent with the message scheme most other objects use, in
that you couldn't override okaySetToMsg(val) in the Settable itself to
yield the message text, which is how the message scheme works for
most other objects.

<p>The new version keeps the redirection step, but renames it to allow
the standard override scheme to be used.  The new property okaySetToMsgProp
evaluates to &amp;okaySetToMsg, and setToInvalidMsgProp evaluates to
&amp;setToInvalidMsg.  This means that you can override okaySetToMsg(val)
and setToInvalidMsg(val) using the standard pattern.

<p>(<a href="http://bugdb.tads.org/view.php?id=0000045">bugdb.tads.org #0000045</a>)

</div>

<!------------------->
<div class=entry>

Underside and RearContainer now provide tryMovingObjInto() method
definitions.  The new methods try the obvious implied commands
suitable for these objects: Underside tries an implied PutUnder, and
RearContainer tries an implicit PutBehind.

</div>

<!------------------->
<div class=entry>

The BannerWindow method updateForRestore() is now called during a
Restore or Undo operation for every banner, even when the banner is
already displayed.  In the past, this method wasn't called on banner
windows that were already present; it was only called when the window
had to be created in the course of the Restore/Undo.  It's now called
uniformly for all banners.

</div>

<!------------------------------- 3.0.17.1 --------------------------------->
<div class="sepbar"><a name='3017a'></a>3.0.17.1</div>
<p><b><i>Released 8/12/2008</i></b>
<p>

<!------------------->
<div class=firstentry>

<i>This version has no library changes; this release is to correct
a TADS 3 compiler problem introduced in 3.0.17.</i>

</div>


<!------------------------------- 3.0.17 --------------------------------->
<div class="sepbar"><a name='3017'></a>3.0.17</div>
<p><b><i>Released 8/9/2008</i></b>
<p>

<!------------------->
<div class=firstentry>

<b>Risk of incompatibility:</b> The standard handling for the TakeFrom
action has been changed slightly.  The changes generally make it
easier to code objects by unifying the handling of Take and TakeFrom
for most objects, but some slight adjustments to existing code might
be required - see below.

<p>First, Thing.dobjFor(TakeFrom)'s action() handler now actually
replaces the TakeFrom with a Take action.  In the past, the handler
merely invoked the Take action() handler.  For the most part, this had
the same effect as replacing the action, but not always; some
arrangements of subclasses and overrides caused subtle differences.
Actually replacing the action ensures that a successful TakeFrom is
handled <i>exactly</i> like a regular Take, which means that custom
behavior for Take will automatically apply exactly the same way to
TakeFrom without any explicit TakeFrom overrides.  Of course, you can
still override dobjFor(TakeFrom) separately if you do want it to
behave differently from Take.

<p>Second, Immovable.dobjFor(Take) now fails the action in the check()
handler rather than the action handler, which allows us to remove
Immovable.dobjFor(TakeFrom) entirely.  In the past, TakeFrom was
separately overridden to ensure that the indirect object wouldn't
attempt to carry out the action, but this is no longer necessary,
since the basic Take check() phase (which TakeFrom's check() phase
invokes) will fail the command.

<p>These two changes should essentially eliminate the need to override
TakeFrom when all you want to do is make it behave the same as Take.
TakeFrom should now always follow Take's lead, so if you simply want
TakeFrom and Take to behave the same way, just override Take and
you're set.

<p>Some existing code might not work properly with the changes to
Immovable.  In particular, you'll need to look at any objects of class
Immovable (or any subclass of Immovable) where you've overridden the
dobjFor(Take) action() handler.  In the past, overriding the action()
handler for Take was enough to override Immovable's handling of the
command, since Immovable failed the command in the action() handler
and did nothing in the check() handler.  With the change, the check()
handler cancels the action.  This means that your overridden action()
handler might never be invoked.  The solution is simply to insert an
empty dobjFor(Take) check() handler in your object:

<p>
<pre>
   boulder: Immovable 'boulder' 'boulder' "It's a big boulder. "
      dobjFor(Take)
      {
        verify()
           { /* my original verify routine... */ }
        check() { }   // THIS HAD TO BE ADDED DUE TO THE LIBRARY CHANGE !!!
        action()
           { /* my original action routine... */ }
      }
    ;
</pre>

<p>If you're not sure whether you have any objects needing this change,
you can add this bit of code to your game, and then run the game and
type IMMTEST to get a list of objects that you should inspect:

<p>
<pre>
   VerbRule(immtest) 'immtest' : IAction
     execAction()
     {
       "Immovables with dobjFor(Take) action() overrides:\n";
       forEachInstance(Immovable, new function(x)
       {
         if (overrides(x, Immovable, &actionDobjTake))
           "\t!!! <<x.name>>\n";
       });
     }
   ;
</div>

<!------------------->
<div class=entry>

Krister Fundin's Tips extension has now been integrated into the
library as a standard feature.  This system makes it easy to create
custom one-time tips of the sort that the library has traditionally
used for things like the explanation of the NOTIFY command the first
time the game's score changes.  The library now uses the Tips system
for its standard tips, and the system is readily extensible with
custom, game-specific tips.  A new chapter in the <i>Technical
Manual</i> describes the system.

</div>

<!------------------->
<div class=entry>


It's now possible to determine if a script file is currently being
read, and if so, the modes being used to read it.  To get this
information, call <tt>setScriptFile(ScriptReqGetStatus)</tt>.  If
input is currently being read from a script, the function returns an
integer value giving a combination of <tt>ScriptFileXxx</tt> flags
describing the reading mode; for example, the return value will be
<tt>(ScriptFileQuiet | ScriptFileNonstop)</tt> for a script being read
in quiet, non-stop mode.  Note that a return value of 0 (zero)
indicates that a script <b>is</b> being read, but that none of the
mode flags are applicable - that is, the script is being read in the
default modes, with output and "more" prompts displayed.  If a script
is <b>not</b> currently being read, the return value is nil.

<p>The new flag <tt>ScriptFileEvent</tt> will be included in the
return value if applicable.  This lets you determine whether the
script being read is an event script or a plain command-line script.
Note that this new flag is "query only" - if you include it in the
'flags' argument in a call to setScriptFile() to start reading a
script, the function ignores it, since the script reader determines
the type of the script to be read automatically by examining the
file's contents.  The purpose of this flag is to let you find out how
the script reader is treating the file, rather than letting you tell
the script reader how to treat the file.

<p>Note that this new form of setScriptFile() is only supported in VM
versions 3.0.17 and higher.  If you call
<tt>setScriptFile(ScriptReqGetStatus)</tt> on an earlier VM, a
run-time error result, because older implementations of the function
accept only a filename string or nil as the first argument.  You can
use try-catch to handle this situation - a run-time error indicates
that this form of the function isn't supported, in which case the
script status information is not available.

</div>

<!------------------->
<div class=entry>

Two new actions have been added: RecordEvents and RecordEventsString.
These are variations on the Record and RecordString actions that
record event scripts (rather than ordinary command scripts, as Record
and RecordString do).  The English library defines verb syntax for
these new actions ("record events", "record events on", and "record
events '<i>filename</i>'").

</div>

<!------------------->
<div class=entry>

A new parsing mechanism makes it possible to rewrite commands based on
"global" conditions.  Unlike remapTo, which lets you associate
remapping rules with the objects involved in the command, the new
mechanism lets you rewrite a command even before the objects are
resolved.  There are cases where it's important to be able to apply
the rewrite before any object resolution has taken place, because the
resolution process itself can vary substantially depending on the type
of action being performed.  remapTo has to wait until after objects
are resolved, which is sometimes too late.

<p>This new mechanism is implemented via a new class, GlobalRemapping.
To create a rewrite rule, you create a GlobalRemapping object, and
define its getRemapping() method.  This method looks at the action to
determine if it's of interest, using whatever criteria you want.  In
most cases, this means checking the action type to see if it's an
action you want to rewrite, and possibly checking to see if certain
objects are involved as well.

<p>The library defines one GlobalRemapping object, giveMeToAskFor,
which rewrites commands of the form "X, GIVE ME Y" to the alternative
format "ME, ASK X FOR Y".  The library formerly <i>tried</i> to
perform this same rewriting via an iobjFor(GiveTo) check() method in
Actor, but this approach didn't work in many cases due to interference
from several other checks made earlier in the execution process.  The
old check() scheme has been deleted in favor of the new mechanism.

<p>For full details, see the new chapter on Global Command Remapping
in the <i>Technical Manual</i>.

</div>

<!------------------->
<div class=entry>

A new set of Action methods makes it possible to temporarily override
the meaning of a pronoun, for as long as the action is in effect.
Action.setPronounOverride() creates an override, which associates an
object with a particular pronoun type (PronounMe, PronounYou, etc).
This new meaning overrides the usual meaning, but only for the
duration of the action.  Action.getPronounOverride() looks for an
override defined with setPronounOverride() for this action.

<p>This new mechanism is designed mainly to support GlobalRemapping.
In particular, a remapping that changes the target actor usually needs
to override the meaning of "you" in the rewritten action, so that
"you", "your", and "yours" are interpreted as referring to the
<i>original</i> target actor rather than the target actor of the
rewritten format.

<p>For details, see the new chapter "Global Command Remapping" in
the <i>Technical Manual</i>.

</div>

<!------------------->
<div class=entry>

The classes BaseSurfaceContentsLister, BaseRearContentsLister, and
BaseUndersideContentsLister are now all based on a new class,
BaseContentsLister.  This new class unifies the code that was formerly
defined separately in the three subclasses -
BaseSurfaceContentsLister, BaseRearContentsLister, and
BaseUndersideContentsLister are now trivial subclasses with no
overrides of their own.  (They're still present as separate classes,
(1) for the sake of compatibility with existing code, and (2) because
the distinct classes could still be useful for other types of
container-type-specific overrides beyond what the library defines.)

<p>The three subclasses exist to provide customized wording in the
contents listings generated for the corresponding specialized
container types.  However, the variation in the wording provided by
the library definitions was always very simple - the only thing that
varies is the preposition used to describe the relationship between
the container and its contents ("on" for a Surface, "under" for an
Underside object, "behind" for a RearContainer or RearSurface).  As it
turns out, the needed preposition is available as a property of the
container object, namely objInPrep.  This makes it possible to unify
the code for the three classes by referring to this property rather
than hard-coding the preposition - by doing this, the code for the
three subclasses becomes identical, which allows it to be consolidated
in a common base class.

<p>The advantage of this change is that it's no longer necessary to
change a specialized container's contents-lister class simply because
you want to change the preposition used to describe the relationship
between contents and container.  In the past, you had to change
<i>both</i> objInPrep and the contents lister.  Now, changing
objInPrep is enough - since the default contents listers refer to
objInPrep, changes to objInPrep will automatically flow through to the
wording in contents listings.

<p>Because the class structure is the same as before, existing code
should work unchanged, and you can still use contents lister
customizations to achieve effects beyond the simple wording changes
that objInPrep provides, if needed.

</div>

<!------------------->
<div class=entry>

<p>The new class ActorHelloTopic makes it easier to
create a greeting message for cases where the NPC initiates a
conversation through a script.  Place an ActorHelloTopic object
anywhere a HelloTopic would go to create a greeting specifically
for the case of an NPC-initiated conversation.

<p>[Update for 3.0.18: disregard the following.  These changes
were not effected as described, and weren't quite what was intended.
See <a href="#3018-byetopic-convnode">this entry</a> for an update.]

<p><i>
ByeTopic objects can now be used with actors who use conversational
states (ConversationReadyState, InConversationState).  In the past,
the conversational states largely bypassed the topic-based Goodbye
processing, so goodbyes had to be written with the specialized goodbye
methods on the state objects.  This made the conversation states
harder to use, since it created special cases you had to be aware of.
Now, you can set up a goodbye message by locating a ByeTopic within
the InConversationState or within any ConvNode.
</i>

</div>


<!------------------->
<div class=entry>

The class ComplexComponent now defines stagingLocations as the lexical
parent's (which is normally the ComplexContainer's) location.  This
makes it easier to embed a nested room (a platform, booth, etc) as a
component of a complex container object, by allowing inbound travel
into the nested room to bypass the complex container and move directly
between the enclosing location and the component/nested room.  As with
other aspects of complex containers, the container and component are
meant to look and act like a single object, from the player's
perspective, so it's not desirable to treat the container and
component as separate objects for the purposes of nested room travel.

<p>Along the same lines, ComplexContainer now tries to remap the
actions StandOn, SitOn, LieOn, Board, and Enter to a suitable
component.  These actions are now automatically remapped to the object
returned from the new method getNestedRoomDest(), if any.  If that
method returns nil, the actions are not remapped after all.

<p>The new getNestedRoomDest() method of ComplexContainer looks for a
suitable component to use as the destination of a nested room travel
command.  By default, it first looks to see if the sub-surface
component is a NestedRoom object, and if so, returns that; otherwise,
it checks the sub-container component, and returns that if that's a
NestedRoom; otherwise it returns nil.  This default behavior makes
everything automatic for cases where you have exactly one component
that's a nested room.  If you want to define more than one nested room
within a complex container (for example, a large crate that you can
STAND ON and also GET IN), you will need to override
getNestedRoomDest() to return the appropriate destination by verb, or
you can simply override the dobjFor(action) remapTo() definition to
point remap to the correct component.

</div>

<!------------------->
<div class=entry>

A bug in the parser sometimes caused "truncated plurals" to be
selected ahead of exact matches in a player's answer to a
disambiguation question.  By design, the parser prefers an exact match
to a singular noun ahead of a partial match to a plural (for example,
with the default six-letter truncation, the word "object" in command
input would match either the singular "object" or the plural
"objects", but the parser assume the singular word was intended
because it's an exact match for the input).  However, this principle
was being ignored in this case due to the bug.  This has now been
corrected.
(<a href="http://bugdb.tads.org/view.php?id=0000006">bugdb.tads.org #0000006</a>)

</div>

<!------------------->
<div class=entry>

In the past, if a ConvNode was activated via the &lt;.convnode&gt;
tag, and the ConvNode's noteActive() method displayed any text, the
text displayed within noteActive() appeared out of order in the final
output relative to the text containing the &lt;.convnode&gt; tag.
This happened because &lt;.convnode&gt; is processed within an output
filter, so the entire string containing the &lt;.convnode&gt; had to
be processed by the filter before any of it was actually displayed; if
any text was displayed in the course of recursively called routines
such as noteActive(), that text would as a result show up first in the
final output.

<p>The &lt;.convnode&gt; output filter now captures any text that's
displayed in the course of activating a new ConvNode, and re-inserts
the text into the stream at the proper point.  This ensures that the
text appears in the correct sequence, so it's now safe to display text
from within a noteActive() routine.
(<a href="http://bugdb.tads.org/view.php?id=0000003">bugdb.tads.org #0000003</a>)

</div>

<!------------------->
<div class=entry>

In the past, TIAction verbs (those taking a direct object and an
indirect object, such as PUT IN or UNLOCK WITH) had the side effect of
clearing the parser's memory of gender-specific pronoun antecedents.
For example, after typing "LOOK AT BOB; UNLOCK THE DOOR WITH HIS KEY",
the parser would forget that "him" refers to Bob, even though there
wasn't anyone else mentioned in the second command to supersede the
meaning of "him".  This has been fixed.
(<a href="http://bugdb.tads.org/view.php?id=0000020">bugdb.tads.org #0000020</a>)

</div>

<!------------------->
<div class=entry>

The Room class now applies a lower level of disambiguation
"likelihood" for the Examine action to a remote room than for a room
containing the actor.  In the past, the class applied a
lower-than-default likelihood for a room containing the actor, on the
assumption that a player who types EXAMINE FOO probably means to
examine a nearby object rather than the enclosing room, when both are
called FOO.  However, there's a third possibility, which is that
there's a remote room (i.e., a separate top-level room that's
connected to the current location by a sense connection) in scope
that's <i>also</i> called FOO.  In these cases, we'd still want to
select the nearby object over either room; but in cases where we only
have the two rooms to decide between, it seems most likely that the
player would want to refer to the enclosing room rather than the
remote one.  This new distinction in the likelihood levels of
enclosing and remote rooms accomplishes this: the most likely
selection is still a nearby non-room object, the next most likely is
the enclosing room, and the least likely is a remote room.


</div>


<!------------------------------- 3.0.16 --------------------------------->
<div class="sepbar"><a name='3016'></a>3.0.16</div>
<p><b><i>Released 4/10/2008</i></b>
<p>

<!------------------->
<div class=firstentry>

The new class SimpleLister provides simplified interfaces for creating
formatted lists of items.  This class is useful when you just want to
create a textual listing, using the standard serial-comma generation
and so on, without all the hassle of specifying a sense environment,
point of view, etc.  The class also has a method that creates a text
string for a listing (rather than displaying the list directly, which
is what the base Lister normally does).

<p>Two concrete instances of SimpleLister are provided, to further
simplify particular listings: objectLister, which can be used to
format a list of simulation objects; and stringLister, which can be
used to format a list of string values.

</div>

<!------------------->
<div class=entry>

Commands of the form "X, Y", where both X and Y were words not in the
game's dictionary, caused a run-time error ("nil object reference").
This was due to a library bug in the code that resolves the actor
object when giving orders to an actor ("BOB, GO EAST").  This has been
corrected.

</div>

<!------------------->
<div class=entry>

The Goal object has a new property, goalFullyDisplayed, that the hint
system automatically sets to true upon displaying the last hint in the
Goal's menu list.  This can be used, for example, to close a hint for
a red herring after the player's seen the full list of hints; this
might be desirable to remove clutter from the menu, since the player
probably won't worry about an object again once it's been revealed
that it's just a red herring.

</div>

<!------------------->
<div class=entry>

The templates for TravelMessage, NoTravelMessage, and DeadEndConnector
now accept an event list (given as a list in square brackets) in lieu
of a double-quoted message string.  These classes were already mixable
(via multiple inheritance) with EventList, so this change simply makes
it more convenient to define instances when using this capability.

</div>

<!------------------->
<div class=entry>

Top-level rooms (i.e., Room objects) didn't properly handle ENTER
commands (e.g., ENTER HALLWAY) when attempted from a separate
top-level room connected via a sense connector.  The ENTER handling
for Room incorrectly assumed that only one top-level room was in scope
at a time, which isn't true when rooms have sense connections.  The
handler also failed to handle the simpler situation where the actor
was in a nested room within the target room.

<p>The Room dobjFor(Enter) handler has been improved to handle
such situations.  The new handling is as follows:

<ul>

<li>If the actor is already <i>directly</i> in the target room (for
example, the player types ENTER HALLWAY while already in the hall),
the behavior is as before ("You're already in the hallway").

<li>If the actor is <i>indirectly</i> in the target room (for example,
the PC is sitting in a chair in the hall, and types ENTER HALLWAY),
the command is replaced with GET OUT OF <i>outermost nested room
containing actor within target room</i>.

<li>If the actor is in a separate top-level room, <i>and</i> there's
a travel connector from the actor's current location to the target
room, the command is replaced with TRAVEL VIA <i>connector</i>.

<li>Otherwise, the command fails with the message &amp;whereToGoMsg
("You'll have to say which way to go").

</ul>

</div>

<!------------------->
<div class=entry>

In the past, when NestedRoom.checkMovingActorInto() decided it had to
perform an implied action to move the actor into the nested room, the
routine assumed that the action failed if the actor didn't end up in
the nested room <i>and</i> in the room's default posture.  This
condition does hold for the library NestedRoom subclasses when the
defaults are inherited, but overriding either the default posture or
the implied command for a particular instance can make the condition
fail.  When the condition fails, the routine infers that the implied
action failed, and terminates the whole command.

<p>This condition - specifically, the test for posture - is overly
strict.  The routine isn't documented as guaranteeing the default
posture, and in fact it never did guarantee the default posture
anyway, as the implied action was always bypassed if the actor's
location was initially correct, regardless of posture.

<p>So, the condition has now been changed to remove the default
posture check.  The implied command (if any) is now considered
successful if the actor is directly in the nested room afterward.

</div>

<!------------------->
<div class=entry>

Two changes to BasicChair simplify the way the "get in" commands for
the object and its subclasses are implemented.

<p><b>First</b>, the tryMovingIntoNested() routines in BasicChair and
its subclasses have been unified into a single base-class method.  In
the past, each BasicChair subclass overrode tryMovingIntoNested() to
perform the implied action matching the subclass type - SitOn for
BasicChair, LieOn for BasicBed, StandOn for BasicPlatform.

<p>Now, the overrides have been removed, and the functionality has
been been unified into a single method on BasicChair that the
subclasses all inherit.  The BasicChair version of the method handles
all of the subclasses by deferring to the default posture object (as
returned from the defaultPosture property).

<p><b>Second</b>, the dobjFor(Board) definitions have been unified
in a single BasicChair definition, rather than requiring overrides
in each subclass as in the past.  As with tryMovingIntoNested(),
the dobjFor(Board) definition in BasicChair now calls upon the
default posture object to carry out the appropriate command.  This
removes the need to override dobjFor(Board) in each subclass.

<p>The benefit of these changes is that there's less to override when
creating a custom type of BasicChair subclass.  Setting the
defaultPosture also automatically takes care of setting the implied
action for "get in" and the mapped action for "board", since
tryMovingIntoNested() and dobjFor(Board) now choose the sub-action
that matches the default posture.  Of course, if for some reason you
want these actions to differ from what the default posture selects,
you can still override tryMovingIntoNested() and/or dobjFor(Board) to
achieve whatever special effects you want.  For typical objects where
the two match, though, these changes means less work is needed to keep
everything in sync.

</div>

<!------------------->
<div class=entry>

The "standing" posture object's setActorToPosture() method has been
changed slightly.  In the past, the routine performed an intransitive
Stand action, which causes the actor to stand up in whatever location
it's currently occupying.  This was at odds with the specification of
the method: the routine should not only make the actor stand up, but
make the actor stand in a given location; the old version ignored the
target location.  The routine now does use the target location, and
executes a transitive StandOn action with the target location as
direct object.

<p>The old implementation was the way it was because the transitive
StandOn action didn't always work properly when applied to top-level
rooms.  However, the handling of StandOn for top-level rooms has since
been improved, so this is now a viable implementation.  This makes the
method work consistently with its specification and with the
corresponding methods in the other pre-defined posture objects.

</div>

<!------------------->
<div class=entry>

The Decoration class now overrides the SEARCH action so that it uses
the standard Thing handling, to be consistent with the way LOOK IN is
handled.  In the past, SEARCH instead was handled by the Decoration
catch-all verb handler, which shows the generic "that's not important"
message.  This led to different default Decoration behavior for SEARCH
vs LOOK IN, which was inconsistent with the library's usual default
treatment of the two actions as synonymous.

</div>

<!------------------->
<div class=entry>

The English library's typographical output filter object
(typographicalOutputFilter) ordinarily adds an "en" space (a space
that's slightly wider than a normal inter-word space) after any
sentence-ending punctuation, such as a period or question mark.  This
produces looser spacing between sentences, which some people find
easier to read.  However, it had an undesirable side effect, which was
to add the same spacing after honorific abbreviations like Mr. and
Mrs. - these look exactly like sentence endings, as far as the simple
substitution rule was concerned.

<p>The filter now specifically looks for a pre-defined set of
abbreviations, and suppresses the extra spacing when it finds one.
The abbreviations are given by the property
typographicalOutputFilter.abbreviations - to change or add to the set
of abbreviations, modify typographicalOutputFilter to change this
property.  (Note that this property is only evaluated once, at program
start-up, so changing it on the fly won't have any effect.  If you do
want to modify the set of abbreviations dynamically, you'll have to
instead update typographicalOutputFilter.abbrevPat to use a new
RexPattern object with the new set of abbreviations.)

</div>

<!------------------->
<div class=entry>

DistanceConnector now allows moving objects through the connector via
moveInto - in particular, DistanceConnector now overrides
checkMoveThrough() to return a "success" indication.
In the past, DistanceConnector inherited checkMoveThrough() from
SenseConnector, which disallowed a move via moveInto() if the distance
connector was involved.

<p>In the abstract, there's usually no good reason that an object
can't be moved through a distance connector.  The only reason to
disallow it might be that the distance involved is so great that it
would take an impractical amount of time to complete the move.

<p>More to the point, though, player commands will generally disallow
this kind of operation for reasons of reachability - a touchObj
precondition is involved for any basic command that moves an object
from one container to another (TAKE, DROP, PUT IN, PUT ON, etc), and
that precondition will fail separately because the distance object is
unreachable.  Because of this, a moveInto() involving a distance
connector is almost certainly due to a programmatic (scripted)
operation, rather than a basic player command.  In the past, you could
work around this by calling moveIntoForTravel() instead of moveInto(),
but this was a needless complication.  This change allows moveInto()
to succeed even if a distance connector is involved.

</div>

<!------------------->
<div class=entry>

The ShuffledEventList object has a new property, suppressRepeats, that
lets you control whether or not a given event can occur twice in a
row.  This property corresponds to the suppressRepeats property of
the ShuffledList object.

<p>By default, this is set to true, which yields the former behavior.
You can set this to nil if you don't want to suppress repeats.  With
very small lists (of three or four elements), the suppression of
repeats sometimes makes the result sequence look fairly un-random,
because the no-repeats constraint reduces the number of available
permutations.  If you see output for a small event list that doesn't
look random enough, you might try setting suppressRepeats to nil to
see if that produces more pleasing results.

</div>

<!------------------->
<div class=entry>

ShuffledList now ignores suppressRepeats for a two-element list.  If
the list has only two elements, and repeats aren't allowed, the list
will necessarily yield the predictable sequence A-B-A-B..., which
defeats the purpose of the shuffled list.

</div>

<!------------------->
<div class=entry>

The Lockable class's dobjFor(Open) check() method now inherits the
default handling.  Since Lockable is designed to be used as a mix-in
class, this addition ensures that any additional Open checks inherited
from other superclasses are properly invoked.

</div>

<!------------------->
<div class=entry>

The comment pre-parser object (commentPreParser) now sets a runOrder
value that's lower than the default, so that it runs before other
pre-parsers that inherit the default runOrder.  In most cases, it's
unnecessary (and even potentially problematic) to run comments through
other pre-parsers, since most are designed to parse the usual sorts of
command syntax, not the free-form text allowed in comments.  Running
the comment pre-parser first effectively bypasses other pre-parsers
when a comment is encountered, since the comment pre-parser halts
further processing of the command when it detects that the command is
actually a comment.

</div>

<!------------------->
<div class=entry>

In the past, if an actor returned nil from obeyCommand(), the parser
ignored the command for the purposes of the AGAIN command.  A
subsequent AGAIN command in this case simply repeated the
<i>previous</i> command - the one just before the refused order.  This
has been corrected; the parser now remembers a command for AGAIN even
if the actor to whom the command is directed refuses it.

</div>

<!------------------->
<div class=entry>

Thing.setGlobalParamName() didn't correctly delete any previous name
from the global table.  (This would only have been a problem if you
used the method more than once on a particular object, to change the
object's global parameter name on the fly, which seems highly
unlikely.)  This has been corrected.

</div>


<!------------------------------- 3.0.15.3 --------------------------------->
<div class="sepbar"><a name='3015c'></a>3.0.15.3</div>
<p><b><i>Released 11/2/2007</i></b>
<p>
<!------------------->
<div class=firstentry>
   <i>There are no library changes in this release.</i>
</div>


<!------------------------------- 3.0.15.2 --------------------------------->
<div class="sepbar"><a name='3015b'></a>3.0.15.2</div>
<p><b><i>Released 9/13/2007</i></b>
<p>

<!------------------->
<div class=firstentry>

NonObviousVerifyResult.resultRank is now defined as the same value as
IllogicalVerifyResult.resultRank.  This makes the parser treat
illogical and non-obvious objects as equivalent in cases of ambiguity,
so that the parser won't choose one over the other.  In the past,
non-obvious objects were ranked lower than illogical objects, which
caused the parser to choose an illogical object over a non-obvious
object in cases of ambiguity.  This didn't quite make sense; for the
purposes of choosing among ambiguous objects, non-obvious objects
really should be treated as equivalent to ordinarily illogical
objects, since the point of the non-obvious designation is that the
object appears at first glance to be illogical for a given verb.

</div>

<!------------------->
<div class=entry>

The parser now incorporates Michel Nizette's vocabLikelihood
extension.  This extension lets each object set an "intrinsic
likelihood" value that affects how the parser chooses among ambiguous
objects.  When the parser can't tell the difference between two
objects using the normal 'verify' procedure, it compares the
vocabLikelihood properties of the two objects, and chooses the one
with the higher value if they differ.  This makes it easier to
fine-tune the disambiguation process to reduce unnecessary prompting.

</div>

<!------------------->
<div class=entry>

SensoryEmanation.endEmanation() now resets displayCount to nil.
displayCount was documented as being automatically reset when a period
of continuous presence ended, but in the past no actual resetting was
done.  We set the value to nil, rather than to 0 or 1, to make it more
obvious (when debugging, for example) that the object is not currently
in scope.

</div>

<!------------------->
<div class=entry>

The English library now defines suitable custom objInPrep,
actorInPrep, and actorOutOfPrep values for Surface, Underside, and
RearContainer.  This ensures that the default messages produce
reasonable relational descriptions when referring to the contents of
these specialized container types.  (In the past, only
Surface.objInPrep was suitably customized.)

</div>

<!------------------->
<div class=entry>

BasicOpenable.tryImplicitRemoveObstructor() now only attempts an
implied Open if the object is closed.  When the object is already
open, the routine now does nothing.  This change is necessary because
objects can conceivably create an obstruction even if they're already
open: once the object's open, if it's still creating an obstruction,
another implied Open would be pointless (and, in fact, could cause
an infinite loop).

</div>

<!------------------->
<div class=entry>

The new Thing method isOrIsIn(obj) returns true if 'self' is either
inside 'obj' or equal to 'obj'.  This is useful for cases where you
want to check if a given object is anywhere within another object's
containment tree, <i>including</i> the other object itself.

</div>

<!------------------->
<div class=entry>

When a MultiLoc object is the point-of-view object in a sense
calculation, it now connects all of its multiple containers to the
scope in addDirectConnections().  In the past, a MultiLoc's containers
were only considered part of the scope when the point of view was
<i>inside</i> the MultiLoc, but it makes sense for the MultiLoc itself
to be the same way, since it inherently "sees" all of its containers.

</div>

<!------------------->
<div class=entry>

LocateInParent is now defined as a class.  (It was always meant to be,
but the definition lacked an explicit 'class' keyword in past version.)

</div>


<!------------------------------- 3.0.15.1 --------------------------------->
<div class="sepbar"><a name='3015a'></a>3.0.15.1</div>
<p><b><i>Released 7/19/2007</i></b>
<p>

<!------------------->
<div class=firstentry>

<b>Compatibility warning:</b> The message property cannotTalkToSelf
has been renamed to cannotTalkToSelfMsg, for consistency with other
message property names.  (You should search your existing game code
and update any references to the old name to use the new name
instead.)

</div>

<!------------------->
<div class=entry>

<p>The new gameMain property beforeRunsBeforeCheck lets you control
the relative ordering of the "check" phase and "before" notifiers.

<p>In the past, the library always ran the "before" notifiers -
beforeAction and roomBeforeAction - <i>before</i> running the check()
handlers for the objects involved in the action.  To ensure
compatibility, the default setting for the new property is
beforeRunsBeforeCheck = true - this causes "before" to run before
check(), as it always has.

<p>However, in many ways, it's more logical and practical to run the
check() phase first first, and <i>then</i> run the "before" notifiers.
This ordering allows the "before" handlers to assume that the action
is more or less committed to running to completion, since they know
that the check() phase has already tested the action and allowed
it to proceed.  The most common use of "before" handlers is to carry
out side effects of an action, so by running all of the check() tests
first, the "before" handlers can more confidently invoke their side
effects, without worrying that the action will later fail due to a
check() condition.

<p>Now, you can never truly call an action "committed" until it's been
fully carried out, since even a "before" handler can conceivably
cancel a command (with "exit", for instance).  You could set up a
situation where an action is affected by two "before" handlers, and
the one that runs later cancels the command - thus invalidating any
assumption in the first one that the command is committed.  However,
this is relatively unusual, and in any case it's under your control:
if you don't use "before" handlers to cancel commands, it won't occur.

<p>If you want to use the new alternative ordering, where "check" runs
before the "before" notifications, simply set beforeRunsBeforeCheck to
nil in your gameMain object.  Some authors have tested this ordering
with existing games and found it to work well with existing code, but
be aware that you could trigger subtle changes - you might have
unknowingly created dependencies on the relative ordering of check()
and "before" that will only show up under certain conditions.  We
therefore recommend using the new alternative ordering only for new
code or for projects that are relatively early in their development
cycle, to ensure thorough testing of the new ordering.

</div>

<!------------------->
<div class=entry>

ThingState now allows tokens to be shared among multiple states
associated with the same object.  In the past, state words had to be
unique among an object's states: it wasn't possible to have a set of
states such as "unpainted", "painted red", and "painted blue", because
it was invalid for "painted" to appear in two states.  This sort of
sharing is now allowed.

<p>The old rule was that a word could match an object only if the word
didn't appear in any of the object's <b>other</b> (i.e., non-current)
ThingState token lists.  The new rule is that a word can match an
object if (a) the word appears in the object's <b>current</b>
ThingState token list, <b>or</b> (b) the word <b>doesn't</b> appear in
any of the object's <b>other</b> ThingState token lists.  Condition
(a) is what's new; it allows words to be shared among states by
allowing a word to match the current state as long as it's in the
current state's list, regardless of whether it appears in other
states' lists.

</div>

<!------------------->
<div class=entry>

In the English library, when a command triggers a chain of several
implied actions, the announcement for the implied actions now adds
the word "then" in each conjunction: "(first standing up, <b>then</b>
taking the box, <b>then</b> opening it)".  In the past, "then"
appeared only in the final conjunction; most people find it reads
more naturally to use "then" in each conjunction.

</div>

<!------------------->
<div class=entry>

The English library now uses the adjustDefaultObjectPrep() mechanism
to generate implied action announcements.  This means that verbs like
SitOn and GetOutOf will use object-specific prepositions when they're
announced as implied actions: "(first sitting on the bench)" vs
"(first sitting in the car)".

</div>

<!------------------->
<div class=entry>

The actions GetOutOf and GetOffOf now adjust the prepositions in their
generated verb phrases according to the actorOutOfPrep definition for
the direct object.

</div>

<!------------------->
<div class=entry>

AccompanyingInTravelState.initiateTopic() now defers to the next state
object.  Since the in-travel state is designed to be ephemeral, it's
unlikely that one of these would actually contain its own initiated
topics, so in almost all cases the desired topic would come from the
state that the actor will be in following the travel.

</div>

<!------------------->
<div class=entry>

The library now defines a simple template for ShuffledList.  The new
template takes a single list parameter giving the value list.

</div>

<!------------------->
<div class=entry>

ListGroupCustom now defines groupDisplaysSublist = nil by default.
This type of group is intended mainly for cases where you want to
display a collective message to describe the group, rather than
listing its elements individually, so we usually don't want the
inclusion of a ListGroupCustom message to trigger the "long list"
format (i.e., with semicolons) in the overall list.  This change
makes this behvior the default.

</div>

<!------------------->
<div class=entry>

Non-physical CollectiveGroup objects (i.e., those with 'nil'
locations) didn't work when the associated individuals were MultiLoc
or SenseConnector objects. This has been corrected.

</div>

<!------------------->
<div class=entry>

Actor.knowAbout() now considers an object to be known if it's
<i>currently</i> in sight.  In the past, an object was known if it was
specifically marked as known, or it was marked as having been
previously seen.  For the most part, an object that's currently
visible will also be marked as having been previously seen, since this
marking occurs whenever a Look command or travel to a new location
lists an object.  However, if an object comes into scope (via
moveInto) while an actor is in a given location, the object won't be
marked as having been seen until the next Look command or subsequent
travel away from and then back to the location.

<p>This change corrects a subtle problem that involved possessive
phrases in commands.  In the past, an object that just came into scope
was excluded from matching a possessive noun phrase under certain
circumstances, such as in the response to a disambiguation question.
This should no longer occur.

</div>

<!------------------->
<div class=entry>

In the past, the library <i>seemed</i> to allow commands like PUSH TV
INTO BOX (i.e., commands to push a pushable object into a nested
room), but on closer inspection it didn't really carry them out:
instead, it carried out only the underlying basic travel command,
without actually moving the object supposedly being pushed around.
The library now rejects PUSH INTO <i>nested room</i> commands with a
new message, &amp;cannotPushObjectNested ("You can't push the TV
there").

<p>The library rejects these commands by default because we think
it'll be relatively rare that games will need to allow them.  Given
that, it didn't seem worth complicating things by adding a bunch of
new methods to provide generalized support, and we also didn't want to
introduce that much new code at the current point in the release
cycle.

<p>However, the library does now provide a new hook that will make it
easier for games to implement PUSH INTO <i>nested</i> commands if they
need to.  The new hook will also make it possible to implement riding
vehicles into nested rooms, which wasn't previously possible.  The new
hook is a new Traveler method, travelerTravelWithin().

<p>This new method is called on the Traveler object when a nested-room
travel command (GET IN, STAND ON, SIT ON, LIE ON, PUSH X INTO, etc) is
performed.  In simple cases, the Traveler is simply the Actor
performing command.  However, if the actor is riding in a Vehicle, the
Traveler is the Vehicle object; and if the command is a PUSH travel
command, such as PUSH TV INTO BOX, the Traveler is a special ephemeral
object, of class PushTraveler, created just for the command.

<p>The library provides default implementations of the new hook method
for Actor, Vehicles, and PushTraveler.  For Actor, the method simply
does the same thing that travelWithin() used to do, so existing code
will work as it did before.  For Vehicle, the method calls the same
method on the Actor, so again it will work as it used to.  For
PushTraveler, the method simply terminates the command with the new
message &amp;cannotPushObjectNested.

<p>If you want to allow pushing objects into nested rooms, you'll need
to modify PushTraveler.travelerTravelWithin() to do basically the same
thing that PushTraveler.travelerTravelTo() does.  You'll probably want
to set up a new set of notification methods parallel to
beforeMovePushable() and movePushable() - you could just use those
same routines, but you'll probably want to set up new custom
nested-room versions instead, since the conditions and messages will
probably need to be different for nested rooms from those used for
room-to-room travel.

<p>Note that you could also take advantage of the new method to allow
an actor to ride a vehicle into a nested room.  The default handling
in Vehicle defers to the underlying Actor, and the actor performs the
travel as though the Vehicle were any other nested room - which means
that the actor gets out of the vehicle, then gets into the new nested
room.  If you instead wanted this type of command to mean "ride
vehicle into nested room," you can override travelerTravelWithin() on
the vehicle, so that the method moves the Vehicle itself into the new
nested room.  (You'll also have to set up preconditions that move the
vehicle to the proper staging locations using the same rules that are
used for actors, which could take a little work - that's the main
reason the library doesn't support it out of the box yet.)

</div>

<!------------------->
<div class=entry>

In the past, if an NPC was using AccompanyingState to follow around
the player character, and the pair went through an AutoClosingDoor,
the door was reported as having closed twice during the turn -
once for each actor going through.  AutoClosingDoor now skips the
auto-closing step if the actor going through is in an accompanying
state.

</div>

<!------------------->
<div class=entry>

The parser's "OOPS" mechanism had a problematic interaction with
literal phrases that showed up under certain conditions.  In
particular, if the player entered a command that caused some kind of
follow-up question, such as a disambiguation query ("which book do you
mean...") or missing-object prompt ("what do you want to unlock it
with?"), <b>and</b> the player chose to ignore the follow-up question
and instead just enter a new command, <b>and</b> the new command
contained a literal phrase ("type asdf on keypad", say), the OOPS
mechanism was overly aggressive in deciding the command contained a
typo.

<p>The root of the problem was that follow-up questions are parsed
according to their own special grammars, which are much more limited
than the full grammar used at the main command prompt.  Normally, when
the player responds with something that doesn't match one of these
special grammars, the parser assumes the player intended to bypass the
follow-up question and just enter a new command.  However, if parser
manages to find a non-dictionary word in the player's input, it
invokes the OOPS mechanism to see if the player actually intended to
answer the follow-up question but made a typographical error entering
the response.  The problem is that if the player entered a
literal-phrase verb, the presence of a non-dictionary word
<i>doesn't</i> necessarily imply a typographical error.  For normal
commands (as opposed to follow-up questions), this isn't an issue,
because the parser finds the literal when matching against the full
grammar.  For follow-up questions, though, the parser never noticed
the literal-phrase interpretation of the input, since it wasn't
matching against the full grammar, so it prematurely decided that the
input as mis-typed.

<p>The OOPS mechanism now makes an extra check when presented with a
non-dictionary word in the response to a follow-up question.  Before
deciding that the input really does contain a typo, the OOPS mechanism
first checks the input to see if it matches anything in the full
command-line grammar; if the parser finds a match, it assumes that the
entry was meant as a brand new command, and so it bypasses the
follow-up question and re-parses the input as a new command.

</div>

<!------------------->
<div class=entry>

In the past, calling getOrigTokenList() on an EventAction object
caused a run-time error.  This was because EventActions don't have the
token list data that the parser normally attaches when creating an
Action to represent a parsed command line, which in turn is because
these actions aren't created from command parsing but are instead
"synthetic" actions, created internally by the library for bookkeeping
purposes.  (This same problem might have affected other synthetic
actions as well, but it's only known to have shown up with
EventActions.)

<p>This has been corrected.  Action.getOrigTokenList() now checks to
make sure there's a parser token list attached to the action, and if
not, the method return the parent action's token list; and if there's
no parent action, the method simply returns an empty list.

</div>

<!------------------->
<div class=entry>

HermitActorState now sets its property limitSuggestsion to true by
default, to prevent the TOPICS command from displaying any topic
suggestions from the actor or conversation node.  This is desirable
because the hermit state effectively blocks any topics defined outside
the state: the whole point of the state is that it makes the actor
essentially unresponsive to conversational overtures.  So there's
generally no point in offering topic suggestions while the actor is in
the state.

<p>In some cases, you might want to override this for a particular
hermit state object.  In particular, if it's not outwardly obvious
that the actor will be unresponsive, you might still want to allow
suggestions, since the player has no way of knowing that the actor
won't respond to questions until she attempts asking them.  Similarly,
if the hermit state is expected to persist for a short time only, you
might want to continue to allow suggestions so that the player knows
there are useful topics to explore when the actor becomes responsive
again.

</div>

<!------------------->
<div class=entry>

ByeTopic now overrides impliesGreeting to suppress any implied HELLO
greeting.  This means that if the player explicitly says GOODBYE to an
NPC, and no conversation is in progress, the goodbye response will be
displayed by itself, without an implied greeting exchange.  In the
past, ByeTopic inherited the default 'true' value for impliesGreeting,
so saying GOODBYE to an NPC outside of a conversation caused an
implied greeting, followed immediately by the explicit goodbye
response.  In most cases, this ended up looking pretty strange - not
only was the self-canceling HELLO-GOODBYE exchange odd on its face,
but in most cases the implied greeting also looked redundant from the
player's perspective, because a player tended to say GOODBYE
explicitly only when she was under the impression that some kind of
conversational interaction was already under way.

</div>

<!------------------->
<div class=entry>

In the past, conversation-flow problems sometimes occurred if a topic
changed its "isConversational" status as a side effect of showing the
response for the topic.  This was because
ActorTopicDatabase.showTopicResponse() waited until after invoking the
response to determine whether the response should affect the
conversation flow, so the status change side effect caused
showTopicResponse() to use the new setting - meant for the next
response - rather than the setting for the response it actually
showed.  This has been corrected; showTopicResponse() now makes its
determination based on the isConversational status as it stands just
before invoking the response.

</div>

<!------------------->
<div class=entry>

The finishGameMsg() function now explicitly runs the score notifier
daemon before it displays the end-of-game message.  This ensures that
the usual score-change message is displayed if any points were awarded
in the course of the action that triggered the end of the game.
Without the explicit invocation, the notifier daemon wouldn't
typically get a chance to show a notification for the final point
award: the notification is normally shown just before the next command
prompt after points are awarded, and at the end of the game there's
not usually another command prompt forthcoming.

</div>

<!------------------->
<div class=entry>

In the English library, inlineListingContentsLister didn't always
generate correct verb agreement for its prefix message for a "wide"
listing ("You are carrying tongs (which <b>contains</b> ...)").
This has been corrected.

</div>

<!------------------->
<div class=entry>

In the past, searching a RoomPart nominally containing a RoomPartItem
sometimes caused a "nil object reference" run-time error.  This was
due to a missing point-of-view object setting; the code where the
error occurred now applies a default POV of the command actor when
no explicit POV is set.

</div>

<!------------------->
<div class=entry>

Container and Openable objects now apply a touchObj precondition to
the Search action.  This requires that the actor be able to reach the
object in order to search it.  This change is intended to better
enforce the idea that searching a container involves some actual
physical manipulation, such as shifting the contents around to look
behind or under things, momentarily removing contents to see what's
underneath, and so on.  The actor at least has to be able to reach the
object to perform this kind of manipulation.

</div>

<!------------------->
<div class=entry>

In the past, AGAIN didn't work properly when used to repeat a FOLLOW
command involving an NPC using the "guided tour" mechanism (the
TourGuide and GuidedTourState classes).  This was due to a subtle
turn-timer problem with AGAIN that affected commands like FOLLOW that
use nested or replacement actions in the course of their execution.
This problem was observed in the FOLLOW/AGAIN situation, but could
also have affected other commands.  The root problem has been
corrected.

</div>


<!------------------------------- 3.0.15 --------------------------------->
<div class="sepbar"><a name='3015'></a>3.0.15</div>
<p><b><i>Released 3/8/2007</i></b>
<p>

<!------------------->
<div class=firstentry>

The Follow action has always adjusted the scope list to include any
NPCs that the target actor remembers having seen leave, whether or not
they're still within sight.  This allows you to FOLLOW a character
who's no longer present - the whole point of FOLLOW would be defeated
if this weren't possible, after all.  However, in the past, this scope
list expansion created duplicate entries in the scope list if an actor
with a "follow memory" was also still physically present - the actor
was added to the scope list once for ordinary visibility, then again
for the "follow memory."  This duplication caused problems in some
situations, since other parts of the library expect the scope list to
contain only unique entries.  The Follow action now ensures that the
list remains unique after its additions.

</div>

<!------------------------------- 3.0.14 --------------------------------->
<div class="sepbar"><a name='3014'></a>3.0.14</div>
<p><b><i>Released 2/9/2007</i></b>
<p>
There are no library changes in TADS 3.0.14.


<!------------------------------- 3.0.13 --------------------------------->
<div class="sepbar"><a name='3013'></a>3.0.13</div>
<p><b><i>Released 1/19/2007</i></b>
<p>

<!------------------->
<div class=firstentry>

The adv3 English library has a new option setting for the parser's
truncation length.  The truncation length has always been customizable
in the low-level system objects that the parser uses to look up and
match vocabulary words, but the library didn't formerly provide a good
way for games to override <i>its</i> truncation length setting.  In
effect, the truncation length was hard-coded into the English library,
and the only way for authors to change it was to edit en_us.t; most
authors would rather not do that because of the hassle of merging
their own changes into future library updates.

<p>The new setting is in gameMain.parserTruncLength.  The default
setting is 6 characters - this is the same as the English parser's old
hard-wired setting, so existing code will behave the same as it did in
the past.

<p>As part of this change, the new method
languageGlobals.setStringComparator() lets you change the active
string comparator dynamically.  You can use this method if you want to
change the truncation length, or other comprator settings, on the fly
during the game.

</div>

<!------------------->
<div class=entry>

The English library now allows a TAction VerbRule to specify a custom
preposition for a default object announcement, overriding the
preposition coded in the verbPhrase.  This is useful for a few verbs
where the preposition tends to vary according to the direct object.
For example, SIT might use ON in some cases but IN for other cases:
"on the stool" vs "in the car."

<p>To accomplish this, TAction.announceDefaultObject() first parses
the verbPhrase to get the standard preposition, then calls a new
method on self, adjustDefaultObjectPrep(prep, obj).  'prep' is the
default preposition from the verbPhrase, and 'obj' is the direct
object of the command.  The routine returns the new preposition
string.  The default implementation simply returns 'prep', but
the StandOn, SitOn, and LieOn actions override this to return the
direct object's actorInPrep.

</div>

<!------------------->
<div class=entry>

InitiateTopics can now be located within ActorState objects.  In the
past, InitiateTopics were only found when they were directly within an
Actor or a TopicGroup within an actor.  The library now looks for
InitiateTopics in the current actor state object as well, which is
more consistent with other topic types.

</div>

<!------------------->
<div class=entry>

inputManager.pauseForMore() now re-activates the transcript if it was
active before the pause.  In the past, this function simply flushed
output and left the transcript deactivated.  This was problematic for
certain library subsystems that depend upon the transcript being
active throughout a command.  Now, the function flushes the
transcript's pending output up to the pause, then reactivates the
transcript after the pause, so that transcript capture proceeds as
normal throughout the rest of the command.

</div>

<!------------------->
<div class=entry>

In the past, the library generally assumed that NestedRoom objects
would only be located inside either Rooms or other NestedRooms, but
never inside ordinary Things.  However, in practice it's often useful
to be able to put a nested room inside something that's not itself
a nested room.

<p>A number of small library changes should now make NestedRooms
work properly when located inside ordinary Thing objects.  The
changes are mostly internal and should have no impact on existing
code, but for reference, here's what's changed:

<ul>

<li>The methods getRoomPartLocation(), getLocTraveler(),
atmosphereList(), roomDaemon(), getDropDestination(), and
effectiveFollowLocation() have been moved to Thing, with essentially
no changes.  These are the methods the library calls on containers of
nested rooms, so moving them to Thing allows any game object to
contain a nested room.

<li>The definitions of most of the above methods have been removed
from BasicLocation, since BasicLocation now simply inherits the Thing
definitions.  The definitions of roomDaemon() and atmosphereList()
have been moved to Room instead, since those definitions were intended
for top-level rooms.

<li>Room now defines checkActorOutOfNested() to find and defer to
the child object containing the actor.  This ensures that the check
is forwarded to the nested room containing the actor.

</ul>

<p>In addition to the changes above, NestedRoom no longer assumes that
its immediate location is the destination when an actor within the
nested room leaves the nested room.  Instead, NestedRoom now
consistently uses the value given by exitDestination.  Further,
NestedRoom.exitDestination itself no longer uses the immediate
container as its default setting, but instead uses the default staging
location as given by the defaultStagingLocation method.

</div>

<!------------------->
<div class=entry>

A change in 3.0.10 introduced a parsing problem with distinguishing
nouns from plurals when the words were right at the parser's
truncation length.  To be more precise, if you defined a noun that was
exactly the truncation length, <i>and</i> you also defined a plural
for that noun as the noun plus "s" (or, actually, as the noun plus any
other letters), then the parser would incorrectly interpret the noun
word in player input as though it were plural.

<p>For example, the default truncation length is 6 characters, so this
problem occurred with "button" and "buttons" defined as a noun and
plural, respectively.  In this case, if you had two or more objects in
scope with vocabulary like 'red button*buttons', and the player typed
something like "x button", the parser incorrectly treated the "button"
in the player's input as though it were plural, so it applied the
Examine command iteratively to all of the buttons in scope, rather
than asking the player which singular button they intended to examine.

<p>This problem has now been corrected.

</div>

<!------------------->
<div class=entry>

The message definition for cannotSetToMsg was missing from the English
message list (in en_us/msg_neu.t).  The message is now there.

</div>

<!------------------->
<div class=entry>

A command of the form PUSH <i>pushable</i> INTO <i>object</i>, where
the second object was some random, non-enterable thing, yielded an
unformatted message ("{that/he dobj} {is} not something you can
enter").  The underlying problem was that the action remapping invoked
by PushTravelViaIobjAction didn't properly set up the object
parameters for the remapped verb, leaving the message system unable to
find the direct object.  This has been corrected.

</div>

<!------------------->
<div class=entry>

The Attachable class had a problem that caused a run-time error when
the player entered a command of the form DETACH <i>object</i>, where
<i>object</i> was an Attachable and the command had no indirect
object.  The problem came from a name conflict between an Attachable
method called cannotDetachMsg(obj), which took one parameter, and a
library messages property of the same name, which takes no parameters.
When the message resolution system tried to retrieve the library
message from the direct object, it invoked the zero-parameter version
of the property, which caused the run-time error due to the parameter
mismatch with the one-parameter version implemented in Attachable.

<p>To fix this problem, the method in Attachable has been renamed to
cannotDetachMsgFor(obj).  The library message has the same name as
before.

<p>Any existing code that overrode the Attachable method will have to
adjust for the name change.  That said, it seems almost impossible for
this change to affect existing code, since the very bug that we're
talking about here would have prevented the override from working
properly in the first place.

</div>

<!------------------->
<div class=entry>

A library bug caused a run-time error ("stack overflow") on commands
like REMOVE ME or REMOVE <i>nested room containing me</i>.  This has
been corrected.

<p>(The specific problem is as follows.  The library assumes that a
REMOVE X command will result in the actor taking X, and so as a sanity
check calculates how much weight the actor would be holding if that
were allowed.  When X is the actor or contains the actor, the
hypothetical weight check created a circular containment situation;
the stack overflow came from the library's attempt to recursively
visit all of the hypothetical contents of the actor, which is of
course an infinite loop in a circular containment situation.  To avoid
this problem, the library now ignores hypotheticals that would create
circular containment.  It's safe to ignore these hypothetical tests
because commands that perform them should always be disallowed anyway,
since actual circular containment is never allowed.)

</div>

<!------------------->
<div class=entry>

A library bug caused a run-time error ("nil object reference") on
entering a command of the form <i>object</i>, <i>unknown word</i>,
where <i>object</i> was any in-scope non-Actor object.  This has
been corrected.

<p>(The problem came about because the parser attempted to treat such
a command as though it were directed to an NPC.  This is some special
handling that applies when the command has a syntax error; the point
is to let the author customize the parsing error messages for orders
given to particular actors.  However, when <i>object</i> isn't an
actor, this is problematic, because the library assumes that it can
call certain Actor methods on the object in question.  The fix is that
the library will only apply this handling in cases where the object is
actually an Actor; in other cases, it won't assume that the command
was intended as an order to an NPC, so it will simply use the default
parsing error messages.)

</div>


<!------------------------------- 3.0.12 --------------------------------->
<div class="sepbar"><a name='3012'></a>3.0.12</div>
<p><b><i>TADS 3.0 General Release version - Released 9/15/2006</i></b>
<p>

<!------------------->
<div class=firstentry>

The library didn't properly handle situations where an NPC order
involved multiple objects and a failed implied sub-action.  If an
implied action failed for one of the objects involved, the implied
action was assumed to have failed for all <i>subsequent</i>
objects in the multiple object list as well, even if the subsequent
implied actions actually succeeded.  This resulted in self-contradictory
transcripts, where an implied action was reported as successful, but
then was followed by a message that the implied action had failed:

<p><pre>
  Bob takes the coin.
  Bob must be holding the coin first.
</pre>

<p>The problem was that the implied action mechanism was incorrectly
considering the failure status for the entire top-level command when
determining if the subsequent implied actions failed.  Instead, it
should have been checking the status of the implied actions
themselves.  It now does this by looking for a failure report within
the implied action's reports, rather than looking for a failure
anywhere within the entire transcript.

</div>

<!------------------->
<div class=entry>

SpaceOverlay.getWeight() now omits the object's "contents" from the
weight calculation if the contents are to be abandoned when the object
is moved.  If the contents are to be abandoned, it means that they're
not actually attached to or contained within the space overlay, but
are simply colocated with it; they thus have no contribution to the
overlay's total weight.  If the contents are <i>not</i> to be
abandoned on moving the overlay object, they're effectively attached
to it, so they do contribute to its weight as normal.

</div>

<!------------------->
<div class=entry>

CaptureFilter is now a subclass of OutputFilter (it was formerly just
an 'object'); and SwitchableCaptureFilter is a subclass of
CaptureFilter (it also was just an 'object').  This should make no
difference functionally, as an output filter is only required to
implement the filterText() method, but is desirable anyway in that it
makes an ofKind(OutputFilter) test recognize these object types as
output filter subclasses.

</div>


<!------------------------------- 3.0.11 --------------------------------->
<div class="sepbar"><a name='3011'></a>3.0.11</div>
<p><b><i>Released 9/8/2006</i></b>
<p>

<div class=firstentry>

<i>Very</i> slight compatibility risk: NameAsOther (and thus
NameAsParent) no longer maps the "in" names to its target object.  The
"in" names are the names generated when an object is described as
contained within the NameAsOther.  In the past, these were mapped to
the target object along with all of the ordinary names for the object.
However, this was the wrong behavior for ComplexComponent, which
inherits from NameAsOther, because the containment relationship
between a ComplexContainer and its contents is defined by the
container subclass mixed with ComplexComponent in the object's
superclass list, <i>not</i> by the target object, which in this case
is the ComplexContainer of which the ComplexComponent is a part.

<p>Although it's conceivable that some other applications of
NameAsOther would actually want the old behavior, it seems highly
unlikely, so we don't expect any practical compatibility list.

<p>However, we have provided a new mix-in class, ChildNameAsOther,
that adds mappings for all of the "in" names to the target object.
So, if you have a NameAsOther that depends upon the old "in" name
mapping, just add ChildNameAsOther to the object's superclass list
(right after NameAsOther or NameAsParent), and you'll get the same
behavior as before.

</div>

<!------------------->
<div class=entry>

In 3.0.10, the ImpByeTopic was differentiated into a couple of
subclasses to allow handling implicit goodbyes differently when
desired (see <a href='#ImpByeTopicSubclasses'>below</a>).  However,
this change didn't handle one type of goodbye correctly, namely the
NPC-initiated goodbye, via npc.endConversation().  The change
incorrectly made it so that those goodbyes were treated the same as
explicit <i>player</i>-initiated goodbyes.

<p>Prior to the 3.0.10 change, NPC-initiated goodbyes were subsumed
into the undifferentiated "implicit goodbye" category, and they
should clearly remain in that category; they simply need to be
differentiated like the other implicit goodbyes were in the 3.0.10
change.

<p>To this end, the new topic class ActorByeTopic has been added; this
is analogous to BoredByeTopic and LeaveByeTopic, and is used when the
NPC terminated the conversation via npc.endConversation().  In the
absence of an active ActorByeTopic, the active ImpByeTopic will be
used instead.  This restores compatibility with pre-3.0.10 code (where
there was no differentiation among "implied goodbye" types, and
npc.endConversation() events were handled as implied goodbyes), while
providing a specific topic type to handle this one type of goodbyes.

</div>

<!------------------->
<div class=entry>

The English library's "instructions" module (instruct.t) now uses HTML
markups to display typographical quotes and apostrophes ("curly
quotes") throughout the text of the standard instructions.  Thanks to
Greg Boettcher for making this improvement.

</div>

<!------------------->
<div class=entry>

The detailed-naming scheme for object announcements (see <a
href='#getInScopeDistinguisher'>below</a>) introduced in 3.0.10 has
been made optional, and disabled by default.  Testing reveals that the
mechanism as currently designed is too twitchy for some people's
taste, so we've disabled it by default for the time being; however,
the code is all intact, for those who want to use it as-is or tweak it
for their needs.  To enable the detailed announcement naming, set
gameMain.useDistinguishersInAnnouncements to true.

</div>

<!------------------->
<div class=entry>

The BannerWindow system had a flaw in the way it re-initialized
banners after a RESTART.  The problem showed up in cases where there
were dependency orderings among the windows, so that one window's
initBannerWindow() had to call another's initBannerWindow() in order
to create the windows in the correct order.  The problem didn't always
happen even in cases of ordering dependencies, since it also depended
on the arbitrary ordering of the VM's internal object lists.  When it
happened, the problem manifested itself by creating extra copies of an
affected banner window at each RESTART.  This has now been corrected.

</div>

<!------------------->
<div class=entry>

In banner.t, the formerly anonymous InitObject that handles banner
initialization (and post-RESTART re-initialization) now has a name,
bannerInit.  This is so that games can use "modify" and "replace" with
the object, and also so they can refer to it from the execBeforeMe
properties of other InitObjects, for initialization dependency
ordering purposes.

</div>

<!------------------->
<div class=entry>

"Follow mode" for NPCs ("Bob, follow me") didn't work correctly when
the actor being followed moved between two top-level rooms connected
by a sight sense connector.  This has been corrected.  (The problem
was that the code that carried out the "follow" attempted to move the
follower using a "local travel" action - something like STAND ON STAGE
or ENTER BOOTH - any time the target actor was still in sight.  The
follower now attempts local travel only if the target is still in
sight <i>and</i> the target is within the same top-level room;
otherwise, the follow uses a suitable full-fledged travel action.)

</div>

<!------------------->
<div class=entry>

In Actor.actorActionFollow(), if the actor is already in "follow" mode
for the requested other actor, a message is now displayed to this
effect (alreadyFollowModeMsg: "I'm already following Bob").  This
won't be a factor by default, since the library automatically cancels
"follow" mode any time a new command is issued to an actor
<i>before</i> attempting to enact the new command.  However, games
might want to override this auto-cancel behavior, in which case they
might encounter this situation in actorActionFollow().  In the past,
the routine did nothing at all - it didn't even show a message, so the
generally undesirable "Nothing happens" was displayed by default.

</div>

<!------------------->
<div class=entry>

In the past, an actor that started in an InConversationState triggered
a run-time error at start-up, due to an initialization order problem
in the library.  This has been corrected.  (In particular, an actor's
boredAgendaItem property is now initialized via a perInstance()
definition rather than in initializeActor().  This ensures that the
property is initialized before it's needed.  In the past, the order of
initializations sometimes resulted in the library trying to use the
actor's BoredAgendaItem object before it was initialized, leading to a
"nil object reference" error.)

</div>

<!------------------->
<div class=entry>

Room's condition for remapping the GetOutOf action to the Out action
has changed slightly.  In the past, this remapping was performed only
if the 'out' direction had an <i>apparent destination</i>, which is
only the case when the actor attempting the travel already knows the
destination (such as from past experience or at-hand information).
This condition wasn't quite right, though.  Instead, the condition
should have been simply that the 'out' direction has an apparent
<i>connector</i> - that is, there's a visible way to travel in the
'out' direction.  Room has been changed to use the new condition.

</div>

<!------------------->
<div class=entry>

The template (in en_us/en_us.h) for DeadEndConnector now makes the
apprentDestName entry optional.  This allows using the template to
define a dead-end connector that merely displays a message when
traversed, without giving it a name.

</div>

<!------------------->
<div class=entry>

In the English library, PathPassage now limits its remapping of the
Take action to the TravelVia action to cases where the entered verb
phrase was literally "take."  This prevents other phrasings, such as
"pick up path" or "get path," from being interpreted as attempts to
travel along a path.

</div>

<!------------------->
<div class=entry>

The message sayTravelingRemotely in the English library has been
corrected to add the word "to" before the destination name.

</div>


<!------------------------------- 3.0.10 --------------------------------->
<div class="sepbar"><a name='3010'></a>3.0.10</div>
<p><b><i>Released 8/17/2006</i></b>
<p>

<div class=firstentry>

<b>Incompatibility warning:</b> <i>(This note concerns a change that
was made in 3.0.9 but inadvertantly omitted from the 3.0.9 release
notes.  We're mentioning it now in case anyone was affected by it
and needs help adjusting their code for the change.)</i>

<p>In version 3.0.9, gameMain.verboseMode was changed from a simple
true/nil property to an object of class BinarySettingsItem.  Any
existing game code that attempted to turn verbose mode on or off by
setting gameMain.verboseMode to true or nil will now encounter a run-time
error the first time the player enters a travel command.

<p>If you want to set the default verbosity mode explicitly in your
game, you can't do it any more by setting gameMain.verboseMode to true
or nil.  Instead, you can add a line like this to a start-up routine,
such as gameMain.newGame():

<p>
<pre>
   gameMain.verboseMode.isOn = true; // turn on verbose mode
</pre>

<p>Note that the verbosity mode is now part of the "global
preferences" mechanism, so in most cases it's best for games not to
change it explicitly, instead leaving it up to the player to decide on
the setting.  In the past, some authors liked to set a verbosity mode
that they felt was most suitable for the game.  Now that the player
can specify a set of default preferences that they wish to apply to
all games, it's better for authors not to presume to change the
player's default settings without a good reason.  As with any other
rule, there are bound to be exceptions, so if you have a really good
reason to override the player's preferences then you should feel free
to do so.  But if you're tempted to override the player's preferences
just because <i>you</i> like it a particular way, you might want to
reconsider.

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: The Lockable class now has
initiallyLocked set to true.  This means that <i>all</i> Lockable
objects now start out locked by default (i.e., unless your game code
specifically overrides initiallyLocked to set it to nil for a given
Lockable).  In the past, Lockable didn't define initiallyLocked at all
(so it defaulted to nil), but Door and IndirectLockable defined it as
true - so some Lockables formerly started out locked by default while
others were unlocked by default.  This change should be generally
beneficial, since (1) it simplifies matters by making the initial lock
status consistent across all Lockables, and (2) the vast majority of
Lockables start out locked anyway, so "locked" is the better default.

<p>If you have any Lockables in existing code that you specifically
intended to start out unlocked, and you didn't explicitly set
initiallyLocked to nil in those objects, you'll have to do so now.

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: The method Action.callVerifyPrecond has
been renamed to callVerifyPreCond - that is, the 'c' in 'precond' is
now capitalized.  This change is for better naming consistency, since
all of the other symbol names in the library that include the
substring "precond" capitalize the C.  This routine is intended mostly
for internal use within the library, so it should affect little or no
existing game code.

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: The NOTE command has been removed, and
replaced by a new comment syntax that lets the player enter a comment
by starting a command line with a punctuation-mark prefix.

<p>The default comment prefix is now an asterisk ("*").  You can
change this to any prefix string you'd like by modifying the
commentPrefix property of the commentPreParser object.  You can also
control whether or not leading whitespace is allowed before the
comment prefix (it is by default) by modifying commentPreParser's
leadPat property.

<p>Using NOTE as the comment prefix was problematic because NOTE is a
common enough word that games often want to use it in an object's
name, and this creates situations where a user might want to start an
input line with NOTE with the intention of referring to an object, not
of entering a comment.  It was essentially impossible in some of these
cases to reliably determine which the player meant.  The new approach
avoids these problems by using syntax that should be unambiguous in
nearly all games.

<p>In the past, there was a StringPreParser object in the English
library that helped the NOTE command by quoting the note text in some
cases.  This preparser has been removed, and a new preparser has been
added in its place, but this time in the general library, in misc.t.
The new object is called commentPreParser, and it performs all of the
comment handling itself, without the need for a separate NOTE action.

<p>As part of this change, NoteAction and NoteIAction have been
eliminated.  In the unlikely event that you used 'modify' to change
the behavior of these actions, you'll have to rework your code.  Look
at the commentPreParser object for details of the new arrangement.

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: Each actor now has its own separate
lookup table of ConvNode names.  This means that you don't have to
worry about making ConvNode names unique globally - you only have to
make sure that names are unique within a single actor's set of nodes.

<p>This shouldn't affect existing game code, except for cases where
you refer directly to conversationManager.convNodeTab.  You should
scan your source for occurrences of "convNodeTab" and change any that
you find to "actor.convNodeTab", where "actor" is the Actor who owns
the table.  The most likely place for game code to refer to
convNodeTab is in a "modify conversationManager" definition.

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: Thing.getExtraScopeItems() is now
required to return a list - nil is no longer a valid return value
for this method.  Use an empty list instead of nil to indicate that
there's nothing to add to the current scope.  The old nil return
code was inconsistent and unnecessary, as an empty list always
functionally meant the same thing anyway.

<p>It's very unlikely that this change will affect any existing
game code, since any game code that overrides this method almost
certainly did so to add something to the scope.  However, you
do a quick search through your game code for getExtraScopeItems(),
and make sure that you don't have any nil returns; if you do,
simply change them to empty lists ("return [];").

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: Thing.getListedContentsInExamine() has
been renamed to getContentsForExamine(), and its operation changed
slightly.  The old name was a bit misleading, in that the method
actually needs to return all of the visible contents of the object,
whether or not they're marked as listable.  Unlistable contents need
to be included in this list so that their listable contents can be
included recursively.  This is the operational change: in the past,
only listable contents were included in the returned list; now, all
visible contents are included.

<p>This change corrects an inconsistency that occurred in cases where
an object had fixed-in-place contents that themselves had contents.
In the past, directly examining such an object didn't mention anything
about the contents of the second-level containers, while a simple LOOK
<i>did</i> include the inner contents.  The change makes the two cases
consistent.

<p>This change should have little or no effect on existing code, since
the former getListedContentsInExamine() method is an internal method
that's unlikely to have been called or overridden in game code.  If
you overrode this routine, though, you'll need to apply the name
change to your code, and make any adjustments for the slight change in
the method's semantics.

</div>

<!------------------->
<div class=entry>

Minor incompatibility warning: the "equivalent object" mechanism has
changed substantially, although existing game code shouldn't be
affected unless it was modifying the equivalence mechanism itself.

<p>In the past, equivalence was based on the superclass of the object.
Two objects were equivalent if (a) they both had isEquivalent set to
true, and (b) they had identical superclass lists.  This approach to
equivalence was occasionally problematic, particularly when using
"proxy" objects to modify the behavior of objects involved in
equivalence groups.  In addition, the superclass approach was somewhat
counterintuitive: the whole point of the equivalence mechanism is to
treat objects with identical names as interchangeable, but using
superclasses as the basis of the equivalence had nothing to do with
the naming.

<p>The new scheme is based on a new property called equivalenceKey,
which is defined in the language module.  In the English library, the
default setting of this new property is the disambigName of the
object.  So, equivalence groups are now simply based on the basic
disambiguation name of the object.  This is much more consistent with
the disambiguation mechanism itself, because it means that the parser
decides whether objects are interchangeable using essentially the same
logic that the player uses intuitively: if the game always refers to
two objects by the same name, they're interchangeable.

<p>Another advantage of the new scheme is that it's much more
customizable than the old scheme.  Since the basis of the equivalence
decision is now distinguished as a separate property (equivalenceKey),
you can control equivalence groups simply by overriding the property.
You could even effectively restore the old scheme by defining
equivalenceKey as getSuperclassList() - this would make the immediate
superclass list of an object the basis of its equivalence grouping,
producing the same behavior as in the past.

<p>Note that if you change an object's equivalenceKey dynamically
during play - or if you change its underlying disambigName property -
the object's listing group <b>won't</b> be automatically updated.  If
you do make such a change and you want to update the object's listing
group, just call initializeEquivalent() on the object.  (Under the old
scheme, there was really no way to change an object's grouping - even
if you changed its name, it was still grouped based on its class,
which could have caused strange results in listings.  The new scheme
at least allows for this kind of change, although it requires this
manual step to keep the list grouping settings in sync.)

</div>

<!------------------->
<div class=entry>

In the past, when EXAMINE was applied to a Room, the Room simply
turned the command into a nested LOOK AROUND command.  This has
changed slightly.  Now, the Room directly does the work that LOOK
AROUND would do, without the nested command, and with the difference
that the initial line with the room name in boldface isn't included in
the output.  (This is accomplished by omitting the LookRoomName flag
from the 'verbose' flags for the Actor.lookAround() call.)

<p>There are two reasons for this change.  First, when the player
explicitly types EXAMINE <i>room name</i>, it's somewhat redundant to
include the room name in the output.  Second, when the player types
EXAMINE ALL or EXAMINE <i>list of things</i>, the standard
multi-object-command output format already prefaces the results for
each item in the list with the name of the item ("kitchen:"), which
made the room name line especially redundant in this case.

</div>

<!------------------->
<div class=entry>

An object can now be associated with more than one CollectiveGroup.
This allows an object to be a member of multiple disjoint groups.
For example, you could create a group for "treasure," and a group
for "jewelry," and put some objects in both groups, while leaving
others in one group or the other.

<p>To define multiple CollectiveGroups for a given object, use the new
property 'collectiveGroups' on the objects that you want to associate
with the groups.  Set this property to a list with the CollectiveGroup
objects to associate with the given object.

<p>You can still use the single-valued 'collectiveGroup' property, so
existing game code will continue to work unchanged.  However,
'collectiveGroup' is now obsolescent, so you should not use it for new
code - use 'collectiveGroups' instead.  For compatibility with
existing code, the library's default definition of
Thing.collectiveGroups is a method that returns an empty list if
collectiveGroup is nil, or a one-element list containing the
collectiveGroup value if the value is not nil.  Since this is slightly
ineffecient, support for the old 'collectiveGroup' will probably
eventually be removed, at which point the default for
'collectiveGroups' will simply be an empty list.

</div>

<!------------------->
<div class=entry>

Several new classes bring functionality parallel to
RestrictedContainer to surfaces, undersides, and rear containers and
surfaces.  The new classes are RestrictedSurface, RestrictedUnderside,
RestrictedRearContainer, and RestrictedRearSurface.  These new classes
(along with RestrictedContainer itself) are all based on the new
mix-in class RestrictedHolder, which defines generic containment
restriction rules that can be applied to any container subtype.

<p>The new classes work just like RestrictedContainer did, and
RestrictedContainer itself hasn't changed its behavior (it's been
refactored slightly for the new base class, but this is just an
internal change that shouldn't affect any existing code).  To
accommodate the new types of restriction, suitable new library "player
action" messages have been added (cannotPutOnRestrictedMsg,
cannotPutUnderRestrictedMsg, cannotPutBehindRestrictedMsg).

</div>

<!------------------->
<div class=entry>

In the past, the default Search action handling was the same as for
LookIn.  Now, the Search handling is slightly different for Container
and Openable.

<p>First, Openable adds an objOpen precondition for Search if the
actor isn't inside the object; for LookIn, this is skipped if the
object is transparent.

<p>Second, in the Search check() method, Container requires that the
object be openable or transparent to the "touch" sense, or that the
actor is inside the container.  LookIn is similar, but only requires
that the container to be non-opaque in the <b>"sight"</b> sense.

<p>The reason for these changes is that Search implies a more thorough,
physical examination than LookIn does.  To most people, an explicit
search involves physically poking through an object's contents, while
"look in" is more passive, implying just having a look inside.

</div>

<!------------------->
<div class=entry>

In the past, the Thing handlers for PUT UNDER and PUT BEHIND included
touchObj preconditions on the direct object instead of objHeld
preconditions.  These have been changed to objHeld conditions; since
these verbs generally require physically moving the direct object, the
correct precondition is that the direct object be held, just as for
the other PUT verbs.

</div>

<!------------------->
<div class=entry>

A new Action method, getEnteredVerbPhrase(), returns the action's
original verb phrase text as typed by the player.  The return value is
a string giving the verb phrase in a canonical format: specifically,
the result is all in lower-case, and each noun phrase in the player's
input is replaced by a placeholder token: '(dobj)' for the direct
object, '(iobj)' for the indirect object, '(topic)' for a topic
phrase, and '(literal)' for a literal text phrase.  Only the verb
phrase is included in the result - there's no target actor phrase, and
no sentence-ending punctuation included.  The noun phrase replacements
apply to the <i>entire</i> noun phrases, so the single placeholder
'(dobj)' could represent an entire list of direct objects.  For
example, if the player types "BOB, PUT THE BOOK AND PENCIL IN THE BOX
AND GIVE IT TO ME", calling getEnteredVerbPhrase() on the PutIn action
would yield 'put (dobj) in (iobj)', and calling the method on the
GiveTo would yield 'give (dobj) to (iobj)'.

<p>There are two reasons why the method returns the canonical format
rather than the full text of the entire command.  First, the full text
is already readily available, via gAction.getOrigText(), so there's no
need for a new method to retrieve this information.  Second, and more
importantly, the canonical format isoaltes the verb phrase structure
of the player's input, independently of any noun phrases, making it
easy to determine exactly which verb phrasing the player actually used.

<p>This method is most useful in cases where the library's verb rules
define two or more different phrasings for the same Action, and you
need to be able to distinguish exactly which variant the player
entered.  For the most part, this is unnecessary: when the library's
verb rules include synonyms, it's because the different phrasings
usually have exactly the same abstract meaning, hence it's enough to
know which Action matched the grammar.  In some cases, though, a
particular verb applied to a particular object has an idiomatic
meaning different from the usual meaning for other objects, and in
those cases the generic synonyms often fail to be idiomatic synonyms.

<p>For example, the library defines "get (dobj)" and "take (dobj)" as
synonyms for the Take action, because GET and TAKE can almost always
be used interchangeably.  However, if you were defining an "aspirin"
object, you might want to treat the command "take aspirin" as meaning
"eat aspirin," but you would still want "get aspirin" to mean "pick up
aspirin."  You could handle this by overriding the dobjFor(Take)
action() method on the aspirin object, comparing
gAction.getEnteredVerbPhrase() to 'take (dobj)', and calling
replaceAction(Eat, self) if it's a match.

</div>

<!------------------->
<div class=entry>

The new Action method getPredicate() returns the verb phrase match
tree object that the parser resolved to the Action.  The English
library uses Action objects as predicate match tree objects, so in the
English version this simply yields the original Action.  However,
non-English libraries can use separate objects for verb phrase match
tree objects, so if you need any information from the verb phrase's
grammar tree (for example, if you need to call getOrigText() or
getOrigTokenList()), you should use action.getPredicate() rather than
using the action object directly.  (This does <b>not</b> apply to the
new method getEnteredVerbPhrase() above - that method is explicitly
defined on the Action, not the grammar object.  getEnteredVerbPhrase()
itself calls getPredicate() to get the grammar information, so you can
simply call getEnteredVerbPhrase() directly on the Action object.)

</div>

<!------------------->
<div class=entry>

The library looks to a new global variable, gLibMessages, to determine
which object to use as the "library message" source.  (This is the
object used for messages that don't logically relate to the current
actor; generally, these messages are replies to meta-commands, or text
fragments used to construct descriptions.)

<p>In the past, the library simply used the libMessages object
directly as the source of these messages.  Now, the library instead
uses the current value of gLibMessages as the message source.  The
default value of gLibMessages is libMessages, and the library never
changes this value itself, so the default behavior is exactly the same
as before.

<p>The purpose of this change is to allow a game to switch to a new
set of library messages dynamically during play.  For example, if your
game is structured into chapters with different points of view, you
might want to use a distinctive writing styles for the different
chapters, in which case you'd want to change all of the library
messages at each chapter transition.  To do this, simply set
gLibMessages to refer to a new object at each point when you want to
switch message sources; subsequent messages will come from your new
source object.  Note that it's not necessary to do this if you only
want to customize messages statically (i.e., throughout the entire
game); for that, you can just 'modify libMessages'.

</div>

<!------------------->
<div class=entry>

In the past, the Floor class replied to THROW <i>object</i> AT FLOOR
with the same default message ("you should just put it down instead")
in all cases.  This reply is no longer used in cases where the Floor
is unreachable; instead, the standard THROW handling applies, since
the player couldn't accomplish the same thing with DROP.

</div>

<!------------------->
<div class=entry>

RoomPart.getHitFallDestination() will now take into account any
explicit 'location' setting in the RoomPart when determining the
destination.  In the past, an explicit 'location' setting was ignored,
and a valid destination could only be found if the RoomPart was in the
same top-level room as the actor.  Now, if the RoomPart has an
explicit non-nil location setting, that takes precedence in
determining the destination.  This is useful when creating connected
top-level locations with room parts that you want capable of serving
as THROW targets.

</div>

<!------------------->
<div class=entry>

When throwing an object at a target, and the target happens also to be
the place where the object is described as landing when thrown at that
target (i.e., the target is the nominal drop destination of its own
the "hit-fall" destination), a new default message is used, of the
form "The projectile lands on the target."  In the past, the message
was the awkward "The projectile hits the target without any obvious
effect, and falls to the target."  This was most likely to occur when
the target was something like a floor or ground object, since that's
the only case where the target is likely to also be the nominal drop
destination.  This change is in the routine
DropTypeThrow.standardReport().

</div>

<!------------------->
<div class=entry>

GIVE TO, SHOW TO, and THROW TO now use different messages depending on
whether the indirect object is an actor or an inanimate object.  For
ordinary Things, the message is now of the form "You can't give
anything to X"; for Actors, the message is "The X does not appear
interested."  In the past, the latter message was used for all
objects, animate or not.  Imputing "interest" to an inanimate object
could be read as either intentionally snide (as though the library
were sarcastically calling the player dense for trying such an
obviously stupid thing) or simply wrong (as though the library didn't
know the difference); since msg_neu is supposed to affect a neutral
narrative tone, neither alternative is desirable.

<p>In addition, showing or giving an Actor to itself is now handled
with a separate message ("Showing X to itself would accomplishing
nothing").

</div>

<!------------------->
<div class=entry>

REMOVE <i>dobj</i> now uses a separate reply if the object is already
being held: "There's nothing to remove the X from."  In the past, the
command was unconditionally turned into TAKE <i>dobj</i>, which showed
"(from you)" as the implied indirect object part, which was a bit
awkward.

</div>

<!------------------->
<div class=entry>

When the THROW <i>direction</i> command is used with a nonportable
object (as in THROW DESK EAST), the result is now the same as for
commands like MOVE and PUSH: "The desk cannot be moved."

</div>

<!------------------->
<div class=entry>

The default response for THROW DOWN has been changed to use the same
message as for DROP when applied to an object that's not currently
being held: "You're not carrying that."

</div>

<!------------------->
<div class=entry>

In statusLine.beginStatusLine(), in the StatusModeApi case, there was
some leftover old code ("&lt;body bgcolor=statusbg text=statustext&gt;")
right after the call to setColorScheme() that effectively undid the
color settings made in setColorScheme().  The old code has been deleted.

</div>

<!------------------->
<div class=entry>

The library now uses the same default message in response to a command
to throw the player character in a direction (as in THROW ME EAST) as
it does as for THROW ME AT <i>something</i>.

</div>

<!------------------->
<div class=entry>

A new Thing method, adjustThrowDestination(), gives a prospective
landing site for a thrown object a chance to redirect the landing to
another object.  getHitFallDestination() now treats the result it
calculates using getDropDestination() as tentative, and calls this new
method on the tentative result object to determine the actual
destination.  The default implementation of the new method in Thing
simply returns 'self', which confirms the tentative destination as the
actual destination.  BulkLimiter overrides the new method to redirect
the landing site to the BulkLimiter's location's drop destination if
the thrown object would overflow the BulkLimiter's capacity.

<p>This change corrects a problem that occurred when a thrown object
landed in a BulkLimiter that was already near capacity.  In the past,
the BulkLimiter applied its capacity control by effectively blocking
the THROW before it happened.  With the change, the THROW will be
allowed to proceed, and the thrown object will land in the nearest
suitable container of the original target.

<p>Note that any game code that overrides getHitFallDestination()
should be sure to call adjustThrowDestination() on its tentative
return value.  Games usually won't have any reason to override
getHitFallDestination(), so this change shouldn't affect most existing
code.


</div>

<!------------------->
<div class=entry>

In ActorState, the beforeTravel() method no longer ends the current
conversation if the actor is merely moving between nested locations
within the same top-level location.  These aren't usually true
departures that should trigger conversation termination, so the method
no longer treats them as such.

</div>

<!------------------->
<div class=entry>

A new travel connector class, DeadEndConnector, can be used for
situations where travel through the connector is impossible, but for
reasons that can only be learned by attempting to go through the
connector.  For example, this can be used for a passage that turns out
to be blocked by a cave-in that isn't visible from the passage
entrance, or in a situation where you describe the actor as wandering
around in a direction for a while but giving up and returning to the
point of origin.

<p>DeadEndConnector supplements FakeConnector, which is most useful
for exits that look like connections but can't be traversed for
reasons that are apparent before the travel is ever physically
attempted - in particular, for motivational reasons ("You can't leave
town without finding your missing brother").  DeadEndConnector differs
from FakeConnector in that DeadEndConnector acts as though the
physical travel were actually occurring.  It fires all of the normal
travel notifications, so any side effects that would occur on ordinary
travel will also occur with a DeadEndConnector.

</div>

<!------------------->
<div class=entry>

"Push travel" has been changed slightly to handle situations where the
object being pushed has side effects that affect the description of
the destination location.  The most common situation where this arises
is when the object being pushed is (or contains) a light source, but
it could happen in many other custom-coded situations.

<p>In the past, the object being pushed wasn't moved to its new
location until after the new location had been described.  The point
of this sequencing was to exclude the pushed object from the new
location's description, simply by keeping it out of the new location
until after the description was displayed.  This exclusion is
desirable because it would otherwise look as though the pushed object
were already in the new location on the player character's arrival,
which would be confusing.  However, it prevented any side effects of
the pushed object's presence from being taken into account in the new
location's description.  If the pushed object was a light source, for
example, and the new location was otherwise unlit, the new location
was described as dark.

<p>Now, the library tentatively moves the pushable object to the
destination of the travel, and marks the object (via the new
Actor.excludeFromLookAround mechanism) for exclusion from the location
description.  It then moves the actor and shows the description of the
new location.  Finally, it moves the pushable back to the origin
location, and then moves a second time, this time for real, to the
destination location.

<p>(The reason for moving the pushable twice - first tentatively,
before the travel, then again "for real," after the travel - is that
the method that makes the final move is overridable and so might
actually do something other than move the pushable to the travel
destination.  Even if it leaves the object unmoved, though, or moves
it to a different final destination, the tentative first move is still
a valid intermediate step.  At the point we're generating the
description of the new room, the player character is <i>in the
process</i> of pushing the pushable into the new room - the PC is
notionally walking along with the pushable at that stage.  If the
overridable final-move method wants to do something different, it can
do so; it will simply have to describe the change, which it had to do
in the past anyway.  At that point, the PC will already be in the new
location, and so will in fact have pushed the pushable this far;
anything that happens in the overridable method happens <i>after</i>
the intermediate stage where we generated the description, so any side
effects of the pushable's tentative presence were valid at that point,
no matter what happens afterwards.)

</div>

<!------------------->
<div class=entry>

In the English library, the Push-Travel commands (PUSH X NORTH, PUSH X
UP RAMP, etc) now only accept single direct objects.  In the past, the
grammar phrasings allowed direct object lists, but actually pushing
multiple objects into a new room is a practical impossibility, so
there's no point in accepting it in the grammar.

</div>

<!------------------->
<div class=entry>

The mechanism for describing "local" NPC travel has been enhanced.
Local NPC travel is travel where an NPC moves from one top-level
location to another, and both top-level locations are in view of the
PC.  In these cases, special handling is needed because the NPC isn't
truly arriving or departing in the usual sense; the NPC is instead
moving closer to, further away from, or laterally with respect to, the
PC.

<p>In the past, the local NPC travel mechanism did everything via the
"local arrival" message: the NPC generated only this one special
message at the destination end of the travel.  The new mechanism adds
two messages analogous to the local arrival message: a "local
departure" message and a "remote travel" message.  Here's how they're
used:

<ul>

<li>If the PC is moving <i>closer</i> to the PC, the <b>local
arrival</b> message is displayed at the destination end of the travel.
"Closer" means that the NPC is moving from a top-level location that
<i>doesn't</i> contain the PC to a top-level location that does
contain the PC.

<li>If the PC is moving <i>further away</i> from the PC, the <b>local
departure</b> message is displayed at the origin end of the travel.
"Further away" means that the NPC is moving from the top-level
location that contains the PC to a different top-level location that
doesn't.

<li>If the PC is moving <i>laterally</i>, the <b>remote travel</b>
message is displayed at the destination end of the travel.
"Laterally" means that the NPC is moving between two top-level
locations, neither of which contain the PC.  Note that there's no good
basis for preferring to show the message on the origin or destination
side of the travel in this case, since the generic situation is so
symmetrical, but at the same time it's necessary to choose one or the
other because we don't want two messages for this kind of travel.  So,
we have to make an arbitrary choice, and the library chooses to show
the message on the destination side.

</ul>

<p>These new rules obviously require some new methods.  Here's the
new arrangement of methods:

<ul>

<li>The local arrival message is embodied in
TravelConnector.describeLocalArrival(), which by default calls
Traveler.sayArrivingLocally(), which by default calls
libMessages.sayArrivingLocally().  Note that these aren't new - this
part of the mechanism carries forward unchanged from past versions.
However, their <i>usage</i> has changed, in that the library in the
past called the local arrival messages in <i>all</i> cases of local
travel, but now calls it only in <i>certain</i> cases, as described
above, and calls the local-departure or remote-travel methods in other
cases that formerly all folded into the local-arrival case.

<li>The local departure message is embodied in
TravelConnector.describeLocalDeparture(), which by default calls
Traveler.sayDepartingLocally(), which by default calls
libMessages.sayDepartingLocally().  These methods are new.

<li>The remote travel message is embodied in
TravelConnector.describeRemoteTravel(), which by default calls
Traveler.sayTravelingRemotely(), which by default calls
libMessages.sayTravelingRemotely().  These methods are new.

</ul>

<li>Existing code should continue to work correctly with the new
framework, although with one caveat: if you customized a
describeLocalArrival() or sayArrivingLocally() method, you might want
to add corresponding customizations for the new local-departure and/or
remote-travel methods.  If you don't, your local-arrival customization
will still work in the cases where it applies under the new rules, but
it won't be invoked in all the cases it was in the past.

</div>

<!------------------->
<div class=entry>

AccompanyingInTravelState now describes local travel using its
standard departure message.  This ensures that the correct messages
are displayed when accompanying an actor in local travel or travel
between two connected top-level locations (such as locations linked by
distance).

</div>

<!------------------->
<div class=entry>

TravelAction.actionOfKind(cls) now properly handles the case where
'cls' is the base TravelAction class.  (In the past, asking about
TravelAction itself caused a run-time error.)

</div>

<!------------------->
<div class=entry>

The various SettingsItem objects defined in the library are now all
named objects.  In the past, some of these (such as
gameMain.verboseMode) were defined as embedded objects; this made it
more difficult to modify their behavior, since it wasn't possible to
use 'modify' to alter the objects directly.  The behavior should be
exactly the same as in the past; the only difference is that the
objects are now easier to customize.

</div>

<!------------------->
<div class=entry>

The putDestMessage that was defined in defaultFloor and defaultGround
has been moved to the base Floor class instead - this message should
be common to most floor/ground type objects, not just for the default
ones in the library.

</div>

<!------------------->
<div class=entry>

The method standing.tryMakingPosture(loc) now generates the command
STAND ON <i>loc</i>, rather than simply STAND as it did in the past.
This makes the behavior consistent with the sitting and lying postures.

</div>

<!------------------->
<div class=entry>

Room can now be used as the direct object of STAND ON, SIT ON, and LIE
ON.  These are handled simply by remapping the commands to the room's
"floor" object (specifically, the object returned from the room's
roomFloor method).  This is in part to accommodate the change above to
standing.tryMakingPosture(), and in part to provide better automatic
handling for player commands like SIT IN YARD.

</div>

<!------------------->
<div class=entry>

RoomPart now applies some additional disambiguation filtering in cases
where two or more top-level locations are linked by a sense connector.
When a resolve list contains multiple RoomPart objects, and some of
those RoomParts are local and some remote, RoomPart will reduce the
list to include only the local RoomParts.  (A "local" object is one
within the same top-level location as the actor; a "remote" object is
one that's in a separate top-level location that's linked by a sense
connector.)

</div>

<!------------------->
<div class=entry>

If a RoomPart has an explicit 'location' setting, that location will
no longer add the RoomPart redundantly to the location's 'contents'
list.  In the past, the RoomPart would show up twice in the contents
list, because it was added once by virtue of being in the RoomParts
list, and again by virtue of its 'location' setting.

<p>In addition, when a RoomPart has an explicit 'location' setting, it
will now automatically add itself to that location's 'roomParts' list.
This means that you don't have to manually set both properties, which
saves a little work and also makes your game easier to maintain, since
you won't have to remember to make coordinated changes to both
settings in your source code if you change the room part later.

</div>

<!------------------->
<div class=entry>

RoomPart and TravelConnectorLink now have a default sightSize of
'large'.  This means that it's possible to examine these objects at a
distance.  Room parts are things like walls and ceilings that tend to
be large and to contain large-scale details that would be
realistically discernible at a distance - the details are typically
things like doors and windows.  Similarly, TravelConnectorLink (which
you'd mainly use via its subclasses Enterable and Exitable) is for
things like building exteriors, which likewise tend to have
large-scale details.

<p>In cases where you create a RoomPart or an Enterable or Exitable
that has fine-grained details that would be too small to see at a
distance, <i>and</i> the object is visible from a separate top-level
location linked by distance, you might want to override this to set
the sightSize back to medium.  When there's no distance-linked
top-level location, this shouldn't be an issue, since there'd be no
way to examine the object from a distance to begin with.

</div>

<!------------------->
<div class=entry>

RoomPartItem now overrides useSpecialDescInRoom() and
useSpecialDescInContents() to return nil, and no longer overrides
useSpecialDesc and useInitSpecialDesc.

<p>In the past, RoomPartItem overrode useSpecialDesc and
useInitSpecialDesc (setting them to nil) in order to prevent room part
items from being included in LOOK descriptions, but this had the bad
side effect of preventing showSpecialDesc() from showing the
initSpecialDesc.  This change uses the more precise methods to select
exactly where the special desc should be shown, without affecting the
selection of which special desc to show.

</div>

<!------------------->
<div class=entry>

Thing.isListedInContents now calls useSpecialDescInContents(location)
to make its determination.  In the past, it called useSpecialDesc
directly; this was incorrect because it didn't properly take into
account the differentiation among contexts that the various
useSpecialDescInXxx methods provide.

</div>

<!------------------->
<div class=entry>

The exit-list generator (exitLister.showExitsWithLister) now considers
two destination locations to be equivalent based on the destination
room object rather than the destination room name.  This means that
two distinct exit locations will now be listed separately even if they
have the same name.  For example, in the past, if the east and west
exits led to separate rooms that both happened to be named "the
hallway," the listing formerly read "east (or west), to the hallway",
but will now read "east, to the hallway; west, to the hallway".  The
old approach of merging list entries based on name alone produced odd
results in some cases, and didn't have any obvious benefits; the new
approach should produce more predictable results.

</div>

<!------------------->
<div class=entry>

TIAction has a new method, retryWithAmbiguousIobj(), that lets an
action handler specifically ask for disambiguation from a list of
possibilities.  This is the TIAction equivalent of the TAction method
retryWithAmbiguousDobj(), and works the same way; the only difference
is that the disambiguation list applies to the indirect object rather
than to the direct object.

</div>

<!------------------->
<div class=entry>

The TAction and TIAction methods retryWithAmbiguousDobj() and
retryWithAmbiguousIobj() can now be called before the "iteration"
phase of the command execution, specifically during
Action.beforeActionMain(), and they'll work properly: they'll ask
their disambiguation question, then apply it to the entire iteration
for the other object list.  For example, if you call
retryWithAmbiguousIobj() during beforeActionMain() to prompt for a new
indirect object for a PUT IN command, the player's response will
automatically be applied to the whole direct object list if the player
specified multiple direct objects.  In the past, it wasn't possible to
call these "retry" methods during beforeActionMain(), so if they were
used during commands with multiple objects in the other object slot,
the result was that the "retry" - and its question to the user - was
repeated for each object in the list.

<p>(This new flexibility involves two supporting changes.  First, the
various initForMissingXxx() methods in various Action subclasses now
detect that the iteration over the object list hasn't begun yet, and
they simply retain the entire object list (rather than the current
iteration item, as they did in the past) for the retry.  Second, to
support the first change, the class PreResolvedAmbigProd now accepts
an entire object list instead of just a single iteration element.
These are internal methods that game code is unlikely to call
directly, so the only visible effect of these changes should be the
new flexibility in how the "retry" methods can be used.)

</div>

<!------------------->
<div class=entry>

In the past, initializeThing() was sometimes called multiple times in
the course of dynamically creating an object (with 'new').  This
happened when creating objects based on classes that inherited from
Thing more than once (classes like this include Flashlight, Passage,
Room, Chair, Bed, Platform, NominalPlatform, Booth, and
UntakeableActor).  This happened because the default constructor for
any object based on multiple base classes simply inherits each of the
base class constructors, one after the other; when more than one base
class itself inherits from Thing, this results in multiple inherited
invocations of the Thing constructor, which in the past resulted in
multiple invocations of initializeThing() for the new object.

<p>Now, initializeThing() is only called once.  The Thing constructor
now tests a flag before calling initializeThing; it only calls the
method if the flag isn't set, and it sets the flag after calling the
method.  This ensures that subsequent inherited constructor calls
simply skip the call to initializeThing().  The constructor also skips
the call to its own inherited base class constructor when the flag is
set; this ensures that the vocabulary initializations in VocabObject
are only invoked once per object.

</div>

<!------------------->
<div class=entry>

Room has a few command-handling enhancements, for rooms that have
associated vocabulary.  LOOK IN <i>room</i> is now treated the same as
EXAMINE <i>room</i>; LOOK UNDER and LOOK BEHIND are refused ("You
can't look under that"); SMELL and LISTEN TO <i>room</i> are now
equivalent to simply SMELL and LISTEN; BOARD and ENTER are treated as
redundant ("You're already in that"); and GET OUT OF is a little
smarter about remapping, so that it only remaps to GO OUT if there
actually is an OUT direction defined for the room, and fails with an
error if not ("You'll have to say which way to go").

</div>

<!------------------->
<div class=entry>

NestedRoom.makeStandingUp() now leaves the actor's posture unchanged
if the travel to the new location fails.  It does this by noting the
original posture before the travel attempt, and checking after the
travel attempt to see if the actor is still in the starting nested
room; if so, the routine restores the saved posture.  This ensures
that a failed travel attempt won't cause a posture change in the
original nested location.

</div>

<!------------------->
<div class=entry>

NominalPlatform now overrides hideFromDefault() to always return true.
Nominal platforms are meant to be used as internal objects and not to
appear as simulation objects, so it's generally not desirable for them
to be used as defaults.

</div>

<!------------------->
<div class=entry>

AccompanyingState had a problem that caused infinite recursion
(leading to a stack overflow) when an actor in an AccompanyingState
was explicitly moved via scriptedTravelTo().  The problem was simply
that the actor attempted to accompany itself on its own travel, and
that accompanying travel triggered a further accompanying travel, and
so on.  This has been corrected: actors in accompanying travel states
now explicitly ignore their own travel for the purposes of
accompanying travel.

</div>

<!------------------->
<div class=entry>

The library uses a separate default message in cases where an Actor is
holding an object used in ENTER, BOARD, SIT ON, etc.  In the past, the
message was the rather awkward "You can't do that while the chair in
in Bob."  The new message is phrased "...while Bob is holding the
chair" instead.  The default message for non-Actors is unchanged.

</div>

<!------------------->
<div class=entry>

FOLLOW caused a run-time error if the follower was holding the
NPC to be followed.  This was because effectiveFollowLocation
wasn't defined for ordinary objects.  This has been corrected
by defining Thing.effectiveFollowLocation to return the location's
effectiveFollowLocation, or just 'self' if the object has no
location.

</div>

<!------------------->
<div class=entry>

<a name='ImpByeTopicSubclasses'></a>

There are two new subclasses of ImpByeTopic, to allow you to
differentiate between the two implicit ways of ending a conversation.
BoredByeTopic handles cases where the NPC ends the conversation
because of "boredom" (that is, inactivity in the conversation that
exceeds the NPC's attentionSpan setting), while LeaveByeTopic handles
cases where the PC simply walks away from the NPC in mid-conversation.

<p>BoredByeTopic and LeaveByeTopic extend the hierarchy that already
existed with ByeTopic and ImpByeTopic.  If there's an active
ImpByeTopic and no active BoredByeTopic or LeaveByeTopic objects at
the time of an implied "goodbye", the ImpByeTopic will be used for
both cases (this also happens to be exactly the way the library worked
in the past, before the two new subclasses were added, so this change
won't disturb existing code).  If there's an active BoredByeTopic as
well as an active ImpByeTopic, the BoredByeTopic will be selected over
the ImpByeTopic to handle "boredom" goodbyes; likewise, if there's an
active LeaveByeTopic, it will be selected over an active ImpByeTopic
to handle goodbyes triggered by the PC's departure.

</div>

<!------------------->
<div class=entry>

The "boredom" mechanism in InConversationState has been changed
slightly.  In the past, it was implemented directly in the takeTurn()
method of InConversationState.  Now, it's handled with an AgendaItem
instead - specifically, a new subclass called BoredomAgendaItem, which
the Actor and InConversationState classes manage automatically.  This
change should have no effect on existing code, since the new code
implements the same behavior as the old version.  The benefit of this
change is that it makes it easier for a game to customize the boredom
behavior, since it's now part of the more general "agenda" mechanism
instead of being buried in ad hoc code inside the conversation state
class.

</div>

<!------------------->
<div class=entry>

The suggested topic lister had a problem that showed up when several
topic suggestions were present with the same listing name, and some of
the topics were inactive while others were active.  The lister
automatically removes redundant entries from suggestion lists by
removing multiple items with the same name, but in the past, the
lister sometimes incorrectly removed the <i>active</i> elements
instead of the inactive ones, effectively eliminating the suggestion
entirely from the list.  This has been corrected: the lister now only
removes a redundant suggestion if there's another <i>active</i>
suggestion with the same listing name.

</div>

<!------------------->
<div class=entry>

InitiateTopic no longer sets any pronoun antecedents when triggered.
(It did set its match object as a pronoun antecedent in the past.
This was undesirable because an InitiateTopic is triggered by internal
calculations in the game, not by anything the player has done.)

</div>

<!------------------->
<div class=entry>

ConvAgendaItem now checks to make sure the player character is present
before declaring itself ready.  This ensures that an NPC won't attempt
a conversational agenda item unless the PC is actually present to hear
what the NPC has to say.  (This change is in ConvAgendaItem.isReady.)

</div>

<!------------------->
<div class=entry>

Actor.executeAgenda() formerly marked an agenda item as done if
invoking the item threw any sort of exception.  Now, this is only done
on a run-time error (a RuntimeError exception); in cases of other
exceptions, the item's doneness isn't changed.  The original purpose
of the doneness change was to reduce debugging hassles in cases where
an agenda item encountered an error; in such cases, if the item wasn't
marked as done, the scheduler would end up invoking the item in an
infinite loop, because it would look perpetually ready to run.
However, doing this on <i>all</i> exceptions interfered with certain
non-error cases where exceptions were used to jump out of the action
handling.  Limiting the caught exceptions to runtime errors should
retain most of the intended benefits while avoiding the problems with
a more general error catcher here.

</div>

<!------------------->
<div class=entry>

Actor.initiateConversation() now handles a nil 'state' argument
slightly differently.  In the past, if 'state' was nil, the actor's
state was simply left unchanged.  Now, the method will switch the
actor to the state returned from the current state's
getImpliedConvState() method.  In most cases, the net effect is
exactly as before - i.e., the actor's state is left unchanged -
because the default getImpliedConvState() simply returns 'self'.
However, ConversationReadyState overrides getImpliedConvState() to
return the associated InConversationState.  This change makes it
easier to initiate a conversation when using an actor with
conversational states, since it will generally pick the correct
conversational state automatically.

<p>Note that the ActorState method getImpliedConvState() is new with
this change.

</div>

<!------------------->
<div class=entry>

Due to a bug, &lt;.convnode&gt; tags displayed inside npcGreetingMsg
methods weren't handled properly if the greeting was displayed due to
NPC initiation of the conversation (via npcInitiateConversation()).
This has been corrected.

</div>

<!------------------->
<div class=entry>

ConvNode.canEndConversation() can now return a special value,
blockEndConv, that indicates that the actor said something to force
the conversation to keep going.  You should always use this if you
display a message in the routine <i>and</i> you want to prevent the
conversation from ending.  Returning blockEndConv is <i>almost</i> the
same as returning nil from the method, but has the additional side
effect that the caller will call noteConvAction() on the other actor,
to prevent this actor from generating any further scripted remarks on
the same turn.

</div>

<!------------------->
<div class=entry>

When the library displays a parser error message for a command
directed to an NPC, it now shows the error message in a neutral sense
context.  This ensures that the message is displayed even if the NPC
is in a remote location (this could be the case if we're talking over
the phone, for example).  In the past, the parser message was
generated in the NPC's sense context, so the NPC was in a remote
location that wasn't in scope to the PC, the parser message was
suppressed, resulting in a "Nothing happens" message or the like.

</div>

<!------------------->
<div class=entry>

When a command of the form "actor, xxx" is entered, and the portion
after the "actor" phrase is unparseable, the parser now attempts to
parse at least the "actor" part to determine if the command is being
directed to an NPC.  In the past, the parser didn't do this; the actor
phrase is part of the basic sentence grammar, so if the parser failed
to match the rest of the basic sentence grammar, it didn't bother
trying to figure out if a target actor was included.  To find the
target actor, the parser now makes a second attempt at parsing a
command to see if it matches a very basic sentence syntax that only
includes the target actor specification; if it can match the syntax,
and resolve the noun phrase to an in-scope actor, the parser takes
the result to be the target actor.

<p>The main result of this change is that a few of the low-level
parser message methods - askUnknownWord, specialTopicInactive,
commandNotUnderstood - are now invoked on the target actor when one is
present in the command.  In the past, because the parser didn't even
figure out that a target actor was present in these cases, these
methods were always invoked on the player character actor.  With this
change, it's now possible to customize a NPC's responses for unknown
words and command phrasings individually by NPC.

</div>

<!------------------->
<div class=entry>

The library now gives a replacement action zero time if it's replacing
an action that itself has zero time.  This corrects some timing
anomalies (particularly with respect to NPCs) that showed up in
certain unusual cases where replaceAction() was used in the course
of an action that itself was being run as a nested action.

</div>

<!------------------->
<div class=entry>

A new parser option lets you cancel remaining commands on the command
line when an action fails.

<p>To implement this, Action.afterActionMain() checks to see if the
action failed, as indicated by a 'reportFailure()' message in the
course of the action handling.  If the action failed, <i>and</i>
gameMain.cancelCmdLineOnFailure is set to true, afterActionMain()
throws a CancelCommandLineException.  This exception is in turn caught
in executeCommand(), which cancels any remaining commands on the
command line and simply proceeds to the next turn.

<p>In addition, the new playerMessages method
explainCancelCommandLine() lets you display an explanation when a
command line is canceled due to the failure of a command.
executeCommand() invokes this new method when it handles a
CancelCommandLineException if there are in fact any remaining tokens
on the command line.  (This check for remaining tokens skips the
explanation when there's nothing left on the command line to cancel,
as the cancellation obviously has no effect in such cases.)  This new
message method doesn't display anything by default; it's just a hook
that you can use if you want to provide an explanation.  Note that
you'll probably want to show this explanation only once per game,
rather than every time a command is canceled (you can use a flag
property to do this - if the flag is nil, show the message and set the
flag to true; otherwise skip the message).

<p>The default setting for gameMain.cancelCmdLineOnFailure is nil.
This provides the traditional handling, which simply continues executing
any remaining commands on the command line even when an action fails.

<p>The reason this new feature is an option rather than simply being
the default new policy is that neither possibility is ideal in every
case.  On the one hand, continuing to execute commands after an action
has failed can lead to confusing results: the failure of the earlier
command can leave things in a state other than what the player was
anticipating, which could change the behavior of subsequent commands.
So the argument in favor of canceling remaining commands is that it
avoids this possible source of player confusion by halting processing
once it appears that the player's thinking is out of sync with the
game's internal state.  On the other hand, exactly what constitutes
failure might not always be apparent to the player, so halting halfway
through a command line might sometimes appear arbitrary to the player,
or even buggy.  The argument in favor of continuing to plow through
the rest of the command line like nothing happened, then, is that it's
simple and consistent.  A prime virtue of any UI is predictability, so
that the user has an easier time forming a working mental model of the
software, and the most predictable behavior is to unconditionally
execute everything on the command line.  Further, given that
multi-level UNDO is available by default in tads3 games, any
unintended effects from extra commands can always be manually undone
as soon as the player realizes what happened.  The arguments on both
sides are valid, so the library leaves it up to the author to set the
game's policy.  (It's even been suggested that this ought to be left
up to the player, via a command that selects the mode, but I think
this would be overkill, so for now this is just an author-controlled
option.  Games are free to add their own command to let the player
control it, of course; it's just a matter of flipping the
cancelCmdLineOnFailure setting at run-time.)

</div>

<!------------------->
<div class=entry>

The Action class has a new method, checkAction(), that is called just
before the existing execAction() method.  TAction and TIAction define
the new method, and perform the calls to the direct and indirect
object 'check' methods in this new method rather than in execAction(),
as was done in the past.

<p>This change should have no effect on existing code, since it's a
simple internal rearrangement.  The benefit is that it's now possible
for game code to call the 'check' phase of a verb explicitly, without
also invoking the 'execute' phase.

</div>

<!------------------->
<div class=entry>

OopsIAction is now defined as an IAction.  (In the past, it was based
directly on Action, which was problematic if an OopsIAction grammar
match was used in certain contexts, such as
CommandRanking.sortByRanking.)

</div>

<!------------------->
<div class=entry>

ObjectPreCondition now uses the same ordering as the underlying
condition.

</div>

<!------------------->
<div class=entry>

During calls to the "verify" methods for remapped actions (i.e.,
actions mapped to different actions using remapTo), the library now
sets gAction to the remapped action.  In the past, during the initial
remap testing stage, the library left gAction with the original action
that triggered the remapping.  This gives game code more consistent
information during the verify phase.

</div>

<!------------------->
<div class=entry>

VocabObject now defines the methods isOwnedBy(obj) and
getNominalOwner().  This allows player input to refer to non-physical
objects, such as topics, using possessive syntax.

</div>

<!------------------->
<div class=entry>

The INSTRUCTIONS command is now ignored for the purposes of UNDO and
AGAIN.

</div>

<!------------------->
<div class=entry>

The parser no longer chooses Unthings as default objects in cases
where noun phrases are missing in player input.  (This is handled via
Unthing.hideFromDefault().)

</div>

<!------------------->
<div class=entry>

The new Thing method setGlobalParamName() lets you add a global
message parameter name dynamically.  In the past, there was no
straightforward way to do this; you had to manually update the message
builder's internal table of names in order to add a new name.  This
method takes care of all of the necessary internal table updates.

<p>You only need to use this method if you want to add or change a
parameter name dynamically at run-time.  The library still
automatically initializes the message builder's tables for
globalParamName settings defined at compile-time.

</div>

<!------------------->
<div class=entry>

The parser now marks a plural-phrase match for a direct or indirect
object as "unclearly disambiguated" if the phrase also matches a
singular noun for an object that's also in scope.  This flag makes
the parser generate an extra message to notify the player that the
parser chose an object from a potentially ambiguous set:

<p><pre>
  &gt;show bob the rags
  (the piece of cloth)
  Bob does not appear interested.
</pre>

<p>If the parser's decision was wrong, the message will alert the
player, so that the player will know to try rephrasing the command
rather than being left with the impression that the intended command
didn't work.

</div>

<!------------------->
<div class=entry>

The event manager (the part of the library that manages fuses and
daemons) now automatically disables a daemon or fuse that throws an
exception out of its main execution method.  The reason this is
important is that an infinite loop would otherwise occur in many
cases: if the object remained active, the event manager would
re-invoke it after the exception, and in most cases the re-invocation
would simply encounter the same exception, at which point the event
manager would invoke it once again, and so on ad infinitum.

<p>Note that this change only comes into play when a fuse/daemon
throws an exception <b>out</b> of its main method.  It won't affect a
daemon/fuse that merely encounters an exception in the course of its
processing, as long as the fuse/daemon catches and handles the
exception.

</div>

<!------------------->
<div class=entry>

A new class, OneTimePromptDaemon, makes it easy to set up a prompt
daemon that only fires once.  It works like an ordinary prompt daemon,
but removes itself from the active event list as soon as it fires.
This can be handy for cases where you want to defer some non-recurring
processing until just before the next command prompt.

</div>

<!------------------->
<div class=entry>

Thanks to Greg Boettcher, the English library's default messages now
use typographical ("curly") quote marks and apostrophes.  In cases of
open/close quote marks, these are generated with
&lt;Q&gt;...&lt;/Q&gt; markups; in cases of apostrophes, &amp;rsquo;
entities are used.

<p>This change is purely cosmetic, so it should require no changes to
existing game code.  It shouldn't even affect test scripts (where you
run an input script and "diff" the output against a reference log) -
by default, the log file mechanism by default generates transcript
output in plain ASCII, and the curly quotes are mapped to ordinary
straight quotes when rendered in plain ASCII.

</div>

<!------------------->
<div class=entry>

<a name='getInScopeDistinguisher'></a>
The library now attempts to be as precise as possible when announcing
objects chosen in vague disambiguations, as defaults for missing noun
phrases, and for multiple objects to a verb.  In the past, the library
simply used the base name of the object being announced, but this
didn't take into account the various things that the parser can use to
distinguish objects on input, such as lit/unlit state, location, and
owner.  The library now generates these object announcements using the
same Distinguisher mechanism it uses to resolve ambiguous noun phrases
in input, ensuring that the generated names are as precise as possible
in distinguishing announced objects from others in scope.

<p>To accomplish this, the announcements call upon a new Thing method,
getInScopeDistinguisher().  This method looks at the Distinguisher
objects associated with the object to be announced, and tries to find
one that can distinguish the object to be announced from every other
object in scope.  If it finds one, it returns it.  If it fails to find
one, it returns the distinguisher that does the best partial job -
that is, the one that distinguishes the object from the largest number
of other in-scope objects.  (The method never returns nil; in the
worst case, it simply returns basicDistinguisher, which distinguishes
objects based on their disambigName properties.)  The announcements
then use the returned Distinguisher to generate the announced name.

<p>Note that in the simplest case, this change results in the
disambigName being used in object announcements; in the past, the base
name was used.  In most cases, this won't cause any change in game
behavior, since the disambigName for most objects is just the base
name anyway.

</div>

<!------------------->
<div class=entry>

The library now suppresses vague disambiguation announcements for
objects specified with indefinite articles when the announcement
would be redundant.  That is, if there's no Distinguisher that can
tell apart any of the possible matches for an object specified with
an indefinite article, the library doesn't bother making the
announcement, because it would add no useful information for the
player.  For example, in the past, you might have seen an exchange
like this:

<p><pre>
   &gt;take a silver coin
   (the silver coin)
</pre>

<p>The parser was making the announcement because it had chosen
arbitrarily from one of several silver coins.  But since all of the
possible matches were indistinguishable anyway, the announcement
doesn't help the player see which one in particular was chosen.  The
library now suppresses the message in this case.  Note, however, that
if it's possible to distinguish any of the possible matches from one
another, you'll still see a message.  For example, if there's a silver
coin and a gold coin present, and the player types TAKE A COIN, the
library will announce which one (gold or silver).  Similarly, if
there's a silver coin on the table and another on the floor, and the
player types TAKE A SILVER COIN, the library will mention the location
of the one chosen: "(the silver coin on the floor)", for example.

</div>

<!------------------->
<div class=entry>

The English library can now correctly generate a plural name for an
object whose name includes an "of" phrase; for example, the library
now correctly generates the plural for "piece of paper" as "pieces of
paper".  In the past, the library pluralized the last word of the
entire phrase, so the result in this example would have been "piece of
papers".  The new algorithm when there's an "of" is simply to
pluralize the last word before the first "of", using the same rules as
for a phrase without "of".

</div>

<!------------------->
<div class=entry>

In the past, the English parser treated a command of the form GIVE
<i>adjective noun</i> as though it meant GIVE <i>noun</i> TO
<i>adjective</i>.  This was almost never what the player actually
meant; the player almost always really meant GIVE <i>object</i> TO
<i>the current interlocutor</i>, where <i>object</i> is named
<i>adjective noun</i>.  The parser now applies that more likely
interpretation when confronted with this syntax.  The same applies to
SHOW.

<p>(As part of this change, a new parser class was added:
ImpliedActorNounPhraseProd.  This is a subclass of EmptyNounPhraseProd
that works almost the same way, but doesn't apply a grammar ranking
penalty for the missing noun phrase if a default interlocutor can be
identified.  The single-noun-phrase grammars for GIVE and SHOW use
this new class, ensuring that they're chosen over the
non-prepositional two-noun-phrase phrasings whenever a default
interlocutor is present.)

</div>

<!------------------->
<div class=entry>

In the past, the English parser treated the word "of" as a non-weak
token when matching noun phrases of the form "x of y".  This meant
that if a noun phrase consisted only of weak tokens and "of", the
parser matched it.  This has changed; "of" is now ignored for the
purposes of the weak-token test, so a phrase consisting only of weak
tokens and "of" is now considered weak overall.

</div>

<!------------------->
<div class=entry>

A bug in the English library caused run-time errors in some cases
involving TopicAction verbs.  The problem was that some of the
TopicAction message generators assumed that they were the current
active verb, which isn't always the case.  This has been fixed.

</div>

<!------------------->
<div class=entry>

The English library defines the new verb phrasings ASK <i>actor</i>
<i>topic</i> and TELL <i>actor</i> <i>topic</i>; these are phrasings
for the new actions AskVague and TellVague, respectively.  These are
defined entirely to provide more helpful error messages in cases where
the player enters an ASK or TELL verb without an ABOUT phrase.  The
default handling for the new actions simply displays an explanation of
the proper ASK ABOUT or TELL ABOUT phrasing.  Some players have been
seen to misinterpret custom phrasings that show up in SpecialTopic
prompts, such as "ask bob why", as general-purpose command phrasing,
and then attempt to use similar phrasing elsewhere in the game.  This
results in "invalid command" errors from the parser, of course, but
the standard error messages were often unhelpful with this particular
kind of phrasing error.  The new handlers are meant to improve on the
standard error messages for this common case.

</div>

<!------------------->
<div class=entry>

The English library now treats the command phrasing CLIMB IN/INTO/IN
TO as a Board action, and CLIMB ON/ONTO/ON TO as a StandOn action.  In
the past, both forms of CLIMB were defined for both of these actions,
which made the choice of which action matched the syntax arbitrary and
unpredictable.  This change ensures that each of these phrasings is
unambiguously assigned to only one action.

</div>

<!------------------->
<div class=entry>

The English library now tries a little harder to figure out whether a
command of the form ENTER <i>text</i> means ENTER <i>text</i> ON
<i>some implied keypad-type object</i>, or GO IN <i>object</i>.  In
the past, the library always used the GO IN interpretation.  Now, the
library assumes the ENTER ON <i>keypad</i> interpretation if there's a
suitable default object present; if there isn't, the library reverts
to the GO IN interpretation.

</div>

<!------------------->
<div class=entry>

The English library formerly allowed any object to match the pronoun
"them"; it now limits "them" matches to (a) objects used in lists in
player input, as in TAKE IRON KEY AND BRASS KEY, and (b) objects
marked as having plural usage via isPlural.

</div>

<!------------------->
<div class=entry>

The parser now lowers the grammar match ranking for any phrasing
involving a plural in a noun slot requiring a single object.  This
makes the parser a bit smarter about picking the right vocabulary
interpretation in cases of nouns that have both singular and plural
usage, such as FISH and SHEEP.

</div>

<!------------------->
<div class=entry>

In the English library, the isHim and isHer properties are now taken
into account for arbitrary Thing objects in parameter substitutions in
messages.  In the past, gender was only taken into account for Actor
objects; non-Actor objects were always "it" or "them" in messages.

</div>

<!------------------->
<div class=entry>

In the English library, the Actor methods theName, theNameObj,
theNamePossAdj, theNamePossNoun, aName, and aNameObj now properly
handle the first-person plural case ("we", "us", "our", "ours", etc).
In the past, a plural Actor with first-person referralPerson
incorrectly used the singular first-person pronouns.

</div>

<!------------------->
<div class=entry>

The PourOnto verb in the English library now correctly uses
onSingleNoun as its indirect object response phrase, matching the
regular grammar for the verb.  (In the past, it incorrectly used
withSingleNoun as the response phrase.)

</div>

<!------------------->
<div class=entry>

The English library now tries harder to avoid duplicating vocabulary
in the lists it constructs from vocabWords properties during
initialization.  First, VocabObject.inheritVocab() now avoids
redundantly scanning vocabulary inherited from superclasses.  Since
this routine's whole point is to explicitly scan the class hierarchy
for each object and add the vocabulary inherited from each superclass,
it needs to bypass the normal automatic inheritance mechanism, which
it now does.  Second, initializeVocabWith() now explicitly removes
duplicates from each word list it updates, to avoid duplication in
cases where an object explicitly defines the same vocabulary word at
multiple inheritance levels.

</div>


<!------------------->
<div class=entry>

The new function isListSubset() determines if one list is a subset of
another list: that is, if every element of the first list also appears
somewhere in the second list.  (This function was formerly defined as
a method in the Lister class, but it's generically useful and wasn't
tied in any way to Lister, so it's been broken out as a function to
make it more readily accessible to other code.)

</div>

<!------------------->
<div class=entry>

The library functions main() and mainRestore() have been enhanced to
catch QuittingException signals.  These functions, of course, are the
main entrypoints for the entire program - the former is for normal
start-up, and the latter is for the special kind of start-up that
restores a saved state directly from the operating system shell, such
as when the player launches the game by double-clicking a saved-state
file on the Windows desktop.  Catching QuittingException in these
functions allows game code to throw QuittingException just about
anywhere, without worrying about the context.  In the past, this
exception was only usable after the main command loop started; in
particular, it wasn't usable from startup or initialization code (such
as the code that displays the game's introductory messages), because
there was no handler to catch the exception in effect while that code
was running.

</div>


<!------------------------------- 3.0.9 --------------------------------->
<div class="sepbar"><a name='309'></a>3.0.9</div>
<p><b><i>Released 8/29/2005</i></b>
<p>

<div class=firstentry>

<b>Minor compatibility-breaking change:</b> In the English library,
the ThingState template now uses "+" rather than "@" to introduce the
listingOrder property value.  The choice of punctuation here is pretty
arbitrary; the reason for the change is that a consensus emerged among
users that "+" would be easier to remember in this template because
the other library templates generally use "+" to mark integer slots.

<p>If you have existing game code that defines any ThingState objects
using the old template, you'll need to change the definitions to use
"+" instead of "@".  Alternatively, you could put your own definition
of the old ThingState template into a common header file that your
game use, in which case you wouldn't have to change any of your
existing object definitions; but you're probably better off just
changing your code to use the new convention, since defining your own
template could cause some slight confusion for other users if you
should share your code in the future.

</div>

<!------------------->
<div class=entry>

<b>Slight risk of incompatibility:</b> Thing.getDropDestination()
must now accept a nil value for the 'obj' argument.  A nil value of
'obj' asks for the drop destination for a "typical" object, rather
than for any specific object.  In the past, it wasn't specified that
'obj' could be nil, and the library never directly called the method
with a nil 'obj' value, so it's possible that some existing game code
might assume that 'obj' is non-nil.  You should do a quick scan of
your game code for getDropDestination() definitions to ensure that
they'll work properly when 'obj' is nil.  In particular, make sure
that you don't evaluate any properties of 'obj' without first checking
that 'obj' is non-nil:

<p><pre>
   getDropDestination(obj, path)
   {
      if (obj.isReallySmall) ...;   <font color=red>// Don't do this!!!</font>
      if (obj != nil &amp;&amp; obj.isReallySmall) ...; <font color=green>// Do this instead</font>
   }
</pre>

</div>

<!------------------->
<div class=entry>

<b>Slight risk of incompatibility:</b> The default value of
Event.eventOrder is now 100 (it was formerly 50).  This default is
essentially arbitrary (since it's only important for relative
ordering), but a value of 100 is more consistent with other similar
ordering defaults elsewhere in the library.

<p>In addition, the eventOrder of the standard sense-change daemon is
now 500, to ensure that the sense-change daemon runs after most other
events.  The library automatically creates the sense-change daemon at
game start-up; this is the daemon that displays messages about new,
ongoing, or ending sounds and odors.  In the past, this daemon had
default priority, so its order relative to other fuses and daemons was
arbitrary.  If another fuse or daemon ran after the sense-change
daemon, and made some change that affected the sensory environment, a
message about the change wasn't displayed until the following turn,
since the chance had already passed to generate the message on the
turn during which the change actually occurred.  This change ensures
that the sense-change daemon runs after most other events, so any
changes that occur in daemons and fuses will be reflected in the
sense-change update for the same turn.

<p>If you've explicitly set eventOrder for any fuses or daemons in
your game, you might need to adjust the values you set.  In
particular, if you set an eventOrder value between 50 and 100 for an
event object to ensure that the event is processed after events that
inherit the default eventOrder, you'll need to raise that value above
100.  You should also consider if it's desirable for those events to
run after the sense-change daemon, as they would have in the past
(since the sense-change daemon used to have default priority), and if
so, raise their eventOrder values to above 500.  Finally, if you have
an existing eventOrder that's over 500, you might want to consider
whether you still want the event to run after the sense-change daemon;
if not, you should lower the value to under 500.

</div>

<!------------------->
<div class=entry>

<b>Possibly incompatible change:</b> The parameter lists of some of
the internal library routines that handle point-of-view have changed.
These aren't likely to affect any existing game code, since these are
mostly used only inside the library itself, but you should check your
code for any mentions of these names to be sure.  You'll need to
adjust any code in your game that either calls or overrides any of
these methods or functions:

<ul>

<li>Thing.fromPOV() has a new parameter giving the actor who's doing
the looking.

<li>Function pushPOV() takes a new parameter giving the actor.

<li>Function callFromPOV() takes a new parameter giving the actor.

<li>Function setPOV() takes a new parameter giving the actor.

<li>Function setRootPOV() takes a new parameter giving the actor.

</ul>

</div>

<!------------------->
<div class=entry>

<b>Very slight risk of incompatibility:</b> In the following methods,
the parameter now gives the point-of-view <i>actor</i> instead of the
point-of-view object.  The POV actor and object are usually the same
anyway, so the effects on existing code should be minimal.  If you
actually need the POV object, you can get it with the getPOV()
function.

<ul>
<li>Thing.showRemoteSpecialDesc
<li>Thing.remoteInitSpecialDesc
<li>Thing.remoteSpecialDesc
<li>Thing.showSpecialDescInContents
<li>Thing.showObscuredSpecialDescInContents
<li>Thing.showDistantSpecialDescInContents
<li>Thing.showRemoteSpecialDescInContents
<li>Actor.listActorPosture
</ul>

</div>


<!------------------->
<div class=entry>

The new function getPOVActor() returns the "point-of-view actor."
This is the actor who's doing the looking that is, the actor who's
performing the action (LOOK AROUND, EXAMINE, SMELL, etc) that's
generating the current description.  This is <i>usually</i>, but not
always, the same as gActor, and it <i>usually</i>, but not always,
returns the same object as getPOV().

<p>The point-of-view actor can differ from gActor in cases where game
code explicitly generates a room description from the point of view of
one actor in the course of processing a command given to a different
actor.  In these cases, gActor will be the actor who's performing the
command, and getPOVActor() will return the actor who's generating
the description.

<p>The point-of-view actor can differ from the point-of-view object
(the object returned by the getPOV() function) when the actor is
observing the location being described through an intermediary object.
For example, if we're generating a description of a remote room
because an actor is examining a closed-circuit TV monitor showing the
remote location, the point-of-view actor will be the actor who's
looking at the monitor, while the point-of-view object will be the
camera in the remote location.  Note that the POV is the camera, not
the monitor: the POV is intended to be the object that's physically
absorbing the light rays, or other sensory equivalents, from the
surroundings being described.

</div>

<!------------------->
<div class=entry>

The library now selects remote descriptions for rooms and other
objects a little differently than before.  In the past, the remoteness
of the point-of-view object was the deciding factor - that is, remote
descriptions were used when the POV wasn't in the same room as the
object being described.  Now, the library bases the decision on the
point-of-view actor, not the POV object: if the actor who's doing the
looking isn't in the same room, the remote description is used.  This
means, for example, that the remote description will be generated when
observing a room through a closed-circuit TV system: even though the
POV (the camera) is in inside the room being described, the actor
who's observing the TV monitor is in a different room, so the remote
description is used.

<p>This change is implemented in Thing.showSpecialDescWithInfo()
and Thing.showSpecialDescInContentsWithInfo().

</div>

<!------------------->
<div class=entry>

The method Thing.lookAroundWithinContents(), which is the part of the
room describer that lists the room's contents, had a bug in past
versions that caused a single object to be listed twice in some
unusual cases.  In particular, if the room itself had brightness 1,
and it contained an object that also had brightness 1, the object was
listed twice: once in a list starting "In the dark you see," then
again in a list starting "The <i>room</i> contains."  The same problem
occurred in a dark room if an object with brightness 1 was inside a
container with brightness 1.  This has been fixed.

</div>

<!------------------->
<div class=entry>

A new mechanism in Actor allows objects to be explicitly excluded from
the "look around" description of a room.  To exclude an object, call
the method excludeFromLookAround(obj) on the actor, passing in the
object 'obj' to be excluded.  The object will be suppressed from room
descriptions until further notice - it won't show up in any of the
visible-object lists, including special descriptions, room contents
lists, or nested contents lists.  To remove an object from the
exclusion list, call unexcludeFromLookAround(obj).

<p>The exclusion that this method applies is over and above any other
listing-selection mechanisms, such as obj.isListed.  It's intended
mostly for ephemeral exclusions that are applied other than by the
object itself, since the object itself can usually more easily control
its own listability via isListed and the like.

</div>

<!------------------->
<div class=entry>

In Thing.adjustLookAroundTable(), the point-of-view actor is no longer
removed from the table; instead, just the point-of-view object is
removed.  In cases where the POV and actor differ and the actor is in
sight of the POV, we usually want to include the actor in the
generated description.

<p>In addition, the method now calls adjustLookAroundTable() on the
actor and POV objects, giving them a chance to make further adjustments
to the table.

</div>

<!------------------->
<div class=entry>

Suppose we have an NPC who's in scope but out of hearing range, such
as when the NPC is on the other side of a transparent, soundproof
window from the player character.  If the player addresses a command
to the NPC, the library now uses the same error message that it uses
for ASK ABOUT and other conversation commands in the same situation.

<p>(This corrects a bug that used to occur.  In the past, the library
attempted to let the NPC respond, rather than generating a parser
error.  The problem with this approach was that the soundproof barrier
stopped the PC from hearing the NPC's response, thus the library could
only report that "Nothing obvious happens."  Now that this is handled
as a parsing error instead of a conversational response, the more
helpful "Bob does not appear to hear you" is displayed.)

</div>

<!------------------->
<div class=entry>

Thing.isListedInRoomPart has changed slightly.  In the past, an object
was listed (i.e., shown in a miscellaneous list of portable contents)
as part of an EXAMINE FLOOR (or EAST WALL or the like) if the object
was nominally part of the room part (that is, nominally on the floor,
or on the given wall, etc) <b>and</b> the object was normally listed
the same way in a LOOK AROUND command.  Now, the object is listed if
it's nominally part of the room part <b>and</b> the new RoomPart
method isObjListedInRoomPart() returns true.

<p>The new method RoomPart.isObjListedInRoomPart returns true by
default if the object does <b>not</b> have a special description for
the purposes of examining the room part - that is, if the object's
useSpecialDescInRoomPart returns nil.  We don't want to include the
object in the miscellaneous list if it has a special description
because the special description will be automatically shown - it would
thus be mentioned twice if we included it in the miscellaneous list as
well.

<p>Floor overrides isObjListedInRoomPart to list an object only if
it's listed normally - that is, the object's isListed returns true.
This is the old behavior that applied to <b>all</b> room parts, but
now it only applies to Floor objects.  The reason we treat Floor
differently is that everything that's directly in a room is by default
nominally on the floor in the room, so if we didn't limit the listings
like this in the case of EXAMINE FLOOR, we'd include all of the
internal fixtures and components of the room, which is generally
undesirable.

<p>The main purpose of this change is that it makes it a little easier
to set up Fixture-type objects that are described as being situated on
walls, ceilings, and the like.  Now, all that's necessary is to give
the object a specialNominalRoomPartLocation - even if the object isn't
normally listed in a room description, as is the case for a Fixture,
we'll now list the object when we examine its room part as long as it
doesn't have an explicit special description for the room part.

</div>

<!------------------->
<div class=entry>

The new mix-in class RoomPartItem can be used to create an object that
shows its special description when an associated room part is
described.  This is useful for things like doors, windows, ceiling
fans, and other objects attached to the room.  The main thing this
class does is to make the object show its special description when its
associated room part is examined (as in LOOK AT EAST WALL), but
<i>not</i> in the main room description (as in LOOK AROUND).  This is
desirable because this kind of object is usually not remarkable enough
to call out with a special description in the overall room, but does
warrant a mention when its associated room part is explicitly
examined.

</div>

<!------------------->
<div class=entry>

SensoryEmanation has a new property, isEmanating, that lets you turn
the object on and off.  By default, is Emanating is true; if you set
this to nil, it shuts off the emanation.  This makes it easier to make
sounds and odors start and stop, which is often useful when the
emanations are associated with dynamic objects such as actors.

</div>

<!------------------->
<div class=entry>

Settable has a new method, canonicalizeSetting(), that converts a
proposed new setting to a "canonical" format.  Settable now uses this
to process the player's input before passing the value to
isValidSetting() or makeSetting(), ensuring that these routines don't
need to perform any further format conversion of their own.

<p>This method makes it much easier to handle superficial formatting
variations in the player's input by centralizing the conversions to
this single routine.  In the past, both isValidSetting() and
makeSetting() had to handle formatting variations since they received
the raw player input.

<p>Settable's default implementation of canonicalizeSetting() doesn't
do anything - it just returns the original player input unchanged.
NumberedDial overrides the method to convert spelled-out numbers to
numeral format and to strip off any leading zeroes from an entered
numeral format; LabeledDial overrides it to convert the input to the
exact case of the matching entry in the list of valid labels.

</div>

<!------------------->
<div class=entry>

The new library routines parseInt() and parseIntTokens() parse a
string or token list (respectively) that contains a spelled-out or
digit-string numeric value.  These routines parse the input and return
the corresponding integer value, or nil if the input can't be parsed
as a number.  For example, parseInt('one thousand and twenty-four')
returns 1024, parseInt('72') returns 72, and parseInt('dusty tome')
returns nil.

</div>

<!------------------->
<div class=entry>

The English library now incorporates Michel Nizette's Past Tense
extension.  This enables the author to select the tense - present or
past - used in library messages, and even allows you to change the
tense dynamically during the game.

<p>The 'master switch" for the active tense is gameMain.usePastTense.
Set this to true to activate past tense in library messages.  The
default is nil, which selects present tense.

<p>A number of new message parameters and verbEndingXxx properties
help in writing messages that can change tense.  The standard library
messages defined in en_us/msg_neu.t use these new features to adapt
automatically to the current tense.

<p>See the comments in en_us/en_us.t for full details.

</div>

<!------------------->
<div class=entry>

The library has a new framework for "global defaults," which lets the
user save certain preference settings as default values for future
sessions.  These saved defaults are global: they apply to <i>any</i>
new game subsequently loaded, provided that the new game supports the
new global defaults system.  Games compiled with library versions
prior to 3.0.9 didn't support this new system, but games compiled with
3.0.9 or later will support it by default, as long as an author
doesn't explicitly disable it for some reason.  The settings are saved
to a file whose name and location are determined by the interpreter
(and which might vary by system, to conform to local conventions).

<p>Two new commands let the user control the global defaults: SAVE
DEFAULTS saves the current settings to the configuration file, and
RESTORE DEFAULTS explicitly loads the file and applies its settings.
These commands both list the full set of saved settings, so that the
user can easily tell exactly which settings are affected.

<p>By default, the library uses the new global settings framework
for the VERBOSE, FOOTNOTES, NOTIFY, and EXITS settings.

<p>The new mechanism is implemented mostly in the new file settings.t.
The main API is exposed through the new settingsManager object, and
the command-line user interface is implemented in the new settingsUI
object.  The new SettingsItem class is used to encapsulate individual
configuration variables.  If you want to create your own extensions to
the set of global default variables, simply create a SettingsItem
object for each new variable you want to add.  The settings framework
will automatically find your new SettingsItem objects, and save and
restore them as needed.

</div>

<!------------------->
<div class=entry>

The new macro gSetSeen(obj) marks an object as having been seen by the
player character.

</div>

<!------------------->
<div class=entry>

The new macro gTopicText returns a string containing the literal text
of the current topic phrase, when the current action contains a topic
phrase.  The text returned is as the user typed it, but converted to
lower case.

</div>

<!------------------->
<div class=entry>

The LiteralAction and LiteralTAction class are now based on a new
common mix-in base class, LiteralActionBase.  This is parallel to the
structure of TopicAction and TopicTAction, with their common mix-in
base class TopicActionBase.  This new arrangement shouldn't at all
change the behavior of LiteralAction or LiteralTAction, and should be
entirely transparent to existing code.

<p>The change has two main benefits.  First, it eliminates some code
duplication, by replacing a few bits of code that were effectively
duplicated in LiteralAction and LiteralTAction with common versions
that both classes now inherit from LiteralActionBase.  Second, game
code can now easily determine if an action involves any sort of
literal phrase, by testing gAction.ofKind(LiteralActionBase).

</div>

<!------------------->
<div class=entry>

The new Thing method failCheck() makes it a little more convenient to
write check() routines.  check() routines frequently use this pattern:

<p><pre>
   check()
   {
     if (condition)
     {
       reportFailure('You can\'t do that for some reason.');
       exit;
     }
   }
</pre>

<p>The failCheck() routine encapsulates the display of the failure
report and the termination of the action with 'exit'.  Using
failCheck(), you can rewrite the code above more concisely,
like so:

<p><pre>
   check()
   {
     if (condition)
       failCheck('You can\'t do that for some reason.');
   }
</pre>

</div>

<!------------------->
<div class=entry>

Occluder.occludeObj() has a new default implementation.  By default,
the method now asks the object being tested for occlusion to make the
decision, by calling the object's isOccludedBy() method.

<p>Thing provides a default implementation of the new isOccludedBy()
method, which simply returns nil to indicate that the object is not
occluded by the given Occluder.

<p>Existing code won't be affected by this change, since any existing
Occluder code already overrides isOccludedBy() to make the per-object
occlusion decision.  The reason for this change is that it's sometimes
easier to decide about occlusion in the individual objects rather than
in the Occluder; the new default Occluder.occludeObj() makes it easer
to write the code that way by providing a pre-defined framework that
already works that way.

</div>

<!------------------->
<div class=entry>

In the past, if a Container was used as the indirect object of PUT IN
or POUR INTO, the library applied an objOpen precondition to ensure
the container was open.  The library now applies the objOpen condition
only if the actor performing the action isn't itself inside the
container.  The reason for the objOpen condition is that putting or
pouring things into a container requires access to the container's
interior, and a container's interior is only reachable from outside
the container when the container is open.  However, when an actor is
inside a container, the actor can reach the inside of the container
whether or not the container is open, so there's no need for the
objOpen condition.

</div>

<!------------------->
<div class=entry>

Fixture, Component, and Immovable now define custom handlers for PUT
BEHIND that are consistent with their handlers for PUT IN, PUT ON, and
PUT UNDER.

</div>

<!------------------->
<div class=entry>

On an actor's attempt to take an item that was inside something the
actor was already carrying, Actor.tryMakingRoomToHold() formerly
double-counted the item's weight in enforcing the actor's carrying
limit - it counted the item first for the weight of carrying the new
item itself, then again for its contribution to the weight of its old
container (because the old container was in the actor's inventory).
The routine now correctly counts the weight only once.  (The new
algorithm uses the whatIfHeldBy() method, which actually tests the
proposed new arrangement to calculate the new weight carried and thus
yields reliable results no matter what configuration previously
existed.)

</div>

<!------------------->
<div class=entry>

TAKE ALL now tries to take everything that's directly in the actor's
current "drop destination", <i>or</i> that's directly in the actor's
direct container, <i>or</i> that's in any intermediate container
between the two.  The former behavior was to take everything in the
actor's direct location only.  This change improves the behavior when
the actor is in something like a chair or bed.  In these sorts of
nested rooms, items dropped usually land in the enclosing room; the
new behavior ensures that a TAKE ALL command attempted while in such a
location will include items that were just dropped while in the same
location.  With the former behavior in this situation, TAKE ALL missed
the items in the drop location, which was likely to confuse players.

</div>

<!------------------->
<div class=entry>

NonPortable now defines a default weight and bulk of zero.  Since
these objects aren't meant to be carried or moved around by actors,
their weight and bulk are essentially irrelevant; but the previous
non-zero defaults occasionally had undesirable side effects in
cases where a non-portable was a component of another object or
among another object's contents.

</div>

<!------------------->
<div class=entry>

An attempt to give an object to an NPC when the NPC is already holding
the object in question is now ruled out as illogical ("Bob already has
that").

</div>

<!------------------->
<div class=entry>

The library now provides commands that let the player control the
display of the exits listing in the status line.  EXITS ON now turns
on <i>both</i> the status line and room description exit listings, and
EXITS OFF turns them both off.  The new command EXITS STATUS (which
can also be entered as EXITS STATUSLINE or EXITS STATUS LINE) turns on
the status line exit listing only, and EXITS LOOK turns on the room
description exit listing only.

<p>In addition, these new commands are now described in the standard
instructions.

</div>

<!------------------->
<div class=entry>

The "probabilistic firing" feature of the RandomEventList class is now
available in a separate mix-in class, RandomFiringScript.  This new
class can be mixed into the superclass list of any Script subclass to
add the random firing feature.

<p>RandomEventList and ShuffledEventList are now based on the new
RandomFiringScript.  This doesn't change their behavior; existing
code based on these classes should continue to work unchanged.

</div>

<!------------------->
<div class=entry>

The SyncEventList class now delegates calls to its scriptDone() method
to its master list object.  This ensures that any explicit calls to a
SyncEventList's scriptDone() method will be handled via the master
list, which is consistent with SyncEventList's handling for most of
its other methods.

</div>

<!------------------->
<div class=entry>

The library now has a better response to the FOLLOW command if the
target NPC departed the player character's present location while the
PC was somewhere else.  Suppose the PC sees Bob in the living room,
then goes to the dining room; while the PC is in the dining room, Bob
departs for a third room (due to some scripted activity).  The player
then returns to the living room.  At this point, it's not possible to
FOLLOW BOB, since the PC didn't see where Bob went.  This much hasn't
changed; what's changed is the library's default response if player
types FOLLOW BOB in this situation.  In the past, the response was
"The last place him was the living room," which is true but not very
helpful (and a little non sequiturish).  Now, the response is "You're
not sure where he went from here."

</div>

<!------------------->
<div class=entry>

NominalPlatform now returns its location's effectiveFollowLocation as
its own effectiveFollowLocation.  A nominal platform isn't meant to be
part of the visible structure of the game world, so, for FOLLOW
purposes, a character on a nominal platform is effectively in the
enclosing room as far as the other characters in the room are
concerned.

</div>

<!------------------->
<div class=entry>

A bug in the parser caused possessive pronouns to be treated
differently in a TopicTAction when the direct object phrase was
missing than when it was provided.  For example, ASK BOB ABOUT HIS KEY
was treated differently from the abbreviated equivalent A HIS KEY.
This has been corrected.

</div>

<!------------------->
<div class=entry>

The parser now drops its preference for untruncated name matches when
resolving an object in "global scope," and instead treats truncated
and exact name matches on an equal footing in these cases.  This
change is analogous to the global scope changes for plurals and
adjective-ending phrases introduced in 3.0.6q and 3.0.6p.  See the <a
href='#global_scope_noun_adj'>adjective-ending notes</a> from 3.0.6p
for details on what global scope is and why its rules on matching are
more lenient.

<p>The practical effect of this change is that topic words will now
match properly even when there are longer and shorter versions of the
same vocabulary defined for various objects.  In the past, if one
object was defined with a six-letter noun, and another object had a
seven-letter noun with the same first six letters as the other object
("coffee" and "coffees", say), the parser filtered out the
seven-letter match in favor of the six-letter match, even though both
objects ought to be equally valid in global scope.  With the change,
both objects are now properly kept as possible resolutions when
parsing a topic phrase.

</div>

<!------------------->
<div class=entry>

The parser now selects Collective objects instead of their
corresponding individuals when matching "all" and "all except
<i>list</i>" noun phrases.

<p>Whether it's better to select the Collective or the individuals
probably varies according to context, since the "right" one is the one
the player intends in a particular command, and that will likely vary
from one command to the next (and from one player to the next).  But
the design of the parser requires that we choose one interpretation or
the other across the board; context sensitivity isn't an option.  Even
if context sensitivity were an option, we might still not have enough
information to correctly read the player's mind every time.  This
change - matching the Collective object instead of the individuals -
seems more likely to yield intuitive results more of the time than the
old behavior.

</div>

<!------------------->
<div class=entry>

The parser now applies the normal filterResolveList() filtering when
resolving a target-actor phrase (such as the "bob" in "bob, go
north"), the same as it does when resolving other kinds of noun
phrases.  In the past, the parser omitted this filtering step for
target actors, which didn't give objects like Unthings and Collectives
a chance to do their special filtering.

</div>

<!------------------->
<div class=entry>

When the player enters a command of the form TAKE ALL FROM
<i>iobj</i>, the TakeFrom action now lets the indirect object
determine what ALL means.  It does this via a new method,
getAllForTakeFrom(scopeList).  Thing implements this method using
almost the same behavior that TakeFrom used in the past: it returns a
list of everything in scope that's directly inside 'self' and isn't a
component of 'self'.  The old behavior simply returned everything in
scope that was directly inside the indirect object.

<p>ComplexContainer overrides getAllForTakeFrom() to return everything
that's in scope and that's directly in (a) the sub-container or
sub-surface, if the object has either, or (b) the sub-rear-surface or
sub-underside, if the object doesn't have a sub-container or
sub-surface; and as with Thing's version, this list is then limited to
objects that aren't components of their direct containers.  Note that
if there's both a sub-surface <i>and</i> a sub-container, the method
will return everything that's in <i>either</i> of these; and likewise
with the sub-rear-surface and sub-underside.

<p>This change is designed primarily to improve the behavior for
ComplexContainers, which wasn't ideal under the old mechanism, as it
only returned the complex container's sub-components, which are
internal implementation objects that are meant to be invisible to the
player.  Clearly, in the case a complex container, it's the contents
of the inner containers that are of interest in TAKE ALL FROM.  This
change also makes it easier to customize the TAKE ALL FROM behavior
for your own special containers, since it gives the container a chance
to determine what ALL means in context.

<p>The grammar class VagueContainerNounPhraseProd, which matches
locational phrases such as "all in box" and "the one in the box," also
uses the new method to determine which objects are involved.  This
provides the same improvement for commands such as LOOK AT EVERYTHING
IN THE BOX when a complex container or other special container is
involved.

</div>

<!------------------->
<div class=entry>

The NounPhraseWithVocab method getVocabMatchList() now takes an extra
parameter, specifying any extra flags that should be OR'd into the
ResolveInfo flags for the items in the match list.  In the past, the
version of the method in the adjective-phrase subclasses took the
extra flags parameter, but the base class method didn't, which made it
difficult to create classes for production types that could define
grammars with either the adjective or noun subproductions.

</div>

<!------------------->
<div class=entry>

In the past, if the player typed STAND while the PC was sitting or
lying on an object derived from BasicPlatform, the library simply made
the PC stand up, remaining on the platform.  In particular, the
library didn't bother checking the allowedPostures property to see if
the platform actually allowed the 'standing' posture; it simply
assumed that standing was allowed on any platform.  This didn't easily
allow for things like booths with limited headroom.  The
makeStandingUp method of BasicPlatform now checks allowedPostures
property, to make sure that 'standing' is listed.  If 'standing' isn't
among the allowed postures, the makeStandingUp method now inherits the
base class handling, which removes the actor from the nested room and
sets the actor's posture to the default for the enclosing location.
This will produce better results in most cases, since the natural
implication of STAND UP when in a vertically confined space would be
to remove oneself from the space.

</div>

<!------------------->
<div class=entry>

It's now possible to control the order in which preconditions are
executed, at the level of the individual preconditions.  The new
PreCondition property preCondOrder gives the order of execution of a
given precondition.  The default for most types of preconditions is
100; for TouchObjCondition (and thus for touchObj), it's 200, which
means that touchObj conditions will execute after other conditions by
default.

<p>It's occasionally useful to be able to fine-tune precondition order
because preconditions can sometimes interfere with one another.  This
is particularly a problem with implied actions that require the actor
to be in a particular posture or location, because many of the
standard preconditions can move the actor around as a side effect.
For example, a doorOpen condition could execute an implied STAND as
part of its implied OPEN DOOR; if another precondition requires the
actor being to be sitting, its effect would be undone if the doorOpen
were executed second.  We can safely STAND and OPEN DOOR first, then
SIT DOWN second, because we'll still satisfy the doorOpen condition
even though we're no longer standing when we're done.

<p>In addition to the new preCondOrder ordering, the default ordering
has changed for two-object verbs (those with direct and indirect
objects).  By default, the direct object preconditions are now
executed first, followed by the indirect preconditions; in the past
this order was reversed.  This is only the default order - the
preCondOrder takes precedence.  That is, the action builds a list
consisting of the direct object preconditions followed by the indirect
object preconditions, then sorts that list in ascending order of
preCondOrder, preserving the existing relative order of objects with
the same preCondOrder.

</div>

<!------------------->
<div class=entry>

adv3.h now defines a couple of new templates for your convenience:

<p><pre>
   SyncEventList template -&gt;masterObject inherited;
   Hint template 'hintText' [referencedGoals]?
</pre>

</div>

<!------------------->
<div class=entry>

When an Unthing is used as a possessive or locational qualifier ("the
key in the unthing" or "the unthing's key," for example), the parser
now shows the Unthing's "not here" message.  In the past, the parser
showed the same default messages for an Unthing as for any other
object, using wording like "The unthing doesn't appear to have that"
or "You see no key in the unthing."  This wording was incongruous for
Unthings because an Unthing represents the absence of an object, and
hence an Unthing can't "appear" to have or contain - or even not have
or not contain - anything.  Showing the Unthing's "not here" message
yields more sensible results.

</div>

<!------------------->
<div class=entry>

An Unthing now responds to LISTEN and SMELL commands with the same
message it uses for EXAMINE (by default, "You don't see that here").
This applies even if the Unthing is distant or obscured.  (In the
past, the inherited Decoration messages for these verbs were used.)

</div>

<!------------------->
<div class=entry>

The English library provides a new template for Unthing:

<p><pre>
Unthing template 'vocabWords' 'name' @location? 'notHereMsg'?;
</pre>

</div>

<!------------------->
<div class=entry>

The finishGame() function now updates the global turn counter to
reflect any turn currently in progress, or, when called from a daemon
or fuse, the turn the player has already completed.  In the past, the
turn counter displayed in finishGame() didn't reflect the turn in
progress that triggered the call to finishGame().  Internally, a turn
isn't counted in the global turn counter until it's finished; but from
the player's perspective, a turn should count as soon as it starts.
This change ensures that the count that finishGame() displays is
consistent with the player's expectations.

</div>

<!------------------->
<div class=entry>

A Lockable that's also an Openable no longer reports its
locked/unlocked status when the object is open.  By default, an
Openable must be closed in order to be locked, so if it's open, it's
always unlocked.  This means that the locked/unlocked status is
effectively redundant information when the object is open.

<p>By way of implementation, the Lockable class has a new method,
lockStatusReportable, that indicates whether or not the lock status is
worth mentioning in the object's current state.  (This doesn't
supersede lockStatusObvious, but rather complements it.
lockStatusObvious still indicates whether or not the lock status is
visually apparent; lockStatusReportable indicates whether it's worth
mentioning from an aesthetic point of view.)  Lockable defers to any
mix-in class that provides the method, and Openable takes advantage of
this by providing an implementation of the method that returns true if
the object is closed, nil if it's open.

</div>

<!------------------->
<div class=entry>

Door and SecretDoor are now based on a new common base class,
BasicDoor.  The new BasicDoor class defines the core internal behavior
of a door: a travel connector object that can be open or closed, that
allows travel only when open, and that can have two objects linked
together to represent the two sides of the door.

<p>The relationship between BasicDoor and Door is analogous to that
between BasicOpenable and Openable.  BasicDoor defines the internal
behavior, while Door adds handling for user commands to manipulate the
door (in particular, OPEN, CLOSE, LOCK, UNLOCK).

<p>This change doesn't affect the functionality of Door; it merely
rearranges the code for Door internally by moving a few methods to the
new BasicDoor base class.  SecretDoor isn't much affected, either, but
does now add support for remembering a recent traversal for
disambiguation purposes, as Door did in the past (and still does).  No
changes should be needed in existing game code.

<p>The main benefits of this change are that it makes SecretDoor
behave more consistently with the Door class, and it provides a single
base class for all door-like objects.  In addition, the new BasicDoor
class makes it easier to define custom doors with special controls,
since it has all of the necessary functionality but doesn't make any
assumptions about handling commands.

</div>

<!------------------->
<div class=entry>

BasicDoor.noteRemoteOpen() now calls a new method,
describeRemoteOpen(), to generate the message describing the change.
This makes it easier to override the message for a door, since you can
simply display the custom message without having to worry about the
sense context.

</div>

<!------------------->
<div class=entry>

The Enterable and Exitable classes no longer accept the GO THROUGH
command.  In the past, these classes did accept GO THROUGH as
synonymous with travel, but this became undesirable when the
EntryPortal and ExitPortal classes were added.  Enterable and Exitable
are meant for things like buildings, where ENTER or EXIT make sense
but not GO THROUGH; EntryPortal and ExitPortal are for things like
doors and passages, where you can equally well ENTER/EXIT them or GO
THROUGH them.

</div>

<!------------------->
<div class=entry>

The AutoClosingDoor class has a new method, reportAutoClose(), that
generates the message that mentions that the door closed behind
whoever just went through it.  The TravelVia action() handler calls
reportAutoClose() after it automatically closes the door; by default,
reportAutoClose() shows the standard library message
&amp;doorClosesBehindMsg.  In the past, the action() handler simply
showed the same library message itself, rather than calling out to a
separate method.

<p>The purpose of this change is to make it easier to customize how
the auto-closing is reported, or whether it's reported at all.  If
you want the door to close silently, without any mention that it
closed, simply override reportAutoClose() to do nothing.

</div>

<!------------------->
<div class=entry>

By default, a FireSource object now removes itself from consideration
as a default indirect object for the BurnWith action if it's not
already lit.  This ensures that the library won't (for example)
attempt to use an unlit candle as a default source of fire to light
another candle.  In the past, under certain circumstances, the library
could cause a stack overflow by trying to light one candle with
another, which it tried to light with the first, and so on.  This
change ensures that a fire source will only be chosen as the default
indirect object for BurnWith if it's already lit.

<p>(Matchstick objects, of course, aren't affected by this change,
since they can light themselves on fire independently.  Matchsticks
thus remain valid as default choices for BurnWith even when they're
unlit.)

</div>

<!------------------->
<div class=entry>

The Wearable class now sets an elevated likelihood (via logicalRank())
for a REMOVE (or TAKE OFF or DOFF) command when the object is being
worn.  This helps avoid disambiguation prompts for these commands.

</div>

<!------------------->
<div class=entry>

When a Hidden object is discovered (via its 'discover()' method), the
object now marks itself and its contents as having been seen by the
player character, assuming they're within sight at the time the object
is discovered.

</div>

<!------------------->
<div class=entry>

The new RoomPart methods moveIntoAdd(room) and moveOutOf(room) make it
easier to dynamically change a room's set of RoomPart objects.  In the
past, there was no straightforward way to change a room's RoomParts
dynamically; these new methods make it easy by making the necessary
updates to the affected room's properties.

</div>

<!------------------->
<div class=entry>

Room.getExtraScopeItems() now adds the room's floor to scope only if
the actor is directly in the room.  In the past, this routine added
the floor to scope unconditionally.  The rationale of adding the floor
to scope is that an actor standing in a room is aware that there's a
floor there simply by virtue of standing on it - but that rationale
only holds when the actor is actually standing on the floor (or
sitting on it, or whatever), and that's only the case when the actor
is actually directly in the room.  If the actor is in a connected
room, or inside a nested room within the outer room, then in most
cases the actor isn't actually in contact with the floor.

<p>Similarly, NestedRoom.getExtraScopeItems() now adds the nested room
to scope only when the actor is directly in the nested room.  The
rationale is the same as for the floor in an outer room.

</div>

<!------------------->
<div class=entry>

The TALK TO command now treats talking to oneself as illogical; in
the past, it was merely considered improbable.

<p>A side effect of this change is that the intransitive
conversational commands (HELLO, GOODBYE, YES, NO) won't try to make
the PC talk to itself by default.  In version 3.0.8, these commands
were enhanced to choose the same default interlocutor as TALK TO would
when the most recent interlocutor is no longer present.  This had the
undesirable effect of choosing the PC as the default target when no
other actors were present.  Now that TALK TO won't choose the PC as
the default actor, HELLO and the rest won't do so, either.

</div>

<!------------------->
<div class=entry>

In past versions, the InConversationState's "boredom counter" was
handled inconsistently in certain cases.  In particular, when an NPC
initiated a conversation, it took one more turn for the NPC to become
bored than it took when the PC initiated the conversation.  This has
been corrected.

</div>

<!------------------->
<div class=entry>

The library now uses the "identity" object when setting a pronoun
antecedent in Actor.setPronounObj().  This ensures that when an
internal program object is being manipulated, and that object
generates a pronoun antecedent, any subsequent command reference to
the antecedent will properly refer to the main simulation object
associated with the internal implementation object.  For example, this
ensures that when a ComplexComponent is manipulated, subsequent
references to "it" refer back to its ComplexContainer parent.

</div>

<!------------------->
<div class=entry>

A library bug introduced in version 3.0.8 caused a run-time error when
the player attempted to address a command to another actor and used a
pronoun to identify the target actor (as in HIM, GO NORTH or ASK HIM
TO GO NORTH - the first phrasing is awkward enough that most players
wouldn't think to use it, but the ASK phrasing is natural enough that
players might try it).  This has been corrected.

</div>

<!------------------->
<div class=entry>

A bug in ThingOrTopicMatchTopic.isMatchPossible caused a run-time
error under certain conditions.  This has been fixed.

</div>

<!------------------->
<div class=entry>

The &lt;.roomname&gt; style tag now adds a newline after the room name
text; this is in lieu of the &lt;.roomdesc&gt; style tag showing a
newline before the room description, as was done in the past.  The
newline is really part of the room name formatting, to ensure that the
room name goes on a line by itself.  This change won't affect most
existing games, since the usual LOOK AROUND format shows the room name
followed by the long description; but the change does ensure that a
room description won't have an extra leading newline in cases where
the room name isn't displayed.

</div>

<!------------------->
<div class=entry>

In Intangible, Fixture, Decoration, Room, and RoomPart,
hideFromDefault() now simply returns nil.  (In the past, these classes
defined hideFromDefault() as returning the inherited value, which
didn't have the desired effect of bypassing the inherited call (from
Thing.hideFromDefault()) to self.hideFromAll().  These classes
override hideFromAll(), but they want to use separate handling for
hideFromDefault().  The old override didn't correctly accomplish this
because of the way the base Thing implementation of hideFromDefault()
is written.)

</div>

<!------------------->
<div class=entry>

The library now responds to commands like THROW ME, THROW ME AT
<i>something</i>, and THROW ME TO <i>something</i> with an appropriate
failure message.  (In the past, these commands were actually allowed,
and used the standard THROW handling, which obviously isn't
desirable.)

</div>

<!------------------->
<div class=entry>

The library now accepts SIT and LIE (and, equivalently, SIT DOWN and
LIE DOWN) as intransitive verbs.  In the past, these were defined as
missing-direct-object forms of the transitive commands SIT ON and LIE
ON, which meant that the library tried to find a default direct
object.  This had the undesirable effect of making an actor who was
already sitting/lying automatically stand up and sit/lie on some other
suitable object in the room, which as a last resort was the default
floor.  The new intransitive verbs check to see if the actor is
already sitting/lying, and if so, simply generate an error message to
this effect.  If the actor isn't already sitting/lying, the new
commands proceed as before: they look for a suitable default object,
and sit/lie on that.

<p>As part of this change, the intransitive SIT DOWN and LIE DOWN
phrasings no longer have [badness], so the parser will match them
as full-fledged intransitive phrasings.

</div>

<!------------------->
<div class=entry>

There are two small changes to the action message processor.

<p>First, it's now possible to define a message method on a Thing that
takes no arguments, even if the message normally does require
arguments.  This makes it more syntactically convenient to define
simple message string or property-redirect methods that require some
small chunk of code, but which don't need any of the argument values
that are normally sent to the message method.  For example, we can now
write this:

<p><pre>
   notImportantMsg = (myGenericMsg)
</pre>

<p>instead of this (which was formerly required):

<p><pre>
   notImportantMsg(obj) { return myGenericMsg; }
</pre>

<p>Second, these sorts of message methods can now return nil to
indicate that they don't want to provide the message after all.  This
is useful when an object only wants to override a library message when
it's in a certain state.  It's also useful when an object wants to
provide the message only when that object is in a particular role in a
two-object command (i.e., a command with both a direct and indirect
object).  Recall that when a command involves both a direct and an
indirect object, the message processor asks both of the objects for an
override; this new capability lets the objects be selective about
providing an override according to their actual roles in the command.

<p>For example, suppose you want your 'vase' object to override the
"not a container" message for PUT IN, but only when the vase is the
indirect object of the PUT IN, not when it's being put somewhere
itself.  To do this, you could write vase.notAContainer like so:

<p><pre>
   notAContainerMsg = (gIobj == self
                       ? 'The vase\'s opening is too small.' : nil)
</pre>

<p>The library provides a pair of new macros that simplifies the
syntax for that kind of conditional message override:  dobjMsg()
and iobjMsg().  These macros simply test to see if gDobj or gIobj
(respectively) equal 'self'; if so, they return the argument, and
if not they return nil.

</div>

<!------------------->
<div class=entry>

The statusLine object has a new method, setColorScheme(), that sets up
the status line's colors.  This change won't affect any existing code,
since it's just a minor internal reorganization, and the behavior is
the same as it used to be.  The point of the change is that it's now
easier to customize the status line color scheme, since you only have
to override this one method, and the only thing the override has to
do is to write out a &lt;BODY&gt; tag with the desired color scheme.

</div>

<!------------------->
<div class=entry>

The English tokenizer now recognizes upper-case "'S" (apostrophe-S)
suffixes as equivalent to the lower-case version.  In the past, the
tokenizer only recognized this token in lower-case.

</div>

<!------------------->
<div class=entry>

In the English version, the SpecialTopic matcher now specifically
rejects matches for several "weak" topic command inputs: I, L, and
LOOK.  The matcher only rejects the matches when these are the
<i>only</i> thing the player typed.  If the player types just "I", for
example, they probably intend to enter an INVENTORY command rather
than to select a special topic that happens to have "I" among its
tokens (as in "tell him I don't know").

</div>

<!------------------->
<div class=entry>

In the English grammar, plurals are now accepted as possessive
qualifier phrases (as in "the women's books").  When a plural
possessive is used to qualify a plural phrase ("the women's books"),
the parser resolves the overall phrase to all of the in-scope objects
matching the base noun phrase that are owned by anyone matching the
qualifier phrase.  When a plural possessive qualifies a singular noun
("the women's book"), the parser makes the same initial selection, but
then prompts for more information if the selection includes more than
one object.

</div>

<!------------------->
<div class=entry>

When a possessive phrase is used to qualify a noun phrase, and the
result is ambiguous, the parser now filters the list of possible
matches using the filterResolveList() mechanism.  This ensures that
special objects - especially Unthings and Collectives - are treated
the same in this case as they are in other situations.  In the past,
for example, the parser included Unthings in a disambiguation list if
the Unthings matched the vocabulary of a possessive qualifier; this
was undesirable because Unthings aren't meant to be treated as actual,
present objects from the player character's perspective.

</div>

<!------------------->
<div class=entry>

In the past, if the player responded to a disambiguation prompt with a
possessive phrase, and the specified possessor didn't own any of the
objects in the original disambiguation list, the parser responded with
a message like "Bob does not appear to have any such thing."  This was
inconsistent with the way disambiguation responses are treated for
other types of responses.  Now, an inappropriate possessive response
receives the same message as would a random adjective that doesn't
apply to any of the original possibilities: "That was not one of the
choices."

</div>

<!------------------->
<div class=entry>

The English version of the library now lets the Action determine which
message to use when there's nothing in scope matching a noun phrase in
a command.  In the past, the parser always used the "noMatch" message,
the default wording of which was "You see no <i>noun phrase</i> here."
This was sometimes jarring for commands that generally refer to
non-visual objects, such as LISTEN TO or SMELL.  With this change, the
library now calls the Action (via its new method noMatch()) to
determine which message to show.  Most actions simply invoke the new
message method noMatchCannotSee(), which shows the same message as
before.  The LISTEN and SMELL actions override noMatch() to call the
new message method noMatchNowAware(), which shows the message "You are
not aware of any <i>noun phrase</i> here."  The new wording should be
more natural when the noun phrase is something inherently non-visual.

<p>(It would be even better if the library could decide based on the
noun phrase itself whether the noun phrase refers to something visual
or not, since the player could just as well try to EXAMINE THE
SULFUROUS ODOR or TAKE THE BEEPING NOISE.  Unfortunately, it's
effectively impossible to do this, since the true meaning of the error
message is that the parser can't determine what the noun phrase
actually refers to.  We don't want to say that outright, of course,
since that would detract from the player's sense of immersion in the
game world by calling attention to the parser and its limitations, so
the best we can do is to find a heuristic that works most of the time.
The addition of the per-action customization improves on the old
scheme and should make incongruous cases relatively rare.)

</div>

<!------------------->
<div class=entry>

The parser's algorithm for choosing grammar matches has been
fine-tuned to handle cases with truncated words and adjective-ending
phrases a little better, particularly in commands involving multiple
objects.  In some cases, when presented with a two-object command
(e.g., PUT X IN Y) in which one of the object phrases failed to match
any in-scope objects, for the <i>other</i> phrase, the parser formerly
chose a noun-ending phrase over an adjective-ending phrase, even if
the adjective-ending version matched an object in scope and the
noun-ending version didn't.  This sometimes yielded odd "you don't see
that" messages that named the object that actually <i>was</i> in
scope, from the player's perspective.  This change should improve
the behavior in situations like this.

</div>

<!------------------->
<div class=entry>

In the English library, the code that tries to figure out whether to
use "a" and "an" for an object's aName now ignores any leading HTML
tags in the object's base name.  This is useful for objects with
aName strings such as "&lt;i&gt;Apple County Times&lt;/i&gt;".

<p>In addition, the code now specially recognizes names that start
with one-letter words (such as "X-ray" or "&lt;q&gt;L&lt;/q&gt;
button"), and assumes they're pronounced by saying the name of the
letter.  So, for example, "X-ray" turns into "an X-ray," since the "X"
is pronounced as "ex."

</div>

<!------------------->
<div class=entry>

The English library now accepts SET as a synonym for PUT in the
commands PUT DOWN, PUT ON, PUT IN, PUT UNDER, and PUT BEHIND.

<p>SET is also now accepted as a single-object verb.  When applied to
a Thing, the library assumes the intention is SET <i>thing</i> ON
<i>something</i>, and prompts for the other object.  When applied to a
Settable, the library assumes the intention is SET <i>settable</i> TO
<i>setting</i>, and prompts for the setting.

<p>Note that the single-object form (simply SET <i>dobj</i>) could be
useful all by itself in some cases: SET ALARM, for example.  For such
cases, you can simply define a custom dobjFor(Set) for the object.

</div>

<!------------------->
<div class=entry>

In the English library, L is now accepted as a synonym for LOOK in the
various forms of the LOOK UP and LOOK FOR commands: L UP topic IN
object, L topic UP IN object, L FOR topic, etc.

</div>

<!------------------->
<div class=entry>

In the English library, THROW <i>iobj</i> <i>dobj</i> is now accepted
as a synonym for THROW <i>dobj</i> TO <i>iobj</i>, allowing phrasing
like THROW BOB THE BALL.

<p>In addition, THROW <i>obj</i> <i>direction</i> (as in THROW BOOK
EAST) is now accepted, via the new action ThrowDir.  The default
handling for ThrowDir (in Thing) is simply to display a message
essentially explaining that the proper command is THROW AT: "You need
to be more specific about what you want to throw the book at."  If the
phrasing is THROW <i>obj</i> DOWN or THROW DOWN <i>obj</i>, though, we
use the same response we use for THROW AT FLOOR ("You should just put
it down instead").

</div>

<!------------------->
<div class=entry>

The parser's grammar ranking mechanism has a new ranking criterion:
"phrasing weakness."  This is an arbitrary numeric value that the
language module can use to rank particular phrasings as relatively
weak, which means that they're less likely to be valid matches.

<p>The English grammar uses this new criterion to mark phrasings as
weak when they involve two object phrases with no prepositional marker
and no qualifier word - things like GIVE BOB BOOK.  These phrasings
are weak because they could be interpreted as a single object with a
missing phrase instead of two objects - if the wording were GIVE GREEN
BOOK, for example, there's probably a GREEN BOOK and a missing object
rather than two objects GREEN and BOOK.  A phrasing such as GIVE BOOK
TO BOB isn't weak because the prespositional marker makes the grammar
fairly unambiguous; likewise, GIVE BOB THE BOOK is relatively clear
because the article "the" can't normally go in the middle of a noun
phrase, so most likely introduces a second noun phrase.

</div>

<!------------------->
<div class=entry>

In the English library, CLIMB UP and CLIMB DOWN without a direct
object are now explicitly recognized in the grammar as missing-object
versions of CLIMB UP <i>dobj</i> and CLIMB DOWN <i>dobj</i>.  This
prevents the CLIMB <i>dobj</i> grammar from treating the UP or DOWN as
a direct object, which usually yielded an ungainly response along the
lines of "you see no up here."  (The missing-object CLIMB UP and CLIMB
DOWN are marked with "badness" in the grammar, which means that if
there actually is an in-scope object with vocabulary words "up" or
"down", the CLIMB <i>dobj</i> form will still be matched - so CLIMB UP
as short-hand for CLIMB THE UP STAIRWAY will continue to work as it
did before.)

</div>

<!------------------->
<div class=entry>

In the English library, the message substitution parameter "{a/he}"
was incorrectly not marked as a sentence subject.  It's now so marked.

</div>

<!------------------->
<div class=entry>

In the English library, the methods askMissingObject(),
missingObject(), askMissingLiteral(), and missingLiteral() have been
moved from class messageHelper (in en_us.t) to playerMessages (in
msg_neu.t).  These methods are just message generators, so they belong
in the message object with all of the other message generators.

</div>

<!------------------->
<div class=entry>

In the English library, the messages for noMatchForAll have been
changed to variations of "You see nothing suitable."  In the past, the
message was "You see nothing to use for 'all' here," which was
somewhat misleading: it suggested that there's nothing present at all,
when the actual point is merely that there's nothing present that can
be used in the manner specified.

</div>

<!------------------->
<div class=entry>

In 3.0.8, OOPS X (for any literal X) was changed so that it didn't
consume a turn, but OOPS (without a literal) was inadvertantly left
unchanged, so it still counted as a turn.  This has been corrected: a
bare OOPS command no longer consumes a turn.

</div>

<!------------------->
<div class=entry>

In the past, if the player typed NOTE without any text for the note,
the parser prompted for the missing text ("What do you want to
note?").  It no longer does this.  Instead, the first time an empty
NOTE is entered, the parser displays a message explaining that NOTE is
usually used to enter a message, in case the player wasn't aware of
that; and after that, the parser simply accepts an empty NOTE the same
as any other.

</div>

<!------------------->
<div class=entry>

In the past, typing the secret command XSPCLTOPIC by itself on a
command line caused a run-time error.  (XSPCLTOPIC is a verb that the
library uses internally to handle SpecialTopic entries.  It's not
something the player ever needs to type, or indeed is ever allowed to
type, but at certain time, the library internally runs XSPCLTOPIC
commands through the normal command processing as though the player
had typed.)  This has been fixed.

</div>

<!------------------->
<div class=entry>

In the past, if the parser asked for a missing literal phrase (such as
for TYPE), and the player responded with input that included a
character that the game's tokenizer didn't accept, the game displayed
an "unknown exception" message.  The problem was that the parser
didn't properly catch the tokenizer's bad-token exception in this
case.  The parser now catches this exception and reports it as normal.

</div>

<!------------------->
<div class=entry>

In the English library, when the parser is announcing the name of each
object in a multi-object command, paragraph breaks are now suppressed
after the object name.  This slightly improves formatting in cases
where the action response for an object happens to start with a
paragraph break.

</div>

<!------------------->
<div class=entry>

In the English library, the verb-phrase builder method (getVerbPhrase())
for TopicAction, TopicTAction, LiteralAction, and LiteralTAction didn't
work correctly.  This has been corrected.

</div>

<!------------------->
<div class=entry>

The new output control pseudo-tag &lt;./P0&gt; cancels the effect
of an immediately preceding &lt;.P0&gt; tag.  This is useful in
certain cases where you want to ensure that a newline or paragraph
break is displayed, even if a &lt;.P0&gt; was just displayed.

</div>

<!------------------->
<div class=entry>

All of the various spellInt-related functions are now implemented in
en_us.t.  Some of these functions were formerly in numbers.t, but that
wasn't the right place for them because some language modules might
need to change these functions' interfaces (for example, to specify
the grammatical case or gender of the result).  This change should
have no effect on any existing game code; it's a purely internal
change.

</div>

<!------------------->
<div class=entry>

The message property 'flashlightOnButDark' has been renamed to
'flashlightOnButDarkMsg' (that is, the suffix 'Msg' has been added)
for consistency with the other message property names.

</div>

<!------------------->
<div class=entry>

The default library message for TASTE has been changed to "It tastes
as you expected" (from "You taste nothing out of the ordinary").  This
emphasizes that the physical action was completed but that nothing
unusual was detected; the old message could have been read as
suggesting that the object in question had no flavor at all, which
obviously isn't true of most objects.

<p>In addition, UntakeableActor and Person now use messages similar to
those used for TAKE ("The cat won't let you," "Bob probably wouldn't
like that"), since these sorts of actors are meant to exhibit
volition, and in the real world would generally not allow themselves
to be arbitrarily tasted.

</div>

<!------------------->
<div class=entry>

A couple of the default library messages for POUR incorrectly referred
to the direct object where they meant to use the indirect object.
These have been fixed.

</div>

<!------------------------------- 3.0.8 --------------------------------->
<div class="sepbar"><a name='308'></a>3.0.8</div>
<p><b><i>Released 9/12/2004</i></b>
<p>

<div class=firstentry>

<b>Compatibility-breaking change:</b> The class formerly named
ShipboardRoom has been renamed to simply Shipboard.  This name change
is for consistency; most of the other similar mix-in classes are named
as simple adjectives.  You should search your game code for any
mentions of ShipboardRoom and change each to Shipboard.

<p>Note that the new class ShipboardRoom is provided for convenience
as a pre-defined combination of Shipboard and Room.  This means that
any rooms you previously defined with the superclass list
<tt>ShipboardRoom, Room</tt> (and just changed, following the
prescription above, to <tt>Shipboard, Room</tt>) can now be written
simply as <tt>ShipboardRoom</tt>.  This is purely for convenience; you
can leave the class list as <tt>Shipboard, Room</tt> and it will
behave the same way.

</div>

<!------------------->
<div class=firstentry>

<b>Compatibility-breaking change:</b> The class formerly named
OccludingConnector is now called Occluder.  This change emphasizes
that the class is a mix-in that isn't limited to use with sense
connectors.

</div>

<!------------------->
<div class=entry>

<b>Possibly compatibility-breaking change:</b> The parameters to the
enterConversation() method of the ConversationReadyState class have
changed.  The old second parameter, 'explicit', has been deleted and
replaced with a new parameter, 'entry', which gives the TopicEntry (if
any) that triggered the conversation entry.  Any game code that calls
or overrides enterConversation() must be changed to accomodate the
parameter change.

<p>The new parameter gives enterConversation() more information about
what triggered the conversation.  This extra information is necessary
because, without it, the conversation system wasn't able to properly
handle topic entries that were marked as conversational but
non-greeting (that is, the isConversational property is true, but
impliesGreeting is nil).  In the past, such entries were incorrectly
treated as though they were entirely non-conversational, so they
didn't enter an in-conversation state when used in a response.

<p>Note that the same information conveyed by the old 'explicit'
parameter can be inferred from the new 'entry' parameter.  When
'entry' is nil, it means that the conversation entry is explicit,
because it was triggered by a direct action (HELLO, etc.) rather than
a TopicEntry.  When 'entry' is non-nil, it means that the conversation
entry is implied by the TopicEntry.

</div>

<!------------------->
<div class=entry>

<b>Possibly compatibility-breaking change:</b> The ConvNode method
processSpecialCmd() has an additional parameter, as does the
SpecialTopic method matchPreParse().  It's unlikely that any game code
will be affected by this, because games don't normally override these
methods - usually, games just define SpecialTopic keyword lists.

<p>The new parameter in both cases gives the "processed" version of
the player's input.  The default SpecialTopic implementation now
matches the processed version of the input rather than the original
text the player entered.

<p>In the English library, the processed input is the player's
original input with any periods, commas, question marks, exclamation
marks, colons, and semicolons removed, and with any leading "A" or "T"
keyword removed.

<p>The purpose of the change to the parameters of these methods is
that it makes it simpler and more efficient to do this filtering.

<p>Note that the punctuation filtering is new.  We filter out the
punctuation because it's not usually meaningful for matching special
topics.  For example, if the player's input contains the correct
keywords to match a special topic, we usually want to match the
special topic even if the player (for example) put a period or
question mark at the end of the command.

</div>

<!------------------->
<div class=firstentry>

<b>Possibly compatibility-breaking change:</b> The format of the
message generated by DropType.getReportPrefix() has been changed so
that the message is expected to be a complete sentence.  This affects
the library messages floorlessDropMsg, droppingObjMsg, throwHitMsg,
and throwShortMsg (this last one is new in this update).  These
methods and messages are mostly for internal use, but if you override
or call DropType.getReportPrefix() in your code, or if you've
customized any of these messages, you'll need to adjust your own
messages for this change.

<p>The old sentence fragment format had a couple of problems.  First,
it was likely to be problematic for some non-English translations.
Second, it was less flexible than the new full-sentence format, even
in English, for the purposes of adding new "drop type" objects and
of adding new messages composed using the prefix.

</div>

<!------------------->
<div class=entry>

The parser's pronoun antecedent rules have changed slightly.  In the
past, when the player entered a command with multiple noun slots (such
as UNLOCK DOOR WITH KEY), the parser always chose the last-resolved
object as the antecedent for any future pronoun.  This meant that the
parser remembered either the direct object or the indirect object,
depending on the verb.  This rule didn't always produce the results
that you'd expect in natural English conversation, and had the further
drawback that the remembered object varied from verb to verb.

<p>The parser now remembers <i>both</i> objects for two-object verbs,
and waits to make a decision until the player actually enters a
command with a pronoun.  When the player types a singular pronoun (it,
he, she), and the most recent command had multiple noun slots, the
parser performs the standard "verify" evaluation on each potential
antecedent and picks the most logical one.  If more than one
antecedent is equally logical, the parser simply picks one arbitrarily,
and announces the choice in the usual manner.  When the choice is
completely arbitrary, it will always be the direct object of the
two-noun command.

<p>Some examples:

<p>
<pre>
   &gt;LOCK DOOR WITH KEY
   Locked.

   &gt;DROP IT
   Dropped.   <i>(the key, because it's illogical to drop the door)</i>

   &gt;UNLOCK DOOR WITH KEY
   (first taking the key)
   Unlocked.

   &gt;OPEN IT
   Opened.    <i>(the door, because it's illogical to open the key)</i>

   &gt;LOCK DOOR WITH KEY
   (first closing the door)
   Locked.

   &gt;EXAMINE IT
   (the door)
   It's a heavy wooden door.
</pre>

<p>In the last command - EXAMINE IT - the choice of the two potential
antecedents is arbitrary, because it's equally logical to examine the
key or the door.  The parser thus chooses the direct object of the
prior command, and announces the choice to alert the player (in case
she was thinking "it" would refer to the key).

</div>

<!------------------->
<div class=entry>

The new Thing method notifyMoveInto(newContainer) complements the
existing moveInto notification routines notifyRemove() and
notifyInsert().  The new notifyMoveInto() method is called last in the
sequence, after notifyRemove() has been called on the old container
tree and notifyInsert() on the new container tree.  notifyInsert()
gives the object being moved a chance to perform any special
additional processing before the move, or to veto the move (which it
can do by displaying an explanatory message and calling 'exit', just
as notifyRemove() and notifyInsert() are allowed to do).

<p>The new routine has several benefits.  First, it provides the
object being moved with the same sort of notifications that the old
and new containers already receive.  Since it runs along with these
other notifications, it allows the same distinction as those other
notifiers between moves that trigger these side effects (via calls to
moveInto) and those that don't (via direct calls to baseMoveInto)
Second, since the new method runs last, after the notifyRemove() and
notifyInsert() notifications, it has the last chance to veto the move;
this means that if it doesn't cancel the move, then the move will
definitely proceed (at least to the extent that baseMoveInto() will be
called).  Any side effects that must be carried out only when the move
will succeed can thus be safely coded here.

</div>

<!------------------->
<div class=entry>

The parser now provides more helpful error feedback when the player
tries to enter a SpecialTopic command that's not active.

<p>First, the library automatically enters all of the keywords defined
by special topics into the game's dictionary.  This ensures that the
parser won't claim that special topic keywords are unknown if they're
used out of context, as it did in the past.  It was confusing when the
parser claimed that special topic keywords were unknown, because the
parser most certainly did know them some of the time.

<p>Second, when the player enters a command that looks syntactically
invalid, but which doesn't contain any unknown words, the parser scans
recent special topics for a match.  If it finds a match, the parser
will show a new message: "That command can't be used right now."  This
old response - "The story doesn't understand that command" - was
potentially confusing, since the story <i>can</i> recognize the exact
same command at other times.

<p>The parser scans the list of special topics most recently listed in
topic inventories, using the new specialTopicHistory object.  This
object keeps track of a configurable number of the most recent
SpecialTopic suggestions listed; set its maxEntries property, which
defaults to 20, to the maximum number of recent entries to scan.  The
purpose of the limit is to ensure that a scan won't take too long, by
limiting the scan to the specified maximum number of SpecialTopic
items.  The trade-off is that the parser will forget older
suggestions, so they'll be met with the old "story doesn't understand"
message if the player tries them.  However, it seems safe to assume
that the player will also forget about older suggestions, and so won't
think to try them.

<p>If you set maxEntries to nil, it essentially removes the limit to
the number of entries to scan.  The library won't maintain the history
list at all in this case.  Instead, to check an unrecognized command,
the parser will simply scan <i>all</i> SpecialTopic objects in the
entire game, whether or not they've ever been suggested in topic
inventory displays.  This option might be preferable for a game where
the total number of items is small enough that scanning them all
doesn't take an appreciable amount of time.  (Or not.  Some authors
might not want the parser to recognize previously-unseen special
topics at all - even to the extent of saying "that command can't be
used right now" - because doing so could conceivably give away
upcoming plot developments.  That is, if the player accidentally types
a command that happens to match a special topic that hasn't ever been
suggested, the player could infer from the special error message that
the command will do something later in the game.  The chances of
actually giving away anything important this way seem rather remote,
but this sort of thing rubs some authors the wrong way.  If you don't
like the idea of using the different error message for special topics
until after they've been suggested at least once, but you also don't
want a limit on the number of past topics to remember, just set
maxEntries to a very high number.)

</div>

<!------------------->
<div class=entry>

The new property pluralOrder lets you control the order in which a set
of objects is processed when the objects match a plural phrase in a
command.  This property applies to all VocabObjects (which is the base
class for any object with vocabulary words); the arbitrary default
value is 100.

<p>In most cases, the order of processing for the matches for a plural
phrase is arbitrary, so you won't need to worry about this new
property.  Once in a while, though, it's convenient to be able to
control the order of matching.  This is especially useful when objects
have ordinal names (first door, second door, etc), or when objects are
named by relative spatial position (top drawer, middle drawer, bottom
drawer).

<p>Note that the new property only controls the order of processing
within an individual plural phrase.  For example, in the command TAKE
BOOKS AND MAGAZINES, the books will be sorted by their relative
pluralOrder values, then the magazines will be sorted by theirs - but
when the command is processed, all of the books will be taken before
any of the magazines, regardless of the relative pluralOrder values.
This is important because it ensures that commands are processed in
the order specified by the player.

<p>Because pluralOrder and the existing disambigPromptOrder will
probably be used in the same way most of the time, disambigPromptOrder
now returns the pluralOrder value by default.  So, for the common case
that the two properties should have the same value, you can simply set
pluralOrder.

</div>

<!------------------->
<div class=entry>

The new function cls() clears the screen, and takes care of a couple
of chores that should always be done at the same time.  First, the
function clears any text captured in the transcript manager, ensuring
that text that was meant to be displayed before the screen was cleared
won't show up on the new, blank screen.  Second, the function calls
the new gameMain.setAboutBox() method after clearing the screen,
ensuring that any &lt;ABOUTBOX&gt; tag is re-displayed; this is
necessary because HTML TADS discards any old &lt;ABOUTBOX&gt;
information whenever the screen is cleared.

</div>

<!------------------->
<div class=entry>

The new method setAboutBox() has been added to the gameMain() object.
This new method is designed as the place to put your game's
&lt;ABOUTBOX&gt; tag, if you provide one.  The method is invoked
during start-up, and is also called from the new cls() function,
ensuring that the about-box information will be re-displayed each time
the screen is cleared.

<p>The default implementation in GameMainDef does nothing.  The new
method is simply a placeholder for the game's (optional) use.

<p>This change is designed to make it easier to manage your about-box
information.  HTML TADS discards any previous &lt;ABOUTBOX&gt; tag
when the screen is cleared, so it's necessary to re-display the tag
whenever you clear the screen.  If you write your &lt;ABOUTBOX&gt; tag
in the new gameMain.setAboutBox() method, and you always use the new
cls() function to clear the screen (rather than calling the low-level
clearScreen() function directly), the library will automatically keep
yout about-box active.

</div>

<!------------------->
<div class=entry>

You can now control whether or not a given verb accepts the word ALL
in its noun phrases.  By default, every verb accepts ALL.  However, if
you set the new gameMain property allVerbsAllowAll to nil, only the
basic inventory-management verbs (TAKE, TAKE FROM, DROP, PUT IN, PUT
ON) will accept ALL, and every other verb will simply show an error
message ("'All' isn't allowed with that verb").

<p>Some authors like to limit usage of ALL to the basic inventory
verbs, either because of tradition or because they think it's a sort
of "cheating" when a player tries commands like OPEN ALL or EXAMINE
ALL.  This feature is probably of particular interest to writers of
puzzle-oriented games.

<p>In addition to the all-or-(almost-)nothing option setting in
gameMain, you can control ALL acceptance on a verb-by-verb basis.  The
new Action property actionAllowsAll controls whether a particular
Action accepts ALL for its noun phrases.  By default, the base
definition in Action simply returns the value of
gameMain.allVerbsAllowAll.  In addition, the basic inventory verbs
(Take, TakeFrom, Drop, PutIn, PutOn) override actionAllowsAll to
return true.  If you want to enable or disable ALL for an individual
action, you can use "modify" to set the property for that action
class.

</div>

<!------------------->
<div class=entry>

The library uses the new Style Tag &lt;.announceObj&gt; to set the
display style for multi-object announcements.  (These are the little
announcements, of the form "blue book:", that precede the responses
when a command is applied to multiple objects.)

<p>The default display style is to show object announcements in bold
text.  When a command operates on several objects, the response can
get rather lengthy; the new bold-face style for the announcements is
intended to make these responses easier to read by making the
boundaries of the sub-parts more visually apparent.

<p>The new StyleTag object is called announceObjStyleTag.  You can use
"modify" with this object to customize the announcement style, if you
want.

</div>

<!------------------->
<div class=entry>

Actor.lookAround(), Thing.lookAroundPov(), and Thing.lookAroundWithin()
now accept a set of bit flags for the 'verbose' parameter.  'true' and
'nil' can still be passed, and have the same meanings as before, so
existing code doesn't need to be changed.  However, the new bit flags
give you more control over the format of the listing.  The flags, which
can be combined with the "|" operator, are:

<ul>
<li>LookRoomName: include the room name, shown on a line by itself at
the start of the description.
<li>LookRoomDesc: show the full description of the room.
<li>LookListSpecials: show the special descriptions (specialDesc) for
visible objects that have them.
<li>LookListPortables: list the portable items that are visible.
</ul>

<p>Note that lookAroundWithin() <i>automatically</i> adds LookRoomDesc
to the flags if the actor has never seen the room before.

<p>If you pass 'nil' for the 'verbose' parameter, the effect is the
same as passing (LookRoomName | LookListSpecials | LookListPortables).
If you pass 'true', the effect is the same as passing (LookRoomName |
LookRoomDesc | LookListSpecials | LookListPortables).

<p>The main effect of this change is that it lets you generate a room
description without including the room title, which wasn't possible in
the past.  This can be useful for cases where the standard LOOK AROUND
format isn't desirable, such as when describing the view through a
sense connector to another room.

</div>

<!------------------->
<div class=entry>

The new Thing method roomRemoteDesc(actor) lets you customize the way
a room is described when it's viewed by an actor from another room.
The library calls this from Thing.lookAroundWithin() when the actor
who's viewing the room is not within the room being viewed.

<p>Note that none of the standard library commands ever call this new
method, because the basic library doesn't provide any command to view
a remote room.  However, games might provide their own commands to do
so, such as LOOK THROUGH KEYHOLE, and you might want to call
lookAroundWithin() to generate the descriptions in these cases.
Doing so will invoke roomRemoteDesc instead of roomDesc to generate
the room description.

<p>The default Thing.roomRemoteDesc implementation simply calls
roomDesc.  You'll probably want to override this any time you actually
use it, to show a suitable description from the remote actor's point
of view.

</div>

<!------------------->
<div class=entry>

A new Thing method, adjustLookAroundTable(), lets you customize the
set of objects that lookAroundWithin() can mention.  By default, this
routine removes the POV and actor objects (which are usually the same
object) from the table, ensuring that these objects aren't mentioned.

<p>In the past, lookAroundWithin() simply removed the actor object
directly, so the default behavior is the same as in the past.
Separating this out into a new method lets games customize which
objects are mentioned and which aren't for the particular room and
point of view.

</div>

<!------------------->
<div class=entry>

The new Thing method isLookAroundCeiling() determines whether the LOOK
AROUND description for a given object is generated by that object
directly, or by its location.  By default, this routine returns true
if either the object is a top-level room (that is, it has a nil
location), <i>or</i> the object's enclosing location isn't visible.
In either of these cases, since it's not possible to see out to an
enclosing location, the current object has to provide its own interior
description.

<p>This method is called from lookAroundPov(), which formerly
performed the same test directly, so the default behavior hasn't
changed.  This has been separated into a new method because the
default condition isn't always ideal.  For example, if the player's
inside a closed wooden booth with a small window that looks out to the
enclosing location, and the player types LOOK AROUND, we'd want to
describe the interior of the booth, not the outside location.  For
this case, you could override isLookAroundCeiling() for the booth to
return true even though the location is visible through the window.

</div>

<!------------------->
<div class=firstentry>

The new TAction method getDobjInfo() returns the full ResolveInfo
object associated with the current direct object.  Similarly, the
new TIAction method getIobjInfo() returns the indirect object's
ResolveInfo.

</div>

<!------------------->
<div class=firstentry>

The parser now keeps track of the noun phrase that was parsed for
each object involved in the command.  This information is kept in
the ResolveInfo object, in the 'np_' property.  This information can
be used, for example, to obtain the original text of the noun phrase
that was resolved to a given object.  For example, to obtain the
original text that resolved to the current direct object being
processed in an action() method, you could write this:

<p><pre>
   local txt = gAction.getDobjInfo().np_.getOrigText();
</pre>

</div>

<!------------------->
<div class=entry>

Due to a bug introduced in the previous release, the method
PresentLater.makePresentByKeyIf() didn't work correctly if the
condition argument was a function pointer.  In these cases, the
routine called the function on the first object matching the key, and
then used that same true/nil result for <i>every</i> matching object.
(Thus, if the first matching object was to be revealed, every
matching object was revealed; if the first was to be hidden, all were
hidden.)  This has been corrected; the method once again calls the
given function individually for each object matching the key.

</div>

<!------------------->
<div class=entry>

Component objects are now hidden from EXAMINE ALL by default.  Since
components are simply detail features of larger objects, it's usually
enough to examine the larger objects; it usually doesn't make sense to
also include the components separately in EXAMINE ALL responses.

</div>

<!------------------->
<div class=entry>

By default, FOLLOW now reports a more helpful message when there's not
enough information to carry out the command.  In the past, the default
message was simply "You don't know where (the actor) went."  This was
misleading when the real problem was that the actor's departure had
been previously observed, but from some other location.  The new
message is of this form: "The last place you saw (the actor) was (the
room where we last saw him)."  Note that the library now keeps track
of the last place we saw each actor, even when we didn't observe the
actor leaving, to ensure that this new message is always accurate.

</div>

<!------------------->
<div class=entry>

The "badness" levels of some of the grammar rules in the English
parser have been re-ranked, to put the various error conditions in a
different order.  In particular, the "miscellaneous noun phrase" rules
now have a lower badness than any of the "missing noun phrase" rules.
In the past, this relationship was reversed, which caused a subtle
problem when a two-noun verb was used with a noun phrase containing a
word not in the dictionary.

<p>Some background: In the English parser, certain grammar rules are
defined specifically to match certain distinct patterns of erroneous
user input.  The point of matching invalid input is to recognize it
and respond intelligently to it, rather than issue a blanket error
message.  Most of these invalid constructs are marked with "badness"
levels, which tells the parser to match them only as a last resort, so
that we match a valid grammar rule over one of these special error
rules whenever possible.

</div>

<!------------------->
<div class=entry>

In the English grammar, each of the verbs with two noun slots (PUT X
ON Y, ASK X ABOUT Y, etc.) has a corresponding special grammar rule
that includes only the first noun slot (PUT X, ASK X, etc.), for cases
where the player inadvertantly or intentionally types the command with
only one noun.  In the past, these rules weren't marked with "badness"
levels.  Now they are: these are treated as having "badness"
equivalent to that of an empty noun phrase.  This ensures that they'll
be matched only as a last resort, when there isn't a more "correct"
interpretation of the phrase.

</div>

<!------------------->
<div class=entry>

CollectiveGroup objects are now explicitly marked as unlisted in room
or object contents or in inventories (that is, a CollectiveGroup's
isListed, isListedInContents, and isListedInInventory properties now
return nil).  In the past, collective group objects incorrectly showed
up in these listings as separate objects under certain circumstances,
such as when their individuals were self-illuminating (brightness = 1)
and the enclosing room was dark.

</div>

<!------------------->
<div class=entry>

In the past, the description of a dark room listed every visible
self-illuminating object, even including those being carried by the
actor doing the looking.  Now, the description excludes objects in the
actor's inventory, since these objects aren't part of the actor's
surroundings.

</div>

<!------------------->
<div class=entry>

In the past, the INVENTORY command included in its listing any items
that were being directly held, even if they weren't visible, on the
assumption that the actor could identify these items by touch alone.
This has now been refined slightly: instead of unconditionally
including directly-held items in the listing, the library now includes
directly-held items that the actor already knows about, as indicated
by the actor's knowsAbout() method.  The rationale is almost the same
as before, but this change means that we no longer assume that the
actor can identify an item by touch unless the actor already knows
about the item.  Of course, this change doesn't affect the listing of
visible items - visible items are listed whether previously known or
not.

</div>

<!------------------->
<div class=entry>

The "finish option" handler for RESTORE (finishOptionRestore) now
terminates any remaining processing on the command line that triggered
the finish options, when the RESTORE is successful.  This ensures that
when the finish options are triggered from somewhere in the middle of
a command (such as in a beforeAction method), there will be no strange
side effects from carrying out the rest of the triggering command.

</div>

<!------------------->
<div class=entry>

In the English grammar, LOOK OUT is now a synonym for LOOK THROUGH.
This allows constructs like LOOK OUT WINDOW, which is more natural
for some objects than LOOK THROUGH but has the same meaning in
virtually all cases.

</div>

<!------------------->
<div class=entry>

In the English grammar, the acceptable phrasing for the SitOn command
no longer includes "sit <i>object</i>" or "sit down <i>object</i>."
These phrasings aren't grammatical, but they were included to match
intransitive inputs (SIT and SIT DOWN) and then ask for the missing
direct object phrase.  Now, rather than matching the intransitive
forms using the main SitOn rule, they're matched using the SitOnWhat
rule.  The same change applies to the LieOn rules.

</div>

<!------------------->
<div class=entry>

UnlistedProxyConnector.primaryConn is now initialized to TadsObject by
default.  In rare cases, game code might invoke a property of an
UnlistedProxyConnector before the object is constructed; this new
default (rather than nil) provides reasonable behavior in these cases,
without requiring an added run-time test for a nil primaryConn.

</div>

<!------------------->
<div class=entry>

In the English messages, the AutoClosingDoor's announcement (of the
door having automatically closed) now has a leading paragraph break,
to set it off from the room description or other travel report that
usually precedes the announcement.

</div>

<!------------------->
<div class=entry>

The English library's rules have changed slightly for substituting
reflexive pronouns in message strings.  In the past, the library
always substituted a reflexive pronoun when an "objective-case"
parameter matched the subject of the sentence; for example, in the
message string "{You/he} can't eat {the dobj/him}," if the direct
object was the same as the actor, the message would be "You can't eat
yourself" (rather than simply "You can't eat you").  The new rule is
<i>almost</i> the same, but has a new exception: if the <i>parameter
name</i> of an objective-case parameter is the same as that of the
subject of the sentence, the reflexive substitution is not used.

<p>For example, the library now displays "{You/he} close{s} the door
behind {you/him}" as "You close the door behind you."  The old rule
would have used "behind yourself" instead, but the new exception kicks
in because both the subject ("{You/he}") and the objective-case item
("{you/him}") refer to the 'actor' parameter object.

<p>The reason the automatic reflexive substitution exists in the first
place is that it allows you to write a message string that refers to
multiple parameters that <i>might</i> end up being the same object
some of the time.  In the first example ("{You/he} can't eat {the
dobj/him}"), the direct object and the actor might sometimes be the
same, but usually aren't; since the library automatically provides the
reflexive pronoun when the direct object happens to be the same as the
actor, the same message string works for any combination of objects
("You can't eat yourself" vs. "You can't eat the deck chair").
However, this rule is too aggressive without the exception.  The point
of the exception is to give authors exact control in cases where they
know <i>in advance</i> that the subject and objective-case object will
be the same, by virtue of the fact that the message is referring to
the same parameter by name in both cases.  In these cases, there's no
need for the library to provide reflexive pronouns conditionally,
because the author knows in advance that the objects will always be
the same - so the author will know whether or not the reflexive
pronoun is desired, and will write it that way, or not, as desired.

</div>

<!------------------->
<div class=entry>

If an exception occurs during an NPC's turn (in ActorState.takeTurn,
for example), the scheduler will now count the NPC's turn as over, so
that other NPC's get a chance to run before the same NPC takes another
turn.  In the past, an uncaught exception during an NPC's turn
bypassed the turn-counting for the NPC, so the same NPC got another
turn immediately; in some cases, this caused the NPC to try the same
erroneous operation again, which set up an infinite loop as the
erroneous NPC code was invoked over and over without giving anyone
else a chance to run.  The same change applies to fuses, daemons, and
any other "schedulable" object.

</div>

<!------------------->
<div class=entry>

In the English library, SCRIPT ON is now accepted as a synonym for
SCRIPT (for consistency with SCRIPT OFF), and RECORD ON as a synonym
for RECORD.  In addition, the RECORD ON/OFF messages have been changed
to sound less geeky (they formerly referred to "RECORD mode," but now
talk about "command recording" instead).

</div>

<!------------------->
<div class=entry>

In the English library, "inside" and "inside of" are now accepted in
locational qualifier phrases (as in "read the coin inside the box").

</div>

<!------------------->
<div class=entry>

When the player looks behind or through a closed door, the library now
assumes that the player's intention is to open the door to see what's
on the other side.  So, the library now applies an objOpen
precondition to these commands, which will implicitly open the door if
it's closed.

<p>In addition, in the case of LOOK BEHIND, the library uses a special
message if the implicit Open was applied: "Opening the door reveals
nothing unusual."  This message emphasizes that we're looking through
the passage, not at the space created between the door and the
adjacent wall (if such a thing is applicable).

<p>When we look behind a door that was already open, the library
assumes that the player's intention is simply to look at the back side
of the door, or the space between the door and the adjacent wall.  In
this case, the inherited Thing message ("you see nothing unusual
behind the door") is used.

</div>

<!------------------->
<div class=entry>

LOOK THROUGH PASSAGE now has a custom response when the passage is
open: "You can't see much through (the passage) from here."  In the
real world, we can typically look through a passage into the next
room, but the library world model doesn't actually allow us to see
anything in the next room; so we don't want to say that we can't see
through the passage at all, but at the same time we can't actually say
we see anything.  The new default suggests that we can in principle
see some distance through the passage, but not far enough to see
anything in the connected location.

<p>When a passage is closed, the inherited Thing message ("you can't
see anything through (the passage)") is used instead, since a closed
passage is assumed to be something opaque, such as a closed door.

</div>

<!------------------->
<div class=entry>

Looking through, under, or behind a room part now yields a custom
response that says that you simply can't do that, rather than using
the inherited Thing defaults (which say that you can't see anything
there).  For room parts, it doesn't generally make sense to perform
any of these actions, which the new custom messages try to convey.

</div>

<!------------------->
<div class=entry>

If a player types simply GO or WALK, the library now displays a more
helpful message: "You'll have to say which way to go."  In the past,
the parser didn't recognize that phrasing at all, so responded with
the standard unknown-verb message.

</div>

<!------------------->
<div class=entry>

PathPassage now uses a custom message for STAND ON: "If you want to
follow the path, just say so."  The inherited default ("That isn't
something you can stand on") doesn't make a lot of sense for paths,
but at the same time, we don't want to treat every path passage as a
separate nested room, so this message seeks to convey that the action
might be logical in the real-world but isn't required in the game.

</div>

<!------------------->
<div class=entry>

Actor now handles a command of the form PUT ME IN <i>container</i> by
replacing it with ENTER <i>container</i>.  This is done any time the
direct object is the target actor.

<p>In addition, the actor is now excluded in all cases from being the
default direct object for PUT IN.  In the past, the actor was selected
as the default if there was nothing better, which occasionally led to
odd results.

</div>

<!------------------->
<div class=entry>

Actor now treats the commands PUT ON and PUT UNDER as illogical when
applied to oneself (as in PUT ME ON THE TABLE).

</div>

<!------------------->
<div class=entry>

Thing now calls verifyMoveTo() to verify a DROP command <i>only</i>
when the object is being held by the actor performing the command.
When the object isn't being held, the DROP will be illogical on that
basis alone - the object definitely won't be moved, so there's no
reason to verify the move.  This is important because some subclasses
use verifyMoveTo() to report other catch-all conditions ("that's too
heavy to move," etc), which in the past sometimes were reported
instead of the more basic problem ("you're not holding that").  By
avoiding the call to verifyMoveTo() when the object isn't being held,
we ensure that the more basic problem is always reported instead of
any applicable catch-all condition.

</div>

<!------------------->
<div class=entry>

The Immovable class incorrectly handled certain two-object actions
(such as PUT IN, PUT ON, MOVE WITH) by failing in the action()
routine.  This still allowed the <i>other</i> object involved in the
command to handle the action successfully.  For these two-object
actions, the class needs to block the action in the check() routine
instead, which it now does.

</div>

<!------------------->
<div class=entry>

When an AgendaItem throws an exception (including things like 'exit'
signals) out of its invokeItem() method, the library now automatically
marks the agenda item as finished (by setting its isDone property to
true).  In most cases, if an agenda item throws an exception, it's
because something went wrong; since the same thing would probably go
wrong again if the item were tried again, allowing the agenda item to
remain in its "ready" state typically resulted in an infinite loop as
the actor kept trying the same item over and over.  This change avoids
infinite loops in these cases by ensuring that an item that throws an
error isn't retried automatically.

</div>

<!------------------->
<div class=entry>

When an object provides its own custom definition for a library
message (via one of the xxxMsg properties), it can now be defined as a
simple single-quoted string, even if the library method for the
message normally takes one or more arguments.  This makes it more
convenient to define these custom messages.  Of course, you can still
provide a full method definition that takes the same arguments as the
corresponding library message method.

</div>

<!------------------->
<div class=entry>

Settable now applies a touchObj precondition to the SetTo action.
This ensures, for example, that a dial is reachable before it can be
turned to a new setting.

</div>

<!------------------->
<div class=entry>

The Floor class now includes a touchObj precondition for StandOn,
SitOn, LieOn, and (as an indirect object for) PutOn.  This ensures
that a floor in a connected but unreachable room (such as a room
connected by distance) will be ruled out as a potential target object
for these verbs, avoiding poor defaults and unnecessary disambiguation
prompts.

</div>

<!------------------->
<div class=entry>

The touchObj precondition now considers a distant object illogical
during its 'verify' phase.

<p>In the past, this precondition treated an object that was visible
but not reachable as still potentially logical, but at reduced
likelihood.  The reasoning was that the obstruction might be easily
removable via an implied action.  For example, an object inside an
openable glass case could be made touchable by opening the glass
case, which could be performed as an implied action.  However, in
the case of distance, there's not usually any way to remove the
obstruction automatically, so there's no point in considering the
object to be logical, even at reduced likelihood.  The precondition
still does exactly this for objects that aren't at a distance, but
now assumes that distance can't be resolved automatically.

</div>

<!------------------->
<div class=entry>

In the past, if the player used a SEARCH command on an Openable, and
the object was closed, the implied OPEN action showed the
newly-revealed contents of the object.  The main SEARCH command that
triggered the OPEN also showed the Openable's contents, so the
contents were listed twice.  Openable now omits the redundant contents
listing for the implied OPEN when the main command is SEARCH, just as
it's long done when the main command is LOOK IN.

</div>

<!------------------->
<div class=entry>

A "conversational" command (HELLO, GOODBYE, YES, NO) now consistently
counts as a turn for the issuing actor, even when a target actor is
specified (as in "BOB, HELLO").  This corrects a subtle inconsistency
that occurred when a conversational command was directed to an NPC
that had a pending agenda item.  In the past, explicitly directing a
conversational command to such an actor ("BOB, HELLO") prevented the
agenda item from executing on the same turn, because specifying the
target actor caused the turn to count against the NPC's turn counter
rather than the PC's; but leaving out the target actor (as in saying
simply "HELLO") counted the action as a PC turn, allowing the NPC to
carry out its agenda item.  Now, both forms of the command ("HELLO"
and "BOB, HELLO") have the same turn-counting treatment, so a pending
agenda item will be allowed to proceed in either case.

</div>

<!------------------->
<div class=entry>

The HELLO, GOODBYE, YES, and NO commands now find a suitable default
actor to talk to if the target actor isn't specified (that is, if the
command entered is simply something like "HELLO" rather than "BOB,
HELLO").  If there's a current interlocutor, and it's still within
earshot, then it's the default.  Otherwise, we look for a suitable
default direct object for a TALK TO command.  This makes things more
convenient for the player, since it allows the player to omit the
target actor any time only one suitable actor is present.

</div>

<!------------------->
<div class=entry>

In the past, saying BYE to an actor in a conversation-ready state
(that is, an actor ready for a stateful conversation, but not
currently in conversation) caused a run-time error.  This has been
corrected.

</div>

<!------------------->
<div class=entry>

Non-conversational topic entries (those with the isConversational
property set to nil) now leave the actor's ConvNode unchanged.
Conceptually, a response that doesn't involve any conversation
shouldn't affect the thread of an ongoing conversation, so it
makes more sense for such topics to leave the ConvNode unchanged.

</div>

<!------------------->
<div class=entry>

In the past, Thing.lookAroundWithin() generated a slightly strange
description when the point of view was a remote room, and the room
containing the actor doing the looking was visible from the remote
room.  In these cases, the actors were described as being "here" ( as
in "Bob is standing here"), even though the "here" in this kind of
description is more properly the remote point-of-view room.  The
actors are now described as though they're in a remote room ("Bob is
standing in the cave"), which is consistent with the perspective of
the rest of the description.

</div>

<!------------------->
<div class=entry>

In the past, no turn was counted for giving an actor an order (BOB, GO
NORTH) that was refused in the actor's obeyCommand() method.  This
didn't entirely make sense, since merely attempting to give an order
to an actor is an in-game action, from the player's perspective.  This
has been changed so that giving an order that's refused counts as one
turn.

</div>

<!------------------->
<div class=entry>

In the past, if an actor was in an accompanying-travel state, carrying
the actor and then traveling to a new room caused a run-time error.
The run-time error has been fixed.

<p>In addition, the accompanying-travel state is now ignored when the
actor is being carried.  When an NPC is being carried, it will
naturally move along with the actor it's accompanying, just as all of
the actor's other inventory items do by virtue of being carried.  We
therefore don't want the NPC to separately travel to the new location,
because doing so makes the actor drop the NPC.

</div>

<!------------------->
<div class=entry>

Thing now defines the methods canSee(obj), canHear(obj), and
canSmell(obj).  In the past, these were defined only by Actor, not by
Thing, since only actors have senses that allow perception of the
physical surroundings.  In some cases, though, an actor uses an
inanimate device as a point of view (a television monitor hooked up to
a remote camera, for example), and in these cases it's necessary to
check visibility (or other senses) from one inanimate object to
another.  The new methods provide this capability.  They can be
overridden as needed; for example, a camera that operates in the
infrared might want to override canSee() to calculate visibility in a
custom "infraredSight" sense rather than in the basic "sight" sense.

</div>

<!------------------->
<div class=entry>

The NOTE command is now ignored for the purposes of the AGAIN command.
For example, if you type INVENTORY, then type NOTE SOMETHING, then
type AGAIN, the game will repeat the INVENTORY command.  There's no
point in repeating a NOTE command, and NOTE is a sort of side
conversation between player and author anyway, so it makes sense for
AGAIN to act like the NOTE never happened.

</div>

<!------------------->
<div class=entry>

The SAVE command is now ignored for the purposes of AGAIN.  There's no
point in repeating a SAVE command immediately, as nothing will have
changed in the game state between two consecutive SAVE commands, and
hence no re-saving is warranted.

</div>

<!------------------->
<div class=entry>

After a game is successfully restored, the memory of the previous
command is forgotten, so the AGAIN command cannot be used.  This
ensures that there's no confusion about whether AGAIN refers back to
the RESTORE command (which would be pointless, as it would just
re-restore the same state), the previous command in the same session,
or the last command before SAVE from the restored game.

</div>

<!------------------->
<div class=entry>

When a "finish options" menu is presented (with finishGame() or
finishGameMsg()), and the player selects the UNDO option, the library
now treats UNDO as the last command for the purposes of AGAIN.  That
is, if the player answers a finish-options prompt with UNDO, and then
types AGAIN, the library performs another UNDO.  (In the past, the
game repeated the command that led to the finish-options prompt, since
that was the last actual command.  However, most players wouldn't
think to make this distinction, and wouldn't want to repeat whatever
command led to the game-ending prompt anyway, so the most reasonable
interpretation of an immediate AGAIN is to perform another UNDO.)

</div>

<!------------------->
<div class=entry>

The RESTORE command is now ignored for the purposes of the UNDO
command.  When a RESTORE succeeds, there's no way to undo anything:
the restore itself can't be undone, and the incoming restored state
initially doesn't have any undo history.  When the RESTORE fails, it
won't make any changes to the game state, so there's nothing about the
RESTORE itself to undo.  The main effect of this change is that typing
UNDO after a failed RESTORE undoes the last undoable command
immediately before the RESTORE.

</div>

<!------------------->
<div class=entry>

In the past, if the player typed an OOPS command at the wrong time
(when there wasn't any spelling error to correct), it was counted as a
turn.  This was undesirable because OOPS is a meta command, not an
in-game action.  The command no longer counts as a turn.

</div>

<!------------------->
<div class=entry>

In the English library, a string pre-parser now wraps the comment text
of a NOTE command in quotation marks, <i>if</i> the text contains any
punctuation marks or the word THEN.  This allows players to enter
arbitrary free-form text in NOTE remarks without any danger of
confusing the parser.

</div>

<!------------------->
<div class=entry>

The formatting in the English instructions has been tweaked slightly
to make it more consistent.  In addition, the parsing of the responses
to the INSTRUCTIONS prompt had a couple of small problems that have
now been corrected.

</div>

<!------------------->
<div class=entry>

A bug in the English library caused message substitution strings of
form "{it's dobj/he's}" (that is, with an apostrophe-S on each example
word, and the parameter name written in the middle of the two example
words) to be expanded incorrectly.  This has been corrected.

</div>

<!------------------->
<div class=entry>

In the English library, the methods (theNamePossNoun, theNamePossAdj)
that build the default possessive name based on the base name of an
object now add an apostrophe-S to a plural name that doesn't end in
"s".  In the past, a bare apostrophe was always added to a plural
name, which produced the wrong results for certain words (the men',
the children', the fish').

</div>

<!------------------->
<div class=entry>

The English library's method that builds the default plural name of
an object (pluralNameFrom) now handles abbreviations more in keeping
with conventional English usage:

<ul>

<li>For single letters, the method now adds an apostrophe-S to small
letters (a's, b's, c's) and to the capital letters A, E, I, M, U, and
V (A's, E's, etc).  For other capital letters, and for non-letters,
the method simply adds an "s" (Bs, Cs, Ds).  (The apostrophe-S
capitals are special because they could be confused with words or
common abbreviations if we just added an "s".)

<li>For words that end in a capital letters or a digit, the method now
just adds "s" (CPAs, PCs, MPs, 1970s, 20s).

<li>For words that end in a period, the method adds apostrophe-S
(Ph.D.'s, M.A.'s).

</ul>

</div>

<!------------------->
<div class=entry>

The new Thing property objInPrep can be used to specify the
preposition to use when describing another object as being within a
given object.  In the English library, the default for Thing is 'in'.
Note that the existing property actorInPrep is now defined by default
as returning the same value as the new objInPrep, since for most
purposes they have the same meaning.

</div>

<!------------------->
<div class=firstentry>

A new message is displayed when a Throw command fails because a
DistanceConnector is in the way.  In the past, the library used the
default Thing message, which describes the projectile as bouncing
off the object that's in the way.  In the case of a distance connector,
this doesn't make any sense.  The library now uses a custom message
that describes the projectile as falling short of the target.

</div>

<!------------------->
<div class=firstentry>

In the past, if an object was thrown through a MultiLoc connector to a
separate top-level room, the object sometimes incorrectly landed on
the originating side of the connector rather than on the target side.
This only happened when the MultiLoc was a peer of the target.  The
thrown object now correctly lands within the target's top-level
location rather than within the origin's top-level room.

</div>

<!------------------->
<div class=entry>

The ComplexContainer class now refers the methods isOpen, isLocked,
makeOpen, and makeLocked to the subContainer, if it's non-nil.  A
complex container appears in the game world as effectively enclosing
the contents of its sub-container, because the sub-container doesn't
usually appear as a distinct object in the game world, so the apparent
open and locked status of the complex container are almost always the
same as for its sub-container.  These new referrals make it a little
easier to write code by removing the need to refer explicitly to the
sub-container when checking or changing the open or locked status of a
complex container.

</div>

<!------------------->
<div class=entry>

An error in BasicOpenable.makeOpen() caused a run-time error ("wrong
number of arguments") in certain cases when a BasicOpenable was used
with multiple inheritance.  In particular, the error ocurred when an
object derived from BasicOpenable also had at least one additional
superclass which itself defined makeOpen(), and the additional
superclass was placed after the BasicOpenable subclass in the object's
superclass list.  This has been fixed.

</div>

<!------------------------------- 3.0.7 --------------------------------->
<div class="sepbar"><a name='307'></a>3.0.7</div>
<p><b><i>Released 6/12/2004</i></b>
<p>

<div class=firstentry>

The default rules in Thing and NonPortable for contentsListed and
contentsListedInExamine weren't quite right, so they've been changed
slightly.  The new default rules are that an object's contents are
<i>always</i> listed when the object is directly examined, and they're
listed in "indirect" examinations if (1) the object is itself
mentioned somehow in the indirect description, and (2) its contents
would be listed in a direct examination.

<p>(A couple of definitions might help.  A "direct examination" is
what happens when the player explicitly EXAMINEs the object; an
"indirect examination" occurs when looking at the room, showing an
inventory listing, or directly examining an enclosing object.  An
object is "mentioned somehow" in an indirect description if either (1)
it's included in the basic generated list of portable items within the
enclosing object that's being examined, as determined by the isListed
property, or (2) it shows as special description, as determined by the
useSpecialDesc method.)

<p>The reasoning behind the new rules is as follows.  First, on
directly examining an object, its contents should almost always be
mentioned; we'd want to conceal the contents only in unusual cases, so
the default for contentsListedInExamine is simply 'true'.  Second,
when indirectly examining an object, we'd normally want its contents
to be included in the description, since they're also, indirectly, the
contents of the enclosing object being examined; however, when the
object itself isn't mentioned in the indirect examination, then we
probably don't want to mention its contents, either.  Furthermore,
if for some reason we've chosen to conceal the contents even when
the object is directly examined, then we almost certainly want to
conceal the contents in indirect examinations as well.

<p>The rule is slightly different, and simpler, in NonPortable:
contentsListed simply returns the value of contentsListedInExamine.
The reason for this different default is that a NonPortable is almost
always a fixed feature of its enclosing objects, and as such is
almost always mentioned, to the extent it merits mentioning, as part
of the custom description of the room or containing object.  This is
sometimes accomplished with a specialDesc, but not always, so the
absence of a specialDesc isn't sufficient reason to think that the
object isn't mentioned.  Since a NonPortable almost always gets some
kind of mention in indirect examinations, then, the default is that
its contents are listed in these cases, too, as long as they'd be
listed in a direct examination.

</div>

<!------------------->
<div class=entry>

The Consultable class now requires that the object be both touchable
and visible for the Consult action (in the past, it only had to be
touchable).  Consultables are typically things like books or maps
whose contents are read visually, so in most cases it only makes sense
to consult a consultable when it's visible.  This change prevents
lookup up information in a consultable while in the dark, for example.

</div>

<!------------------->
<div class=entry>

The new property disambigPromptOrder can be given to any VocabObject
(any simulation object with vocabulary words) to control its ordering
in an interactive disambiguation prompt ("Which book do you mean, the
red book, or the blue book?").  When a disambiguation prompt is shown,
the objects in the prompt are listed in ascending order of this
property value.  By default, disambigPromptOrder is 100; since all
objects have this same default, if you don't override it for any
objects, the ordering of disambiguation lists will be arbitrary.

<p>Arbitrary ordering is usually fine.  However, it's nice to be able
to control the order when objects have ordinals in their names ("first
book," "third button," etc), to make the list order match the nominal
order.  For example, if you have a group of books named "first book,"
"second book," and "third book," you could give these objects
disambigPromptOrder values of 101, 102, and 103, respectively.

</div>

<!------------------->
<div class=entry>

When the parser processes a response to an interactive disambiguation
question ("Which book do you mean..."), it now takes a vocabulary
match to an ordinal name as superseding the alternative interpretation
as a list position.  For example:

<p><pre>
   Which book do you mean, the red book, the first black book, or the
   second black book?
<br>
<br>   &gt;second
</pre>

<p>The parser will now interpret "second" as referring to "second black
book."  In the past, it took this to mean the second item in the list,
which in this case is "first black book"; this is hardly ever what
the player means in these cases, though.

<p>(This change is actually a bug fix.  The parser already had logic
to apply this precedence order, but it didn't work properly.  In
particular, the "adjective ending" preference - the preference for
avoiding a phrase that ends in an adjective - superseded the ordinal
preference.  Adjective endings are obviously not a problem for
disambiguation responses, though, so this has been changed.)

</div>

<!------------------->
<div class=entry>

When the parser asks the player for disambiguation help to choose
among several items that can be distinguished only by their location,
and some of the items are in different top-level locations from the
player character, the parser now describes the remote locations using
the remote room names (rather than with the default "floor" or
"ground" container, as was formerly the case).  This helps ensure
that objects are distinguished properly when several top-level
rooms are connected by sense connectors.

<p><pre>
   Which coin do you mean, the one on the floor, or the one on the
   balcony?
</pre>

<p>In a related change, the parser now chooses a "local"
interpretation of a locational qualifier in cases of ambiguity.  For
example, if the player were to answer the question above with "the one
on the floor," the parser would now assume that the player is talking
about the coin in the local location (i.e., within the player
character's top-level enclosing room).  In the past, if the balcony
also had a floor, the locational qualifier would have been ambiguous.

</div>

<!------------------->
<div class=entry>

The new function dataTypeXlat(val), defined in the system library file
_main.t, returns the "translated" datatype for the given value.  This
is almost identical to dataType(val), except that when 'val' is an
anonymous function, the new dataTypeXlat() returns TypeFuncPtr rather
than TypeObject.  In most cases, it's convenient to treat an anonymous
function pointer value as though it were an ordinary static function
pointer, because the two types are almost interchangeable in their
usage; this function makes it easier to code such cases, because you
don't have to worry about these two different ways that a
function-pointer-like value might appear.

</div>

<!------------------->
<div class=entry>

The new class AskTellShowTopic lets you combine responses for an
object for ASK ABOUT, TELL ABOUT, and SHOW TO in a single topic
response object.  Players sometimes find SHOW TO to be more natural
than ASK ABOUT when an object is present and visible; this new class
makes it convenient when you want to handle either command the same
way.

</div>

<!------------------->
<div class=entry>

A bug in Thing.lookAroundWithinContents caused an infinite loop when
attempting to describe a location in which three or more top-level
rooms were linked by sense connectors.  This is now fixed.

</div>

<!------------------->
<div class=entry>

In 3.0.6q, BulkLimiter defined lookInDesc as doing nothing.  This was
problematic because BulkLimiter is inherited by some special types of
containers, such as Underside and RearSurface, that don't have
interiors for the purposes of LOOK IN.  The problem showed up in
Underside and RearSurface objects: attempting to LOOK IN these
objects showed no reply at all, hence yielded the library's default
"Nothing obvious happens" message.

<p>BulkLimiter no longer defines this property at all.  Instead, this
functionality has been moved to Container and Surface.  Furthermore,
BulkLimiter.examineInterior no longer shows the lookInDesc; instead
Container and Surface now show the lookInDesc as part of their
action() handler for the LOOK IN command.

</div>

<!------------------->
<div class=entry>

The new Thing method hideFromDefault() is similar to hideFromAll(),
but indicates that the object should be hidden from being used as a
default for the given action (that is, it won't be considered as a
possible default when the player types a command that omits one or
more required noun phrases).  By default, this simply returns what
hideFromAll() returns for the same action, since in general an object
that's hidden from ALL should also be ignored for defaulting.

<p>This is a coarser-grained mechanism than using verify() routines
for individual actions, but it's more convenient when you want to
exclude an object from being used as a default for a large number of
actions.

</div>

<!------------------->
<div class=entry>

gActionIs(a) now returns true if 'a' is one of the specific-direction
travel subclasses (NorthAction, SouthAction, etc), and the current
action is a base Travel action that's going the same direction.  This
makes it possible to test for a NORTH command simply by testing
gActionIs(North), which is what you would have expected even in past
versions if you hadn't known better.

<p>(In the past, it was necessary to write a test like this instead:
(gActionIs(Travel) &amp;&amp; gAction.getDirection ==
northDirection).  This two-part test was required because the grammar
rules for NORTH, SOUTH, etc. generate the base Travel action instead
of the specific-direction subclasses.  The grammar rules still do
this, but gActionIs() now calls a new Action method, actionOfKind(),
which TravelAction overrides to encapsulate the two-part test; since
TravelAction does the test for you, there's no longer any need to
write it out by hand.  You can still write the two-part test if you
prefer, and it still works the same as it did before, but it's easier
and clearer to just write gActionIs(North) and the like.)

</div>

<!------------------->
<div class=entry>

The algorithm in Actor.tryMakingRoomToHold has been improved slightly.
(This is the routine that automatically frees up space in an actor's
hands, when the space is needed for the current explicit action, by
moving things being held into "bags of holding.")  The change is a bit
heuristic, but it should work well in most cases.  The new rule: when
there are at least four items that can be moved into bags of holding,
the routine will now find the two that were picked up most recently
and move them to the end of the list of possible items.  In practice,
it's rare to have to put away more than one or two items for a single
action, so this change effectively ensures that the items picked up
most recently won't be put away automatically.

<p>The point of this change is to avoid annoying situations where the
game automatically puts away an object that you just picked up in
order to do something with it.  These situations were especially
annoying when they were entirely automatic (for example, the game
picked up an object automatically, then put it away automatically in
order to make room to pick up another object automatically, then had
to go get the first object out again in order to use it).  It was
rare for this to happen, but it looked pretty silly when it did.

<p>In a related change, the library now arranges the order of putting
things away to ensure that if object A goes inside bag of holding B,
and B goes inside another bag of holding C, then A will be put in B
before B is put in C.  This was almost always the result anyway due
to affinity ordering, but proper nesting order is now explicitly
assured.

</div>

<!------------------->
<div class=entry>

There are two new "illogical" status types that "verify" routines can
use to indicate the logicalness of an action with greater precision.
The library uses these new types when appropriate in its action handlers.
The new types are:

<ul>

<li>illogicalAlready() - this indicates that the action is illogical
because the condition the command seeks to create is already in
effect.  For example, we're trying to TAKE an object that the actor is
already holding, or we're trying to OPEN an object that's already
open.  This new type is almost the same as illogicalNow(), but
provides more detail about the condition.

<li>illogicalSelf() - this indicates that the action is illogical
because it's attempting to use an object on itself in some invalid
way.  For example, we're trying to PUT something inside itself.  This
type is almost the same as illogical(), with the added detail that
it's the self-application that makes the command impossible to carry
out.

</ul>

</div>

<!------------------->
<div class=entry>

The Passage class now considers a closed passage to be invisible in a
dark room.  The reasoning is that, when a passage is open, enough
light from the adjoining room (if the adjoining room is lit) comes
through the passage to make the passage itself visible, although not
enough comes through to light the current room; but when a passage is
closed, not even this small amount of light comes through the passage.

</div>

<!------------------->
<div class=entry>

In the past, the parser matched a plural phrase (such as EXAMINE
BOXES) to the most likely subset of the matching in-scope objects, as
determined by the "verify" logicalness ranking.  This was too
restrictive; it wasn't at all the common-sense interpretation that
most users would expect from a plural usage, which is simply to match
everything that matches the vocabulary.

<p>This has been changed.  There are two possible behaviors, which you
can control via a global configuration property,
gameMain.filterPluralMatches:

<ul>

<li>If gameMain.filterPluralMatches is true, the parser excludes
objects from matching the plural phrase if their "verify" routines
include an "illogical-already" or an "illogical-self" result.  This
means, for example, that TAKE BOOKS will exclude any books that are
already being held, DROP BOOKS will exclude any books that aren't in
the player's inventory.  This is the default.

<li>If gameMain.filterPluralMatches is nil, the parser simply uses
<b>all</b> vocabulary matches for a plural.

</ul>

</div>

<!------------------->
<div class=entry>

The English parser now handles pronouns better in the recently-added
command phrasing TELL <i>actor</i> TO <i>do something</i>.  In
particular:

<ul>

<li>A reflexive pronoun that agrees in number and gender with the
actor will be treated as referring to the actor, as long as there's
not a valid interpretation internal to the predicate.  For example,
TELL BOB TO HIT HIMSELF will treat HIMSELF as referring to Bob.
However, TELL BOB TO ASK BILL ABOUT HIMSELF will treat HIMSELF as
referring to Bill, since that interpretation is entirely
self-contained within the predicate.

<li>A regular pronoun that agrees in number and gender with the
actor will be treated as referring to the actor.  This is especially
important with possessives: TELL BOB TO DROP HIS BOOK will treat
HIS as referring to Bob.

<li>A second-person pronoun is now considered to refer to the
player character, rather than to the target actor.  For example,
TELL BOB TO HIT YOU is taken to mean that Bob should hit the player
character.

<li>The target actor is set as a pronoun antecedent for subsequent
commands from the issuing actor.  For example, after TELL BOB TO GO
NORTH, the command FOLLOW HIM will mean to follow Bob.

</ul>

</div>

<!------------------->
<div class=entry>

The English parser now rejects the phrasing TELL <i>first actor</i> TO
TELL <i>second actor</i> TO <i>do something</i>.  (It formerly
accepted this, but it didn't handle it as stated: in effect, the first
TELL TO was ignored, so the command was treated as simply TELL
<i>second actor</i> TO <i>do something</i>.)

</div>

<!------------------->
<div class=entry>

The English parser now accepts the commands SIT DOWN and LIE DOWN.
The parser accepts these stated intransitively (i.e., without a
direct object), but treats them as synonyms for SIT ON (something
unspecified) and LIE ON (something unspecified), respectively.  That
is, the parser tries to find a suitable default object to sit on, and
prompts the player for the missing object it no default can be
assumed.

</div>

<!------------------->
<div class=entry>

In the English parser, when the command phrasing involves what looks
like an indirect object phrase that doesn't match anything in the
grammar, a "miscellaneous preposition phrase" production is matched.
This type of production is now more consistent about reporting that
"the story doesn't understand that command," to indicate that the
structure of the verb phrase was unrecognized.  In the past, if the
the direct or indirect object phrases were themselves unresolvable,
the parser showed that error instead; this was often less useful,
because the root problem in these cases is really that the overall
verb phrasing can't be parsed.

</div>

<!------------------->
<div class=entry>

The NOTE command now shows a warning if the transcript isn't
currently being saved (with the SCRIPT command).  This command's main
purpose is to let the player embed a comment in the session
transcript, as a means of sending feedback to the author.  There's
not a lot of point in using the command when the transcript isn't
being saved, so there's a good chance that a player using the command
thinks that a SCRIPT command is already in effect.  The warning calls
the player's attention to this.  The warning is only issued the first
time that NOTE is used without logging in effect, but this is reset
each time logging is started and then stopped.

</div>

<!------------------->
<div class=entry>

In the past, real-time events created during pre-initialization
weren't set up properly, because the real-time manager's internal
clock wasn't initialized until run-time start-up.  The clock now
has a static initializer, ensuring that events created during preinit
will have a valid time base.

</div>

<!------------------------------- 3.0.6q --------------------------------->
<div class="sepbar"><a name='306q'></a>3.0.6q</div>
<p><b><i>Released 5/9/2004</i></b>
<p>

<div class=firstentry>

<p><b>Possible compatibility-breaking change:</b> The standard parser
dictionary has been renamed from G_dict to cmdDict (for "command
dictionary").  The dictionary is simply an object, and the new name is
more consistent with other parser object names (in particular,
cmdTokenizer, the standard parser tokenizer).

<p>It's relatively uncommon for game code to refer to the main
dictionary directly, but you should search your code for references
to G_dict and change the name to cmdDict.


</div>

<!------------------->
<div class=entry>

<p><b>Possible compatibility-breaking change:</b> The methods that
describe an actor's location have been changed, in order to improve
consistency and to simplify the code structure.  These changes are
mostly internal to the library, so they're unlikely to affect
existing code unless you've made some rather low-level customizations.

<p>The changes involve a lot of renaming and rerouting of internal
method calls.  The list of changes below is divided into groups of
related changes.

<p><b>Group 1:</b> The "nominal actor container" methods have been
consolidated into a single method.

<ul>

<li>The methods getNominalStandingContainer,
getNominalSittingContainer, and getNominalLyingContainer have been
deleted.  In their place is a single new method,
getNominalActorContainer, which takes the posture as a parameter.
Since it's almost never necessary to differentiate the nominal actor
container by posture, the single method approach is more convenient,
and it's also more readily extensible to new postures.

</ul>

<p><b>Group 2:</b> The Posture object has been taken out of the loop,
as it were, for the methods that describe actors.  The Posture
object's role in the past was to break out these various methods into
a separate version for each posture, and then further dispatch to the
actor's nominal location: for example, the okayPostureChange method
was split up into okayStand, okaySit, and okayLie.

<p>The original idea was that locations might want to customize
extensively by posture, but in practice the multiplicity of methods
turned out to be more trouble than it was worth.  With the present
change, each set of Stand/Sit/Lie variations is now consolidated back
into a single method, which makes the Posture object's role
unnecessary, allowing it to be removed from the dispatch chain.
It's still used in generating the final message, but in most cases
this is now a simple matter of getting the posture's participle
("sitting", etc) from the Posture object and using it to build the
message string.

<p>The following list of changes will look daunting, but it's
unlikely that existing game code will be much affected, as these
methods were always meant mostly for internal use in the library.

<ul>

<li>Actor.actorHereDesc changes:

<ul>

  <li>Posture.actorHereDesc and libMessages.actorHereDesc have been
  deleted.  Instead, the actor calls directly to roomActorHereDesc on
  the nominal actor container.

  <li>The BasicLocation, Floor, and libMessages methods
  actorStandingHere, actorSittingHere, and actorLyingHere have been
  deleted, and replaced by the new method roomActorHereDesc.

  <li>The libMessages methods actorHereStandingOn, actorHereSittingOn,
  and actorHereLyingOn have been deleted, and replaced by the new method
  actorInRoom.

</ul>

<li>Actor.actorThereDesc changes:

<ul>

  <li>BasicLocation, Floor, and libMessages provide definitions of the
  new method roomActorThereDesc.

  <li>NestedRoom.roomRemoteActorDesc has been renamed to
  roomActorThereDesc, and the implementation has been moved from
  NestedRoom to BasicLocation.

  <li>libMessages.nestedRoomRemoteActorDesc has been renamed to
  actorInRemoteNestedRoom, and libMessages.roomRemoteActorDesc has
  been renamed to actorInRemoteRoom.

</ul>

<li>Room status name changes - these affect the mechanism that
generates room title addenda such as "(sitting in the chair)":

<ul>

  <li>Posture.statusPosture has been deleted.  Instead, the (newly
  renamed) Actor.actorRoomNameStatus now handles this directly.

  <li>Actor.statusPosture has been renamed to actorRoomNameStatus, to
  clarify and reflect the broader potential of its purpose.

  <li>The BasicLocation, Floor, and libMessages methods
  statusStanding, statusSitting, and statusLying have been deleted,
  and replaced by the new method roomActorStatus.

  <li>The libMessages methods statusStandingOn, statusSittingOn,
  and statusLyingOn have been deleted, and replaced by the new
  method actorInRoomStatus.

</ul>

<li>Actor posture description changes:

<ul>

  <li>Posture.actorPostureDesc has been deleted.  Actor now handles
  this directly.

  <li>The BasicLocation, Floor, and libMessages methods actorStandingDesc,
  actorSittingDesc, and actorLyingDesc have been deleted, and replaced
  with the new method roomActorPostureDesc.

  <li>The libMessages methods actorStandingOnDesc, actorSittingOnDesc,
  and actorLyingOnDesc have been deleted, and replaced by the new
  method roomActorPostureDesc.

</ul>

<li>Posture change acknowledgment changes - these affect the mechanism
that generates the default responses to commands like SIT and STAND:

<ul>

  <li>Posture.okayPostureChange has been deleted.  Actor now handles
  this directly.

  <li>The BasicLocation and Floor methods okayStand,
  okaySit, and okayLie have been deleted, and replaced by the new
  method roomOkayPostureChange.

  <li>The libMessages methods okayStandMsg, okaySitMsg, and okayLieMsg
  have been replaced by the new method okayPostureChangeMsg.

  <li>The playerActionMessages and npcActionMessages methods
  okayStandOnObjMsg, okaySitOnObjMsg, and okayLieOnObjMsg have
  been deleted, and replaced by the new method roomOkayPostureChange.

</ul>

<li>Changes to the mechanism that mentions that an actor is
sitting/lying/standing in a nested room, as part of the EXAMINE
description of the nested room:

<ul>

  <li>Posture.listActorPosture has been deleted.  Actor.listActorPosture
  now calls the nominal actor container directly instead.

  <li>The BasicLocation and Floor methods listActorStanding,
  listActorSitting, and listActorLying have been deleted, and replaced
  by the new method roomListActorPosture.

  <li>The libMessages methods listActorStandingOn, listActorSittingOn,
  and listActorLyingOn have been deleted.  Their role has been subsumed
  by actorInRoom.

</ul>

</ul>

<p><b>Group 3:</b> Actor "grouping" is now handled in BasicLocation,
rather than only in NestedRoom.

<ul>

<li>The implementation of listWithActorIn() that was formerly in
BasicChair has been moved to NestedRoom.  This means that actors
without special descriptions are now grouped by default with other
actors without special descriptions who are present in the same
location and posture.

<li>NestedActorGrouper has been renamed to RoomActorGrouper, since
it's now used for any room with actors to be grouped, not just nested
rooms.

<li>In order to accommodate the wider range of cases where actor
group lists are now generated by default, RoomActorGrouper now
determines two additional bits of information: it gets the nominal
actor container for the location containing the actors being listed,
and it checks to see if the point-of-view actor is viewing the
listing from a "remote" location (a separate top-level room
connected by a sense connector).  It uses this information to generate
the group prefix and suffix messages differently than before:

<ul>

<li>If the nominal actor container is visible, the grouper calls the
new methods actorInGroupPrefix() and actorInGroupSuffix() on the
nominal actor container to generate the prefix and suffix messages.
BasicLocation and Floor provide suitable default definitions of these
new methods.

<li>If the nominal actor container isn't visible, but the actors are
in a remote location, the new libMessages methods
actorThereGroupPrefix() and actorThereGroupSuffix() are used.

<li>Otherwise, the new libMessages methods actorHereGroupPrefix()
and actorHereGroupSuffix() are used.

</ul>

<li>Actor.actorListWith now returns an empty list if 'self' overrides
specialDesc.  This ensures that a specialDesc defined on the actor
will take precedence over any list group applied by the location.
(This is more important now that BasicLocation applies actor grouping
by default.)

<li>Actor.actorHereListWith has been renamed to actorListWith.  This
method is used whether the actor is local, distant, or remote, but
the old name incorrectly suggested the existence of a separate
actorThereListWith in parallel with the actorHereDesc/actorThereDesc
pair.

</ul>

<p><b>Group 4:</b> Miscellaneous minor changes to the generation
of remote room actor descriptions.

<ul>

<li>NestedRoom.roomRemoteActorDesc now generates a more elaborate
message by default, describing not only the actor's immediate
location, but its outermost visible location as well.  If the actor's
outermost visible location isn't the same as 'self', the method now
invokes libMessages.nestedRoomRemoteActorDesc, which generates a
message of this form: "Bob is in the dining room, sitting in the
chair."

<li>The method inRoomName that was formerly defined in Room is now
defined in Thing instead.  This ensures that a suitable default
remote room name will be generated for nested rooms as well as
top-level rooms.  In addition, the method now simply returns
actorInName by default, which ensures that the preposition used in
the default remote room name will match the one customized via
actorInPrep, if necessary.

</ul>

</div>

<!------------------->
<div class=entry>

The new TravelConnector method connectorGetConnectorTo() gives a
travel connector a chance to scan any "secondary" connectors it knows
about for a connection to a given destination.  In some cases, a
travel connector encapsulates other travel connectors; these are
secondary connectors in the sense that they're linked to the room only
from the first connector, and thus the room can't find them on its
own.  This new method provides a way for a room to query a connector
for any secondary connectors it knows about, in order to find a
connector to a given destination.  The base TravelConnector class
provides a default implementation suitable for most subclasses,
and AskConnector overrides the method to search its list of
secondary connectors.  Thing.getConnectorTo calls the new method
when searching for a connector to a given destination.

<p>The immediate practical benefit of the new method is that it makes
it possible for scripted NPC travel to traverse AskConnectors.  In the
past, an NPC encountering an AskConnector was typically unable to
proceed, since the AskConnector didn't directly link to the
destinations of its underlying connectors, and the underlying
connectors typically weren't linked directly as directions to the
enclosing room.  This made it impossible for the scripted NPC to find
a suitable connector, and thus blocked the scripted travel.

</div>

<!------------------->
<div class=entry>

The properties for choosing whether or not to list the contents of an
object to list in EXAMINE and LOOK AROUND descriptions have been
expanded slightly to provide more control and better consistency.
These changes are all in the Thing class.

<p>The isListed property now returns, by default, the value of
isListedInContents.  The meanings of these properties haven't
changed: isListedInContents controls whether or not the object is
listed when examining the object's <i>direct</i> container, whereas
isListedInContents controls listability for examining <i>indirect</i>
containers, including the enclosing room.  The reason for this change
is that it's rare that we'd want an object to be unlisted when its
direct container is examined, but still want it to be listed when
enclosing containers are examined (whereas the reverse isn't entirely
uncommon, since we sometimes want to mention an object only as a
detail of its direct parent, but not of the broader room context).

<p>The new property contentsListedInExamine lets you control whether
or not an object's direct contents are listed when the object is
examined directly.  In the past, you could do this only by overriding
examineListContents, but the new property makes it easier to control
this behavior.  The new property returns the same thing that
contentsListed used to return.

<p>The contentsListed property now returns the value of
contentsListedInExamine by default.  This is parallel to the change
to isListed.

<p>The new method getListedContentsInExamine() returns the list of
direct contents that should be listed when the object is examined.
This new method is the direct-examination equivalent of the existing
getListedContents() method, and returns the same value that
getListedContents() formerly returned: the subset of direct contents
that appear in the sense info table passed to the method.

<p>The getListedContents() method now simply returns the result
of calling getListedContentsInExamine().

<p>The method examineListContentsWith() now calls
getListedContentsInExamine() to obtain the list of direct contents to
list when examining an object.  In the past, this used the 'contents'
property.  The method also checks the value of
contentsListedInExamine, and skips the entire listing if this
property is nil.

<p>These changes are all designed to be compatible with existing
code.  They should simply add more flexibility and make certain
behaviors easier to customize, but existing code shouldn't be
affected.

</div>

<!------------------->
<div class=entry>

In 3.0.6p, the library started listing the visible, portable contents
of "remote" rooms as part of each room description.  The
implementation had a problem when MultiLoc objects were involved,
though: if a MultiLoc object appeared in more than one of the
connected top-level rooms <i>and</i> had portable contents, those
contents were listed several times - once for each connected
top-level room in which the MultiLoc appeared.

<p>This problem has been corrected: the room description generator
now ensures that a MultiLoc's contents appear only once.  To do this,
the room description code now excludes each object that is also
located in the "local" top-level room <i>or</i> in any connected
remote room whose contents listing has already been generated.

</div>

<!------------------->
<div class=entry>

NestedRoom now overrides roomRemoteActorDesc() to describe the actor
as being in the nested room.  In the past, if the nested room's
location was visible, the nested room deferred to the location to
provide the description.  This produced misleading messages, because
it described the actor as being in the outermost visible room
containing the actor - which was technically true, but left out the
important information about the intermediate nested room.

</div>

<!------------------->
<div class=entry>

Noise and Odor objects no longer include themselves in LISTEN TO ALL
and SMELL ALL, respectively.  These objects formerly did include
themselves in ALL for these commands, since the commands are
obviously highly applicable.  However, because these objects are
intangible, it usually doesn't make sense from the player's
perspective to consider them in ALL, which a player usually thinks of
as applying to the set of discrete, visible objects.  In practice,
including these in ALL was often problematic because these intangible
objects are usually not given names or vocabulary; they usually exist
only to model a feature of their source object, and aren't meant to
look like separate objects to the player.

<p>Along the same lines, Vaporous objects <i>are</i> now included in
EXAMINE ALL, SMELL ALL, and LISTEN TO ALL.  These objects do have a
visible presence, so it makes sense to include them in commands that
examine everything in sight with any sense.

<p>For particular Noise and Odor objects that you do want to
participate in LISTEN TO ALL and SMELL ALL, just override
hideFromAll() to return true for the desired action or actions.

</div>

<!------------------->
<div class=entry>

NonPortable now overrides the inherited Thing verify() handling for
EXAMINE to make an un-held NonPortable as likely as a held Thing for
disambiguation purposes.

<p>Recall that, by default, Thing downgrades the disambiguation
likelihood that EXAMINE refers to an object not being held.  The
reasoning is that an object being held is physically closer to the
actor, so in a real-world situation, it would be more convenient to
closely inspect an object being held than one sitting nearby.  Since
NonPortable objects can't be held, though, this reasoning breaks down
somewhat.  The change removes the disambiguation disadvantage for
NonPortable objects.

</div>

<!------------------->
<div class=entry>

The objHeld precondition uses a new Thing method,
meetsObjHeld(actor), to determine if the object meets the condition.
This new method is called instead of isHeldBy(actor) on the given
object.  This change allows an object to indicate that it's not
<i>actually</i> being held by an actor, but that it's as good as held
for the purposes of the objHeld condition.  It's rare for
meetsObjHeld() to return anything other than isHeldBy(), but does
happen occasionally.  The most obvious case is body parts: these
can't be considered to be held in the actor's hands (unless the actor
is specifically doing so for some reason), but at the same time,
there's no reason the actor should have to hold a body part in order
to carry out actions with objHeld conditions.

</div>

<!------------------->
<div class=entry>

The Wearable class now handles SHOW TO specially: if the object is
being worn by the actor doing the showing, it doesn't require that it
be held.  In the past, the objHeld condition was applied, as it is by
default to any portable object, which meant that the character had to
take off a wearable in order to show it to someone; this doesn't usually
make a lot of sense, thus the change.

</div>

<!------------------->
<div class=entry>

In Thing, remoteSpecialDesc(pov) now calls distantSpecialDesc by
default; distantSpecialDesc in turn calls specialDesc by default.  In
the past, remoteSpecialDesc called specialDesc directly by default.
This change leaves the default behavior the same as before, but it
simplifies the common case where the "distant" and "remote"
descriptions are the same by letting a single override -
distantSpecialDesc - handle both descriptions.

<p>Similarly, remoteInitSpecialDesc(pov) now calls
distantInitSpecialDesc by default (rather than initSpecialDesc, as it
did in the past).

</div>

<!------------------->
<div class=entry>

Room now treats the GetOutOf action as equivalent to Out.  (This
means that if the room has vocabulary, the player can now say "get
out of (room)" as a synonym for "out".)

</div>

<!------------------->
<div class=entry>

The English verb grammar now accepts LEAVE as a synonym for EXIT.

</div>

<!------------------->
<div class=entry>

The English parser now accepts "A" and "T" as abbreviations for ASK
and TELL, respectively, in the full phrasing with ABOUT.  That is,
you can now say, for example, A BOB ABOUT BOOK.  In the past, the A
and T abbreviations could only be used in the super-short forms of
the commands, where only the topic could be specified (as in T BOOK).

</div>

<!------------------->
<div class=entry>

The English parser now accepts the formats ASK <i>actor</i> TO
<i>command</i> and TELL <i>actor</i> TO <i>command</i> as equivalent
to the traditional <i>actor</i>, <i>command</i> format for telling an
actor to do something.  The new ASK TO and TELL TO formats are simply
syntactic variations; they're otherwise handled exactly the same way
as the traditional <i>actor</i>, <i>command</i> format.

</div>

<!------------------->
<div class=entry>

In the English library, SpecialTopic now allows a variation on the
input format to accommodate players who are thinking in terms of
ASK/TELL.  Now, when a SpecialTopic is active, and the player's input
<i>doesn't</i> match the special topic's input pattern, <i>and</i>
the user's input starts with "A" or "T" as a separate word, the
SpecialTopic checks for a match to the rest of the player's input
(i.e., the part following the "A" or "T").  For example, if the
special topic is "apologize for forgetting the anniversary," and the
player types T ANNIVERSARY, the special topic will try dropping the
"T" and matching just the "ANNIVERSARY" part.

<p>This change is designed to accommodate players who are accustomed
to the standard ASK/TELL format, and who might not realize that the
special topic list shows commands meant to be entered literally, or
who are just so in the habit of using ASK/TELL commands that it
doesn't occur to them to leave out the "A" or "T" part.  Since an "A"
or "T" command pretty clearly indicates that the player's intent is
to communicate with the NPC, it makes sense to check the topic the
player is trying against any active special topics.

<p>Note that the special topic parser only accepts the
super-abbreviated formats - the "A" and "T" commands.  This is
because it seems much less likely that it would even occur to a
player to try a special command with the full ASK ABOUT or TELL ABOUT
phrasing.  Once the command is expanded to the full phrasing, the
detailed syntax of the special command suggestions should make it
fairly obvious to the player that the ASK ABOUT or TELL ABOUT part
isn't needed.  In contrast, since the abbreviated "A" and "T" formats
are ungrammatical to start with, it would seem perfectly natural to
use them with arbitrary special command suggestions.

</div>

<!------------------->
<div class=entry>

The RoomPart class now downgrades its logicalness for Examine
commands, in the same way that Decoration does.  Room parts are
generally so much background noise, included only in case a player
explicitly refers to them.  Downgrading the logicalness helps prevent
the room parts from causing nuisance disambiguation questions.

</div>

<!------------------->
<div class=entry>

Due to a parser bug, the phrase ALL IN <i>container</i> (which can
also be written ALL FROM, ALL THAT'S IN, etc) incorrectly ignored the
hideFromAll() status of the objects in the container when determining
which objects to match to the phrase.  This has been corrected; the
phrase now respects the hideFromAll() settings of the objects
involved.

</div>

<!------------------->
<div class=entry>

The English parser now matches words it has parsed as "literal
adjectives" to ordinary adjectives in the dictionary when resolving a
phrase in "global scope."  This change is the literal-adjective
equivalent of the <a href='#global_scope_noun_adj'>similar changes</a>
involving noun phrases in global scope introduced in 3.0.6p.

</div>

<!------------------->
<div class=entry>

Noun phrases that consist entirely of a "literal adjective" word are
now marked as "adjective-ending" phrases for the purposes of ranking
grammatical pattern matches during parsing.  (The omission of this
flagging in the past was an oversight.)

</div>

<!------------------->
<div class=entry>

Due to a bug, the removeEvent() method of the RealTimeEvent class
(the common base class for real-time fuses and daemons) didn't work
properly.  This has been corrected.

</div>

<!------------------->
<div class=entry>

A bug in the Lister class caused in-line contents listings to use the
"long list" format (i.e., with semicolons as the separator between
items) if the enclosing list did.  An in-line contents list is set off
by parentheses, so it stands as an independent list and thus should a
long-list format only if it would need to on its own, irrespective of
the needs of the enclosing main list.  (At least, the parentheses are
used in the English library; other languages might use different
notation, but in any case should use a notation that makes the
contents list similarly independent of the enclosing list.)

</div>

<!------------------->
<div class=entry>

A couple of minor changes to the default LOOK IN handling make it
a little easier to customize the behavior, and reduce the need to do
so.

<p>First, Thing has a new property, lookInDesc, that gives a message
that's displayed by default in response to LOOK IN and SEARCH.  This
shows the standard default ("there's nothing unusual in it") if you
don't provide a custom message.  It happens frequently that a game
wants to depict an object as having some interior features, but
doesn't want to actually model those interior features as separate
objects.  The new lookInDesc makes this more convenient, since you
only need to provide the custom message in this property, rather than
overriding the entire dobjFor(LookIn) handling, as was necessary in
the past.

<p>Second, Decoration now treats LOOK IN as logical by default (in the
past, this was handled by the catch-all routine that makes most
actions respond that the object is "not important"), and applies the
same logical-rank downgrade applied to EXAMINE.  Correspondingly,
the default lookInDesc for Decoration displays the object's "not
important" message.  This means that Decoration objects act by
default as they did before, displaying "that isn't important" in
response to LOOK IN, but can be given a custom LOOK IN response
simply by setting lookInDesc, just as with any Thing.

<p>Third, the English phrasing for finding nothing in an object
specifically searched with LOOK IN or SEARCH has changed slightly, to
report that there's nothing "unusual" in the object.  In many cases,
an object is described as having what would in the real world be
interior features, but those interior features aren't modeled as
actual game objects and hence don't show up by default in response to
LOOK IN or SEARCH.  The slight change in phrasing helps make the
response at least technically defensible.  It's probably still better
in most cases to customize the LOOK IN response anyway, but at least
the default response is a little less jarring in these cases.

</div>

<!------------------->
<div class=entry>

Decoration now treats READ as logical by default, the same as it
does EXAMINE.  (As mentioned above, LOOK IN now has the same treatment
as well.)

</div>

<!------------------->
<div class=entry>

In the Thing class, PUT X IN X and PUT X ON X now respond with custom
messages ("you can't put the X in/on itself").  In the past, the
catch-all message indicating that X isn't a container/surface was
used, which is a less conspicuous problem than attempting to put
something in or on itself.

</div>

<!------------------->
<div class=entry>

In the English library, the
<a href='#pluralToNounExpansion'>plural-to-noun match expansion</a>
introduced in version 3.0.6p is now limited to "global scope," just as the
<a href='#nounEndingToAdjEndingExpansion'>noun-ending-to-adjective-ending
match expansion</a> already was.  English plurals are usually formed
by adding "s" or "es" to the end of a word, so when a noun is six
letters or longer, it usually looks like a truncated form of its plural;
this interacted with the plural-to-noun match expansion to be overly
aggressive in upgrading phrases to a plural interpretation.  The
match expansion is only really important in global scope anyway (for
the reasons why, see the explanation of the
<a href='#nounEndingToAdjEndingExpansion'>noun-to-adjective expansion</a>),
so this change maintains the primary benefits of the match expansion
while avoiding the weird cases that can come up in local scope.

</div>

<!------------------->
<div class=entry>

The parser now considers an indefinite noun phrase to be less
desirable, for grammar selection purposes, than a definite
interpretation of the same phrase.  Object names can occasionally look
like indefinite phrases: an elevator button labeled "1" could be
called a "one button," for example, and a subway might have an "A
train."  When there's an interpretation that exactly matches the
phrase to the name of an in-scope object, the parser will now prefer
that interpretation over one that treats a word like "a" or "one" as
signifying that an arbitrary match to the other words should be
chosen.

</div>

<!------------------->
<div class=entry>

A library bug that caused a run-time error in
Actor.findVisualObstructor() has been corrected.

</div>

<!------------------->
<div class=entry>

The library now executes "prompt daemons" (the special type of daemon
that runs before each command prompt, rather than when the turn
counter changes) before <i>every</i> prompt, rather than just before
a main command prompt.  This ensures that various miscellaneous tasks
are performed whenever the game pauses for user input, even when
input is requested in the course of processing a command.

</div>

<!------------------------------- 3.0.6p --------------------------------->
<div class="sepbar"><a name='306p'></a>3.0.6p</div>
<p><b><i>Released 4/25/2004</i></b>
<p>

<div class=firstentry>

<b>Compatibility-breaking change:</b> The property initDesc, and the
related properties, have been <b>renamed</b>.  Games that define or
use these properties will have to change to use the new names.  You
should search all of your existing source for the old names, and
replace each one with the corresponding new name.

<p><b>Important:</b> you <b>must</b> search for "initDesc" and
replace it with "initSpecialDesc" <b>first</b>.  This is required
because the former "initExamineDesc" has been renamed to "initDesc" -
so you have to make sure you change all the old "initDesc" instances
<b>before</b> you rename "initSpecialDesc" to create new "initDesc"
instances.  Please do your search-and-replace operations in the order
shown below:

<ul>
<li>change "initDesc" to "initSpecialDesc"
<li>change "useInitDesc" to "useInitSpecialDesc"
<li>change "obscuredInitDesc" to "obscuredInitSpecialDesc"
<li>change "distantInitDesc" to "distantInitSpecialDesc"
<li>change "initExamineDesc" to "initDesc"
<li>change "useInitExamineDesc" to "useInitDesc"
</ul>

<p>The purpose of this change is to make the naming more consistent.
The old usage - "initDesc" for a special description and
"initExamineDesc" for the EXAMINE description - was inconsistent with
the respective non-initial properties, "specialDesc" and "desc".  The
qualification was reversed: "specialDesc" was qualified as special,
leaving the EXAMINE description unqualified as simply "desc", while
the initial descriptions qualified the EXAMINE desription rather than
the special one.

</div>

<!------------------->
<div class=entry>

<b>Minor compatibility-breaking change:</b> The Attachable class's
scheme for explaining why the object can't be attached to a given
other object has been changed.  In the past, the method
cannotAttachMsg(obj) returned a message string or
actor-action-messages property, but this created a conflict with
another message property of the same name, which is used by Thing.  To
resolve the conflict, the Attachable method has now been renamed to
explainCannotAttachTo(obj), and rather than returning a message to
display, the new method simply displays the message itself.

<p>If you have any Attachable objects that define cannotAttachMsg,
you must make two changes to each.  First, rename cannotAttachMsg
to explainCannotAttachTo.  Second, rather than returning a string,
display the string directly.

</div>

<!------------------->
<div class=entry>

<b>Possible compatibility-breaking change:</b> The conversation
mechanism has some internal changes to support deferral across
hierarchy levels (<a href='#topicDeferral'>see below</a>).

<ul>

<li>In TopicDatabase.<b>findTopicResponse()</b>, the former first
parameter, 'topicList', has been dropped, and two new parameters have
been added: 'convType', giving the conversation action type; and
'path', giving a list of the inferior topic databases that will be
searched for the topic if it's not found in the current database
(i.e., 'self').

<li>In TopicDatabase.<b>handleTopic()</b>, the former first parameter,
'topicList', has been dropped; and two new parameters have been added:
'convType' and 'path'.  These have the same meanings as above.

<li>In ConvNode.<b>handleConversation()</b>, the new parameter 'path'
has been added.  This <b>only</b> affects the ConvNode instance of
this method - the method of the same name in Actor and ActorState is
unchanged.

</ul>

<p>Note that the TopicDatabase methods findTopicResponse() and
handleTopic() no longer need the topic list parameter because this
information can be obtained from the new convType parameter.

<p>These methods are mostly for internal use by the library, so the
likelihood that your existing game code will be affected is small.
Even so, you should scan through your code for these methods and make
the appropriate adjustments.

<p><b>Important:</b> note that there are two related but independent
methods called handleTopic().  There's the TopicDatabase method,
which <b>is</b> affected by this change, and there's the separate
TopicEntry method, which is <b>not</b> affected.  When you're
scanning your code, you only need to change the TopicDatabase
version.  It's easy to tell which is which at a glance: the
TopicDatabase version takes <b>three</b> parameters, while the
TopicEntry version only takes <b>two</b>.  When you're scanning your
code, <b>only change the three-parameter instances</b>.

<p><b>Additional technical notes:</b> you'll only need to read this
part if you're making some rather advanced overrides to the library.
Please skip this part unless you find something that you're not sure
how to handle in the search-and-replace step above.

<p>If your code contains calls to any of the affected methods, and
you're wondering what to pass for the convType parameter, you should
first check to see if you're receiving that value as a parameter to
the calling code; if so, just pass that parameter down.  This is
usually easy to spot at a glance.  If you have code like this:

<p><pre>
   handleTopic(<b>self.(convType.topicListProp)</b>, actor, topic);
</pre>

<p>then you can simply change it to this:

<p><pre>
   handleTopic(actor, topic, <b>convType</b>, nil);
</pre>

<p>The important thing to note here is that you're already using the
convType parameter to look up the topic list in the old-style call;
you can simply drop the topic list lookup and pass the convType
parameter itself instead (but note that it moves to the last
position).

<p>If you don't have a convType parameter passed in from your caller,
you'll need to choose which one to use.  Look at which topic list
you're passing, and think about what conversational action is
triggering your code.  Then scan through the list of xxxConvType
objects (askAboutConvType, tellAboutConvType, yesConvType,
noConvType, etc) defined in actor.t, and choose one that (1) has the
same topic list property that you're already using, defined in its
topicListProp property, and (2) conceptually matches the action
you're performing.  If you can't find anything appropriate, you might
simply need to define your own ConvType object for whatever extended
action you're defining; just create one following the same pattern
as the existing ones in actor.t.

<p>You can usually just pass nil for the new fourth parameter ('path')
to handleTopic(), findTopicResponse(), and
ConvNode.handleConversation().  You only have to pass a non-nil value
when you're implementing a search through a hierarchy of topic
databases, in which case you'll have to pass a list of the inferior
databases in the hierarchy.  The purpose of the new parameter is to
allow a higher-level database to defer to a match in a lower-level
database, if one exists, so at each level you must pass the remainder
of the "search path" of databases.

</div>

<!------------------->
<div class=entry>

<a name='topicDeferral'></a>
The above changes to the conversation methods are designed to
facilitate a new mechanism that allows a conversation TopicEntry in
one topic database to defer to a TopicEntry from an inferior
database.  This is done through the new TopicEntry method
deferToEntry(entry): this method returns true if 'self' should defer
to 'entry', nil if not.  'entry' is always a non-nil TopicEntry
object from an inferior topic database.

<p>Recall that topic entry databases for conversation are arranged
into a three-level hierarchy for each actor: at the top is the
ConvNode's list of topics, at the middle level is the ActorState
list, and at the bottom level is the Actor list.  We find a matching
topic entry by scanning each level of this hierarchy in turn, and
taking the first match we find.  So, if there's a ConvNode match for
a topic we're looking for, we use it, even if there's a match for the
same topic in the ActorState or Actor.  The matchScore is irrelevant:
the three-level hierarchy always trumps the matchScore ranking.  The
matchScore ranking is only used to choose among different matching
entries <i>at the same hierarchy level</i>.

<p>The new deferToEntry() mechanism allows topic entries to defer
handling across hierarchy levels.  Here's how the new scheme works:
before we start searching the hierarchy, we start by noting the
matching entry at each level.  Then, we search each level from the
top down as before.  At each level, though, we look at the winning
match, and ask it via deferToEntry() if it wants to defer to the
winning match from the next level down the hierarchy.  If so, then
we ignore the match at that level.  This means that we skip the
higher-level match and go straight to the lower-level handling.

<p>The main purpose of this addition is to allow a DefaultTopic
entry to be a catch-all only for topics that aren't handled
explicitly at a lower hierarchy level.  For example, to create a
DefaultTopic that defers to any non-default match at a lower
hierarchy level, add this to the DefaultTopic object:

<p><pre>
   deferToEntry(other) { return !other.ofKind(DefaultTopic); }
</pre>

<p>This tells the topic finder that if there's any match that's
not itself a DefaultTopic at a lower hierarchy level, then this
default should be ignored.

</div>

<!------------------->
<div class=entry>

The English library template for Room has been extended, and the
default relationships that derive one type of Room naming property
from another have changed slightly.  These changes should be fully
compatible with existing game code, and should make it easier
to customize the various kinds of room names.

<p>The template for Room now takes the first string to be the
'roomName' property, the second to be 'destName', and the third to be
the 'name' property.  The 'desc' property is still in the last
position.

<p><pre>
  Room template 'roomName' 'destName'? 'name'? "desc"?;
</pre>

<p>In the past, the 'name' was the first entry, and 'destName' was
the second.  The library took the 'roomName' to be the same as the
'name'.  However, it makes more sense to do this the other way
around: the 'roomName' is now the one that's explicitly defined by
the game, and the 'name' setting is optional.  If the 'name' setting
is omitted, it's derived by default by converting the 'roomName' to
lower case.

<p>The 'roomName' is what's shown as the title of the room, in the
room description and on the status line.  This is usually given in
"title case," meaning that each word has an initial capital letter,
with the exception of minor function words: "Hall of the Ancient
Kings".  This is the format that games have defined all along, but
in the past, they defined it using the 'name' property.  The change
improves matters, because it allows the room's ordinary 'name'
property to be entered separately, in a format suitable for use
when the name is needed in library messages: "You can't have the
ice cave."

<p>The default 'name' derivation - converting the 'roomName' string
to lower case - gives decent results a lot of the time.  However, in
many cases, you'll want to customize the ordinary name separately.
The template makes this easy by adding a slot for the 'name' property
separately from the 'roomName'.

<p>There's one additional change to the default derivations.  In the
past, the 'destName' didn't have a default at all.  Now, the default
is the room's 'theName', which is itself derived, by default, by
prepending the ordinary name with 'the'.  As before, the template
lets you supply a separate, custom 'destName' value.

</div>

<!------------------->
<div class=entry>

The MultiLoc object now transmits sense information to and from
its contents in a more consistent fashion.  In the past, putting
things inside a MultiLoc had somewhat inconsistent results; the
behavior should be more predictable now.

<p>The primary design principle of a MultiLoc hasn't changed: a
MultiLoc is a single object that appears in multiple locations, but
which doesn't provide any sense connection among the multiple
containers.  A MultiLoc is a <i>single</i> object in the sense that
the same object appears, in its physical entirety, in each of its
containers.

<p>In the past, a MultiLoc was essentially a "sense ceiling": sense
information propagated from outside the MultiLoc to its interior, but
didn't propagate from within the MultiLoc to its containers.  This was
intended to prevent the MultiLoc from propagating sense information
among its containers, but it was too restrictive an implementation.
For example, if a MultiLoc contained a flashlight, the flashlight's
light didn't shine into the MultiLoc's locations.  Similarly, if an
NPC was inside a MultiLoc, the NPC couldn't see or hear anything from
any of the MultiLoc's locations, and hence couldn't take part in a
conversation with the PC while the PC was outside the MultiLoc.

<p>The change is that a MultiLoc is no longer a sense ceiling; it's
now more like a wall.  Now, from a point of view inside the MultiLoc,
all of the MultiLoc's locations (and their contents, to the extent
that's appropriate) are visible.  From the point of view of any of
the MultiLoc's containers, the MultiLoc and its contents (as
appropriate) are visible, but none of the MultiLoc's other containers
are visible.  Light is similarly transmitted from inside the MultiLoc
to all of its containers, but not from one container to another.  So,
for example, if a flashlight is inside a MultiLoc, it provides light
to every container of the MultiLoc; but if a flashlight is in one of
a MultiLoc's containers, the light doesn't make it through the
MultiLoc to its other containers.

<p>The main effect of this change is that things located inside a
MultiLoc now behave the way one would expect them to.  In the past,
the asymmetrical "sense ceiling" design led to some odd behavior when
putting objects inside a MultiLoc: an actor within a MultiLoc
couldn't carry on a conversation with someone outside, for example,
because the actor inside couldn't hear out beyond the MultiLoc.
With the change, MultiLoc should behave much more intuitively.

</div>

<!------------------->
<div class=entry>

The ContainerDoor class now defines the isOpen method to return the
same thing as its associated container's isOpen method; and it now
defines examineStatus to display its associated container's
open/closed status.

</div>

<!------------------->
<div class=entry>

A ComplexContainer can now be used as a bag of holding.  Operations
involving the bag-of-holding features of a complex container are
simply passed redirected to the complex container's subContainer
object.

</div>

<!------------------->
<div class=entry>

Certain object contents listings were grammatically incorrect when
showing a single item that had a plural name.  For example, if an item
had the name "some coins," and it was the only item on a table, the
table description said "On the table is some coins."

<p>The listers now take into account the "cardinality" of each item
listed, to ensure grammatical agreement in these cases.  For English,
there are only two degrees of cardinality that matter: one, and many.
The English module therefore assigns a grammatical cardinality of 2 to
items whose isPlural property is set to true, 1 for all others; this
is done with the new Thing method listCardinality(lister).  A lister
calls this new method to determine the cardinality of the list, so
that it can provide the correct information to the methods that
generate the messages.

</div>

<!------------------->
<div class=entry>

The LISTEN TO command now lists not only the sound the object being
examined is making, but the audible sounds of its contents as well.
This ensures that sounds made by components of an object are properly
displayed when the enclosing object is examined, and also ensures that
a container that has a sound source inside will have its sound listed.

<p>The SMELL command has been similarly enhanced.

<p>As part of this change, the thingListenDesc and thingSmellDesc
messages have been moved from libMessages to playerActionMessages, and
renamed thingListenDescMsg and thingSmellDescMsg, respectively.  These
messages are now shown as default description messages, necessitating
the move to playerActionMessages.

</div>

<!------------------->
<div class=entry>

The Distant class now explicitly allows LISTEN TO, the same way
it allows EXAMINE.

</div>

<!------------------->
<div class=entry>

It's now possible to create a SenseConnector that occludes some
objects from view, depending on the point of view.  This is useful
for situations where a sense connector provides only a partial view
of another room.  For example, consider two rooms with a window
between them, providing a view of one room from the other.  Now,
suppose a bookcase is positioned with its back to the window.  When
viewing the room with the bookcase from the other side of the window,
it's not possible to see the contents of the bookcase.

<p>The new class, OccludingConnector, is a mix-in that you can
combine with SenseConnector to create a partially occluded sense
path.  Put OccludingConnector before SenseConnector in the class
list.  You specify which objects to occlude from view by defining the
method occludeObj(obj, sense, pov).  'obj' is an object to test for
occlusion; 'sense' is the sense being calculated; and 'pov' is the
point of view, which is usually the actor performing the command.
Your method must return true if the connector occludes the object,
nil if not.

<p>To implement the window in our example above, we'd do something
like this:

<p><pre>
  OccludingConnector, SenseConnector, Fixture 'window' 'window'
    "It's a small window. "
    connectorMaterial = glass
    locationList = [roomA, roomB]
    occludeObj(obj, sense, pov)
    {
      /* from roomA, we can't see what's in the bookcase in roomB */
      return (pov.isIn(roomA) &amp;&amp; obj.isIn(bookcase));
    }
  ;
</pre>

</div>

<!------------------->
<div class=entry>

<p>OccludingConnector uses a new mechanism that can be used for more
extensive customization of the sense path calculation than
OccludingConnector itself enables.  During each sense path
calculation, the library first builds a table of all of the objects
connected by containment to the point of view.  (This table contains
all of the objects that can possibly be sensed, because sense paths
are based entirely on containment relationships.)  The library then
calls clearSenseInfo() on each item to initialize it for the path
calculation.

<p>In clearSenseInfo(), an object can register itself for an
additional notification at the end of the sense calculation.  To
register for the notification, override clearSenseInfo(), inherit the
default code, and append 'self' to the notification vector:

<p><pre>
  clearSenseInfo()
  {
    inherited();
    senseTmp.notifyList.append(self);
  }
</pre>

<p>Now that the object is registered, it will be notified at the
end of the calculation, after the sense path to each object is fully
calculated, but before the final table of sense paths is constructed.
The notification method is called finishSensePath(objs, sense).  'objs'
is a LookupTable whose keys are the objects connected by containment
to the point of view; 'sense' is the Sense object of the calculation.

<p>You can do anything you want to the sense table in
finishSensePath().  The sense path information for each object is
stored in the object's tmpXxx_ properties - tmpTrans_, tmpAmbient_,
tmpObstructor_, etc.  To change an object's sense path, simply change
those properties.  (OccludingConnector simply sets each occluded
object's path transparency, in tmpTrans_ and tmpTransWithin_, to nil
to indicate that the object cannot be seen.)  You can make additional
objects visible by adding them to the lookup table and setting their
tmpXxx_ properties to the settings you want them to have.

<p>Note that the notification step is required for performance
reasons.  The library <i>could</i> call the notification method on
every object, which would simplify things by eliminating the need for
the extra line of code to register.  However, very few objects are
likely to require this extra notification, and since sense path
calculations are performed very frequently, the library doesn't want
to call the notification method blindly on all objects.  So, to avoid
adding the notification overhead to every object, the library
requires the rare objects that require the notification to register
themselves.

</div>

<!------------------->
<div class=entry>

The logic that decides on the descriptions generated for distant and
obscured objects has changed slightly.  The purpose of these changes
is to make it easier to customize the various ways an object is
described, and to make the selection of description more intuitive.

<p>First, a new type of description has been added: the "remote"
description.  There are three new remote description methods:
remoteDesc, for the EXAMINE description; remoteSpecialDesc, for the
special description; and remoteInitSpecialDesc, for the remote
initial special description.  These new methods are used to provide
the examination and special descriptions when the object is viewed
from a separate top-level location.  For example, if two top-level
rooms are connected by a window, so that an actor in one room can see
objects in the other room through the window, the remote description
is used to describe objects in the other room from the actor's
perspective.

<p>Second, when choosing a special description (as part of a room or
contents listing), the logic is now as follows:

<ul>
<li>If the object is in a separate top-level location from the actor
doing the looking, the remoteSpecialDesc is shown;
<li>otherwise, if the object is obscured, the obscuredSpecialDesc is shown;
<li>otherwise, if the object is distant, the distantSpecialDesc is shown;
<li>otherwise, the specialDesc is shown.
</ul>

<p>In the past, the sightSize was taken into account in selecting the
type of special description to show: the specialDesc was shown if the
object had a large visual size, regardless of the transparency of the
sense path.  Now, the sightSize isn't considered at all.  The reason
for the change is that the distantDesc and obscuredDesc are almost
always custom messages per object, so they will naturally take into
account the visual size of the object; considering the visual size
added an unnecessary extra dimension.

<p>Note how the new remoteSpecialDesc fits into the selection rules:
the remote special description takes precedence over the obscured and
distant descriptions.  That is, if the object being described is in a
separate top-level room from the actor doing the looking, the
remoteSpecialDesc is used, even if the object is <i>also</i> visually
obscured or at a distance.

<p>Third, when choosing an examine description (when the object is
explicitly examined), the logic is now as follows:

<ul>
<li>If the object is in a separate top-level room from the actor
doing the looking, <b>and</b> a remoteDesc method is defined for
the object, the remoteDesc method is used;
<li>otherwise, if the object is obscured, <b>and</b> an obscuredDesc
method is defined for the object, the obscuredDesc method is used;
<li>otherwise, if the object is distant, <b>and</b> a distantDesc method
is defined for the object, the distantDesc method is used;
<li>otherwise, if the object's details are visible (which will be true
even for a distant or obscured object with sightSize set to large), the
ordinary desc is used;
<li>otherwise, if the object is obscured, the defaultObscuredDesc
method will be used;
<li>otherwise, if the object is distant, the defaultDistantDesc
method will be used.

<p>In the past, the 'desc' was used any time the visual details were
visible, even if the object was distant or obscured and even if the
object had a custom distantDesc or obscuredDesc.  The change is that
the distantDesc or obscuredDesc will essentially "override" the
ordinary 'desc' when custom definitions are provided, regardless of
the visual size of the object.  The reason for this change is to keep
the EXAMINE description selection rules consistent with the special
description rules; the rules are essentially parallel in the two
cases.  The EXAMINE selection rules are slightly more complicated
because of the need to generate suitable defaults when a custom
obscured/distant description is not defined: by considering first
whether or not a custom description is available, we can decide to
show the custom distant/obscured description (if one is available),
the default ordinary description (if no custom description is
available <b>and</b> the details are visible), or a default
distant/obscured description (in any other case).

<p>Note that the defaultObscuredDesc and defaultDistantDesc methods
are new.  The default implementations simply display the same default
library messages that the default obscuredDesc and distantDesc
implementations displayed in past versions.

</div>

<!------------------->
<div class=entry>

<p>The logic for deciding whether or not to use the initial special
description and initial examine description for an object has been
refactored slightly.  The refactoring yields the same default effects
as before, so existing game code won't be affected, but the changes
provide better control for overriding the default behavior.

<p>First, the new Thing method isInInitState determines whether or
not to use the initial special and examine descriptions.  By default,
this method returns true if the object has never been moved, nil if
the object has been moved.  That is, the object is considered to be
in its initial state, for the purposes of descriptions, until the
first time the object is moved by an actor in the game.

<p>Second, the new Thing method useInitExamineDesc() indicates
whether or not the initExamineDesc should be used when examining the
object.  By default, this returns true if the object is in its
initial state, as indicated by isInInitState, <b>and</b> the object
defines a non-nil initExamineDesc.  Since isInInitState by default
returns true if the object has never been moved, and nil otherwise,
the default behavior is the same as before, so existing games will
not be affected by this change.

<p>Third, the existing Thing method useInitDesc() looks at
isInInitState to make its determination.  Since isInInitState by
default returns true if the object has never been moved, this has the
same effect as in the past.

<p>These changes make it easier to change the "never moved" logic
that determines whether or not to use initial descriptions, and also
allows you to control the use of the initial special and examine
descriptions independently of one another.  For example, if you want
the initial examine description to be used one time only, rather than
to be based on whether the object has been moved, you could override
useInitExamineDesc() to base its determination on 'described' rather
than on 'moved'.

</div>

<!------------------->
<div class=entry>

In the English library, Room has a new method that provides a
prepositional phrase that can be used to describe objects as being in
the room.  The new method is inRoomName(pov), and it returns a string
that can be used to construct a sentence describing objects as being
in the room.  'pov' is the point of view; this might not be in the
same top-level room, as we could be viewing objects in this room from
the point of view of a separate room that's connected to our room by
a window or another sense connector.

</div>

<!------------------->
<div class=entry>

Room descriptions now include listings of the portable objects
visible in separate top-level locations.  In the past, only the
contents of the point-of-view actor's own enclosing room were
described; now, the contents of each connected top-level room are
described as well.

<p>To generate the new remote room contents listings, the room
describer first determines the set of top-level rooms with items that
are visible from the point of view of the actor doing the looking.
The room describer shows the contents of the local room (the room
containing the point of view) first, using the same procedure it
always has.  Next, the describer runs through the set of other
top-level rooms with visible contents; for each one, it generates a
separate remote contents listing.

<p>Each remote room's contents listing is displayed using essentially
the same procedure used to generate the local room's contents
listing.  However, instead of using the lister defined by the local
room's roomContentsLister property (which is set to the roomLister
object by default), each remote listing is generated using a lister
returned by the new method remoteRoomContentsLister(other).  This
method is called on the point-of-view room, and 'other' is the remote
room whose contents are to be listed.  By default, this returns a
lister that uses the remote room's inRoomName to generate the
description.

<p>You can customize the listing of portable items visible in remote
locations by returning a custom lister from remoteRoomContentsLister().
Note that the new class CustomRoomLister makes this easy, if all you
want to do is to customize the prefix and suffix messages displayed
in the listing:

<p><pre>
  remoteRoomContentsLister(other)
  {
    return new CustomRoomLister('Through the window, {you/he} see{s}', '.');
  }
</pre>

<p>Note that remoteRoomContentsLister(other) is called on the
<i>local</i> room - the room containing the actor doing the looking -
and 'other' is the <i>remote</i> room.  This arrangement lets you
customize the listing in the point-of-view room, which makes sense in
that the overall description is of the point-of-view room.

</div>

<!------------------->
<div class=entry>

When a room is described (as when entering the room, or examining it
with a LOOK AROUND command), everything visible from the room is
marked as having been seen.  In the past, only visible objects that
were located within the actor's top-level enclosing location were
marked as visible; now, everything that's visible is marked as seen,
including objects in other top-level rooms that are visible from the
actor's location.

</div>

<!------------------->
<div class=entry>

The library has an enhanced way of listing an actor's presence in a
room (as part of the room description) when the actor is visible in a
remote location (i.e., a separate top-level room) or at a distance.
In the past, there was no distinction between the normal case and the
distant and remote cases.  Now, when the actor is in a remote room,
or at a distance, a different path is used to generate the message.

<p>To accomplish this change, Actor now overrides remoteSpecialDesc
and distantSpecialDesc.  On LOOK AROUND, the room calls the
appropriate one of these to describe the actor when the actor is at a
distance.  (The normal selection procedure is used: the
remoteSpecialDesc is used if the NPC is in a separate top-level
location from the point-of-view actor, otherwise distantSpecialDesc
is used if the NPC is at a distance.)  The new Actor implementations
of remoteSpecialDesc and distantSpecialDesc invoke the corresponding
new ActorState methods of the same names.  These new ActorState
methods in turn call back to the new Actor method actorThereDesc
(both the distant and remote methods call this one new method).  The
new actorThereDesc calls the new method roomRemoteActorDesc on
the actor's location.  Thing provides a default
implementation of this new methods, which simply calls the same
thing on its the location if there's a location that's visible from
the point of view, or shows a default library message if not.  The
default library message method is also called roomRemoteActorDesc.
This uses the location's inRoomName to generate the description.

<p>This sequence of calls lets you hook in and customize the actor's
distant special description at whatever level is most convenient -
at the actor itself, at the ActorState, or at the containing room.
In most cases, it will probably be most convenient to customize this
in the room, to display a message customized to the appearance of
the room from a distance.  To do this, you'd put a method like this
on the room:

<p><pre>
  roomRemoteActorDesc(actor)
  {
    "\^&lt;&lt;actor.nameIs&gt;&gt; over at the north end of the courtyard. ";
  }
</pre>

<p>Note that the actor to describe is provided as a parameter, and
that the method is responsible for displaying the complete message
describing the actor's presence.

</div>

<!------------------->
<div class=entry>

In the past, an EXAMINE command applied to a room was always treated
as a LOOK AROUND command; this didn't produce good results when the
room being examined was a separate room that the actor doing the
looking wasn't in (i.e., a room connected to the actor's location via
a sense connector of some kind).  This no longer happens; when the
actor doing the looking isn't inside the room, the standard EXAMINE
handling is used, as though the room were any ordinary object.

</div>

<!------------------->
<div class=entry>

Thing.lookAroundPov() now actually sets a global point-of-view object.
This ensures that the POV information can be obtained (via the getPOV()
function) when room descriptions are being shown.

</div>

<!------------------->
<div class=entry>

Thing.addToSenseInfoTable() no longer includes the 'src' parameter.
Instead, the same information can be obtained from
senseTmp.pointOfView.  (The parameter has been removed for effiency:
the information is rarely needed, and is available from this other
source when it is needed.)

</div>

<!------------------->
<div class=entry>

The Thing method canDetailsBeSensed() now takes an addition parameter
giving the point of view.  This is usually the actor performing a
LOOK AROUND, EXAMINE, or other command that's causing a description
of the object to be generated.

</div>

<!------------------->
<div class=entry>

Thing.lookAroundWithinSense now marks each item with a "presence" in
the sense as known to the actor who's doing the looking.  This
ensures that any noises and odors that are actively listed become
known to the actor as soon as they're listed.

Objects are marked as known rather than seen, because it might be
possible to hear or smell objects that can't be seen.  Note that only
objects with a "presence" in the sense are marked as known; an object
with a presence in a sense is one that is actively calling attention
to itself in the sense, via a noise or odor message in the room
description.  Thus, an object that isn't actually making any noise
worth listing doesn't become known just because an actor could hear
it if it were making noise; it has to actually be making some noise
(and say so by setting its soundPresence to true) to become known in
this manner.  Note also that a noise and its source are frequently
separate objects (likewise with odors), and it's the <i>noise</i>
that becomes known in this arrangement, not the source.  This is
important because it's often possible to hear the sound a thing makes
without knowing what's making the noise: we can hear a beeping coming
from inside a closed box, so we now know about the beeping, but we
can't tell that it's coming from an alarm clock, so the alarm clock
remains unknown to us.

</div>

<!------------------->
<div class=entry>

By default, Thing now applies the objHeld precondition to a Show
action; this means that SHOW X TO Y requires X to be held if X is an
ordinary Thing.  In addition, NonPortable only requires that the
object be visible.  This change assumes that portable objects need to
be held up for someone else to look at, as though offering the object
to the other person, while non-portable objects can be merely pointed
out but left in place.

</div>

<!------------------->
<div class=entry>

The Vehicle class now treats an OUT command while an actor is inside
the vehicle as meaning to drive or ride the vehicle out of the
vehicle's enclosing location.  In the past, OUT in a vehicle meant
the same thing as in a nested room: GET OUT of the vehicle.  The old
behavior didn't seem to match most players' expectations, and it had
the drawback that it left no standard way of expressing the intention
of driving/riding the vehicle out of its location.

<p>For certain vehicles, it might still be desirable for OUT to mean
GET OUT.  Fortunately, it's easy to override the default behavior on
a case-by-case basis - just override a vehicle's 'out' property to
return nestedRoomOut:

<p><pre>
   car: Vehicle
     out = nestedRoomOut

     // ...other properties...
   ;
</pre>

</div>

<!------------------->
<div class=entry>

In the past, RoomConnector and OneWayRoomConnector didn't apply the
proper preconditions to travel; in particular, they didn't properly
determine the required initial location for the travel, so they didn't
move an actor out of a nested room before attempting the travel.  This
has been corrected; RoomConnector now uses the travel preconditions
formerly defined in RoomAutoConnector, so all RoomConnector subclasses
(including OneWayRoomConnector and RoomAutoConnector) now use the
correct preconditions.

</div>

<!------------------->
<div class=entry>

Enterable and Exitable objects now add a "touchable" pre-condition to
travel through the objects.  In the past, only the pre-conditions for
the underlying connector were applied; since some types of travel
connectors are not themselves physical objects, this occasionally led
to odd results.  In particular, if an Enterable or Exitable was
visible but not touchable (for example, if the object was at a
distance, or separated from the actor by a window), it was possible
to enter it despite its being unreachable.  This type of anomaly should
no longer occur.

</div>

<!------------------->
<div class=entry>

The departure and arrival messages for NPC's now yield more pleasing
results in cases where an NPC arrives or departs from a visible
"remote" location - that is, a location not part of the PC's
outermost room, but connected to the PC's location by a sense
connector (such as a window between two rooms, or a
DistanceConnector).  There are two cases where the departure and
arrival messages are enhanced.

<p>First, when an NPC departs from or arrives at a remote location,
and the other end of the NPC's travel is out of sight, the library
adds the name of the remote location to the arrival or departure
message.  For example: "Bob leaves to the east from the alley," or
"Bob comes down the stairs to the north end of the courtyard."  The
name of the location is taken from the destName property of the NPC's
location.  The location name is only shown when the location is
remote; when an NPC enters or leaves the PC's outermost room, the
traditional messages ("Bob leaves to the east," etc.) are shown.  The
addition of the location name to the message helps clarify that the
NPC is moving around nearby and within sight, but isn't directly at
the PC's location.

<p>Second, when an NPC starts and finishes its journey within sight
of the PC, the library omits the departure message entirely, and
displays a new type of arrival message.  When the entire journey is
within the PC's field of view, we don't wish to describe the
departure and arrival as two separate steps, since the whole journey
can be described as a single operation; this is what the new type of
arrival message does.  The new message is given by the new
TravelConnector method describeLocalArrival(), which the traveler
calls from its describeNpcArrival method when it determines that the
origin is visible to the PC.  TravelConnector.describeLocalArrival()
in turn calls the new Traveler method sayArrivingLocally(), and the
default implementation of this new method simply displays the library
message given by libMessages.sayArrivingLocally().  The library
message displays a message of the form "Bob enters the alley."  Note
that it might sometimes be desirable to customize the travel
connector's describeLocalArrival() method: you could say things like
"Bob climbs the stairs up to the loft," or "Bob squeezes through the
window into the kitchen," for example.

</div>

<!------------------->
<div class=entry>

BasicLocation.cannotGoThatWay now obtains the message to display from
a new property of 'self', cannotGoThatWayMsg.  By default, this
returns &amp;cannotGoThatWayMsg, which is the library message property
for the default message for this case.  You can easily override a
room's message when travel is not possible in a given direction by
overriding cannotGoThatWayMsg to return a single-quoted string with
your custom message.

</div>

<!------------------->
<div class=entry>

The class GuidedInTravelState formerly defined each of the
sayDepartingXxx() methods separately to show the departing-with-guide
library message.  Now, the class instead defines only sayDeparting()
to display this message.  This creates the identical effect by
default, since all of the sayDepartingXxx() methods inherited from
GuidedInTravelState's base class (AccompanyingInTravelState) simply
call sayDeparting().  The advantage of this change is that it allows
GuidedInTravelState's travel message for all of these different
variations to be customized by overriding sayDeparting(), rather than
overriding each sayDepartingXxx() individually.

</div>

<!------------------->
<div class=entry>

SpaceOverlay now checks the "moved" status of its "identity" object,
not its own "moved" status, to determine if it should abandon its
contents on being moved for the first time.  This makes the operation
work properly when the overlay is a component of a ComplexContainer,
which will usually be the case; since only the parent complex
container is actually marked as moved, checking the status of the
child overlay object wasn't enough.  Checking the identity object
ensures that the status of the larger object of which the overlay is
a part is properly taken into account.

</div>

<!------------------->
<div class=entry>

The TravelPushable method beforeMovePushable() now takes a new
third parameter, 'dest', giving the destination of the travel.

</div>

<!------------------->
<div class=entry>

SpaceOverlay now overrides beforeMovePushable() to call
abandonContents().  This ensures that if the object is a
TravelPushable, and it's pushed to an new location, the contents are
abandoned <i>before</i> the actor moves to the destination location.
In the past, the object waited for the normal moveInto() notification
to abandon its contents; but this notification didn't arrive until
after the actor had already moved to the destination location, so the
actor wasn't able to see the contents being abandoned, thus we weren't
able to list the contents properly.

<p>ComplexContainer also overrides beforeMovePushable(), passing the
notification down to any SpaceOverlay components it has.  This
corrects the same problem for a ComplexContainer that's also a
TravelPushable, and which has SpaceOverlay components.

</div>

<!------------------->
<div class=entry>

SpaceOverlay is now more careful about the way it reveals the
contents of the object when it's moved.  In the past, it simply did
an appropriate kind of nested command (LOOK UNDER for an Underside,
for example) to generate the listing.  This generally showed up
before the main report for the action, so when the main report was a
simple default report (such as "Taken"), it created confusion by
suggesting that the default report somehow applied to the last object
listed in the revelation:

<p>
<pre>
   &gt;take box
   Under the box is a rusty can. Taken.
</pre>

<p>There are two changes to the way this listing is generated.

<p>First, the listing is no longer just a generic LOOK UNDER (or
equivalent).  Instead, it uses a new lister, given by the
abandonContentsLister property of the SpaceOverlay object.  Underside
uses undersideAbandonContentsLister by default, and RearSurface and
RearContainer use rearAbandonContentsLister.  These new listers use
more specific language to describe the revelation, of the form
"Moving the box reveals a rusty can underneath" (or "behind").

<p>Second, the SpaceOverlay takes care to move the listing so that it
follows the main report from the command that triggered the listing.
This ensures that the main report remains close to the command line,
which is required if the terse phrasing of the default reports is
to make sense.

<p>There's one exception, though: if the actor performing the command
ends up in a different location at the end of the command, the
listing is <i>not</i> moved to the end of the report.  Instead, the
listing simply stays at the beginning of the command.  This exception
is important because travel usually triggers a description of the new
location, and once we're in the new location, the revelation of the
SpaceOverlay's contents will seem out of place.  It's better in these
cases to leave the contents listing at the start of the reports.

<p>With these two changes, the old listing above is transformed
into this:

<p>
<pre>
   &gt;take box
   Taken. Moving the box reveals a rusty can underneath.
</pre>

</div>

<!------------------->
<div class=entry>

If all of the changes described above to SpaceOverlay's revelation
listing are still not adequate for some special case in your game,
you can now easily suppress the default listing and generate your own
explicit listing instead, thanks to a couple of new features.

<p>First, the new SpaceOverlay property 'neverListOnMove' lets you
suppress the default listing; just set this property to true, and no
listing will ever be generated when the overlay object is moved.  If
the contents are to be abandoned, the abanonment will still happen,
but no automatic mention will be made of it.  Your code is
responsible in these cases for generating any desired listing.

<p>Second, the new method listContentsForMove() generates the
revelation of the contents in the default format.  SpaceOverlay calls
this method itself to generate the automatic message when
appropriate.  If you set neverListOnMove to true in order to suppress
the default revelation listing, you can call listContentsForMove() at
the appropriate juncture in your own code to generate a substitute
listing.  Of course, you could instead completely customize the
listing with your own method; but if you only want to change
<i>where</i> the listing appears, without changing its contents,
listContentsForMove() makes that easy.

<p>Note also that you can customize the standard listing format used
by providing your own lister, and setting the SpaceOverlay object's
abandonContentsLister to refer to your custom lister.

</div>

<!------------------->
<div class=entry>

In the default Floor class, there were a couple of problems with the
commands SIT ON FLOOR, STAND ON FLOOR, and LIE ON FLOOR that have now
been corrected.  First, when standing in a nested room, STAND ON
FLOOR incorrectly failed with the message "You're already standing."
Second, when already sitting, lying, or standing on the floor,
another command to do the same thing was incorrectly accepted; it's
now rejected with an appropriate message (such as "You're already
sitting on the floor").

</div>

<!------------------->
<div class=entry>

If the player character was in a nested room, and typed a command to
leave the nested room, and immediately followed with an AGAIN
command, the AGAIN incorrectly succeeded, making it look like the
character was getting out of the nested room repeatedly without
getting back in.  This has been corrected; an appropriate message
("you're not in the booth") is now displayed on the errant repetition.

</div>

<!------------------->
<div class=entry>

In ActorTopicDatabase.initiateTopic(), the conversation is "noted"
only if an InitiateTopic is found to handle the request.  Noting the
conversation means that we set the actor's last interlocutor to the
player character, so this change means that initiateTopic() won't
affect the actor's interlocutor unless a conversation is actually
initiated.  (In the past, the routine always noted the conversation.
This caused odd side effects when initiateTopic() was called
speculatively, without knowing for sure that an InitiateTopic was
actually available, since the interlocutor changed even though no
conversational action was visible to the player.  This change ensures
that the interlocutor will only change when a conversation actually
takes place.)

</div>

<!------------------->
<div class=entry>

When an InConversationState object becomes the active state for an
actor, it remembers the previously active state so that it can, by
default, transition back to that previous state when the conversation
ends.  In the past, the InConversationState class remembered
<i>any</i> previous state and used it as the new state at the end of
the conversation.  This has been changed.  Now, the class remembers
the previous state only if the previous state is a
ConversationReadyState, or there's no other previous state already
remembered.  This change makes it easier for an actor to interrupt a
conversation with another activity, and later resume the
conversation, because the interrupting state will no longer "take
over" at the end of the conversation.  You can still explicitly set
the end-of-conversation state explicitly to anything you want; this
change only affects the default state transitions that occur in the
absence of any explicit settings.

</div>

<!------------------->
<div class=entry>

The HELLO and TALK TO commands now defer the implied topic inventory
until the end of the turn, if the response to the HELLO or TALK TO
contains any non-default reports.  This is important because a
non-default report could set the ConvNode for the responding actor,
but such a change doesn't take effect until the transcript is fully
processed at the end of the turn.  In the past, HELLO and TALK TO
always showed the topic inventory right away, so the inventory didn't
necessarily match the new ConvNode's active topics.  With this
change, a ConvNode change within a HELLO or TALK TO will be properly
reflected in the topic inventory.

</div>

<!------------------->
<div class=entry>

The new ConvNode property 'isSticky' lets you create a "sticky"
conversation node.  By default, nodes are non-stick: this yields the
traditional behavior, where the NPC leaves the node if a response
doesn't explicitly stay there.  (If the node is active, and the NPC
shows a response that doesn't set any new node, the actor's current
node is set to nil.)

<p>If you set 'isSticky' to true for a node, the node will stay
active if the NPC shows a response that doesn't set a new node.  In
other words, the "default next node" for any response while the
sticky node is active is the sticky node itself, rather than nil.

<p>Sticky nodes are useful in cases where you want an actor to drive
a conversation along a particular thread, but you still want to allow
the player to digress by talking about other topics.  As long as a
digression doesn't explicitly set a new node, the sticky node will
remain active.

</div>

<!------------------->
<div class=entry>

DefaultCommandTopic now has a matchScore of 3, which makes the
library choose it over a DefaultAnyTopic if both kinds of default
topics are active for a given response.  (In the past,
DefaultCommandTopic had the same matchScore as a DefaultAnyTopic, so
in cases where both kinds were active the library chose one
arbitrarily.  The DefaultCommandTopic should always take precedence,
as it now does, because it's the more specific kind of response.)

</div>

<!------------------->
<div class=entry>

AltTopic now takes its setting for the 'impliesGreeting' property
from its enclosing topic.  This ensures that an AltTopic used within
a HelloTopic or the like will behave the same as its enclosing main
topic by default.

</div>

<!------------------->
<div class=entry>

ByeTopic and ImpByeTopic now work together the same way that
HelloTopic and ImpHelloTopic work together.  Specifically, ByeTopic is
now a catch-all that matches both explicit GOODBYE commands and
implied conversation endings.  (Implied goodbyes happen when the
player character just walks away from a conversation, or the NPC gets
"bored" from lack of attention).  ImpByeTopic still matches only
implied goodbyes; since it's the more specific of the two, it now uses
an elevated matchScore.  This means that if both a ByeTopic and an
ImpByeTopic are active at the same time, the ImpByeTopic will be
chosen for an implied goodbye, and the ByeTopic will be chosen for an
explicit GOODBYE command.

<p>This change makes it easier to program catch-all goodbye messages,
while still allowing differentiation when desired.  To create a
catch-all message that handles both explicit and implicit goodbyes,
just create a ByeTopic.  If you want to differentiate, create one of
each: the ByeTopic will be chosen for the explicit GOODBYE commands,
since the ImpByeTopic won't match those; and the ImpByeTopic will be
chosen for implied goodbye, because both will match, but the
ImpByeTopic's higher matchScore will ensure that it's selected over
the ByeTopic.

<p>Along the same lines, HelloGoodbyeTopicObj now matches implied
as well as explicit goodbyes.  (In the past, it handled implied and
explicit greetings, but only explicit goodbyes.)

</div>

<!------------------->
<div class=entry>

Some of the behavior of InConversationState.endConversation has been
moved to the base ActorState class.  This ensures that the active
ConvNode will be notified if the player walks away from a
conversation.

</div>

<!------------------->
<div class=entry>

The library messages for scoring (showScoreMessage,
showScoreNoMaxMessage, showScoreRankMessage, showFullScorePrefix) now
refer explicitly to "you", not to the player character.  Since the
score is a meta-game feature, it should be attributed directly to the
player, not to the player character.  This is especially important in
games that refer to the player character in the first or third
person, since the distinction between player and player character is
more evident in these cases than it is in second-person games.

</div>

<!------------------->
<div class=entry>

The library message for trying to put an object inside an another
object that already contains the first object (i.e., the "circular
containment" message) now reports the objects as specified, rather
than possibly showing an intermediate container.  In the past, an
intermediate container was shown in some circumstances, especially
when a ComplexContainer was involved; this produced the wrong
messages in some cases.

</div>

<!------------------->
<div class=entry>

In the past, the multiple object announcement ("red book: Taken") was
missing in in some cases where the action was remapped (via remapTo).
This has been corrected.

</div>

<!------------------->
<div class=entry>

The implied action message generator now allows for "silent" implied
actions - implied actions that behave as usual but generate no
announcement text (the normal announcement is the message of the form
"(first opening the door)" shown at the start of the response to the
command).

<p>First, the new libMessages method silentImplicitAction() can be
used in place of the standard announceImplicitAction() to generate
the announcement.  silentImplicitAction() simply shows no message.
To use it, perform the implied action with a call like this:

<p><pre>
   tryImplicitActionMsg(&amp;silentImplicitAction, Open, self);
</pre>

<p>Second, the lister that aggregates a set of implicit actions into a
single announcement message now accepts the empty messages generated
by silentImplicitAction().  This ensures that silent implied actions
can be mixed with announced implied actions in a single command, and
a sensible aggregate announcement will be displayed.

</div>

<!------------------->
<div class=entry>

Thing.setContentsSeenBy() incorrectly marked the object's contents as
having been seen by 'gActor' rather than by the actor passed as a
parameter to the method.  This has been corrected.

</div>

<!------------------->
<div class=entry>

In PresentLater, when the object is made present (via the makePresent
method, or any of the related methods), the object and its contents
are specifically marked as seen by the player character, to the
extent the player character can actually see them at the moment they
become present in the location.  In most cases, when an object comes
into play dynamically via the PresentLater mechanism, the sudden
appearance is the result of some specific event that the game will
describe through custom handling - that is, the game will
specifically mention the new object to the player, so the player
character should remember having seen the object.

</div>

<!------------------->
<div class=entry>

In a two-object command (such as PUT VASE ON TABLE), the parser now
retains the meaning of a pronoun used in the command, regardless of
which object slot the pronoun is used in.  For example, after the
command PUT VASE ON IT, the pronoun "it" is set to refer to the
indirect object, even though "it" would normally refer to the direct
object after a PUT X ON Y command.

<p>In the past, the parser unconditionally set the pronoun antecedent
after a two-object command to the second-resolved object, which in
many such verbs is the direct object.  So, after PUT VASE ON IT, the
pronoun "it" previously referred to the vase.  Due to this change,
though, the explicit use of the word "it" directly within the command
causes meaning of "it" to be left unchanged by the command.  This
change doesn't affect the behavior when no pronoun is used in the
command, so PUT VASE ON TABLE still causes "it" to refer to the vase
on the subsequent command.

</div>

<!------------------->
<div class=entry>

ConsultTopic and DefaultConsultTopic now refrain from setting any
pronoun antecedents for the topic.  This means that after any
consultation command (LOOK UP, FIND IN, etc.), the pronoun antecedent
will be the consultable object, not the topic last sought.

</div>

<!------------------->
<div class=entry>

TopicTAction (used for commands such as ASK ABOUT and CONSULT ABOUT)
didn't work properly if a reflexive pronoun was used as the direct
object, referring back to the topic phrase: LOOK UP BOOK IN ITSELF,
for example.  This showed a couple of symptoms, including "Nothing
obvious happens" responses and run-time errors.  The problem has been
corrected; the action now looks to the topic phrase to resolve the
direct object, producing consistent and appropriate results.

</div>

<!------------------->
<div class=entry>

When a command is directed to an NPC (as in BOB, OPEN DOOR), and the
parser has to prompt interactively for disambiguation or for a
missing noun phrase, the parser now treats gender-matched
third-person pronouns in the reponse as referring to the target
actor.  For example:

<p><pre>
   &gt;look at bob
   He's wearing a red sweater.

   &gt;bill, examine
   What do you want Bill to look at?

   &gt;his book
   The book looks old and dusty; the title on the cover is faded
   to the point of being unreadable.
</pre>

<p>In the past, the parser would have taken the "his" in the
interactive response to refer to Bob, since Bob would have been the
pronoun antecedent up until that point (by virtue of having been
mentioned in the previous command).  With this change, the parser
takes "his" to refer to Bill.  This fits with the phrasing of the
prompt text, and also with the fact that Bill was mentioned more
recently in a command (specifically, in the incomplete "examine"
command).

<p>Similarly, reflexive third-person pronouns (HIMSELF, HERSELF,
ITSELF, THEMSELVES) in interactive responses are taken as referring
to the target actor, when the gender matches.

</div>

<!------------------->
<div class=entry>

The parser is now more consistent in its treatment of truncated
vocabulary matches.  (Truncated matches are words in the player's
command that match longer object names defined in the game, by
truncating the longer object names to the dictionary's minimum length.
For example, the default English dictionary truncation length is 6
characters, meaning that the player can shorten the word FLASHLIGHT to
FLASHL, FLASHLI, etc., when entering commands.)

<p>In the past, the parser treated exact matches as stronger than
truncated matches for singular definite noun phrases (the most common
kind of noun phrase: TAKE BOOK, OPEN THE BOX).  Any time the parser
matched some names exactly and other names only after truncation for
the same user input, the parser kept only the exact matches, filtering
out the truncated matches.  This rule hasn't been changed; what's
changed is that it has now been extended to every kind of noun phrase,
including indefinite phrases (TAKE A BOOK) and plural phrases (TAKE
BOOKS).

</div>

<!------------------->
<div class=entry>

<a name='pluralToNounExpansion'></a>
In the English parser, when the parser matches a plural phrase (i.e.,
a phrase with a vocabulary word defined under the 'plural' property),
the parser now includes both 'plural' <i>and</i> 'noun' matches for
the word.  In the past, only the 'plural' matches were included.

<p>In some cases, it's convenient to define a word that's
grammatically a plural under the 'noun' property, because a single
game object encompasses what looks to the user like a set of
something: a bookcase might define "shelves" as a noun, for example,
since the individual shelves aren't modeled as separate objects.  This
change ensures that if other objects are in scope that define the same
word under the 'plural' property, the bookcase will still match the
word "shelves" when the noun phrase is resolved.

<p>This change doesn't actually make much difference most of the time,
but it is frequently significant in "topic" phrases (as in ASK ABOUT).
Topic phrases have very wide scope, so a particular word can match
numerous objects from all over the game.  In these cases, the old
scheme that included only 'plural' matches was overly exclusive,
causing the parser to omit objects from the topic resolution that the
author would at first glance have expected to be included.  The new
more inclusive matching should reduce the potential for confusing
match exclusions in these cases.

</div>

<!------------------->
<div class=entry>

<a name='#nounEndingToAdjEndingExpansion'></a>
The English parser is now more inclusive in matching nouns and
adjectives at the ends of "topic" phrases.  (Topic phrases are used in
commands like ASK ABOUT and TELL ABOUT, where the player can refer to
physical objects as well as to abstract Topic objects, and can even
use random text that doesn't correspond to any game objects.)

<p>Normally, when the last word of a noun phrase can match one or more
objects in scope that define the word under the 'noun' property, the
parser will ignore any additional in-scope objects that match the same
word under the 'adjective' property.  For example, if there's a desk
in scope that defines 'desk' as a noun, and there's also a desk drawer
that defines 'desk' as an adjective, the parser will interpreter LOOK
AT DESK as referring to the desk, not to the drawer.  However, if
there's a red book present, but there's no object in scope that
defines 'red' as a noun, the parser takes READ RED as referring to the
red book, even though BOOK was left unstated.  This combination of
rules gives the player the convenience of abbreviating the name of an
object to a unique adjective, while avoiding spurious ambiguity in
cases like the desk-and-drawer exmaple.

<p>In cases of "global" scope, though, this strategy isn't as
beneficial.  When resolving a topic phrase, objects from all over the
game have to be considered "in scope" even though they're not
physically present, as it's perfectly reasonable for the player to ASK
ABOUT something that was seen earlier in the game but isn't physically
present at the time of the question.  As a result, the elimination of
adjective bindings for a word can cause subtle problems that are very
difficult to track down, and which sometimes can't be easily fixed
without creating other problems.  Two objects could happen to share
the same vocabulary words, in one case as an adjective and in the
other case as a noun, even though the objects are completely
unrelated.  Thus, the existence of one object can change the way
another object's vocabulary words are treated when matching a topic
phrase.

<p>The English parser now treats topic resolution differently.  When
resolving a topic phrase, the parser no longer makes the strict
noun/adjective distinction.  Instead, the parser considers both kinds
of vocabulary to match.  So, if the player types ASK BOB ABOUT DESK in
our example with the drawer, both the desk and the drawer are now
considered possible topic matches.

<p>This change has the potential to create a different sort of
problem, in that it could include <i>too many</i> possible matches for
a topic phrase.  However, this is a much easier problem to deal with
than the old one, and in most cases won't even be noticeable as a
problem.  In the first place, topic phrases don't require
disambiguation in the normal sense; the parser never asks the player
which object was intended, so the more inclusive matching won't
degrade the user interface by generating more disambiguation queries.
Second, it's much easier to understand why an extra object is matching
a given vocabulary word than to understand why a given object is
failing to match.  A failure to match indicates that some other object
is defining the same word under another part of speech, but it doesn't
tell you which object or where it's defined; when too many objects
match, in contrast, you can easily see (using the debugger, for
example) which extra objects are matching, and make any desired
vocabulary adjustments.  Third, in the vast majority of cases, the
extra matches are completely harmless and not even noticeable.  Topics
are generally handled in conversations, and conversations have to
explicitly include responses for all of the topics they want to match.
If an extra object or two show up in vocabulary matching for a given
conversational command, it won't usually matter, because those
unexpected objects won't have topic matches in the conversation anyway
and will thus simply be ignored.  In cases where you want a
conversation to distinguish among objects with similar vocabulary, you
can add the necessary distinguishing vocabulary to the objects just as
you would in cases of ordinary ambiguity, and you can tweak the topic
list (using match scores, for example) to control which response is
used for which vocabulary.  In the rare cases where it's not
straightforward to fine-tune the matching using object vocabulary, you
can always resort to using regular expressions as the topic match
criteria.

</div>

<!------------------->
<div class=entry>
<a name='global_scope_noun_adj'></a>

Consider a situation where a given object is entered in the dictionary
with two words for a given part of speech, and one of the words
happens to be a leading substring of the other word, and both words
are long enough to trigger "truncated" matching (that is, each word is
at least six characters long, in the default dictionary truncation
configuration).  For example, suppose a given object is entered in the
dictionary with 'noun' words for WINDOW and WINDOWSILL.  Now, if the
player enters a command using the shorter word (WINDOW), the raw
dictionary match list will contain two matches for this object: one
for the exact match to the shorter word, and one for the truncated
match to the longer word.

<p>In the past, this situation sometimes had undesirable results.  In
most cases, the two matches to the same object were collapsed into a
single match, but the "match flags" from the two matches were combined
- so both matches were marked as truncated.  Depending on what other
objects were in scope at the time, this had the effect of eliminating
the object from consideration as a resolution of the noun phrase: even
though it had an exact match in the dictionary, the resolver saw it as
a truncated match because of the combination of the two sets of match
flags.  This was especially likely to affect topic phrases (ASK ABOUT,
for example), because the global scope made it much more likely that
other objects would have exact matches for the same vocabulary.

<p>The parser is now smarter about the way it combines these sorts of
redundant matches.  Instead of simply OR'ing together the match flags,
the parser now specifically keeps only the "strongest" match in these
cases.  In our example, the parser sees that there's a truncated
dictionary match (WINDOWSILL) and an exact match (WINDOW) for the same
object, so it now decides to consider the match to be exact.

</div>

<!------------------->
<div class=entry>

The English parser now accepts IN <i>object</i>, INTO <i>object</i>,
and IN TO <i>object</i> as verb synonyms for ENTER <i>object</i>.
These aren't exactly valid English grammar, but they have a certain
linguistic consistency with other telegraphic IF-ese constructs, and
they seem to naturally occur to some players.  These variations all
have an obvious meaning to an English speaker, and they're not
ambiguous with any other commands, so there should be no harm in
adding them as convenient abbreviations.

</div>

<!------------------->
<div class=entry>

After a misspelling, if the player typed OOPS but left off the
corrected spelling (i.e., just typed OOPS by itself on the command
line), the parser responded with a message saying that OOPS isn't
allowed right now.  This has been corrected; the parser now responds
with a new message explaining the correct syntax, and gives the user
another chance to enter the OOPS command.

</div>

<!------------------->
<div class=entry>

When a single player command triggers more than one implied action
(for example, GO NORTH might trigger OPEN DOOR, which in turn might
trigger UNLOCK DOOR), the reporting mechanism had a couple of problems
when the doubly-nested action (UNLOCK DOOR in our example) itself
triggered a nested action, such as by remapTo or nestedAction.  First,
the reported order of the implied actions was reversed ("first opening
the door, then unlocking it"); second, the doubly-nested one reported
the nested action rather than the original implied action.  Both of
these have now been corrected.

</div>

<!------------------->
<div class=entry>

When you synthesize an action programmatically (via a function such
as replaceAction or nestedAction), the library has to choose a
language-specific final subclass of the generic action you specify.
It does this by choosing a VerbRule that's subclassed from the base
action.  In the past, the choice was entirely arbitrary.  Now, the
library is a little pickier: it now chooses only a final subclass,
never an intermediate class.  That is, it always chooses a VerbRule
which hasn't been further subclassed (or modified with 'modify').
The old, less selective algorithm occasionally caused oddities, such
as choosing a base VerbRule that was subclassed with 'modify', thus
picking up pre-'modify' values of properties such as the verb's
descriptive text.

</div>

<!------------------->
<div class=entry>

The conversationManager object now provides a simple extensibility
mechanism that lets you add your own custom conversation tags.  To
add custom tags, use 'modify' to extend the conversationManager
object, then add two things.  First, define the customTags property,
giving a string with the new tag names you want to add.  The tag
names must be in lower-case letters; do not include the angle
brackets or the leading period in the tag name.  Separate multiple
tag names with "|" symbols.  Second, define a doCustomTag(tag,arg)
method that processes your custom tag or tags.  The 'tag' argument is
a string giving the custom tag that was matched in the output stream;
only the tag name will be included, not including the angle brackets
or leading period.  The 'arg' method is a string giving the argument
to the tag, if any; this is simply the part inside the angle brackets
following any whitespace after the tag.

</div>

<!------------------->
<div class=entry>

SensoryEmanation and its subclasses Noise and Odor will now let you
use Script objects for the hereWithSource and hereWithoutSource
properties.  This is handy in cases where you want to vary the
object's description over time.  If you define these properties as
Script objects, the SensoryEmanation object will invoke their
doScript() methods when an emanation message is to be displayed.

</div>

<!------------------->
<div class=entry>

The Keyring class has a new method, getLooseKeys(actor), that
identifies the loose keys in an actor's possession that are eligible
for automatic attachment when the keyring is taken.  By default, this
returns the actor's direct contents (i.e., the objects the actor is
directly holding).

<p>This can be overridden to consider, for example, loose keys held in
the actor's pocket.  To prevent the keyring from automatically
grabbing any keys when it's taken, simply override this method to
return an empty list.  Note that you don't need to bother limiting the
returned list to include only valid keys, since the caller does this
by considering only objects for which isMyKey() returns true.

</div>

<!------------------->
<div class=entry>

The function withParserGlobals() now takes an additional parameter
giving the actor who issued the command.  (This is an internal
function that's probably not used at all by existing game code, so it
should have no impact on games.  If you are calling this function,
though, note that you'll need to supply the extra parameter.)

</div>

<!------------------->
<div class=entry>

The menu system now sets the main content banner window to use
scrollbars if possible, and automatically scroll to show new text
in any case.  This ensures that hint lists that are too long to fit
in the window will scroll as needed to keep the last hint in view.

</div>

<!------------------------------- 3.0.6o --------------------------------->
<div class="sepbar"><a name='306o'></a>3.0.6o</div>
<p><b><i>Released 3/14/2004</i></b>
<p>

<div class=firstentry>

<p><b>Possible compatibility-breaking change:</b> The property
formerly named 'vocabWords_' has been renamed to 'vocabWords' (the
change is that the underscore formerly at the end of the name has been
removed).  The underscore suffix is conventionally used in the library
to indicate an internal library property that isn't normally for use
by game code, which obviously isn't appropriate in this case, as this
is the property that games usually initialize to set an object's
vocabulary words.

<p>You should search for instances of 'vocabWords_' in your existing
code, and replace them with 'vocabWords'.  Most existing game code
will probably have few, if any, instances of this property name, since
most object definitions in existing game code probably use the
standard library templates to set this property's value without giving
its name.  Even so, you should search through your code and update any
mentions to use the new name.

</div>

<!------------------->
<div class=entry>

The method getOutermostRoom(), which was previously defined in
BasicLocation and NestedRoom, has been moved instead to Thing.  This
ensures that the method will work properly even when a nested room is
located within a non-room object.  The Thing definition simply returns
the enclosing location if there is one, or 'self' if not.

</div>

<!------------------->
<div class=entry>

The new TopicEntry subclass AskTellGiveShowTopic makes it easy to
define a response that covers ASK, TELL, GIVE, and SHOW for a given
object or set of objects.  It's sometimes convenient to be able to
treat all of these commands as equivalent in handling a response.

<p>AskTellGiveShowTopic is based on the new class
TopicOrThingMatchTopic, which can be subclassed to create other
combinations of other subsets of these four verbs (or to add topic
entries for new custom game-defined verbs).  This new class combines
the features of the "Thing" and "Topic" base classes for topic
entries.

</div>

<!------------------->
<div class=entry>

ConvNode has a new method, autoShowTopics(), that returns true if the
node is to show a topic inventory automatically on activation.  By
default, this method returns true if the node contains any active
SpecialTopic entries.  You can override this if desired to generate a
topic inventory automatically under other conditions, or to suppress
the automatic inventory when an active special topic is present
(although the latter probably isn't a good idea).

<p>The main reason you might want to generate a topic inventory
automatically on activating a node is that the node contains one or
more obscure topics that players will be unlikely to guess on their
own.  If it's unlikely that the player would think to ask just the
right thing at just the right time, a topic inventory can help guide
them through the conversation by showing the possibilities.  As
always, only the topics you specifically mark as suggested (with
SuggestedAskTopic, etc) will be listed in the inventory.  When possible,
it's probably better from a game-design perspective to lead players
into asking the right questions more subtly, by putting the right
cues in the conversation itself; when this is impractical, the topic
inventory is a usable substitute.

</div>

<!------------------->
<div class=entry>

The pronoun expansion for CollectiveGroup objects that was introduced
in 3.0.6n has been partially removed.  In the past, when an individual
object was associated with a CollectiveGroup object, the parser
automatically added the group object into consideration for resolving
a subsequent pronoun referring to the individual.  This was meant to
provide better fidelity for resolving pronouns in these cases, but it
led to new problems when the original noun phrase could only have
referred to the individual.  To correct the problems, the parser no
longer puts the collective group into consideration when a pronoun
refers to one of the group's individuals.

<p>The other direction still applies, though: when a pronoun refers to
a CollectiveGroup object, the parser puts the group's associated
individuals into consideration for resolving the pronoun.

</div>

<!------------------->
<div class=entry>

A bug in the CommandTopic class (introduced in 3.0.6n) prevented it
from matching a single Action class as the matchObj correctly.  (It
did work properly when a list of Action classes was given, but not
when a single object was given.)  This has been corrected.

</div>

<!------------------->
<div class=entry>

The HelloGoodbyeTopic class now has its impliesGreeting property set
to true, ensuring that this topic type won't trigger an implied
greeting.  Since a HelloGoodbyeTopic is itself a greeting, an implied
greeting would be undesirable, not to mention that it caused a
run-time error when it occurred.

</div>

<!------------------->
<div class=entry>

A bug in ComplexContainer caused a problem when an object was
initially located in one of the the complex container's sub-containers
via the 'subLocation' property.  In the past, the ComplexContainer
didn't properly re-initialize the object's 'location' property to
reflect that it was actually in the sub-container.  This has been
fixed.

<p>The problem manifested as strange behavior when the contained
object was removed from the sub-container (via TAKE or the like).  In
particular, because the object's 'location' was still set to the
ComplexContainer, the object wasn't properly removed from the
sub-container's contents list, so the object appeared to still be in
the sub-container as well as in its new location.

</div>

<!------------------->
<div class=entry>

A couple of problems involving formatting and real-time events have
been fixed.  In 3.0.6i, fuses and daemons - including the real-time
versions - started running with a transcript context, which means
that their text output is captured.  This caused some interactions
with the input manager that weren't taken into account properly in
the library.

<p>First, if a real-time event itself stopped and asked for input from
the user (by reading a new command line, for example), the transcript
capturing prevented the text displayed by the event from showing up at
all until after the user entered something on the new command line.
It was possible to work around this by deactivating the transcript
prior to showing any output in the real-time event, but this is no
longer necessary.

<p>Second, even if a real-time event didn't display anything, its mere
silent firing caused an extra blank line to show up immediately after
the user next pressed the Enter key to finish a command line.

<p>Both of these problems are now corrected, so there's no need for
real-time events to do anything special with respect to output
formatting or command-line input.

</div>

<!------------------->
<div class=entry>

The new pre-defined message object parameter 'pc' can be used to
refer directly to the player character.  This is similar to the 'actor'
parameter, but refers to the player character actor even if an NPC is
the current active character.  An expression such as "{you pc/he}"
thus refers to the current gPlayerChar, not to the current gActor.

</div>

<!------------------->
<div class=entry>

The library messages for scoring (showScoreMessage,
showScoreNoMaxMessage, showScoreRankMessage, showFullScorePrefix)
incorrectly referred to the current actor rather than the current
player character, which resulted in attributing the score to an NPC
rather than to the player if a score message was generated on another
actor's turn.  These messages now explicitly refer to the player
character.

</div>

<!------------------------------- 3.0.6n --------------------------------->
<div class="sepbar"><a name='306n'></a>3.0.6n</div>
<p><b><i>Released 3/6/2004</i></b>
<p>

<div class=firstentry>

<b>Major compatibility-breaking change:</b> The library's main
entrypoints to the game have changed.  Existing games <b>must</b>
be modified to accommodate this change.

<p>In the past, the game code was responsible for defining two
entrypoints: main() and mainRestore().  The template games generated
by Workbench's "New Project" command defined these two functions as
one-liners that called mainCommon(), where the real action took place.

<p>In the new arrangement, the library now invokes methods of a
new object, gameMain, which each game <b>must</b> define.  For your
convenience, the library defines a class, GameMainDef, that you
can use as the base class of your gameMain object.  This base class
defines suitable defaults for the required methods, so you only have
to override what you need to customize.  Overall, this change should
result in much less required startup code for each game.

<p>If you use GameMainDef as the base class of your gameMain object,
you're only required to define one property in it:

<ul>

<li>initialPlayerChar - set this property to the Actor object that
serves as the initial player character in the game.  You <b>must</b>
set this; GameMainDef can't provide a default for you here.

</ul>

<p>In addition, there are a couple of optional optional methods that
you can use for customization:

<ul>

<li>showIntro() - show the game's introduction.  Most games will want
to override this to show the prologue text for the game.

<li>showGoodbye() - show the game's "goodbye" message.  Override this
if you want to add a parting message as the game terminates.

</ul>

<p>Most games will find it sufficient to define only initialPlayerChar
and showIntro(), and simply inherit the default handling for everything
else from GameMainDef.  However, there are several additional methods
that you can override if you want to do something special.

<ul>

<li>newGame() - the library invokes this method to start a new game.
The default version calls showIntro() to show the introductory text,
then runs the main command loop until the player quits, then calls
showGoodbye() to show the goodbye message.  You can override this
if you want to do something extra, such as showing a pre-game
options screen.

<li>restoreAndRunGame(filename) - the library invokes this method to
restore and start running a saved game that the user selected when
launching the interpreter.  It should rarely be necessary to override
this.

<li>setGameTitle() - the library invokes this method at start-up to
set the interpreter's window title to show the game's title, as
defined in versionInfo.name.  It should rarely be necessary to
override this.

</ul>

<p>If your existing game code uses the Workbench-generated template,
or you follow the same pattern, then rewriting your code to fit the
new design is relatively straightforward.  Just follow these steps.

<ul>

<li><b>Save a copy</b> of your existing code before you do anything
else.  If things don't seem to work properly after you finish
applying this update, you can compare the modified version with your
backup copy to help track down the problem.

<li><b>Delete</b> your main() and mainRestore() functions.  Your game
code doesn't need to define these routines at all any more, since the
library now defines them.

<li><b>Create</b> a new object definition for gameMain:

<p><pre>   gameMain: GameMainDef
     initialPlayerChar = me
     showIntro()
     {
       // TO DO!
     }
   ;
</pre>

<li><b>Find</b> your introductory text, and anything else you
customized in your old mainCommon() routine, and move it into the
showIntro() method (replacing the "TO DO!" comment in the
example above).

<li><b>Delete</b> your mainCommon() function.  It has now been
subsumed into your new gameMain object.

</ul>

<p>That's it - if you were using the standard Workbench template
for mainCommon(), you're now finished.

<p>If you made certain kinds of changes to the template main(),
mainRestore(), or mainCommon() that Workbench produced when you
originally created your game, you might have to do some additional
work.  These extra changes are uncommon, but check this list to make
sure they don't apply to you:

<ul>

<li>Do you have anything in main() or mainRestore() beyond a simple
call to mainCommon()?  If so, you'll probably have to move that code
into the showIntro() method, or you might even have to override
newGame() (and possibly even restoreAndRunGame()).  This is beyond the
scope of this simple recipe, so please refer to the definition of
GameMainDef in misc.t for full information on the new setup.

<li>If you customized the code in mainCommon() that restores the file
specified by 'restoreFile', you'll need to override
restoreAndRunGame().  You can probably just move your existing code
from your old mainCommon() into a new mainGame.restoreAndRunGame()
method.  Refer to the definition of GameMainDef in misc.t.

<li>If you player character isn't named 'me', you'll need to change
the initialPlayerChar definition accordingly.

</ul>

</div>

<!------------------->
<div class=entry>

<b>Minor Compatibility-breaking change:</b> A few properties that
were previously in libGlobal and other library objects have been
moved into the new gameMain object instead.  The relocated properties
all select optional library behavior; they've been moved to gameMain
to make it easier for game authors to select non-default option
settings.  In the past, you had to use 'modify' to change these
settings, or explicitly assign them from your startup code; now, you
simply have to include any non-default option settings as property
values in your gameMain object definition.

<p>The properties moved are:

<ul>

<li>The former libGlobal.verboseMode is now gameMain.verboseMode.

<li>The former exitLister.enableStatusline is now
gameMain.showExitsInStatusline.

<li>The former libGlobal.allowYouMeMixing is now
gameMain.allowYouMeMixing.

<li>The former libMessages.scoreRankTable is now
gameMain.scoreRankTable.

<li>The former libScore.maxScore is now gameMain.maxScore.  (This value
is also now nil by default, since there's no reason for the library to
assume a particular maximum score.)

</div>

<!------------------->
<div class=entry>

<b>Compatibility-breaking change:</b> The format of the verbPhrase
string has changed slightly for the English version of the library.
Game-defined verbs might need to be adjusted to the new format.

<p>The change is that prepositions in a verb phrase are now grouped
inside the parentheses of the "(what)" placeholders for the objects,
if the prepositions go with the noun phrases.  For example, the
LookIn action's verbPhrase string has changed from 'look/looking in
(what)' to 'look/looking (in what)'.  The difference is subtle: by
moving the preposition 'in' so that it's inside the parentheses with
the direct object's "(what)" placeholder, we're telling the library
that the 'in' is part of the direct object noun phrase.  Contrast
this with the verbPhrase for Doff, which is now 'take/taking off
(what)': this tells us that the preposition 'off' is part of the verb
structure, not part of the direct object.

<p>How can you tell which way it goes?  There are two rules you
should use to determine this.

<p>First, if the preposition separates the direct and indirect
objects, such as the IN in PUT X IN Y, then it <i>always</i> goes
inside the indirect object phrase, hence 'put (what) (in what)'.

<p>Second, for any other preposition, use the "it test": try writing
the verb using 'it' in place of 'what', and ask whether it sounds
right for the preposition to go before or after the 'it'.  For
example, for the Doff action, TAKE IT OFF sounds right, and TAKE OFF
IT is obviously wrong.  This means that the preposition 'off' belongs
in the verb phrase, hence 'take off (what)'.  In contrast, for the
LookIn action, LOOK IN IT sounds right, not LOOK IT IN, so the
preposition goes with the direct object, hence 'look (in what)'.  If
the "it test" indicates that the preposition goes <i>before</i> the
'it', then the preposition is part of the direct object and thus goes
<i>inside</i> the parentheses of the "(what)"; if the preposition
goes <i>after</i> the 'it', then the preposition is part of the verb
and goes <i>outside</i> the parentheses.

<p>Prepositions that go with the verb are uncommon in two-object
verbs, but they do occur.  An example from the library is
ConsultAbout, one form of which uses the verbPhrase 'look/looking up
(what) (in what)'.  We'd write LOOK IT UP IN IT, so the preposition
'up' goes after the direct object pronoun and is thus part of the
verb, while the preposition 'in' goes before the indirect object
pronoun and is thus part of the indirect object.  In case there's any
ambiguity about whether the 'up' goes with the verb or with the
indirect object, try the un-it test: we'd write LOOK UP TOPIC IN
BOOK, so clearly the 'up' is not part of the indirect object, but is
just part of the verb.

</div>

<!------------------->
<div class=entry>

<b>Compatibility-breaking change:</b> The TextList classes have been
removed, leaving only the more general EventList classes.  The
TextList classes have been gradually converging with the EventList
classes anyway, to the point where the TextList classes have become
nothing more than renamed versions of the corresponding EventList
classes.  Retaining the parallel set of names for otherwise equivalent
classes is bad because it steepens the learning curve for new users
and makes for more to remember for experienced users; so, the
redundant names have now been dropped.

<p>Existing code will need to be scanned for occurrences of TextList,
StopTextList, RandomTextList, ShuffledTextList, and SyncTextList.
Replace these names with CyclicEventList, StopEventList,
RandomEventList, ShuffledEventList, and SyncEventList, respectively.
(Note that you can simply do a global search-and-replace to change to
suffix TextList to EventList, except that you must change occurrences
the TextList when it occurs as an entire word to CyclicEventList.)

<p>In addition, the following property names must be changed:

<ul>
<li>textStrings to eventList
<li>firstStrings to firstEvents
<li>messagePercent to eventPercent
<li>messageReduceAfter to eventReduceAfter
<li>messageReduceTo to eventReduceTo
</ul>

<p>If you really don't want to change your existing code, you can
always use #define to create macros with the substitutions.  You
really should change your code if possible, though, since using the
old names is likely to create confusion as the old names recede from
your memory and from the documentation.

</div>

<!------------------->
<div class=entry>

<b>Compatibility-breaking change:</b> In ConversationReadyState,
the greeting and goodbye messages have been changed.

<p>First, the greetingList property is no longer used; instead, the
state now looks for a HelloTopic entry and uses its response.  In
addition, you can differentiate between explicit HELLO commands and
implied greetings generated by other conversational commands (ASK TO,
for example) by creating separate HelloTopic and ImpHelloTopic
objects.  In most cases, it's not necessary to distinguish the two
cases, so you can simply use a single HelloTopic to cover both cases.

<p>Second, the enterFromByeMsg and enterFromConvMsg methods have been
removed, along with the enterFromByeList and enterFromConvList
properties.  Instead, the state now looks for a ByeTopic or
ImpByeTopic entry, depending on whether the conversation is ending
due to an explicit GOODBYE command or due to an automatic ending (due
to the other actor walking away, or due to an inactivity timeout) and
uses its response.

<p>You should scan your existing game code for any greetingList,
enterFromByeMsg, enterFromByeList, enterFromConvMsg, and
enterFromConvList properties, and change them to HelloTopic,
ByeTopic, and ImpByeTopic as appropriate.

<p>Note that both the HELLO and GOODBYE topic entries go in the
ConversationReadyState, not in the InConversationState.  This is
because these handlers typically describe the transition to and from
the "ready" state.  A single in-conversation state could work with
several "ready" states, so putting the hello/goodbye topic entries in
the in-conversation state wouldn't allow any differentiation among
the several "ready" state transitions.  Keeping the hello/goodbye
entries in the "ready" states themselves makes this differentiation
easy.  For example, this allows a "goodbye" message to say something
like "Bob goes back to sweeping the porch."

<p>

</div>

<!------------------->
<div class=entry>

<b>Possibly compatibility-breaking change:</b>  The internal methods
that handle conversational commands in Actor have changed.  The changes
are isolated to the internal methods that route the commands within
and between the Actor and ActorState objects, not to the main public
interfaces that game code usually uses.  Even so, since it's occasionally
useful to override these internal methods, some existing game code
might be affected.

<p>In general terms, these changes are designed to concentrate the
handling of all conversational actions along a single path.  In the
past, each type of conversational command was handled by its own
cluster of methods, so the Actor and ActorState had a set of parallel
methods for HELLO, GOODBYE, YES, NO, ASK ABOUT, ASK FOR, TELL ABOUT,
SHOW TO, and GIVE TO.  This old design was intended to make it easy to
override these handlers in isolation, but experience has since shown
that it's much more useful to be able to override all of the handlers
in concert instead.  The new design therefore consolidates all of
these different conversational actions into a single method that's
parameterized with the type of action.  There are still several
methods because of the sequence of processing points through the Actor
and ActorState, but there are no longer several clusters of methods:
each of the old clusters is now a single method.

<p>An additional benefit of these changes is that HELLO and GOODBYE
are now handled through the topic database like everything else.  This
has two useful effects.  First, it means that a DefaultAnyTopic entry
will now respond to a HELLO or GOODBYE along with everything else.
This is highly desirable in most cases, because these defaults are
usually meant to convey a blanket response to all conversational
overtures.  Second, it means that it's now a bit easier to customize
HELLO and GOODBYE responses: just use HelloTopic, ByeTopic, and
HelloByeTopic objects as desired.

<p><b>Advice:</b> Because there are a lot of details to these
changes, we suggest you scan your code for mentions of the affected
methods, to see if your code is affected at all.  If your code
doesn't define or call any of these methods, you shouldn't be
affected.  The methods are:

<p>
<ul>
<li>sayToActor
<li>handleConversation
<li>yesNoFrom
<li>answerQuestion
<li>hearAbout
<li>beShown
<li>beGiven
<li>answerRequestFor
</ul>

<p>Now to the specific changes.

<p>Actor.sayToActor() has some changes to its parameters.  The
'prop', 'propArgs', and 'topicListProp' parameters have been dropped,
and the new 'topic' and 'convType' parameters have been added.
'topic' is a special object representing the topic; the library
defines the singletons helloTopicObj, byeTopicObj, yesTopicObj,
and noTopicObj for the corresponding library actions.  'convType'
is an object of type ConvType describing the type of action being
performed.

<p>The new helloTopicObj and byeTopicObj singletons have
been added, as mentioned above.  These are used as special topic
placeholders for the HELLO and GOODBYE commands, respectively.

<p>The new ConvType class has been added, and singleton
instances for all of the standard library conversation actions (HELLO,
GOODBYE, YES, NO, ASK ABOUT, ASK FOR, etc.) have been defined.

<p>The 'topicListProp' and 'handler' parameters of
ActorState.handleConversation() has been dropped, and the new
'convType' parameter has been added.  'convType' is a ConvType
object representing the conversation type.

<p>The 'topicListProp' parameter of
ConvNode.handleConversation() has been replaced with a new 'convType'
parameter, which is a ConvType object describing the conversation
type.

<p>Actor now provides a handleConversation() method.  The
ActorState will invoke this method by default when the ActorState's
own handleConversation() method doesn't handle the action.  This new
Actor method is in lieu of the former cluster of per-command handlers
in Actor: yesnoFrom, answerQuestion, hearAbout, beShown, beGiven,
answerRequestFor.

<p>All of the per-command handlers in Actor and ActorState
have been removed: yesNoFrom, answerQuestion, hearAbout, beShown,
beGiven, answerRequestFor.  These are replaced by the
handleConversation() method in Actor and ActorState, as mentioned
above.

<p>The new Actor method defaultConvResponse() is a general
handler for showing the default response when a conversational action
isn't otherwise handled (that is, it's not handled by any topic
database entry, and the ActorState doesn't want to handle it
specially).  This new method provides an easy way to show the same
response for every conversational action - just override this one
method, and you can show a common response for all conversation
commands.  By default, this method routes looks at the convType
parameter to determine the conversation type, and invokes the Actor
method that provides the default response for that particular
conversation type, using the same default response methods used in the
past (defaultGreetingResponse, defaultGoodbyeResponse, etc).

<p>The ActorState object can now <i>optionally</i> define any
of the default response handlers that Actor can define
(defaultGreetingResponse, defaultAskResponse, etc).  When these are
defined, they'll be called when the state object doesn't provide a
suitable TopicEntry in its topic database.  Note that these
effectively override the Actor's topic database <i>and</i> default
response handlers for a given type of action.  The order of handling
for a conversational action is now ConvNode, ActorState TopicEntry
list, ActorState default response method, Actor TopicEntry list, and
finally Actor default response method.

</div>

<!------------------->
<div class=entry>

<b>Possibly compatibility-breaking change:</b> A change to the
library's message system makes it easier to customize the default
response messages for individual objects.  In the past, if you wanted
to customize the message for OPEN COCONUT, say, you'd have to
override the 'verify' method for the 'coconut' object's
dobjFor(Open).  With this change, you can create a custom per-object
message more easily: you simply define coconut.cannotOpenMsg with the
custom message string.

<p>You can use the new message customization scheme any time the
library generates a standard response message using code like this:

<p><pre>  dobjFor(Open)
  {
    verify { illogical(&amp;cannotOpenMsg); }
  }
</pre>

<p>Any time you see library code like that, you can override the
default response message for that action on an individual object
simply by defining the message property in your object:

<p><pre>  coconut: Thing
    cannotOpenMsg = '{You/he} would need something sharp to do that. '
  ;
</pre>

<p>In addition to illogical(), this also works with illogicalNow(),
inaccessible(), defaultReport(), defaultDescReport(), extraReport(),
mainReport() reportBefore(), reportAfter(), reportFailure(), and any
other verify or action reporting routines.

<p>Here's how this works.  In the past, when a verify, check, or
action routine generated a message using a message property, the
library looked up the message in the current actor's "action message
object," which is usually playerActionMessages when the actor is the
player character, and npcActionMessages otherwise.  Now, the library
still looks there, but only <i>after</i> checking the individual
objects involved in the command to see if any of them define the
message property.

<p>The library looks first at the direct object, then at the indirect
object.  If you were to create your own custom verbs with three or
more object slots, such as PUT COIN IN SLOT WITH TWEEZERS, the
library would automatically continue on to those extra objects as
well.  If the library finds the message property in any of these
objects, it stops and uses that object as the source of the message;
if it can't find the message property among these objects, the
library simply falls back on the standard message object
(playerActionMessage or whatever).

<p><b>Important:</b> As part of this change, all of the library
message properties have been renamed to end in "Msg".  This affects
every message property, so if you've created your own "action message
object," or you've used 'modify' to change playerActionMessages
and/or npcActionMessages, you'll have to do some extensive searching
and replacing to add the "Msg" suffix to every message property name.
Sorry about this; the proposed change was put to the TADS 3 mailing
list, and no one objected.  The naming change isn't gratuitous.  The
reason for the name change is that it should greatly reduce the
chances of collisions between message properties and properties
defined for internal use by an object.  The library itself formerly
had a number of these collisions, so it was necessary to rename at
least those properties; using the naming convention consistently for
all of the message properties will help ensure that games don't
inadvertantly introduce their own name collisions.

<p>There's one last detail to mention.  An object can override a
message property with <i>another</i> message property.  For example,
the Vaporous object in the library uses this feature:

<p><pre>  notWithIntangibleMsg = &amp;notWithVaporousMsg
</pre>

<p>When a message property in an object points directly to another
property, the library takes this as an indirection to another library
message from the action message object.  This feature is mostly for
the library's benefit, since library objects are required to get all
of their messages from the action message object (to ensure that the
library can be translated without rewriting entire object
definitions).

</div>

<!------------------->
<div class=entry>

<b>Minor compatibility-breaking change:</b> The Script method
getState() has been renamed to getScriptState(), and the Script
property curState has been renamed to curScriptState.  This change
allows Script and its subclasses to be combined (with multiple
inheritance) with Thing (which defines its own meaning for getState)
and with Actor (which defines its own curState).  It's sometimes
desirable to combine Thing or Actor with a Script subclass, because
that's an easy way to attach simple scripting behavior to these
objects.

<p>Existing game code that overrides or calls getState or curState
for a Script object (including any EventList subclass) will need to
be changed to use the new name.  You should scan your source code for
occurrences of these names, and rename them as needed.  Note that
you should <b>not</b> rename curState properties that pertain to
Actor objects, since Actor.curState has <b>not</b> been renamed.

<p>In most cases, game code won't have any reason to override or
access these script properties at all, so most game code should be
unaffected by this change.  Game code usually just defines instances
of the library EventList subclasses using templates, and such code
won't be affected by this change.

</div>

<!------------------->
<div class=entry>

<b>Minor compatibility-breaking change:</b> The library objects
redirectTravelIn, redirectTravelOut, and redirectTravelDown have been
renamed to askTravelIn, askTravelOut, and askTravelDown,
respectively.  The names changes are for consistency with the naming
of the new class AskConnector.

</div>

<!------------------->
<div class=entry>

The PresentLater class has a new property, initiallyPresent, that lets
you override the standard behavior of the class, which is to make the
object initially absent from the game map.  This new property is set
to nil by default; if you override it to true, the object will be
initially present in the game, like any ordinary object.  This new
property would seem to defeat the purpose of the class, but it
actually extends the class to situations where an object comes and
goes during the game, but starts out present.  Using PresentLater with
initiallyPresent set to true, you can still use all of the
PresentLater showing and hiding mechanisms, such as the key-based and
conditional methods; this is often more convenient than moving objects
in and out of the game map individually and manually.

</div>

<!------------------->
<div class=entry>

The Attachable class now automatically notifies itself and each of its
attachments whenever the Attachable is carried by a traveler, by
calling the new method travelWhileAttached().  The method does nothing
by default, but games can override it as needed to enforce conditions
or carry out side effects when an attached object is moved indirectly
via travel.

</div>

<!------------------->
<div class=entry>

The Attachable class now has a way of specifying the "direction" of
an attachment relationship, for the purposes of descriptive messages.
Formerly, attachments were always described symmetrically: if A was
attached to B, then examining A generated a status message along the
lines of "A is attached to B," while examining B generated a message
like "B is attached to A."  This didn't always work; "the note is
attached to wall" is fine, but "the wall is attached to the note"
isn't quite right.  The new feature lets you specify that the note is
always said to be attached to the wall, never vice versa.

<p>The direction of a relationship is specified by the new Attachable
method isMajorItemFor(obj).  By default, this method always simply
returns nil, which means that there are no "major" items by default,
which makes all attachment relationships symmetrical by default.  If
you wish, you can override isMajorItemFor() so that it returns true
in some cases.  When A.isMajorItemFor(B) returns true, the
relationship will always be described such that B is said to be
attached to A: examining A will yield "a B is attached to the A,"
while examining B will show "the B is attached to an A."

<p>A few new methods have been added to support the new feature;
these are mostly for internal use, but could potentially be used by a
game to fine-tune the way attachments are listed.  The new method
isListedAsAttachedTo(obj) lets the object indicate whether or not
'obj' is listed among the things 'self' is attached to; by default,
this returns true if 'obj' isn't permanently attached <b>and</b>
'self' isn't the "major" item for 'obj'.  The new method
isListedAsMajorFor(obj) is essentially the major-list counterpart: it
indicates whether or not 'obj' is listed among the things attached to
'self' when 'self' is described.  By default, this method returns
true if 'self' <b>is</b> the "major" item for 'obj', <b>and</b>
obj.isListedAsAttachedTo(self) returns true (that is, 'obj' thinks it
should be listed as attached to 'self').  Finally,
majorAttachmentLister returns the lister to use for the items
attached to 'self' for which 'self' is the "major" item in the
relationship; by default, this uses a MajorAttachmentLister instance.

</div>

<!------------------->
<div class=entry>

The new classes Underside, RearContainer, and RearSurface make it
easier to model situations where one object is behind or under
another.  Underside can be used to model the space under an object, or
for the bottom surface of an object.  RearContainer models the space
behind an object, and RearSurface models its back surface.

<p>In addition to letting you set up "under" and "behind"
relationships among objects initially, these new classes support the
PUT UNDER and PUT BEHIND commands to let actors add new contents under
and behind the objects.  (The PUT BEHIND command is also new in this
release.)  An Underside can have new objects added under it with PUT
UNDER, and a RearContainer or RearSurface can have new contents added
with PUT BEHIND.  These commands can optionally be disallowed for a
given Underside or RearContainer/RearSurface: override the properties
allowPutUnder and allowPutBehind, respectively.  The new classes
derive from BulkLimiter, so you can use the usual BulkLimiter
properties to control the individual and total bulk allowed under and
behind the objects.

<p>ComplexContainer has been extended to support these new classes.
The new ComplexContainer property subUnderside can be set to an
Underside object representing the space under or bottom surface of the
complex container; the new property subRear can be set to a
RearContainer or RearSurface representing the space behind or back
surface of the complex container. PUT BEHIND and LOOK BEHIND commands
on the complex container are routed to the subUnderside; PUT UNDER and
LOOK UNDER are routed to the subRear; and both subcomponents are
included in the regular LOOK AT display.

<p>These additions were adapted from work originally done by Eric Eve.

</div>

<!------------------->
<div class=entry>

It's now easier to set up objects so that they're initially inside the
component sub-containers of a ComplexContainer.  In the past, if you
wanted to create an object in your source code so that it was
initially inside a ComplexContainer's internal container, for example,
you had to explicitly set the object's 'location' property, rather
than using the "+" syntax.  Now, you can use the "+" syntax as long as
you add a little extra information: give each contained object a new
property, 'subLocation', and set it to the property of the component
sub-container you want to use as the initial location.  For example,
here's how you'd create a washing machine as a complex container,
with a blanket inside and a laundry basket on top:

<p><pre>
  + washingMachine: ComplexContainer 'washing machine' 'washing machine'
    subContainer: ComplexComponent, Container { /* etc */ }
    subSurface: ComplexComponent, Surface { /* etc */ }
  ;

  ++ Thing 'blanket' 'blanket'
    subLocation = &amp;subContainer
  ;

  ++ Container 'laundry basket' 'laundry basket'
    subLocation = &amp;subSurface
  ;
</pre>

<p>The blanket and the laundry basket are nominally directly inside
the washing machine itself, according to the "+" syntax, but their
'subLocation' settings ensure that they end up in the desired
component sub-containers during initialization.

<p>Note that 'subLocation' is only intended for initialization, so the
library automatically sets subLocation to nil for each object right
after the initial setting is used.  This helps avoid any unpleasant
surprises should the object be moved into a different ComplexContainer
later on.  When you're moving objects around on the fly in your
program code, there's no reason to use subLocation at all; instead,
just specify the appropriate component as the explicit destination of
the moveInto: <tt>towel.moveInto(washingMachine.subSurface)</tt>, for
example.


</div>

<!------------------->
<div class=entry>

The Openable class has a new property, openingLister, that specifies
the lister to use to display the list of items revealed when the
object is opened.  By default, this is set to the
openableOpeningLister object.  Individual objects can override this
if they want to customize the message listing the revealed items.

<p>In addition, the object formerly called openingLister has been
renamed to openableOpeningLister.

</div>

<!------------------->
<div class=entry>

The new CommandTopic makes it easier to generate a response when an
NPC receives a particular command.  Just create a CommandTopic, with a
list of the Action classes you wish to match.  Actions are matched on
class alone; if you want to match something more specific, such as
matching a particular direct object of a particular action, you'll
have to create a custom matchTopic() method for your CommandTopic
object.  If you want to create a default response that matches any
action, use a DefaultCommandTopic.

<p>CommandTopic works like any other TopicEntry object, so you can put
these in ConvNode, ActorState, and Actor topic databases to provide
responses under the specific conditions you need to match.

<p>As part of this change, ActorState.obeyCommand() now invokes
handleConversation() to look for a response to the command, specifying
the Action object as the topic and 'commandConvType' as the
conversation type object.  This looks as usual in the ConvNode,
ActorState, and Actor conversation topic databases for a CommandTopic
to handle the response, or for a DefaultAnyTopic if there's no
CommandTopic.

</div>

<!------------------->
<div class=entry>

The parser now gives more weight to explicit owners when resolving
possessives.  If a noun phrase is qualified by a possessive ("my
book"), and the noun phrase is ambiguous even with the possessive
qualifier (because the possessor is carrying more than one matching
object), the parser will now choose an object with an explicit
"owner" property over one without an explicit owner.  When the parser
resolves this kind of ambiguity by choosing an explicitly owned
object over one that's merely being carried, it will mark the chosen
object with the UnclearDisambig flag to indicate that it's a best
guess.

</div>

<!------------------->
<div class=entry>

The library no longer treats "brightness" (the sensory intensity of
light, sound, etc.) as diminishing over a "distant" containment
boundary.  In the past, distance diminished brightness by one level.
While this was arguably physically realistic over large distances, in
practice it proved to be undesirable for the typical scales in IF
settings, where "distant" is usually used to indicate that something's
tens or hundreds of feet away, not miles.

</div>

<!------------------->
<div class=entry>

The sense mechanism has a new feature that allows an object to take on
its own special sensory status.  An object can use this feature to
override the normal sense path mechanism and decide for itself how it
appears to the senses.  The change is comprised of two new methods.

<p>First, when building the sense information table, the library now
calls a new method, addToSenseInfoTable, on each object connected by
containment to the source object.  This method by default does what
the library has always done: it evaluates the temporary sense
properties set up by the containment path traversal, and adds a
SenseInfo object to the table based on the sense properties.  An
objects can now override this method to add a table entry based on a
different sensory status.

<p>Second, when finding the containment paths from one object to
another, the library calls the new method specialPathFrom on the
target object if (and <b>only</b> if) no ordinary containment path can
be found.  This method can supply its own custom containment path.
This allows an object to exist outside of the normal containment
hierarchy but still get a chance to represent its connection to
the normal containment hierarchy as it sees fit.

</div>

<!------------------->
<div class=entry>

When a CollectiveGroup object has no location, it now takes on the
sensory status of its individuals.  It will take on the "best" sense
status of any individual in scope, which is the one that's most
transparent and (transparencies being equal) has the highest ambient
level.

<p>This change makes it much easier to work with CollectiveGroup
objects, because it makes a CollectiveGroup as visible, audible, etc.
as any of its individuals.

<p>Note that this change doesn't affect CollectiveGroup objects that
have a normal location.  These objects already participated in the
sensory model in the normal manner, and will continue to do so.  This
change only affects group objects with no location.

</div>

<!------------------->
<div class=entry>

The handling of the "catch-all" Default handlers has changed
slightly.  The sequence of processing is now as follows:

<p>
<ul>
<li>The iobjFor(All) and dobjFor(All) handlers run first, if defined.
<li>The iobjFor(Default) and dobjFor(Default) handlers run next, <i>if</i>
they "override" the verb-specific handlers.
<li>The iobjFor() and dobjFor() handlers for the specific verb run next,
<i>unless</i> the corresponding Default handlers override them
</ul>

<p>In the past, the 'verify', 'check', and 'action' methods for the
Default handlers were called <i>in addition to</i> any verb-specific
versions of the methods.  For example, if an object defined a
dobjFor(Default) with an action() method, and the player entered an
OPEN command on the object, the Default action handler ran, and then
the dobjFor(Open) action() method <i>also</i> ran.  In most cases,
this made no difference, because the base Thing class doesn't even
define action() or check() handlers for most verbs, since it
disallows most verbs in the verify() stage.

<p>With this change, the Default handlers now run <i>instead of</i> the
verb-specific handlers, when the Default handlers run at all.  The
rules about when Default handlers override verb-specific handlers,
and vice versa, haven't changed.  A Default handler still overrides
any verb-specific handler inherited from a base class, and any
verb-specific handler defined in the same class as the Default
handler or in any subclass still overrides that Default handler.

<p>Note that the relative order of the All and Default handlers has
been reversed: the All handler now always runs first.  This makes the
sequence of methods proceed from most general to most specific.

</div>

<!------------------->
<div class=entry>

If an 'exit' occurs within a PreCondition object's
checkPreCondition() method, it's now treated as a failure of the
enclosing action that invoked the precondition.  The normal pattern
that most preconditions use is as follows: first, evaluate if the
condition is met; second, if the condition isn't met, try an
appropriate implied action to try to bring it into effect; third,
re-test the condition to see if the implied action did what it was
meant to; and fourth, if the condition still doesn't apply, use
'exit' to terminate the triggering action.  It's this use of 'exit'
that's now interpreted as a failure of the enclosing action.

<p>Note that this doesn't apply if 'exit' is used within a nested
implied action; this only applies if 'exit' is used within the
precondition's checkPreCondition() method itself.

</div>

<!------------------->
<div class=entry>

The library now defines a template for the Achievement class, taking
a double-quoted string for the achievment's description text.

</div>

<!------------------->
<div class=entry>

The new function finishGameMsg() makes it easier to show one of the
conventional end-of-game messages, such as "*** YOU HAVE DIED ***" or
"*** YOU HAVE WON ***".  This function takes two parameters: a
message specifier, and a list of extra finishing options.  The extra
options are the same as for the existing function finishGame().

<p>The message specifier can be one of several standard, pre-defined
objects, or it can simply be a string to display.  The pre-defined
object ftDeath, ftVictory, ftFailure, and ftGameOver display messages
for death of the player character ("YOU HAVE DIED"), victory ("YOU
HAVE WON"), failure ("YOU HAVE FAILED"), and simply "game over",
respectively.  Alternatively, you can make up your own messages for
unconventional cases ('YOU HAVE SUFFERED A FATE WORSE THAN DEATH',
say) simply by specifying a string.  Your string will be displayed
surrounded by "***" sequences to yield the conventional formatting,
or with other sequences that might vary by language.  You can also
pass nil as the message specifier, in which case no message at all
is displayed.

</div>

<!------------------->
<div class=entry>

The value of gameMain.maxScore (formerly libScore.maxScore) is now
allowed to be nil.  In addition, the default value in GameMainDef is
now nil.  When this value is nil, the SCORE and FULL SCORE commands
simply won't mention a maximum score for the game.

<p>If your game has complex scoring that makes it difficult or
impossible to state a maximum possible score, or if you simply don't
want to give this information to the player, simply set maxScore to
nil in your gameMain object.  The library uses nil as the default
because there's no reason for the library to assume that a game will
have a particular maximum score (the library formerly used a default
value of 100, but this was overly presumptuous).

</div>

<!------------------->
<div class=entry>

The library's scoring system has a new, optional usage style that
provides two benefits.  First, it lets you define the number of points
an Achievement is worth as part of the Achievement object, better
encapsulating the information about the Achievement.  Second, the
library can use this new information to automatically compute the
maximum possible score in the game, saving you the trouble of figuring
this out manually (and of keeping the stated maximum in sync with the
game as you make changes).

<p>If you explicitly set the maxScore property in your gameMain object,
the library will <b>not</b> automatically compute the maximum score.
Your explicit maxScore setting always overrides the computed value.

<p>To take advantage of the new capabilities, simply define the new
'points' property for each Achievement object you create.  Then,
rather than calling addToScore() or addToScoreOnce(), both of which
take a parameter specifying the number of points to award, call the
new Achievement methods awardPoints() or awardPointsOnce() instead.
For example, suppose you have some existing code that looks like
this:

<p><pre>
  vase: Thing
    handleBreakage()
    {
      // ... do the real work here...

      scoreMarker.addToScoreOnce(10);
    }

    scoreMarker: Achievement { "breaking the base" }
  ;
</pre>

<p>This code defines a nested object called 'scoreMarker' to describe
the scoring item, and the 'handleBreakage' method awards the Achievement
object, assigning it 10 points in the score.  Using the new style,
you'd change the code above to look like this instead:

<p><pre>
  vase: Thing
    handleBreakage()
    {
      // ... do the real work here...

      scoreMarker.awardPoints();
    }

    scoreMarker: Achievement { +10 "breaking the base" }
  ;
</pre>

<p>The "+10" in the nested Achievement definition assigns the object a
value of 10 in its 'points' property (using a template defined in
adv3.h), indicating that the item is worth 10 points in the score.
Rather than specifying this in the code that awards the Achievement,
we define it as part of the Achievement object itself.  The code that
awards the points doesn't need to specify the number of points; it
just calls the awardPoints() method of the Achievement object, which
awards the points defined in the object.  This makes the code easier
to read, since you can see the description of the scoring item and the
number of points it's worth in one place.

<p>To take advantage of the library's automatic computation of the
maximum possible score, you have to follow a few rules:

<ul>

<li>Use <b>only</b> Achievement objects to award points.  Never
call addToScore() with a string value to award an ad hoc scoring item.

<li>Set the 'points' property of each of your Achievement objects
to the number of points the item is worth.

<li>If an Achievement can be scored more than once, <b>also</b> set
the 'maxPoints' property to the maximum number of points the item will
contribute to the score.  This is usually just 'points' times the number
of times the item can be awarded.

<li>Only define Achievement objects statically.  Never use 'new
Achievement' to create an Achievement dynamically.  (If you create new
Achievements dynamically, the library won't know about them at
start-up time, obviously, so it can't count their contributions to the
maximum score.)

<li>Always award Achievements through their awardPoints() or
awardPointsOnce() methods.  (This ensures that each Achievement is
scored with the number of points specified in its 'points' property.)

<li>Achievements can't be mutually exclusive.  That is, there must
exist at least one solution of the game in which every Achievement
object is awarded.  (If you have Achievement objects that represent
different solutions to the same puzzle, so that only one of these
achievements can actually be awarded in any given traversal of the
game, the library would incorrectly count the score contributions of
all of the alternatives in the maximum score.  The correct maximum
would count only the single highest score among the alternatives.  The
library has no way of expressing mutual exclusion among Achievements,
so if your game has such a situation, you'll need to set
libScore.maxScore manually.)

</ul>

<p>If you follow these rules, the library will accurately compute the
maximum score value, so you don't need to bother figuring out how many
points are in the game yourself, and you don't need to worry about
initializing libScore.maxScore in your game's start-up code.

<p>If your game can't follow the rules above (because you have
alternative solutions to puzzles that assign different scores, for
example, or because your game has alternative paths with different
maximum scores), you'll need to figure the maximum score manually,
and set the property 'maxScore' to this value in your 'gameMain'
object.  Explicitly setting gameMain.maxScore in your code will
override the library's automatic computation.

</div>

<!------------------->
<div class=entry>

The finishGame() and finishGameMsg() functions now display the
current score (using the same message that the SCORE command normally
displays) if the finishOptionFullScore option is in the extra options
list.  In fact, these functions will announce the score if any extra
option has the property showScoreInFinish set to true;
finishOptionFullScore has this option set to true, so including it in
the extra options list causes the score to be announced.  If you want
the end-of-game announcement to include the score, but you don't want
to offer the FULL SCORE option, you can include finishOptionScore in
the extra options list; this is an "unlisted" option, so it doesn't
add anything to the list of offered option list, but it does cause
the end-of-game announcement to include the score.

</div>

<!------------------->
<div class=entry>

Actor.holdingDesc (which provides the default description of what an
actor is holding as part of processing an Examine action on the
actor) now uses pretty much the same handling that Thing uses when it
lists the contents of an object.  The only difference is that
Actor.holdingDesc still uses the special holdingDescInventoryLister
as the contents lister.  One important consequence of this change is
that examining an actor marks the actor's contents as having been
seen by the player character, just as examining an ordinary object
marks the object's contents as seen.  Another is that the scope of
objects included in the listing is limited to objects the
point-of-view actor can actually see.  In the past, the examined
actor listed everything in "inventory scope," which includes objects
that are directly held even if they're not currently visible; this is
correct for an inventory listing from the point of the view of the
actor taking the inventory (because the actor can presumably identify
directly held items by feel, even in the dark), but the new
sight-only behavior is more appropriate for examining another actor.

<p>This change also adds a new Thing method examineListContentsWith().
This is simply a service method that performs the bulk of what
Thing.examineListContents() did before, but is parameterized by
a lister to use to generate the listing.

</div>

<!------------------->
<div class=entry>

The new class AskConnector makes it easy to define a directional
connection when the direction is ambiguous.  For example, suppose
that you have two doors leading north, and you don't want to use the
traditional trick of distinguishing the doors' respective directions
as northeast and northwest.  (If you had ten doors leading north
instead of two, the traditional northeast/northwest trick wouldn't
help anyway.)  If the player types NORTH, you would like the parser
to ask which door to use.

<p>AskConnector makes this easy.  Simply define the room's 'north' as
an AskConnector object, and set the AskConnector instance's property
'travelAction' to 'GoThroughAction'.  The connector, when invoked for
travel, will try running the GoThroughAction, but with a missing
direct object; this will make the parser ask the player which door to
use with the usual prompt for a missing object: "What do you want to
go through?"

<p>If the direction has a specific set of possible objects, as in
our example of two doors leading north, you can further refine the
parser's question by specifying the 'travelObjs' property.  Set this
to a list of the possible direct objects for the action.  If you set
this property, you should also set 'travelObjsPhrase' to a string
giving the noun phrase to use in disambiguous questions: in our
example, we might set this to 'door', so that the question becomes
"Which door do you mean...?".

</div>

<!------------------->
<div class=entry>

The English library now provides a default verbPhrase for the
TravelVia action ('use/using (what)', which is pretty vague, but
TravelVia is fairly vague itself).  This lets the parser generate
usable messages in cases where a TravelVia action elicits a parser
prompt, such as when using TravelVia in askForDobj().

</div>

<!------------------->
<div class=entry>

TravelPushable has several small changes.

<p>First, TravelPushable.movePushable() now uses moveIntoForTravel()
to move the object, rather than moveInto().  This corrects a problem
that occurred when the starting and destination locations were
connected by a sense connection (such as a distance connector).

<p>Second, movePushable() and describeMovePushable() each now take an
additional argument giving the connector being traversed.

<p>Third, the new method beforeMovePushable() gives the pushable
object a chance to do any necessary work just before the travel takes
place.  This is especially useful for adding a message describing
anything special that happens when pushing the object out of its
current location.  By default, this routine does nothing.

</div>

<!------------------->
<div class=entry>

The new Traveler methods canTravelVia() and explainNoTravelVia() allow
a traveler to disallow travel via a particular connector and/or to a
particular destination.  These new methods essentially provide a
complement of the "travel barrier" mechanism, which allows a connector
to disallow travel by a particular traveler.  The new methods are
useful becuase it's often more convenient to tie a travel condition to
the traveler than to the connector.  For example, you might want to
implement a condition that prohibits a particular actor from going
outside; you could do this by defining a canTravelVia() method on the
actor that returns nil if the destination is an OutdoorRoom.

</div>

<!------------------->
<div class=entry>

The new BasicLocation methods enteringRoom(traveler) and
leavingRoom(traveler) make it more convenient to write code that
responds to an actor's arrival into or departure from a room.  These
methods are called from travelerArriving() and travelerLeaving(),
respectively; they differ only in that (1) they have simpler
parameter lists, leaving out information that frequently isn't needed
to write an arrival/departure event handler, and (2) the base class
implementations don't do anything, so there's no need to use
'inherited' to inherit up the base class behavior.  These new methods
are purely for convenience, to make the very common task of writing
arrival/departure event handlers a little less work.

</div>

<!------------------->
<div class=entry>

The new class ContainerDoor makes it easy to create a door for a
container, if you want the door to act like a separate object in its
own right.  This works with the ComplexContainer class: create a
parent as a ComplexContainer, and inside it create a ContainerDoor
and the normal secret actual Container.  The door will redirect
commands like open, close, lock, and unlock to the secret inner
container, but will still appear as a separate object.

</div>

<!------------------->
<div class=entry>

In the past, the base TravelConnector methods describeArrival() and
describeDeparture() simply showed the most generic travel messages
("Bob is leaving the area").  This meant that replacing a simple room
connection with a TravelMessage connector meant giving up the
directional message that a normal room connection generated ("Bob is
leaving to the east").

<p>Now, the directional message is the default in the base
TravelConnector class.  If there's a direction property linked to the
connector from the origin (for a departure) or destination (for an
arrival), the base TravelConnector messages will now show the
directional version of the message.  The generic, non-directional
message will only be shown when no directional link can be found.
Note that this doesn't affect the more specific types of connectors
and their custom messages, so stairs will still say "Bob goes up the
stairs," doors will still say "Bob leaves through the wooden door,"
and so on.

</div>

<!------------------->
<div class=entry>

The new TravelConnector method isConnectorPassable() indicates whether
or not a traveler can pass through the connector.  This can be used in
game code that probes the map to determine if a connector can be
traversed in its current state.

</div>

<!------------------->
<div class=entry>

In the past, the noTravel object, and the NoTravelMessage and
FakeConnector classes, incorrectly displayed their special messages on
attempted travel even when it was dark in the room.  In the dark, the
"dark travel" message should take precedence.  This has been
corrected.  (The problem was that these classes overrode the
dobjFor(TravelVia) check() method to bypass the normal darkness check.
The unnecessary override has been removed, so the standard darkness
check is now made, so the dark-travel message is now shown instead of
any special message.)

</div>

<!------------------->
<div class=entry>

The BasicLocation methods getTraveler() and getPushTraveler() have
been renamed and moved into Thing.  These methods are now called
getLocTraveler() ("get location traveler") and getLocPushTraveler()
("get location push traveler"), respectively.

<p>This change is necessary to allow actors to hold other actors, and
to allow intermediate containers within rooms (that is, to allow a
Room to hold an arbitrary Thing subclass, which in turn holds a
NestedRoom).  Actor has methods with the names getTraveler() and
getPushTraveler(), but these methods have a different purpose than the
old BasicLocation methods: the Actor methods get the traveler when the
actor is initiating the travel, and the old BasicLocation methods get
the actual traveler when a traveler within the location initiates
travel.  The use of the same name created a conflict between these
different purposes, so one or the other set had to be renamed.  In
addition, limiting these methods to BasicLocation prevented ordinary
Things from holding actors who could travel; adding them to Thing
corrects this.

</div>

<!------------------->
<div class=entry>

The logic in Vehicle.getTraveler() that determines whether to move
the vehicle or the traveler within the vehicle has changed slightly.
Rather than basing the decision on travel barriers, the routine now
moves the traveler rather than the vehicle only if the connector is
contained within the vehicle - that is, the connector leads somewhere
from inside the vehicle.  The connector is considered to be inside
the vehicle if (1) it's a physical object (a Thing) that's inside the
vehicle, or (2) one of the direction properties of the vehicle is set
to the connector.  (The old logic had the undesirable side effect of
implicitly removing the traveler from the vehicle if the vehicle
couldn't cross a barrier, which was really too automatic.)

</div>

<!------------------->
<div class=entry>

In the past, the way push-travel actions was handled caused a problem
in certain cases involving remapping of actions.  The problem showed
up most readily with StairwayUp and StairwayDown objects;
specifically, PUSH x DOWN acted differently than PUSH x DOWN y, where
y was a StairwayUp or StairwayDown and the room's 'up' or 'down'
pointed to y.  These commands obviously should have been equivalent.

<p>Stairways were the only library objects that exposed the problem,
but it was possible to define your own objects with the same bad
behavior.  In general, the problem occurred whenever a two-object
push-travel action (PUSH x UP y, PUSH x THROUGH y, PUSH x INTO y,
etc.) was attempted, <i>and</i> the indirect object's handler for the
corresponding travel action (ClimbUp, GoThrough, Enter, etc.) was
defined using asDobjFor(), <i>and</i> the handler for the target
action of the asDobjFor() was itself defined using a remapTo().

<p>The problem has been fixed, so any two-object push-travel action
should now be handled equivalently to the corresponding one-object
(directional) push-travel action on the same travel connector.

</div>

<!------------------->
<div class=entry>

The Chair, Bed, and Platform classes can now <i>all</i> allow
standing, sitting, and lying on the object.  In the past, Chair only
allowed sitting, Bed allowed lying and sitting, and Platform allowed
all three.  The set of postures allowed can now be customized for
each individual object.

<p>The new property allowedPostures contains a list of the postures
that the object allows.  By default, Chair allows sitting and
standing, and Bed and Platform allow sitting, standing, and lying.
You can override allowedPostures for an individual Chair, Bed, or
Platform object to add or remove allowed postures.  When a posture
isn't in the allowed list, it will be ruled as "illogical" in the
verification stage.

<p>In addition, the new property obviousPostures contains a list of
the postures that are "obvious" for the object; these are the
postures that are most natural for the object.  The obvious postures
are enumerated separately from the allowed postures to control
defaulting: if a posture is allowed but not obvious for an object,
then the corresponding command will be ruled as "nonObvious" in the
verify stage, ensuring that the command will only be accepted if
stated explicitly (that is, the player will be able to perform the
command, but the parser won't automatically guess the command based
on incomplete information from the player).  By default, it's obvious
to sit on a chair, to sit or lie on a bed, and to sit, lie, or stand
on a platform.

<p>The three separate classes are still three separate classes for a
couple of reasons.  First, each one has a primary, "natural" posture
associated with it: sitting on a chair, lying on a bed, standing on a
platform.  This primary posture is the one that the library will
assume for implied actions and incomplete commands.  Second, Platform
differs from the other two in that objects dropped while standing on
a platform land on the platform, whereas objects dropped while on a
chair or bed land in the enclosing room.

<p>Note that a posture that isn't allowed by allowedPostures will
be treated as illogical.  If you want to create an object for which
a given posture makes physical sense, but isn't allowed for some
other reason (character motivation constraints, for example), you
should include the posture in allowedPostures and then disallow the
corresponding command using the check() routine.

</div>

<!------------------->
<div class=entry>

NestedRoom now defines 'out' to use the special 'noTravelOut'
connector, which will automatically treat an OUT command as a GET OUT
OF command while in the nested room.  Without this, the 'noTravelOut'
would typically be "inherited" from the enclosing room anyway, but
not always: if the enclosing room defined its own OUT, the nested
room would pick up that one instead, which isn't usually appropriate
when within a nested room.  This change ensures that nested rooms
behave consistently even when nested within rooms with their own
explicit 'out' connections.

</div>

<!------------------->
<div class=entry>

The HighNestedRoom class now prohibits exiting the room, by default.
It does this by setting the exitDestination property to nil; this
indicates that the room has no natural exit location, so it's not
possible to leave it.  HighNestedRoom generates an appropriate
message ("It's too long a drop to do that from here") when an
attempt to exit the location fails.

<p>The base NestedRoom now checks, in the GetOutOf action's check()
handler, that there is a non-nil exitDestination.  If there's not a
valid exit destination, the check() handler calls the new method
cannotMoveActorOutOf() to display an appropriate message, then
terminates the command with 'exit'.

</div>

<!------------------->
<div class=entry>

By default, NestedRoom now uses the new travel connector nestedRoomOut
for its "out" link, rather than noTravelOut as it did in the past.
The nestedRoomOut connector works just like noTravelOut, except that
nestedRoomOut is "apparent" to characters, so it shows up in the EXITS
list.  Since OUT is usually a valid travel command while in a nested
room (the command exits the nested room), it makes sense to list OUT
explicitly as a possible direction while in a nested room.  To
override this for a particular nested room, just set 'out' to
noTravelOut; to change this behavior for all nested rooms, do the same
thing with 'modify NestedRoom'.

</div>

<!------------------->
<div class=entry>

The new Floorless class is a mix-in that can be combined with any
other type of Room class to create a floorless version of the room.
Mix Floorless in ahead of the Room base class in the superclass list
of the room you're creating; Floorless will, among other things,
subtract any default floor/ground object from the base room's
roomParts list.

<p>The existing FloorlessRoom class has been retained, but is now
simply a convenience class that combines Floorless and Room.  This
provides the same behavior as the old FloorlessRoom class, so existing
code should not be affected.

</div>

<!------------------->
<div class=entry>

Some fine-tuning has been applied to announcements for cascading
implied actions in certain cases.  When a series of nested implied
actions fails, the parser now announces only the first of the series.
For example, in the past, if a travel action initiated an OPEN DOOR
which initiated an UNLOCK DOOR which failed, the parser showed
something like this: (first trying to unlock the door and then open
it).  The parser now shows only this: (first trying to unlock the
door).

<p>The reason for dropping the extra announcements is that they don't
really tell the player anything useful, so they're just unnecessary
verbosity.  Because of the recursive relationship of the implied
action in these cases, the first action is nested in the second,
which is nested in the third, and so on; so the second and subsequent
actions all failed as a direct result of the first one failing (in
our example, the OPEN fails because it requires the UNLOCK to
succeed, so when the UNLOCK fails the OPEN must also fail).  This
means that we never actually get around to trying the second and
subsequent actions; when the first action fails, we give up on
trying any of the others.  The only thing they tell the player is
why the failed action was attempted at all (in our example, the
implied OPEN explains why we're attempting the implied UNLOCK).
But the rationale in these cases is almost always obvious to the
player, so even this isn't a very good reason to keep the extra
announcements.

<p>This behavior can be controlled via
implicitAnnouncementGrouper.keepAllFailures.  The property is nil
by default; to list the entire stack of failures for these cases,
change it to true.

</div>

<!------------------->
<div class=entry>

The extra "testing" step for opening Lockable objects has been
removed.  This extra step was introduced in 3.0.6m to make the cascade
of implied actions more plausible for these cases, but the extra
verbosity was really too much, so it's been removed in the interest
of simplicity.

<p>Instead, a Lockable now tests a new method, autoUnlockOnOpen(); if
this returns true, then OPEN implies UNLOCK, otherwise it does not.
This means that, if autoUnlockOnOpen returns nil, and the object is
locked, then an OPEN command will simply fail with an error message
("the door seems to be locked"), and the player will have to enter an
explicit UNLOCK command.

<p>The new autoUnlockOnOpen() method is defined as follows:

<ul>

<li>For Lockable, the method returns the value of the lockStatusObvious
property.  This means that OPEN implies UNLOCK if the lock status is
readily observable, and requires a separate, explicit UNLOCK if not.

<li>For KeyedLockable, the method returns true if the inherited value
is true, OR if the actor is carrying a known key for the object.  By
default, a KeyedLockable automatically remembers keys as known once
they're successfully used, so once an object is successfully unlocked
with a key, an OPEN command will automatically imply UNLOCK on
subsequent attempts, as long as the actor is carrying the same key.
This is a concession to playability, in that it eliminates the need
to spell out every step of operating a door or other keyed lockable
after the first time through, but it's also arguably more realistic:
the actor knows from experience how to operate the door, so we can
see the automatic UNLOCK as merely leaving some boring details out of
the narration.

</ul>

<p>Some authors might always prefer the automatic UNLOCK to forcing a
player to type a separate UNLOCK command for objects with non-obvious
locking status.  Which way you prefer is a matter of taste.  On the
one hand, the extra UNLOCK command is a little annoying to players,
and is exactly the sort of thing the precondition mechanism was
created to avoid.  On the other hand, the automatic UNLOCK is weird
when the lock status isn't apparent, because until the OPEN fails, we
have no way of knowing that the object was locked in the first place
and thus no reason to try the implied UNLOCK; it's an instance of the
parser revealing game-state information that the player character
isn't supposed to know.  It also could be seen as actually detracting
from playability by making the game do too much automatically, taking
away a certain amount of control from the player (the player could
think: "I didn't even know that door was locked; if I had, I wouldn't
have tried to unlock it right now.")

<p>By default, the library implements the more realistic but also
more tedious behavior, requiring a separate UNLOCK to OPEN a locked
object whose lock status isn't obvious.  If you prefer to make UNLOCK
automatic on OPEN for a given object, simply override
autoOpenOnUnlock() to return true unconditionally for that object; if
you prefer to make UNLOCK automatic for all objects, modify Lockable
to make autoOpenOnUnlock() return true in all cases.

</div>

<!------------------->
<div class=entry>

The implied command behavior of keyed-lockable objects has been
changed slightly.  In the past, attempting to OPEN a keyed-lockable
triggered an implied UNLOCK, which asked for a key.  Thus, a command
like OPEN DOOR, or even GO NORTH, could be answered with a question
("What do you want to unlock it with?").  This was a little awkward
because the player never actually said in so many words that they
wanted to unlock the door.  Now, keyed-lockable objects simply
point out that a key is required to open the lock:

<p><pre>
  &gt;go north
  (first trying to unlock the iron door)
  You need a key to unlock the door.
</pre>

<p>Note, however, that if the actor knows which key to use, and one
of the known keys is in sight, then the command will be allowed to
proceed implicitly.  In these cases, it won't be necessary to ask for
the key, since the actor's knowledge of the key allows it to be
supplied automatically as a default.

</div>

<!------------------->
<div class=entry>

The Keyring class now follows the normal Thing conventions for
mentioning the contents of the keyring.  Formerly, Keyring.desc
generated the list of contents, using a lister defined in the property
'examineLister'.  Now, Keyring has no separate 'desc' method;
instead, the listing is generated by the standard Examine code
inherited from Thing, and the 'examineLister' property has been
renamed to 'descContentsLister' to accommodate the inherited
Thing methods.

</div>

<!------------------->
<div class=entry>

The new class CustomImmovable makes it easy to create an Immovable that
uses a single customized message to respond to all attempts to move
the object.  Just override cannotTakeMsg, and the "move" and "put in"
messages will use the same message.  The new class CustomFixture does
the same thing for Fixture.

</div>

<!------------------->
<div class=entry>

The new class FueledLightSource abstracts some of the functionality
that was formerly in Candle, to create a base class for objects that
provide light using a limited fuel supply.  The new base class
doesn't assume that it's something that burns, as Candle does, so you
can use the new class to create things like limited-use flashlights.
Candle is now based on the new class.  This change shouldn't affect
any existing game code; the implementation of Candle has merely been
rearranged internally to the library, so no changes should be
required to existing code.

<p>An additional improvement in the new FueledLightSource class is
that the fuel source is no longer assumed to be the object itself.
This lets you model the fuel source as a separate object; for example,
you could use a separate battery object as the fuel source for a
flashlight, allowing a character in the game to swap out a dead
battery for a new one.  Simply override the 'fuelSource' property
of your FueledLightSource object to specify the object that provides
the fuel.  By default, the fuel source is still 'self', so Candle
objects in existing source code won't need any changes.

</div>

<!------------------->
<div class=entry>

The tryMakingRoomToHold method in Actor now checks each object it's
about to move into a "bag of holding" to make sure the object that's
to be held isn't inside the object to be moved.  This ensures that the
attempt to make more room to hold things doesn't inadvertantly move
the object to be held out of reach, defeating the purpose of making
room to hold it.  This change ensures that the object to be held
stays where it is, since all of its containers stay where they are.

</div>

<!------------------->
<div class=entry>

UnlistedProxyConnector.ofKind now returns true if the caller is
asking about UnlistedProxyConnector, and <i>also</i> returns true if
the caller is asking about the class of the underlying connector.
This makes a proxy look like its underlying connector and also like a
proxy, which is consistent with the rest of its behavior.

</div>

<!------------------->
<div class=entry>

The new DefaultTopic property 'excludeMatch' can be set to a list of
topics (Thing or Topic objects) to exclude from the catch-all match.
By default, this is just an empty list, so nothing is excluded.
Individual DefaultTopic objects can provide a list of objects to
exclude from the catch-all.  This is useful when you're creating a
DefaultTopic for a ConvNode or ActorState, but you want one or more
specific topics to be referred to the enclosing topic database for
handling.  By including the topics in the excludeMatch list, you
ensure that they won't be caught in the catch-all DefaultTopic, which
will let them propagate to the enclosing topic database.

</div>

<!------------------->
<div class=entry>

ConvNode.npcContinueConversation() now returns true if anything was
displayed in the course of the method, nil if not.  This lets a caller
determine if the NPC actually had anything to say.

<p>ActorState.takeTurn() now uses this information to consider the
NPC to have finished its turn if the ConvNode added a conversational
message.  In the past, merely having a non-nil ConvNode was enough to
make takeTurn() consider the turn to be taken entirely by the
ConvNode; now, the turn is only considered finished if the ConvNode
actually wanted to say something.  This allows ordinary actor-state
background scripts to continue running even when a ConvNode is
active, as long as the ConvNode doesn't generate any NPC conversation
messages.

</div>

<!------------------->
<div class=entry>

The nestedActorAction() function now sets a visual sense context for
the new actor.  (In the past, the nested action incorrectly executed
within the same sense context as the enclosing action, which allowed
actions that shouldn't have been visible to be reported, and vice
versa.)

</div>

<!------------------->
<div class=entry>

If an implied action announcement comes immediately after other
report messages for an action in which the implied action is nested,
the command transcript now automatically inserts a paragraph start
just before the implied action announcement.  It's often desirable to
invoke a nested action in the course of handling a main action, and
in some cases the nested action can trigger implied actions of its
own.  This new transcript feature makes the spacing look better in
these cases when the main action reports its own results before
invoking the nested action.

Similarly, if an implied action announcement occurs after a result
message from a previous implied action, a paragraph break is inserted
before the second implied announcement.  This improves readability
in these cases.

</div>

<!------------------->
<div class=entry>

The CommandTranscript method summarizeAction() now interacts properly
with conversational responses.  A change in 3.0.6m caused a problem
when attempting to summarize a series of conversational messages
(generated by TopicEntry activation); specifically, the summarizer
didn't recognize the new "in-band" conversational boundary markers
that the conversation manager started generating in 3.0.6m.  The
summarizer now handles the conversation markers properly.

</div>

<!------------------->
<div class=entry>

The AgendaItem class has a new property, initiallyActive, that
indicates that an agenda item is active at the start of the game.
During initialization, the library will automatically add each
initially active agenda item to its actor's agenda (by calling
addToAgenda() on the actor).

</div>

<!------------------->
<div class=entry>

The new AgendaItem property agendaOrder makes it easy to control the
priority order of agenda items.  The agenda list is now sorted in
ascending order of the agendaOrder values; this means that the lower
the number, the earlier the item will appear in the agenda list.
Actors choose the first item in the list that's ready to run, so
ready-to-run agenda items will always be executed in order of their
agendaOrder values.  By default, agendaOrder is set to 100; set a
lower value if you want the item to go earlier than other items, a
higher number if you want it to go later.  If you don't care about the
ordering, you can leave the default value unchanged.

<p>Note that readiness is more important than agendaOrder.  Suppose
that AgendaItem A has a lower agendaItem value, and thus goes earlier
in the list, than AgendaItem B.  Despite this list order, if B is
ready to run and A is not, B will be executed.

</div>

<!------------------->
<div class=entry>

The new class SuggestedAskForTopic can be mixed into an AskForTopic
object's superclass list to add the "ask for" to the topic inventory.
This works in parallel with the other SuggestedTopic subclasses.

</div>

<!------------------->
<div class=entry>

In the past, AltTopic didn't work properly with SpecialTopic.  This
has been corrected; you can now create AltTopic children of
SpecialTopic entries, and they'll work as you'd expect.

<p>In a related change, SpecialTopic now inherits from
SuggestedTopicTree, rather than SuggestedTopic as it did in the past.
This ensures that a special topic will be suggested in the topic
inventory when any of its AltTopic children are active.

</div>

<!------------------->
<div class=entry>

The library now defines template variations that allow defining
firstEvents lists with various TopicEntry/ShuffledTextList
combinations: TopicEntry, MiscTopic, SpecialTopic, DefaultTopic,
AltTopic.  Now, if you define an instance of one of these classes,
your definition can include two lists: the first will be the
firstEvents list, and the second will be the eventList list.

</div>

<!------------------->
<div class=entry>

The new DefaultAskForTopic class lets you define a default response
to an ASK FOR command.  This new class is parallel to the other
DefaultTopic subclasses.

</div>

<!------------------->
<div class=entry>

The various DefaultTopic subclasses are now arranged in a hierarchy
of low "match score" values.  In the past, all DefaultTopics used a
match score of 1, which generally made them rank lower than any
non-default topic, but didn't differentiate among different default
topics that matched the same input topic.  Now, the single-type
defaults (DefaultAskTopic, DefaultTellTopic, etc.) have a match score
of 3, the multi-type defaults (DefaultAskTellTopic, etc.) have a
match score of 2, and DefaultAnyTopic has a score of 1.  This means
that a single-type default will take precedence over a multi-type
default, which will in turn take precedence over an ANY default.
This lets you define a DefaultAskTopic that will handle any ASK
command, for example, and a DefaultAnyTopic to handle everything else.

</div>

<!------------------->
<div class=entry>

The initiateTopic() method (in Actor, ActorState, and ConvNode) now
remembers that the player character is talking to the NPC.  This
ensures that commands that check the current interlocutor, such as
TOPICS, properly recognize that the characters are talking to one
another.

</div>

<!------------------->
<div class=entry>

A problem in the library generated a spurious "you're not talking to
anyone" message under certain obscure circumstances involving an
automatic "topic inventory" scheduled at the start of a conversation.
This is now fixed.

</div>

<!------------------->
<div class=entry>

In some cases, if an actor was in a ConvNode but didn't say anything
on a given turn, the actor was incorrectly set as the most recent
pronoun.  The library was being overly aggressive about setting the
pronoun as though the actor had said something, as a convenience to
the player to respond to the actor.  The library no longer sets the
pronoun unless the actor actually says something (i.e., some text is
generated in the course of the actor's turn while in the ConvNode).

</div>

<!------------------->
<div class=entry>

In the English language module, the vocabulary initializer now
ignores extra spaces after delimiters (such as '/' or '*').  This
makes it easier to break up long vocabulary initializers across
multiple lines of code.  For example:

<p><pre>
  + Thing 'big large huge gigantic giant book/tome/volume/
          text/manuscript' 'huge tome'
    // etc
  ;
</pre>

<p>Note the line break in the middle of the list of nouns.  This
introduces an extra space into the string, which is now perfectly
okay.

</div>

<!------------------->
<div class=entry>

In the English parser, the literal adjective wildcard string has been
changed.  In the past, "*" (an asterisk within double quotes) was the
wildcard character.  This made it difficult to match literally an
asterisk in the input, so the wildcard is now the character \u0001
(i.e., Unicode code point 1), which is highly unlikely to be used in
input.

</div>

<!------------------->
<div class=entry>

In the English parser, 'miscVocab' was used as a token property
instead of 'miscWord' in a few places.  The correct token type
should have been 'miscWord'; this has been corrected.

</div>

<!------------------->
<div class=entry>

The menu system now "wraps" up-arrow and down-arrow keys at the top
and bottom of a list of menu items; that is, if the first menu item
is selected and user presses the up-arrow, the selection moves to the
last menu item, and a down-arrow at the last item selects the first
item.

</div>

<!------------------->
<div class=entry>

The library now provides a template for MenuTopicItem, with slots for
the title string, an optional heading string, and the menu contents
list.

</div>

<!------------------->
<div class=entry>

When a locked door with lockStatusObvious was examined, a message
indicating its status (locked or unlocked) was meant to be displayed,
but wasn't.  This has been corrected.

</div>

<!------------------->
<div class=entry>

A recent change to OOPS processing (in 3.0.6j) introduced a bug:
typing OOPS after a misspelling in a response to an interactive
parser query didn't work.  For example, if your answer to a
disambiguation question ("which book do you mean...") contained a
typo, you couldn't use OOPS to correct that typo.  This now works
properly again.

</div>

<!------------------->
<div class=entry>

Typing AGAIN after a SpecialTopic command didn't work in the past.
This has been corrected.  AGAIN can now be used to repeat a special
topic, as long as the same comamnd is still valid as a special topic;
if the command isn't a valid special topic any longer, the parser
will simply say that the command cannot be repeated.

</div>

<!------------------->
<div class=entry>

The new Thing method expandPronounList() allows an object to
effectively reverse the effects of filterResolveList() when a pronoun
refers to the object in a subsequent command.  The parser calls this
new method on each of the objects in the "raw" binding for a pronoun
(that is, the set of program objects that were resolved in the
previous command that established the antecedent of the pronoun).

<p>The Thing and CollectiveGroup objects use this new method to
ensure that a collective group's filtering is applied consistently
for each command, whether the command uses a full noun phrase or a
pronoun to refer to the groupable objects.

</div>

<!------------------->
<div class=entry>

When a noun phrase in a player command refers to an object that has
"facets" (as indicated by the object's getFacets() method), and more
than one facet of the object is in scope, the parser will now
automatically choose only one facet of the object.  The parser chooses
the facet that has the best transparency in the actor's sight-like
senses; if the visibilities are equivalent, then the parser chooses
the facet with the best touch transparency; if visibilities and
touchabilities are equivalent, the parser chooses one arbitrarily.
This change ensures that different facets of the same object will
never create ambiguity in the parser, which is important because a set
of facets is always meant to implement what the player sees as a
single game world object.

<p>In a related change, the parser's method of choosing a facet as the
antecedent of a pronoun has changed slightly.  First, the parser now
considers all in-scope facets when an antecedent has facets, even if
the base antecedent object is itself in scope.  Second, the parser
chooses which in-scope facet to use based on the same criteria as
above: visibility, then touchability.  This ensures that when multiple
facets are in scope (because of sense connectors, for example), the
most readily visible <i>and</i> reachable one will be selected.

</div>

<!------------------->
<div class=entry>

The parser now selects a default antecedant for a pronoun whenever
possible, based on the objects in scope.  For example, if you type
LOOK AT HIM, and you haven't established a prior meaning for HIM (by
referring to a male actor with a previous command), <i>or</i> the
prior meaning of HIM is no longer valid (because that actor is no
longer present), then the parser will assume that HIM refers to a
male actor who is present, assuming there's exactly one.  If there
are no in-scope objects matching the gender of the pronoun, or
multiple matching objects are in scope, the parser has no way of
guessing what the pronoun means.  When a pronoun could only refer to
one object, though, the parser will assume that that's the object you
meant.

</div>

<!------------------->
<div class=entry>

In 3.0.6l, the parser started accepting HIM and HER to select a
unique gendered object from a disambiguation query ("which one do you
mean...").  This handling has been improved slightly: the parser now
treats HIM and HER as <i>narrowing</i> the choices, rather than
requiring a unique match.  If more than one of the choices matches
the pronoun, the parser narrows the choices to the ones that match
and asks for disambiguation help again, this time offering the
reduced list of choices.

</div>

<!------------------->
<div class=entry>

A bug in turn timing showed up when an implied command used
replaceAction(); due to the bug, such a command didn't consume a
turn.  This showed up, for example, when a travel command (GO NORTH)
triggered an OPEN DOOR command, which in turn triggered an UNLOCK
DOOR command, which replaced itself via askForIobj() with an UNLOCK
DOOR WITH WHAT? command.  This has now been corrected.

</div>

<!------------------->
<div class=entry>

In the various places where nested actions are created (nestedAction,
nestedActorAction, remapTo, etc), it's now easier to specify literal
and topic objects.  In the past, it was necessary for the caller to
wrap these types of objects in the appropriate internal parser
structures, such as a ResolvedTopic.  This is no longer necessary:
actions that use special wrappers internally will now automatically
create the appropriate wrappers for you.

<p>In practice, this means that you can simply use a string in any
nested action context where a literal is required, and you can use
a simple Thing or Topic object in any context where a topic is
required.  Examples that formerly required special coding, but now
work in the obvious fashion:

<ul>
<li>remapTo(TypeLiteralOn, typewriter, 'hello')
<li>nestedAction(AskFor, bob, goldKey);
</ul>

</div>

<!------------------->
<div class=entry>

A remapTo() object argument can now be a string, when the new verb
accepts a literal in that position.  For example, you can use
remapTo(TypeLiteralOn, typewriter, 'hello') to remap to the command
TYPE "HELLO" ON TYPEWRITER.

</div>

<!------------------->
<div class=entry>

The parser failed to announce a defaulted object under certain obscure
circumstances.  In particular, if a remapTo() on a two-object action
remapped a command, and the source of the remapping was itself chosen
as a defaulted object, the announcement was missing.  The announcement
will now be generated.

</div>

<!------------------->
<div class=entry>

In libMessages, obscuredReadDesc() and dimReadDesc() incorrectly
returned a string rather than displaying a message, resulting in no
message being displayed when reading a Readable under dim or obscured
visual conditions.  This has been corrected; these libMessages methods
now display their messages directly.

</div>

<!------------------->
<div class=entry>

In the default English messages, the various messages indicating that
an actor is in the room and situated in or on a nested room (such as
sitting in a chair, or standing on a platform) have been changed
slightly.  In the past, these said something like "Bob is here,
sitting on the chair."  Now, the essentially pointless "here" part
has been dropped, so the messages read more simply: "Bob is sitting
on the chair."

</div>

<!------------------->
<div class=entry>

The English library message for attempting to take an UntakeableActor
referred to the wrong object (the actor instead of the direct object)
in one of its clauses.  The message has been corrected.

</div>

<!------------------->
<div class=entry>

The English library message listing the newly revealed objects after
opening an Openable now uses specialized phrasing when an NPC performs
the action: "Bob opens the box, revealing..."  The PC version hasn't
changed: "Opening the box reveals..."

</div>

<!------------------->
<div class=entry>

The English library's default message for attempting to ask oneself
for something (ASK ME FOR...) incorrectly referred to the
substitution parameter "{iobj}" (which isn't available with an ASK
FOR command, because the second noun phrase is actually a topic
phrase).  This has been corrected.

</div>

<!------------------->
<div class=entry>

The English version of the INSTRUCTIONS command now automatically
senses the presence of certain optional conversation features and
mentions the corresponding commands only if they're used in the
game.  In particular, the TOPICS command will be mentioned only
if there are SuggestedTopic instances in the game; the existence
of special topics will be mentioned on if there are SpecialTopic
instances; and the TALK TO command will be mentioned only if
there are InConversationState instances.  This reduces the manual
work needed to customize the conversation system instructions;
if your game uses these features, they'll be mentioned, otherwise
they won't.

</div>

<!------------------->
<div class=entry>

A style tag name can now contain digits, as long it starts with an
alphabetic character.  (In the past, style tag names were only
allowed to contain alphabetic characters.  This makes style tag
naming more consistent with the HTML tag naming rules.)

</div>

<!------------------->
<div class=entry>

The new function overrides(obj, base, prop) makes it easy to test
whether or not the given object 'obj' overrides the property 'prop'
that 'obj' inherits from base class 'base'.  This function returns
true if 'obj' derives from 'base' (that is, obj.ofKind(base) returns
true), <b>and</b> 'obj' and 'base' get their definitions of 'prop'
from different places.

<p>In the past, the library tested in a few places to see if a given
property or method was inherited from a given library base class.
This was <i>almost</i> the same test that overrides() performs, but
didn't work properly in cases where a library base class had been
modified by a game or library extension; when 'modify' is used to
extend a class, the defining class for methods defined in the original
(pre-modification) version of the class is the original version, not
the new version created by 'modify', which takes on the original name.
To allow for 'modify' usage, all of the tests the library used to make
along these lines have now been replaced with calls to overrides()
instead.

</div>

<!------------------->
<div class=entry>

The SENSE_CACHE conditional compilation has been removed, so the sense
caching code is now permanently enabled.  This shouldn't affect any
existing code, since I'm not aware of anyone who's wanted to use the
option to disable the sense cache.

<p>(This is simply an internal change to eliminate some unnecessary
extra source code that's been disabled for a long time anyway.  When
the sense-cache mechanism was first introduced, it was made optional,
so that any games that had problems with the caching could turn it
off.  The code has been active by default for a long time now, and I'm
not aware of anyone who has found it necessary or desirable to disable
it, so there no longer seems to be any value in the added complexity
of having both options.  Removing the conditional option simplifies
the source code by removing the effectively dead code for the option
of disabling the sense cache.)

</div>

<!------------------->
<div class=entry>

Due to a bug in the parser, a run-time error occurred in certain cases
when the player entered a two-object command that was missing its
indirect object, and then answered the parser's prompt for the missing
object.  This has been corrected.

</div>

<!------------------->
<div class=entry>

The standard library tokenizer now accepts function pointers and
anonymous function pointers in the fourth slot (the converter
callback) in a token rule.  The function is invoked using the same
arguments that are used when calling a method of 'self' to convert
the token value.

</div>

<!------------------------------- 3.0.6m --------------------------------->
<div class="sepbar"><a name='306m'></a>3.0.6m</div>
<p><b><i>Released November 15, 2003</i></b>
<p>

<div class=firstentry>

<b>Important compatibility-breaking change #1:</b> The 'explicit'
parameter has been removed from Thing.lookAround() and
Actor.lookAround(), as well as from the internal Thing service
methods lookAroundPov(), lookAroundWithin(), and
lookAroundWithinSense().  This extra parameter was an historical
relic that's no longer used, so it's being removed to simplify the
interfaces to these routines.  Game code is likely to call
lookAround() in a few places, and might even override it, so authors
should check their existing game code and remove this parameter from
any calls or overrides.

</div>

<!------------------->
<div class=entry>

<b>Important compatibility-breaking change #2:</b> The AltTopic
mechanism has been changed slightly.  In the past, AltTopics were
nested one within another to form a group of alternatives.  Now,
AltTopics are still nested within their parent TopicEntry, but
they're no longer nested within one another; instead, they're
simply siblings.  So, for old game code like this:

<p><pre>
  <font color=red><b>// OLD WAY!!!</b></font>
  + TopicEntry @lighthouse "It's very tall...";
  ++ AltTopic "Not really..." isActive=(...);
  +++ AltTopic "Well, maybe..." isActive=(...);
  ++++ AltTopic "Okay, it is..." isActive=(...);
</pre>

<p>...you'd now instead write it like this:

<p><pre>
  // the new way
  + TopicEntry @lighthouse "It's very tall...";
  ++ AltTopic "Not really..." isActive=(...);
  ++ AltTopic "Well, maybe..." isActive=(...);
  ++ AltTopic "Okay, it is..." isActive=(...);
</pre>

<p>The only change you need to make is to remove the additional
nesting from the second and subsequent AltTopic in each group - simply
put all of the AltTopics in a group at the same '+' nesting level.

<p>The old nesting scheme had a tendency to get unwieldy whenever a
single topic had more than one or two alternatives.  The new scheme
makes game code a little cleaner when defining large AltTopic lists.

</div>

<!------------------->
<div class=entry>

<b>Possible compatibility-breaking change #3:</b> The getTraveler()
methods, in both Actor and BasicLocation, now have an additional
parameter giving the connector being traversed.  This allows the
routine to take into account both the actor and the connector
involved in the travel, which can be useful in some cases.

<p>For example, you might want to set up a travel connector that
leads out of a vehicle, in which case you'd want the actor within the
vehicle rather than the vehicle to be the traveler when the connector
is traversed.  In these cases, you'd override the vehicle's
getTraveler() method to check the connector, returning the actor
rather than the vehicle when the outbound connector is the one being
traversed.

<p>In addition, for greater generality, the "actor" argument to
BasicLocation.getTraveler() (and subclass overrides) has been renamed
to indicate that it now takes a <i>traveler</i> rather than merely an
actor.  Vehicle.getTraveler() takes advantage of this: it now
recursively asks its container for the traveler, passing itself
(rather than the traveler within itself) as the proposed traveler.
These changes allows for situations where an actor is inside a
vehicle that's inside another vehicle, for example.

<p>Finally, Vehicle.getTraveler() now makes an additional check
before returning itself as the traveler: if the connector allows the
traveler within the vehicle to pass (as indicated by the connector's
canTravelerPass() method), but the connector doesn't allow the
vehicle itself to pass, then getTraveler() simply returns the
original traveler rather than trying to make the vehicle travel.
This makes it easy to set up an outbound connector from within a
vehicle - simply set up the connector's canTravelerPass() to exclude
the vehicle itself, and a traveler within the vehicle will
automatically leave the vehicle behind on traversing the connector.

</div>

<!------------------->
<div class=entry>

There are a few minor interface changes in the travel mechanism, all
of which should be transparent to existing game code.

<p>The TravelConnector method connectorBack() now takes a <i>Traveler</i>
object rather than an Actor as its first argument.

<p>The TravelConnector method fixedSource() now takes a Traveler instead
of an Actor as its second argument.

<p>The Thing method getTravelConnector() now accepts a nil 'actor'
argument.  When the actor is nil, it means that the caller is
interested in the structure of the map independently of any actor's
present ability to perceive that structure.  This is useful in some
cases, such as auto-mapping, where we want to know what the map is
actually like rather than merely what it looks like to a given actor
at a given time.

<p>The internal handling of the various PushTravel action subclasses
now uses only the 'verify' stage of the action handling for the
indirect object, when there's an indirect object at all.  For
example, PUSH BOX THROUGH DOOR only calls the door's
dobjFor(GoThrough) 'verify' handler, not any of its other handlers.
This change reflects the fact that the action of a push-travel is
always carried out by a nested TravelVia with the special
PushTraveler object, hence the only need we have for the indirect
object handlers at all during the initial PushTravel handling is for
disambiguation via the 'verify' routine.  The old implementation was
problematic when the indirect object remapped decomposed verb, because
it incorrectly remapped the entire action before the proper nested
action could be invoked.  This change corrects the problem, allowing
the PushTravel varieties to work correctly for any combination of
objects.

<p>In the Traveler class, describeDeparture() and describeArrival()
now show their messages in a visual sense context for the traveler, if
the player character isn't involved in the travel.  This ensures that
the travel is properly described (or properly <i>not</i> described) in
situations where the traveler is visible to the player character but
the motivating NPC isn't, or vice versa, such as when an NPC is inside
an opaque vehicle.

</div>

<!------------------->
<div class=entry>

The Fixture and Immovable classes are now based on a new common base
class, NonPortable.  This change is entirely a matter of the
library's internal organization, and is entirely transparent to game
code - Fixture and Immovable behave exactly like they did before.

<p>The new class was introduced for two reasons.  First, it
consolidates the behavior common to all non-portable objects,
eliminating a small amount of redundancy in the former arrangement.
Second, and much more importantly, it roots all of library's
non-portable object classes in a single base class.  This means that
code can reliably test an object for unportability by checking
obj.ofKind(NonPortable).  In the past, it was necessary to write
(obj.ofKind(Immovable) || obj.ofKind(Fixture)); not only is that test
more cumbersome, but its very form is suggestive of the potential for
additional "||" clauses in the future.  The new arrangement
formalizes in the library a single root class for all unportable
objects, ensuring a clean way for the library and library extensions
to add any future specialized unportables without breaking existing
game code.

<p>Note that this change does <b>not</b> break existing game code
that uses the "||" test; other than the new common base class, the
inheritance structure for Fixture and Immovable and their subclasses
has not changed.  Even so, it wouldn't be a bad idea to replace any
"||" tests in your existing code with the simpler ofKind(NonPortable)
test, because this will ensure that your code takes advantage of the
insulation from future changes that the new class affords.

</div>

<!------------------->
<div class=entry>

The Fixture class (and by inheritance, its subclass Component) now
considers an instance to be owned by a given object if the object is
the Fixture's location, or the location is owned by the object.
Since a Fixture/Component is a permanent part of its location,
it usually is appropriate to consider the component to be owned
by anything that owns the location, as well as to consider the
component owned by the location itself.

</div>

<!------------------->
<div class=entry>

The new mix-in class Attachable (in extras.t) makes it easier to
define objects that can be attached to one another, such as a hose
and a faucet, a plug and an electrical outlet, or a rope and a
railing.  Attachable is meant to be combined (using multiple
inheritance) with Thing or a Thing subclass.  The class provides a
number of methods that you can override to control which objects can
be attached to one another, and the special effect of enacting out
those attachments.

<p>The Attachable class provides default handlers for AttachTo,
Detach, DetachFrom, and TakeFrom, but it's relatively easy to define
additional, customized action handlers in terms of these default
actions using the standard 'remapTo' mechanism.  For example, if
you were defining a rope, you could define a TieTo action, and then
map TieTo to AttachTo in your rope object.

<p>The new classes PermanentAttachment and PermanentAttachmentChild
are subclasses of Attachable for cases where you describe objects as
attached in the story text, but you don't want to allow the objects
to be detached from one another.  Describing objects as attached
tends to invite a player to try to detach them; these classes lets
the objects provide customized responses to the player's attempts,
without actually allowing the objects to come apart.  (These classes
aren't intended for mere components; the Component class is adequate
for that.  PermanentAttachment is for situations such as a ball
attached with a string to a paddle, where essentially separate
objects are conspicuously attached to one another.)

</div>

<!------------------->
<div class=entry>

The new mix-in class PresentLater makes it easy to set up objects that
aren't in the game world initially, but will appear later in response
to some event.  For example, you might want to create a hidden door
that isn't part of the game world until the player casts the DETECT
HIDDEN DOORS spell, or you might want to create a pile-of-leaves
object that shows up at the foot of a tree after the player shakes the
tree.

<p>The traditional way of programming these sorts of objects was to
create the object with a 'nil' initial location, then use moveInto()
to move the object into the game upon the triggering event.
PresentLater provides an alternative.  To use PresentLater, you set up
the object in its eventual location, as though it were going to be
there from the start, but you add PresentLater at the start of the
object's superclass list.  During pre-initialization, the library will
remember the object's starting location, and then move the object to
'nil', effectively removing it from the game world.  Later, when you
want to the object to appear, simply call makePresent() on the object,
and it will automatically move to the eventual location that was noted
during start-up.

<p>The advantage of using PresentLater is that you define the object's
eventual location as part of the object itself, as though it were an
ordinary object; this means that you don't have to specify its
eventual location as part of some method (in a moveInto call)
elsewhere in the source code.  Another advantage is that you can use
the makePresentByKey() method to bring a whole set of related objects
into the game world at once: you can give each PresentLater object a
"key" property, which is just an arbitrary value you choose to
identify a group of objects, and then bring all objects that have that
key into the game world at once.

</div>

<!------------------->
<div class=entry>

The new class Unthing represents the <i>absence</i> of an object.  This
class is useful for the occasional situation where a player is likely to
assume that an object is present even though it's not.  For example,
sometimes an object becomes hidden, but a player might not notice that;
rather than letting the regular parser error handle it, we can create
an Unthing that explains that the object can no longer be seen.
Unthing is a simple subclass of Decoration, with a customized default
handling message.

</div>

<!------------------->
<div class=entry>

The travelerDirectlyInRoom precondition object has been replaced with
a new TravelerDirectlyInRoom class.  This change allows the caller to
create the precondition object with the full set of information it
needs via the class's constructor.  This change is probably
transparent to existing game code, as game could would have little
reason to use this precondition.

</div>

<!------------------->
<div class=entry>

The class Thing now defines the method checkTravelerDirectlyInRoom();
the default implementation simply defers to the container.  This
ensures that connectors that are defined inside ordinary objects (for
example, a hole in a bookcase) will properly ensure that a traveler is
in the Thing's containing Room or NestedRoom before travel.  In the
past, the absence of this method meant that there were no conditions
at all on a traveler's initial location in such cases.

</div>

<!------------------->
<div class=entry>

The dropDestinationIsOutRoom precondition now moves the actor,
rather than the traveler (to the extent that they differ), to the
outer room when needed.  (Since the actor is attempting to reach the
outer room in these cases, it makes more sense to move the actor,
rather than any vehicle the actor is inside.)

<p>Similarly, the Floor object's SitOn and LieOn handlers now apply a
precondition requiring the actor, rather than the traveler, to be in
the room directly containing the Floor object.

</div>

<!------------------->
<div class=entry>

The new VocabObject method getFacets() returns a list of "facets"
of an object.  These are other objects that share the same parsing
identity; for example, the two sides of a door are facets of the
same physical object, from a character's perspective, so each side
would return a list containing the other side from getFacets().
In fact, the Door class overrides getFacets() to do just this.

<p>The parser uses getFacets() to resolve an out-of-scope pronoun
antecedent, if possible.  If the player uses a pronoun, and the
antecedent is out of scope, the parser calls the antecedent's
getFacets() method, and looks for a facet that's in scope; if it
finds an in-scope facet, the parser uses that facet as the
replacement antecedent.  For example, if you type OPEN DOOR, GO
THROUGH IT, THEN CLOSE IT, the parser will now correctly resolve the
second "it" to the door.  In the past, the second "it" wasn't
resolvable, because it referred to the side of the door that's in the
other room and thus out of scope after the travel.  Using the new
facet list capability, the parser can now resolve the second "it"
to the side of the door that is in scope.

<p>(If more than one new facet of the object is in scope in these
cases, the pronoun resolver will take the one that's most readily
visible - that is, the one that has the most "transparent" sense path
in the actor's visual senses.  If all of the in-scope facets are
equally visible, the resolver just picks one arbitrarily.)

<p>By default, VocabObject.getFacets() simply returns an empty list.
The Door and Passage classes override the method to return a list
containing the linked object representing the other side of the door
or passage, if there is one.  The new MultiFaceted object returns the
list of facet objects that it synthesizes; each facet instance of
a MultiFaceted does the same thing.

<p>You can customize getFacets() whenever you use multiple objects
with a shared parser identity.  One common case where you might want
to do this is "object transmutation," where you substitute one object
for another in order to effect a radical change in the setting.  For
example, you might have one object representing a wooden dining
table, and another representing the pile of splintered wood that an
enraged chef turns it into after the guests insult his cooking.  In
this case, you could override getFacets() in the table so that it
returns the pile-of-splintered-wood object.

</div>

<!------------------->
<div class=entry>

The class AutoMultiLoc has been removed, and its capabilities have
been rolled directly into the MultiLoc class itself.  All of the
initialization properties and methods (initialLocationClass,
isInitiallyIn, and buildLocationList) have been moved into MultiLoc,
and they work the same as they used to.  There really wasn't any need
for a separate AutoMultiLoc class, since the two styles of
initialization (enumerated and rule-based) can coexist quite easily in
the single class.

<p>Along the same lines, the DynamicMultiLoc class has been removed,
and its functionality has been rolled into MultiLoc.  In particular,
the reInitializeLocation() method is now part of the base MultiLoc
class.

<p>If you have any AutoMultiLoc or DynamicMultiLoc objects in your
existing game code, you should simply change the AutoMultiLoc or
DynamicMultiLoc superclass to MultiLoc.  The objects should then
behave the same as they did before.

</div>

<!------------------->
<div class=entry>

MultiLoc.moveOutOf() caused a run-time error due to a mismatched
call to notifyRemove().  This is now fixed.

</div>

<!------------------->
<div class=entry>

The new classes MultiInstance and MultiFaceted are useful for cases
where you want to create an object in multiple locations, but
MultiLoc isn't suitable.  A MultiLoc is suitable when a single object
is contained <i>entirely</i> and <i>simultaneously</i> in more than
one location; when a single large object spans several locations, or
when you simply want to duplicate a ubiquitous background object in
several places, the new classes are better.

<p>MultiInstance is good when you want to duplicate a ubiquitous
background object in multiple locations: trees in a forest, the sun
in outdoor locations, crowds in the street.  MultiFaceted is for
large objects that span many locations, such as rivers or long ropes.
MultiLoc isn't ideal for these sorts of cases because the sense
system treats a MultiLoc as a single object that's entirely in all of
its locations at once; this means, for example, that if it's lit in
one place, it's lit everyplace.

<p>MultiInstance and MultiFaceted work mostly like MultiLoc from the
programming perspective.  Internally, though, rather than appearing
itself in each of its locations, a MultiInstance or MultiFaceted
creates a separate "instance" object for each of its locations.  Each
instance is an ordinary singly-located object, so the library creates
one per location.  The instance objects are instances of a template
that you define as part of the MultiInstance or MultiFaceted object.

<p>The new classes present the MultiLoc multi-location interface, so
you can add and subtract locations as needed, using the usual
routines: moveInto(), moveIntoAdd(), moveOutOf().  You can also set
the initial set of locations as you would for a MultiLoc: you can set
locationList to the list of initial locations, or you can define
initialLocationClass, isInitiallyIn, and/or buildLocationList.

<p>The instances of a MultiInstance or MultiFaceted are all
essentially identical, so these classes are only good for relatively
homogeneous objects.  These classes aren't appropriate for cases
where you want to present distinctive aspects of an object, such as
the different sides of a large building, or distinctive individual
objects, such as different people in a crowd.  When the individual
parts are distinct, you're best off just creating separate objects
for the different instances.  The new classes are mainly for
convenience in cases where you'd otherwise have to repeat an
identical object definition in several locations.

</div>

<!------------------->
<div class=entry>

The new pre-conditions dobjTouchObj and iobjTouchObj can be applied
to the indirect or direct object (respectively) of a two-object
action, to require that the one object can touch the other.  This is
useful for actions where the actor manipulates one of the objects
directly, but manipulates the other object only indirectly using
the first object.

<p>For example, PUSH COIN WITH STICK would be a good
place to use iobjTouchObj as a direct object precondition: the
actor is manipulating the stick directly, so the actor has to be
able to touch the stick, but the coin only needs to be reachable
indirectly with the stick.  Another example: PLUG CORD INTO OUTLET
requires direct manipulation of the cord, but only the cord needs
to touch the outlet, so this would be a good case for dobjTouchObj
as a precondition on the indirect object.

<p>In the class Thing, the default direct object handlers for the
actions MoveWith, TurnWith, ScrewWith, and UnscrewWith now use the
iobjTouchObj condition rather than touchObj condition.  These verbs
all generally model interactions where the direct object only needs
to be reachable through the indirect object.  The new class Attachable
uses dobjTouchObj as a precondition on the indirect object.

<p>To enable the new iobjTouchObj condition, the TouchObjCondition
class can now handle a yet-unresolved source object during the
verification stage.  When the source object is nil, the pre-condition
simply skips its verification stage.  This allows a TouchObjCondition
to be applied across objects for a two-object action: for example, it
allows you to apply a condition to the direct object that the indirect
object can touch it.

</div>

<!------------------->
<div class=entry>

The new preconditions sameLocationAsIobj and sameLocationAsDobj let
you require that a given object is in the same immediate location as
the other object of a two-object command.  You use sameLocationAsIobj
as a precondition on a direct object, and sameLocationAsDobj as a
precondition on an indirect object.  Both of these condition objects
are based on the class SameLocationCondition, which you can construct
dynamically to require the target object to be in the same location as
an arbitrary second object, which need not be directly involved in the
command.

<p>These conditions use the new Thing method tryMovingObjInto(obj),
which tries to move the given object 'obj' into 'self'.  This method
is customized in Room, Container, Surface, and Actor to generate
appropriate implied commands for those classes, and you can override
it in your own objects as needed.

</div>

<!------------------->
<div class=entry>

The new Actor method endConversation() effectively lets an NPC say
GOODBYE of its own volition, ending a conversation without waiting
for the player to leave or say GOODBYE.  This is the complement of
Actor.initiateConversation: it lets an NPC initiate the end of a
conversation.

<p>The new conversation-ending code endConvActor indicates that we're
ending the conversation of the actor's volition.

</div>

<!------------------->
<div class=entry>

The new ConvNode method noteLeaving() is called when the conversation
node is about to become inactive.  This is the complement of
noteActive().  This method doesn't do anything by default, but
instances can use it to trigger side effects when leaving the node.

</div>

<!------------------->
<div class=entry>

The conversation manager's mechanism that keeps track of conversation
responses has been changed to make it better able to handle multiple
conversations on a single turn.  In particular, the conversation manager
now flags the start and end of each response text in the text stream.
Because the "transcript" subsystem captures displayed text
and defers its actual output until later, difficult synchronization
problems arose if a game tried to trigger multiple responses from
different actors on a single turn.  This change should be transparent
to existing game code.

</div>

<!------------------->
<div class=entry>

TopicEntry has a new method, setTopicPronoun(), that tries to set a
pronoun antecedent when the topic is matched.  The default
handleTopic() method automatically calls the new method.

<p>It's not always possible for setTopicPronoun() to guess about an
antecedent for a topic phrase match, because TopicEntry instances can
match more than one game object, and topic phrases by their nature can
refer to more objects than are present visually.  The new method will
set a pronoun antecedent for the topic if the topic phrase in the
player's input yields one object when "intersected" with the
TopicEntry's 'matchObj' list.  The method first looks only at in-scope
objects, then looks to the "likely" list, but only if there are no
in-scope matches.  If the intersection yields more than one object,
the library doesn't set a pronoun antecedent at all, since the match
is ambiguous.

<p>Since this heuristic procedure can't always decide on an
antecedent, you might occasionally want to set the antecedent
explicitly in a particular TopicEntry.  You can do this by overriding
the TopicEntry instance's setTopicPronoun(fromActor,topic), in which
you'd call fromActor.setPronounObj(obj), where 'obj' is the game
object you want to set as the antecedent.

</div>

<!------------------->
<div class=entry>

In the past, when an "again" command was used to repeat a command
directed to a non-player character ("bob, go east"), the turn counter
incorrectly advanced by two turns.  This was due to an error in the
mechanism that allows one actor to wait for another to finish a
command.  This is now fixed.

<p>A separate problem prevented an undo savepoint from being created
for an "again" command repeated a command directed to another
character.  Since no savepoint was created, typing "undo" after such
an "again" command took back not only the "again" turn but the turn
before it as well.  The savepoint is now created properly.

</div>

<!------------------->
<div class=entry>

Due to a bug, the conversation mechanism didn't enter a conversation
(i.e., didn't show the "greeting protocol") if a DefaultTopicEntry was
used for a response.  This has been fixed.

<p>As part of this change, the ActorTopicEntry class, which was
introduced in the refactoring of the TopicEntry class introduced in
3.0.6l, has been eliminated.  On further consideration, the
bifurcation of TopicEntry into actor-associated and
non-actor-associated subtypes wasn't very clean, since it implied a
similar split for some of the other classes that work with TopicEntry,
notably AltTopic and DefaultTopic.  This was too unwieldy.

<p>So, ActorTopicEntry has been removed.  In its place, the "topic
owner" abstraction, which was introduced in 3.0.6l, has been used
throughout the base TopicEntry class to replace the need for an
associated actor.  This means that the base TopicEntry can do
everything that it did before (and everything that ActorTopicEntry did
before), but without any assumption that there's an associated actor.
The getActor() method is still present, but it's now strictly for the
convenience of game code; the library no longer assumes that topic
entries to be associated with actors.  The TopicEntry.getActor()
method simply returns the topic owner if it's of class Actor,
otherwise nil.

<p>These changes should have no impact on existing game code, since
the ActorTopicEntry was intended as an internal class structure only.

</div>

<!------------------->
<div class=entry>

A bug in the TopicResolver class caused a run-time error for
a command like ASK <i>someone</i> ABOUT ALL.  This is now fixed.

</div>

<!------------------->
<div class=entry>

When the ConsultAbout action picks a default consultable object based
on the actor's last ConsultAbout command, the action now marks the
defaulted object as such, which triggers the usual announcement of
the default object.

</div>

<!------------------->
<div class=entry>

The typographicalOutputFilter object (in en_us.t) is now a little
smarter about what it considers sentence-ending punctuation.  If a
lower-case letter or a hyphen of some kind follows what the filter
would otherwise take for sentence-ending punctuation, it doesn't treat
it as a sentence ending.  This gives better results in the common case
of an exclamation point or question mark within a quoted passage:
"'Who are you?' he asked."  It also helps in some less common
cases, such as when an exclamation point is embedded in a sentence,
such as in an interjection set off by dashes ("And then -- oh no! --
I dropped it").

</div>

<!------------------->
<div class=entry>

The PendingCommandInfo class has been refactored into a couple of
subclasses for a cleaner class structure.  PendingCommandInfo is now
an abstract base class; the new concrete subclasses
PendingCommandToks, PendingCommandAction, and PendingCommandMarker now
implement the specialized behavior that was formerly embedded in the
single class and handled conditionally.  These classes are mostly for
internal use in the library, so this should have no impact on any
existing game code.

</div>

<!------------------->
<div class=entry>

Some messages in BasicContainer have been modified slightly to remove
the assumption from the base class that it's an object that can be
opened.  First, the new properties cannotTouchThroughMsg and
cannotMoveThroughMsg give property pointers, referring to
playerActionMessages properties, that specify the messages to use
when an object cannot be reached or moved through the container's
containment boundary.  By default, these now refer to the new messages
cannotTouchThroughContainer and cannotMoveThroughContainer, which don't
say anything about the container being closed.  Second, BasicOpenable
class overrides these two new properties to refer to the original
cannotTouchThroughClosed and cannotMoveThroughClosed messages.
Third, the tryImplicitRemoveObstructor() method that was formerly
in BasicContainer has been moved to BasicOpenable instead, eliminating
the assumption in BasicContainer that the obstruction can be removed
by opening the container.

<p>Note that these changes are designed in such a way that objects
based on both Openable and Container (either by mixing the two
superclasses, or by using the library class OpenableContainer) should
be unaffected.  Objects based on Container or BasicContainer, without
any Openable mix-in, should now behave more logically, in that they
won't assume anything about being openable.

</div>

<!------------------->
<div class=entry>

The touchObj precondition incorrectly reported two failure messages
if an implied command failed trying to remove an obstruction to touch.
The failure message of the implied command itself was shown, and a
separate failure message explaining that the target object isn't
reachable was also shown; in such cases, only the implied command
failure should have been reported.  The precondition now omits the
redundant second message.

</div>

<!------------------->
<div class=entry>

KeyedLockable is now more flexible about the "known key list" and who
owns it.  In the past, the "master object" of a linked lockable (the
master object of a two-sided door, for example) always owned the known
key list; this made it impossible to have separate keys operate the
two sides of a door, and also created a dependency on which side of
the door was the master.  Now, KeyedLockable instead uses the local
side's known key list if it has one, and only uses the master side's
list if either the local side has an empty list or the master side has
no list; only if the local side has an empty list, and the master side
has a list, is the master side used.  This makes initialization of
two-sided doors much more flexible, because it no longer matters which
side is the master for the purposes of the known key list.

</div>

<!------------------->
<div class=entry>

In 3.0.6j, we introduced the notion of whether or not the status of a
Lockable is known.  The idea was that actors shouldn't just
automatically unlock a door on trying to open it unless they have
some reason to know the door is locked in the first place.
Unfortunately, this mechanism took away the important playability
convenience feature that automatically unlocks locked doors when it's
obvious how to do so.

<p>This mechanism is now replaced with something a little more
subtle, which solves the same problem without any loss of convenience
for the player.  Instead of letting the original OPEN command fail on
encountering a door that's locked but not previously known to be
locked, the library now inserts a "testing" action into the sequence
ahead of the implied UNLOCK.  The "testing" action represents the
actor's first attempt to open the lockable, as in attempting to turn
a locked doorknob.  This first phase fails, but instead of letting
the rest of the command fail, we consider the actor to have
<b>immediately</b> learned from the first phase that the object is
locked, so we proceed directly to an implied UNLOCK action.  The
result looks like this:

<p><pre>
&gt;go north
(first trying the door and finding it locked, unlocking it, then
opening it)
</pre>

<p>Note that the lockStatusObvious property of the former scheme
still applies.  If lockStatusObvious is true, then the extra
"testing" phase is omitted, since we can tell just looking at the
object that it's locked.  Note also that the "testing" phase is
only used when the object is actually locked; when it's not locked,
the OPEN command succeeds, so there's no need to split the OPEN
action into the two phases.

</div>

<!------------------->
<div class=entry>

The Door class now uses a custom cannotTravel() message, rather than
using the default message for the location.  The message explains that
the travel is not possible because the door is closed; the generic
cannot-travel message for a room simply claims that the travel is
impossible, which isn't as specific as we can be about it.

</div>

<!------------------->
<div class=entry>

The Openable class has a new method, openStatus, that makes it easier
to override the open/closed status addendum that's shown as part of
the object's description.  The openableContentsLister now calls this
method to show the status; the default implementation just says "it's
open" (or equivalent, adjusted for gender and number).  An Openable
can override this to customize the message as needed.

</div>

<!------------------->
<div class=entry>

The Passage class's initialization of a two-sided relationship has
been refined slightly.  In the past, the non-master side of a
two-sided passage explicitly set its master object's otherSide
property to point to the non-master side.  Now, instead of setting
the property directly, the non-master side calls the master object's
initMasterObject() method with the non-master side as the parameter;
by default, initMasterObject() simply sets 'otherSide' to the other
object.  This makes it easier to customize the initialization for
cases where more than two objects are involved in a passage
relationship, or where the passage relationship is dynamic, by
allowing the master object to directly control its own initialization.

</div>

<!------------------->
<div class=entry>

In the Candle class, when the object runs out of fuel, it now displays
its "burned out" message <i>before</i> actually cutting off its light
source (by marking itself as unlit).  In the past, the order of these
operations was reversed, which caused the library to suppress the
"burned out" message when the candle was the only light source.  The
message was suppressed because these operations are performed in a
daemon that runs in the "sight" sense context of the candle itself;
once the candle is marked as unlit, it becomes invisible when there's
no other light source, and so any message displayed in its sight
context is suppressed.  By showing the message while the candle is
still marked as lit, we ensure that the message will be seen as long
as the candle is in view of the player character.

</div>

<!------------------->
<div class=entry>

The Readable class now generates its "obscured" and "dim" default
descriptions properly.  A bug formerly caused a run-time error when
attempting to read a Readable under these sense conditions.

</div>

<!------------------->
<div class=entry>

The menu system now includes an automatic sorting mechanism,
which sorts a menu's entries into a game-defined order each time the
menu is displayed.  The default initializeContents() method in the
MenuObject class does the sorting, based on the new 'menuOrder'
properties of the items in the menu.  The 'menuOrder' property is
an integer value giving the relative order of an item among its
siblings.  By default, 'menuOrder' returns the 'sourceTextOrder'
value for the menu item, so the default ordering is simply the
original ordering of the items in the source file.

</div>

<!------------------->
<div class=entry>

In the English module, the new property isQualifiedName generalizes
the function of the existing isProperName property.  isProperName
indicates that a 'name' property is "proper," meaning it's the name
of a person or place - the kind of noun that's usually capitalized in
English.  Proper names don't require "qualification" when they appear
in sentences, which basically means that they don't need articles
like "the" or "a", because they're inherently definite.  The new
isQualifiedName property can be set to true for an object when the
name is fully qualified, but isn't proper.  By default, a proper name
is considered qualified, but the two properties can be set
independently as needed.

<p>An example of a non-proper but qualified name is "your book."
This isn't the proper name of the book, but the possessive pronoun
makes it fully qualified, making it incorrect to add an article when
using the name in a sentence.

<p>In practice, at the moment, "qualified" and "definite" have the
same effect, which is to omit any articles when the name is used in a
sentence.  The new property is intended to separate the two concepts
in case there's a need to distinguish them in the game or in future
library changes.

</div>

<!------------------->
<div class=entry>

The English parser has a new bit of fine-tuning in its verb phrase
chooser for a particular type of ambiguous phrasing.  In certain
sentences in English, a preposition can be interpreted either as part
of a noun phrase or as a structural part of the verb; for example,
DETACH STRING FROM BOX could be interpreted either as a verb with two
objects (STRING as the direct object, BOX as the indirect object), or
as a verb with a single object (STRING FROM BOX as the direct
object).  English speakers will almost always assume the two-object
interpretation automatically in cases like this; English is such a
strongly positional language that the verb phrase structure tends to
dominate everything else in a sentence.  In the past, the parser
didn't care one way or the other, so when both interpretations were
valid, the parser sometimes arbitrarily chose the much less probable
single-object version.  The parser now takes the verb structure
dominance into account by preferring the intepretation with more
"noun slots" in the verb phrase, whenever there's ambiguity.

</div>

<!------------------->
<div class=entry>

The English parser's tokenizer now treats ampersands essentially as
though they were alphabetic characters for the various kinds of
"word" tokens.  Ampersands have no other meaning to the standard
parser, and show up every so often in names of things, so it makes
sense for the parser to accept them as parts of words.

<p>Note that an ampersand is treated as alphabetic, not as a
punctuation mark.  This has two implications that might be
counterintuitive, at least to the extent that ampersands look to most
people like punctuation marks.  (In fact, they're not punctuation
marks at all; they're actually ligatures of "et," Latin for "and,"
although the glyph has become so stylized in modern typefaces that
it's hard to see that unless you know what to look for.)  First, an
ampersand is <b>not</b> a token separator, so a sequence like
"T&amp;V" will be read as a single token.  Second, when an ampersand
is surrounded by whitespace (or other token separators), so that it
does count as a separate token, it'll be parsed as a "word" token,
not as punctuation.  For example, "Bob &amp; Sons" is read as three
"word" tokens.  This means that you can use a lone "&amp;" as an
adjective or noun in defining an object's vocabulary.

</div>

<!------------------->
<div class=entry>

In the English module, Thing.conjugateRegularVerb() incorrectly
applied an "-ies" ending to verbs ending in a consonant plus a "y",
such as "say".  This affected routines like itVerb() and nameVerb().
The routine now uses a regular "-s" ending when a vowel precedes
a terminal "y".

</div>

<!------------------->
<div class=entry>

The parser now allows possessive pronoun adjectives ("her book") to
refer back to the previous noun phrase in the same action.  For
example, ASK BOB ABOUT HIS HAT will treat "his" as referring to Bob.
This is accomplished by first trying to find an earlier noun phrase
in the same action that matches the pronoun in number and gender.  If
we find a match, we use it, otherwise we use the ordinary pronoun
antecedent from a previous command.  Note that the number/gender
match ensures that we don't get overzealous in applying this: if we
type ASK BOB ABOUT HER BOOK, we find that BOB doesn't match HER, so
we look to the meaning of HER from a previous command.

<p>As part of this change, the Action routine that was formerly
called getReflexiveBinding has been renamed to getAnaphoricBinding.
The new name better reflects the more generalized function, since it
can be used for other kinds of anaphoric bindings besides reflexives.
This is an internal method that is highly unlikely to be
used in any game code, so this change should be transparent.

<p>("Anaphor" is the linguistic term for any sort of reference to an
earlier noun phrase in a sentence; a reflexive is a particular kind
of anaphor that re-uses a noun phrase from an earlier "slot" in a
predicate to fill another slot in the same predicate, such as HIMSELF
in ASK BOB ABOUT HIMSELF.  The reason reflexives exist in English and
other languages is that they're unambiguously anaphoric: in ASK BOB
ABOUT HIMSELF, HIMSELF can only refer to Bob, whereas the HIM in ASK
BOB ABOUT HIM almost certainly refers to someone other than Bob from
a previous sentence or clause.  The name change in the method
reflects the fact that there are other kinds of anaphoric constructs
besides reflexives; in ASK BOB ABOUT HIS BOOK, the HIS refers
anaphorically to BOB, but it's not reflexive.)


</div>

<!------------------->
<div class=entry>

In Actor.executeActorTurn(), when a pending response is delivered,
the actor now clears its memory of the pending response.  (In the
past, the pending response wasn't cleared, so an NPC with a pending
response would keep delivering the pending response over and over.)

</div>

<!------------------->
<div class=entry>

When AskFor changed to a TopicTAction in 3.0.6l, the Actor handler for
GiveTo was affected but wasn't updated properly.  The GiveTo handler
changes a GiveTo command directed to another actor into an AskFor
command (BOB, GIVE ME THE CROWBAR becomes ASK BOB FOR CROWBAR), so the
AskFor change required this rephrasing to be cast in the new
TopicTAction terms.  This change wasn't made, so the GiveTo handler
didn't work properly.  This has now been fixed.

</div>

<!------------------->
<div class=entry>

Actor.desc no longer shows the postureDesc as part of the description
of an NPC.  Instead, this is shown in examineStatus().  This change
shouldn't affect any existing code; it merely moves around where the
calls are made, but still makes all the same calls in the same
sequence.  The change makes it easier to override an Actor's 'desc'
without changing the overall display format.

</div>

<!------------------->
<div class=entry>

A bug in the sense system prevented a self-illuminating object (an
object with a brightness of 1) from applying its self-illumination to
its own interior surface; the illumination was considered external
only.  This was inconsistent with the normal sense-transmission
rules, and it's now been corrected.  A self-illuminating object is
now considered to have an ambience level of 1 on both its inner and
outer surface.

</div>

<!------------------->
<div class=entry>

A subtle bug in the sense system caused ambient sense energy levels
to be transmitted incorrectly into the interior of objects with
non-transparent fill media.  In particular, the sense system
incorrectly applied the fill medium to the ambience level at the
inner surface of an object as transmitted from the outside of the
object.  This was incorrect because it meant that a viewer on the
inside of an object saw the ambient level to the object adjusted
<i>twice</i> for the fill medium: once for the incorrect adjustment
at the inner surface, and once more for the path from the viewer,
through the fill medium, to the inner surface.  This has been
corrected: the ambient level arriving at the inner surface of an
object from outside the object is now calculated without any
adjustment for the fill medium, and any further transmission inward
is then adjusted for the fill medium.

<p>This problem showed up by making an object invisible from its own
interior when the object had a non-transparent fill medium, and the
light coming in from outside wasn't bright enough to penetrate the
fill medium twice.  For example, a transparent booth filled with
attenuating fog, with external normal illumination (brightness 3),
was not visible from its interior because of the double traversal
of the fog.  Such a booth is now visible from its interior.

</div>

<!------------------->
<div class=entry>

When looking for an object's default associated Noise or Odor, the
Thing methods getNoise() and getOdor() now only consider objects with
an active "presence" in their sense.  That is, getNoise() will only
return a Noise object with a non-nil soundPresence property value,
and getOdor() will only return an Odor with a non-nil smellPresence.
This makes it easier to turn an object's associated sense data on and
off, since you can simply use the presence properties of the Noise
and Odor objects.

</div>

<!------------------->
<div class=entry>

In 3.0.6j, CollectiveGroup stopped matching singular phrases and
phrases with quantities specified (as in "five coins").  This behavior
hasn't changed, but it's now easier to control, with the new method
isCollectiveQuant().  This method returns true if the given "required
quantity" allows using the collective, nil if not.  By default, this
returns true if and only if there's no specific quantity needed (in
which case the quantity parameter is nil).

</div>

<!------------------->
<div class=entry>

RandomTextList and ShuffledTextList can now handle arbitrary event
entries in their lists, using the same rules as the base EventList
class.  (In the past, only strings and nil values were allowed in
these specialized subclasses, but they now use the base class handling
to carry out each event, so they can now handle any sort of event the
base class can.)

</div>

<!------------------------------- 3.0.6l --------------------------------->
<div class="sepbar"><a name='306l'></a>3.0.6l</div>
<p><b><i>Released October 4, 2003</i></b>
<p>

<div class=firstentry>

The actor knowledge and "sight memory" systems have been revamped to
make it easier to keep track of individual knowledge for different
actors.  <b>A few key interfaces have changed, so existing games will
have to make corresponding changes.</b>

<p>First, the main interface changes:

<ul>
<li>obj.seenBy(actor) is now actor.hasSeen(obj)
<li>obj.setSeenBy(actor, stat) is now actor.setHasSeen(obj)
<li>obj.isKnownBy(actor) is now actor.knowsAbout(obj)
<li>obj.setKnownBy(actor, stat) is now actor.setKnowsAbout(obj)
</ul>

<p>Note that the "stat" parameter has been removed from the two "set"
methods.  This parameter was essentially superfluous, since it's rare
to the point of non-existence for a game to want to mark something as
un-seen or unknown after it's been previously seen or known; the new
methods elide this parameter and act like the old methods acted with
the parameter set to true.

<p>You have a choice of how to update your existing game code to the
new interfaces.  The first option is to do the search-and-replace
operations in the list above throughout your game's source code; this
is the recommended option, because it'll make your code consistent
with future documentation.  The second option is to modify the
VocabObject class to reinstate the old methods, defining them in
terms of the new ones:

<p><pre>
modify VocabObject
  seenBy(actor) { return actor.hasSeen(self); }
  setSeenBy(actor, flag) { actor.setHasSeen(self); }
  isKnownBy(actor) { return actor.knowsAbout(self); }
  setKnownBy(actor, flag) { actor.setKnowsAbout(self); }
;
</pre>

<p>Second, how do the changes facilitate separate NPC knowledge
tracking?  The change here is that the Thing and Topic 'seen' and
'isKnown' properties that underlay the old system are still used, but
are now only <i>defaults</i> for tracking the seen/known information.
The actual properties used to track the information are determined on
an actor-by-actor basis, using the new Actor.seenProp and
Actor.knownProp properties.

<p>By default, Actor defines seenProp as &amp;seen, and knownProp as
&amp;isKnown.  This means that, by default, there's only one
"global" set of knowledge.  To track an NPC's knowledge individually,
simply set seenProp and/or knownProp to new properties unique to that
actor.  For example:

<p><pre>
bob: Person
  // ... other definitions...
  seenProp = &amp;bobSeen
  knownProp = &amp;bobKnown
;
</pre>

<p>This specifies that 'bob' will individually track its knowledge,
separately from any other actors.  When you call bob.setKnowsAbout(obj),
the library will examine obj.bobKnown and obj.bobSeen, because those are
the properties that track bob's knowledge.  Note that this individual
tracking is completely automatic once you define seenProp and knownProp,
since the Actor methods hasSeen, setHasSeen, knowsAbout, and setKnowsAbout
all use seenProp and/or knownProp to do their work.

<p>Note that because the default values in Actor for seenProp and
knownProp are (respectively) &amp;seen and &amp;isKnown, everything
works roughly the same way it did before if you don't override these
properties.  In particular, if you don't care about tracking
individual NPC knowledge, which typical games probably won't, you
only have to worry about 'seen' and 'isKnown' as before.  So, if you
want to initialize an object as pre-known, before the start of the
game, simply set isKnown=true for that object as in the past.

<p>Third, a minor enhancement: the GIVE and SHOW iobjFor() handlers
in Actor now automatically mark the object being shown, and its
visible contents, as having been seen by the actor being shown the
object.  For games that track NPC knowledge separately, this will
ensure that the target of a GIVE or SHOW takes note of having seen
the object in question.

</div>

<!------------------->
<div class=entry>

A new class, Consultable, can be used to implement things like books
and file cabinets: inanimate objects in which an actor can look up a
topic, to find some information.  This class works almost exactly
like the Actor conversation system.  Another new class, ConsultTopic,
serves as the TopicEntry subclass for Consultables.  Simply create
one or more ConsultTopic objects, and locate them within the
Consultable, to populate the consultable object's database of
responses.

<p>In support of the new Consultable class, the TopicDatabase and
TopicEntry classes have been refactored a bit.  In particular, these
two classes no longer assume that they're associated with an actor,
and no longer assume that they're involved in conversation.  The
parts of the former implementations that made assumptions about actor
or conversation associations have been moved into a pair of new
subclasses, ActorTopicDatabase and ActorTopicEntry.  The existing
classes that were based directly on TopicDatabase and TopicEntry are
now based on the new ActorXxx subclasses instead.  For almost all
existing game code, this change should be entirely transparent,
because the final subclasses that most games use still have the same
names and work the same way they did before; the only changes are
some internal reshuffling to abstract out most of the functionality
into the new base classes.

<p>In addition, the TopicResolver class has a new subclass,
ConvTopicResolver, that's used for the conversational actions (ASK
ABOUT, TELL ABOUT).  The base TopicResolver doesn't differentiate
at all among topics; it simply considers everything to be an
equally good match.  The ConvTopicResolver differentiates topics
into three sublists, as it did in the past: objects that are in
physical scope or are known to the actor performing the command;
objects that are "likely" topics, as indicated by the performing
actor's isLikelyTopic(); and everything else.

</div>

<!------------------->
<div class=entry>

The ConsultAbout action in the English module now adds grammar for
some incomplete forms, such as "look up (topic)".  If the player
enters one of these incomplete forms, the parser will prompt for
the missing object in the usual fashion.

<p>Similarly, when the direct object is missing from a CONSULT ABOUT
command, the default is the last object consulted by the same actor,
as long as that object is still visible.  The new Actor property
lastConsulted keeps track of the last object consulted; the new Actor
method noteConsultation() sets this property.  The Consultable class
calls gActor.noteConsultation(self) in its ConsultAbout action()
handler.  This saves the player some typing, since they can leave out
the object to be consulted when they're looking up a series of topics
in the same consultable (they can type simply LOOK UP BOB, for
example).

</div>

<!------------------->
<div class=entry>

The TopicEntry scoring system now uses nil to represent a non-match.
This means the valid scoring range now includes zero and negative
values, which in turn means that it's no longer a problem if
matchScoreAdjustment values reducing scores to zero or below.  This
makes it easier to use score adjustments, since there's no longer any
need to worry about interactions between score values and adjustment
values taking a final score out of range.

</div>

<!------------------->
<div class=entry>

The AskFor action is now a TopicTAction instead of a TIAction.  That
is, the indirect object is now a topic rather than an ordinary
resolved object.  The TIAction implementation was never really
appropriate, since ASK FOR conceptually needs topic-oriented rules
for the indirect object: one needs to be able to ask for things that
aren't in scope, as well as for abstract topics (ASK FOR HELP, ASK
FOR DIRECTIONS).

<p>This change should have little or no impact on existing games.

</div>

<!------------------->
<div class=entry>

The new TopicEntry subclass AskAboutForTopic can be used to make a
single topic entry respond to either ASK ABOUT or ASK FOR for a given
game object or objects (read the name as "ask about/for topic").
Similarly, AskTellAboutForTopic can respond to ASK ABOUT, TELL ABOUT,
or ASK FOR (read the name as "ask/tell about/for topic," although the
TELL FOR combination implied in that reading doesn't make any sense,
obviously).

</div>

<!------------------->
<div class=entry>

The limitSuggestions property now applies to ActorState objects
as well as to ConvNode objects.  Suggestions are effectively arranged
into a hierarchy: the top level of the hierarchy is the ConvNode, the
next level is the ActorState, and the bottom level is the Actor.
The full list of suggestions consists of the ConvNode's suggestions,
plus the ActorState's suggestions, plus the Actor's suggestions.
However, if limitSuggestions is true at any level of the hierarchy,
then suggestions below that point are not included in the full list.
So, if the ConvNode's limitSuggestions property is true, only the
ConvNode suggestions are included.  If the ConvNode's limitSuggestions
property is nil, but the ActorState's limitSuggestions property is
true, then the ConvNode and ActorState suggestions are both included.
If limitSuggestions is nil for both the ConvNode and ActorState, then
the suggestions at all three levels (ConvNode, ActorState, and Actor)
are included in the full list.

</div>

<!------------------->
<div class=entry>

The new class SuggestedTopicTree makes it easy to create a tree of
AltTopic alternatives that acts as a single suggested topic.

<p>Normally, when you create a tree of AltTopic alternatives,
you can make each AltTopic a separate suggestion.  Each alternative
is effectively an independent topic for suggestion purposes, so
asking about one doesn't satisfy the PC's curiosity about any of
the other alternatives.  This means that the game might make the
same suggestion several times, as the different alternatives become
active.

<p>In many cases, it's better to treat the whole group of alternatives
as a single suggestion, so that the suggestion is only made once (or
only as many times as desired) for the whole set.  This is what
SuggestedTopicTree is for.  To use this class, simply add SuggestedTopicTree
to the superclass list for the <b>main</b> TopicEntry (that is, the
TopicEntry at the root of the tree: the one containing all of the
AltTopic alternatives).

<p>Note that the new TopicEntry property altTalkCount keeps track of
the number of invocations for an entire alternative group.  This
property is kept in the outermost TopicEntry for an AltTopic group,
and is incremented each time the outermost TopicEntry or any of its
AltTopic objects is invoked (via ASK ABOUT, TELL ABOUT, etc).
SuggestedTopicTree uses this new counter to determine if the PC's
curiosity has been satisfied for the set of alternatives as a group.

</div>

<!------------------->
<div class=entry>

The former ConversationManager method setRespondingActor() has been
renamed to beginResponse(), and a new method finishResponse() has been
added.  Each call to beginResponse() should have a corresponding call
to finishResponse().

<p>This change allows the conversation manager to defer setting the
new default ConvNode in the responding actor until after the response
has been finished.  This ensures that a ConvNode's noteActive()
method will not be invoked in response to a &lt;.convstay&gt; tag.
In the past, the conversation manager immediately transitioned the
actor to the default next ConvNode at the start of showing the
response, so if the response contained a &lt;.convstay&gt; tag, this
caused a transition back to the starting ConvNode, and thus a call to
noteActive() on the ConvNode object.  The new scheme ensures that the
actor's ConvNode won't change at all when processing a
&lt;.convstay&gt; tag.

</div>

<!------------------->
<div class=entry>

The AgendaItem class has a new method, resetItem(), that is invoked
each time the item is added to an actor's agenda (via
Actor.addToAgenda()).  By default, this method sets the item's isDone
property to nil, as long as the property isn't a method.  This makes
it easier to re-use agenda items, since you don't have to worry about
resetting isDone explicitly.

</div>

<!------------------->
<div class=entry>

The Surface class now uses a custom Lister,
surfaceInlineContentsLister, to show its in-line contents listing.
The new lister shows the in-line contents using the format "(on which
is...)".  In the past, Surface simply inherited Thing's in-line
contents lister, which phrases things in terms of containment
("(which contains...)"), which isn't quite right for surfaces.

<p>For naming consistency, the Lister formerly named
keyringListingContentsLister has been renamed to
keyringInlineContentsLister.  The old name was a bit odd and didn't
properly call attention to the "in-line" aspect.

</div>

<!------------------->
<div class=entry>

Whenever an object's contents are listed via EXAMINE, LOOK IN, or
OPEN, the library now automatically marks all of the object's visible
contents as having been seen.  Only contents that are actually
visible to the character performing the command will be marked as
seen, but it doesn't matter whether or not the contents are mentioned
at all in the description of the object.

</div>

<!------------------->
<div class=entry>

The new Thing method useSpecialDescInRoom(room) lets an object specify
whether or not its special description should be shown in a LOOK AROUND
description.  By default, this simply returns useSpecialDesc().  In
some cases, it might be desirable for an object to show its special
description only when a container is examined, but not in a room
description; this methods lets the object control this.

</div>

<!------------------->
<div class=entry>

<p>The new Thing property suppressAutoSeen can be used to suppress
the library's automatic "seen" marking.  By default, the library
automatically marks every visible object as having been seen whenever
a LOOK AROUND command is performed.  The library also automatically
marks as seen every visible object within a container when the
container is explicitly examined (with EXAMINE, LOOK IN, or OPEN, for
example).

<p>suppressAutoSeen is nil by default.  If you set it to true for an
object, then the library will not mark the object as having been seen
in any of the standard cases, even when the object is visible.  The
game must mark the object as having been seen by explicitly calling
setSeenBy(), if and when desired.

</div>

<!------------------->
<div class=entry>

DistanceConnector now derives from Intangible as well as
SenseConnector.  This makes it easier to use DistanceConnector, since
it's no longer necessary to mix it with a Thing subclass.  Each
distance-connector object needs to derive from Thing so that it fits
into the normal sense model, but these objects will almost never have
any physical presence in the game; Intangible fills both of these
needs.

</div>

<!------------------->
<div class=entry>

The DistanceConnector template in adv3.h, which sets the locationList
property, has been changed into a generic MultiLoc template.  This
lets you initialize any MultiLoc object's location list by specifying
the list of locations after the class name when defining the object.

</div>

<!------------------->
<div class=entry>

The Room template in en_us/en_us.h now accepts a room that defines
only a 'name' property; the 'desc' property is now optional.  This
lets you use the template to define the room name even if you want
to define a complex method for the 'desc'.

</div>

<!------------------->
<div class=entry>

A bug in the Sense class incorrectly considered objects to be out of
range of the 'smell' and 'sound' senses when the objects had distant,
obscured, or attenuated sense paths.  This has been corrected.

</div>

<!------------------->
<div class=entry>

A Door object's getDoorOpenPreCond() can now return nil, if it's
not desirable to use a precondition for opening the door.

</div>

<!------------------->
<div class=entry>

The BasicChair, BasicBed, and BasicPlatform classes now include
a touchObj precondition for the SIT ON, LIE ON, and STAND ON commands.

</div>

<!------------------->
<div class=entry>

Where it makes sense, the preconditions that report failures with
messages along the lines of "You must open (something) first" now set
the pronoun antecedent to the object mentioned.  This makes exchanges
like this work as one would expect:

<p><pre>
  &gt;north
  You must open the door first.

  &gt;open it
</pre>

</div>

<!------------------->
<div class=entry>

In the hint system's Goal class, the new properties openWhenKnown and
closeWhenKnown let you tie a hint topic to the player character's
knowledge of a Topic or Thing.  If you set a Goal object's
openWhenKnown to refer a Topic or Thing, then the Goal will become
"open" as soon as the Topic or Thing becomes known to the PC.
Likewise, if you set closeWhenKnown to a Topic or Thing, the goal
will become "closed" when the Topic or Thing becomes known.

<p>The new Goal properites openWhenRevealed and closeWhenRevealed
let you tie a hint to a &lt;.reveal&gt; tag.  You can set these
properties to (single-quoted) strings giving &lt;.reveal&gt; tags
to test.

</div>

<!------------------->
<div class=entry>

The Goal class has two new methods, openWhen and closeWhen, that
compute the conditions for opening and closing the hint topic,
respectively.  These methods isolate the conditions that were
formerly included in-line in the updateContents() method.

<p>Isolating the conditions in separate methods makes it easier to
use 'modify Goal' to add new custom open/close sub-conditions.  For
example, suppose you wanted to add a pair of new custom Goal
properties that open and close hint topics based on a Thing being
moved for the first time.  You could do this like so:

<p><pre>
  modify Goal
    openWhenMoved = nil
    closeWhenMoved = nil
    openWhen = (inherited || (openWhenMoved != nil &amp;&amp; openWhenMoved.moved))
    closeWhen = (inherited || (closeWhenMoved != nil &amp;&amp; closeWhenMoved.moved))
  ;
</pre>

</div>

<!------------------->
<div class=entry>

The new library function intOrdinal(n) returns a "numeric ordinal"
representation of the number: '1st', '2nd', '3rd', and so on.
(Thanks to Søren J. Løvborg for suggesting this and providing a
sample implementation.)

<p>Along the same lines, the new library functions spellIntOrdinal(n)
and spellIntOrdinalExt(n, flags) return fully spelled-out ordinals
('first', 'second', 'third', etc).  The 'Ext' version takes the same
bit-flag values as spellIntExt().

</div>

<!------------------->
<div class=entry>

The library no longer considers the player character to be an
antecedent to a third-person pronoun when the game itself refers to
the PC in the first or second person (as determined by the PC Actor's
referralPerson property).  In the past, typing X ME and then X IT
examine the player character twice.  This will no longer happen,
except in third-person games, since the first X ME won't set ME as an
antecedent for HIM, HER, IT, or THEM.  This isn't especially important
for IT and THEM, but it can be for HIM and HER if the PC has a specified
gender.

</div>

<!------------------->
<div class=entry>

The library now treats HIM and HER a little differently in disambiguation
responses.  If HIM or HER is given as the answer to a disambiguation
question ("which one do you mean..."), the parser first looks to see
if there's a prior meaning of the pronoun that applies; it always did
this much.  This is the new part: if there is no prior meaning for
the pronoun, or the prior meaning isn't one of the choices in the
query, then the parser looks to see if any of the objects in the query
match the pronoun.  If there's exactly one match, the parser takes that
as the result.

</div>

<!------------------->
<div class=entry>

The English library module defines a few new methods related to
pronouns and gender.  The new Thing methods canMatchHim, canMatchHer,
canMatchIt, and canMatchThem determine if an object can match these
individual pronouns.  By default, these simply return true if the
corresponding isHim/isHer/isIt flags are true.  Actor overrides these
so that they return true if the inherited version returns true
<i>and</i> the actor can be referred to in the third person, which is
determined by testing the additional new Actor method
canMatch3rdPerson.  The new canMatch3rdPerson method returns true if
the actor isn't the player character, <i>or</i> the game refers to
the PC in the third person.

</div>

<!------------------->
<div class=entry>

The former Actor methods canTouch(obj) and findTouchObstructor(obj)
have been moved to Thing.  There wasn't any need for these methods to
be special to Actor, and it's sometimes useful to establish
reachability between arbitrary non-Actor objects, so these are more
appropriate for Thing than Actor.

</div>

<!------------------->
<div class=entry>

The new class TouchObjCondition implements a generic object-to-object
reachability condition.  This is similar to the existing touchObj
pre-condition, but allows for arbitrary source objects, whereas
touchObj can only test to see if the current gActor can touch an
object.  touchObj is now a subclass of TouchObjCondition.

</div>

<!------------------->
<div class=entry>

In the past, throwing an object at a MultiLoc object, or at a component
within a MultiLoc object, didn't work properly.  This has been corrected.

<p>In order to allow throwing at MultiLoc objects, the interface to a
Thing method, getDropDestination, has been altered slightly.  This
method now takes an additional parameter giving the "sense path" that
was used in the operation that's seeking the drop destination.  The
new sense path parameter is a list in the same format returned by
Thing.selectPathTo.  This path information allows getDropDestination
to determine whence the MultiLoc object was approached - that is, it
allows a MutliLoc object to find out which of its containers or
containment peers was last traversed to reach the object.  This path
can be nil, but when it's supplied, it tells us how we're approaching
the drop destination.

<p>Note that this change slightly affects the interfaces to several
Thing methods: getHitFallDestination, throwTargetHitWith,
stopThrowViaPath, throwViaPath, and throwTargetCatch.  In all of these
routines, the former 'prvCont' parameter is now replaced with the
'path' parameter.  Similarly, the processThrow method passes the path
rather than the previous container.

</div>

<!------------------->
<div class=entry>

In the English grammar, abbreviated words that include periods in the
abbreviation (as in "Main St." or "J. Pretensions") are now treated a
little differently, to ensure that abbreviated words don't have any
bad interactions with unabbreviated equivalents.  This change should
be completely transparent to existing game code.

<p>First, the tokenizer no longer treats an abbreviation as a single
token that includes the period, but rather as two separate tokens:
one for the word itself, and a separate token for the period.  The
period is entered not with the ordinary punctuation token class, but
with the new 'tokAbbrPeriod' class.  Second, wherever ordinary noun
tokens were allowed in the grammar, the grammar now instead accepts
the new subproduction 'nounWord'.  This new production matches an
ordinary noun token, <i>or</i> a noun token followed by a
tokAbbrPeriod token.  Third, and similarly, the existing 'adjWord'
production now accepts an adjective token followed by a tokAbbrPeriod
token.  Fourth, the vocabulary initialization
(VocabObject.initializeVocabWith, which parses the vocabWords_
string) now enters each token that ends in a period with the period,
as it did, but also <i>without</i> the period.  So, for example, the
vocabWords_ string 'main st.' will create an adjective 'main', a noun
'st.', and a second noun 'st' (in other words, 'st' is entered in the
dictionary both with and without a trailing period).

<p>This corrects a problem that could have occurred with the old
scheme if the same word was used abbreviated and unabbreviated.  For
example, if 's.' was used as an abbreviated word (for a string like
's. main st.', for example), and 's' was also entered in the
dictionary as a verb (which it is by default, for the South action)
the command "s." was not properly handled.  The problem was that the
tokenizer would see that "s." was entered in the dictionary with the
period, so it tokenized it with the period.  This precluded
interpreting it as two tokens, 's' and '.', so the 's' was not
matched to the verb, hence the command was rejected as not understood.

<p>A useful side effect of this change is that each abbreviation is
now automatically entered in the dictionary without its period.  This
should be helpful to players who choose to avoid the extra typing of
entering the periods in abbreviations.

</div>

<!------------------->
<div class=entry>

The new Hidden class can be used to implement objects that are present
but not seen.  This is useful for objects that are too inconspicuous
to be noticed, or are positioned in such a way that they can't be
readily seen (but in such a way that the ordinary sense mechanism
would think the object was visible).

</div>

<!------------------->
<div class=entry>

The BulkLimiter class now parameterizes all of the messages that
were previously coded directly as failure reports.  The new BulkLimiter
properties tooLargeMsg, becomingTooLargeMsg, and becomingTooFullMsg
join the existing tooFullMsg in specifying the various failure reports;
these properties in turn contain property pointers that refer to
messages defined in the playerActionMessages object.  This makes it
easier to create "cosmetic" subclasses of BulkLimiter that define
customized types of containment relationships.

</div>

<!------------------->
<div class=entry>

The new macro askForTopic(action) allows a single-object TAction to
ask for a topic phrase and retry the command as a TopicTAction.  This
allows, for example, a CONSULT action with no topic specified to ask
for a topic and turn itself into a CONSULT ABOUT action.

<p>To enable this change, the parser includes a new grammar
production, EmptyTopicPhrase.  This new production represents a topic
phrase that requires an interactive response from the player.

</div>

<!------------------->
<div class=entry>

In the past, it wasn't possible to use askForDobj() to convert a
LiteralAction into a LiteralTAction, or a TopicAction into a
TopicTAction, by requesting a missing direct object from the player.
This was due to an oversight in the library, which has now been
corrected.

<p>Another similar, though more subtle, oversight made it impossible
to use askForDobj() to convert a TAction into a TIAction.  This is an
unusual scenario, because the usual way to perform this conversion
would be through askForIobj(): it's almost always the indirect object
that's missing in these cases.  However, there are cases where a
missing direct object is possible; for example, we might want a
full-fledged SPRAY verb that takes only one object, as in SPRAY AIR
FRESHENER, but also have a two-object form for things like SPRAY SINK
WITH DISINFECTANT, in which it's the direct object that's missing
from the two-object form when we type SPRAY DISINFECTANT.  (This
particular example is a bit contrived, since we could just as well
have defined the verb as SPRAY DISINFECTANT ON SINK, but even so, we
don't want to be forced to find such a rephrasing.)  In these cases,
askForDobj() can now be used.  When a TAction is retried as a
TIAction with askForDobj(), the direct object of the TAction now
becomes the <i>indirect</i> object of the TIAction; this is plainly
the only way it can be, since we know the direct object is missing by
virtue of the fact that we're asking for it.

</div>

<!------------------->
<div class=entry>

The interface of the method Actor.trackFollowInfo() has been changed
slightly to improve its flexibility.  In the past, this method assumed
that the current action was actually performing the travel; now, the
method instead takes an additional argument to eliminate this
dependency.  The new third argument gives the starting location of the
travel; this is normally simply the location of the actor traveling,
but could be something else; for example, when the actor is inside
a vehicle, then the starting location is the vehicle's location.

</div>

<!------------------->
<div class=entry>

The new class NestedRoomFloor can be used for convenience in creating
an object that serves as the floor of a nested room.

</div>

<!------------------->
<div class=entry>

The Floor class now accepts STAND ON commands.  STAND ON FLOOR is
simply remapped to STAND UP.

</div>

<!------------------->
<div class=entry>

The BurnWith action now resolves its direct object first.  This is
the better resolution order for this action, since it allows the
direct object to set the scope for choosing the indirect object,
which is likely to be omitted and thus require a suitable default
to be chosen.

<p>In addition, the FireSource class now declares it illogical to
burn an object using itself as the fire source.  It's common for a
Candle to also be a FireSource; this change prevents such an object
from being chosen as its own default fire source in a command like
LIGHT CANDLE, which would cause an infinite loop as we tried to light
the candle with itself, which would require first lighting the
candle, which would default to lighting it with itself again, and so
on.

<p>The FireSource and Matchstick classes have also been fine-tuned to
work together a little better.  The FireSource class now specifies a
logicalRank of 150 when used as the indirect object of BurnWith.  The
Matchstick class uses a logical rank of 160 when lit and 140 when not
lit.  This makes a matchstick an especially logical choice for
starting a fire under all conditions, but makes a non-matchstick an
even better choice when it's already burning.  A lit match trumps
everything (160), next best is an already-lit non-matchstick
FireSource (150), and when there's nothing else around that's
burning, a matchstick will still be a good choice (140).  This
ensures that we don't light a new match when there's another fire
source readily at hand, but at the same time ensures that we'll
default to using a match when no better choice is available.

</div>

<!------------------->
<div class=entry>

When an implicit action is interrupted with an interactive prompt,
the announcement of the implicit action is now phrased as "trying"
the action.  This is along the same lines as the change in 3.0.6k
that phrased failed implicit actions as "trying"; since an interactive
prompt interrupts an implied action, it makes more sense to refer to
the implied action as being merely attempted at this stage.

<p>Internally, the announcement generator distinguishes between
failed actions and actions interrupted for interactive input, so it's
a fairly easy matter to customize the types of messages separately.
To customize the "asking" case separately from the "trying" case,
customize the askingImpCtx object; in particular, override its
buildImplicitAnnouncement() method and its useInfPhrase property as
needed.  The default in the library is to use the same message
style for both cases.

</div>

<!------------------->
<div class=entry>

Due to a bug in the library, using "exit" to abort an action from
within a check() handler did not properly mark the action as failed
within the transcript, which meant that the "trying" form of an
implicit action announcement was not generated.  This has been
corrected.

</div>

<!------------------->
<div class=entry>

In the past, when an implied action was remapped to another action
(via remapTo), the normal announcement of the implied action wasn't
generated.  This has been corrected: the announcement will now be
shown as usual.

</div>

<!------------------->
<div class=entry>

The parser is now a little smarter about excluding items with ALL
EXCEPT in cases of simple remappings.  In many cases, remapTo is used
to create simple object-to-object synonyms for certain verbs; for
example, OPEN DESK might be remapped to OPEN DRAWER when it's obvious
that the two commands mean the same thing.  In these cases, when an
object is excluded from the ALL list with EXCEPT, the parser will now
look for these simple synonym remappings, and it will treat them as
equivalent.  So, if OPEN DESK is remapped to OPEN DRAWER, and the
player types OPEN ALL BUT DESK or OPEN ALL BUT DRAWER, then the desk
and drawer will be excluded from the ALL list.

<p>Note that the parser can only exclude synonym remappings when
they're remapped using the remapTo (or maybeRemapTo) mechanism.
Remappings that are done using replaceAction() or the like can't
be detected as synonyms, so they won't be excluded.  Remappings
that aren't simple synonyms won't be excluded, since remapping
to different verbs or word orders changes the meaning of the
command enough that the EXCEPT list shouldn't exclude the new
objects.  For example, if OPEN DOOR remaps to PUSH BUTTON, because
a button is used to operate a mechanical door, OPEN ALL BUT BUTTON
would <b>not</b> exclude the remapping to PUSH BUTTON, since we
didn't say not to PUSH the button, only not to OPEN the button.

</div>

<!------------------->
<div class=entry>

The standard "weak vocabulary" checking in Thing now takes into account
truncatable vocabulary words, as well as any other special dictionary
comparison rules, by using the main dictionary's string comparator
to check for weak tokens.  Note that this routine uses the global
property languageGlobals.dictComparator, so if the game ever changes
the main dictionary's string comparator object, it should also change
this global property at the same time.

</div>

<!------------------->
<div class=entry>

The Topic class now specifically disallows sensing a topic object
with any physical senses.  This ensures that a topic object will
never be in any physical scope, even if the object is part of a
containment hierarchy.  (It's sometimes convenient to include a topic
as part of a containment hierarchy in order to associate the topic
with a physical game world object.)

</div>

<!------------------->
<div class=entry>

The possessive qualifier resolver (PossessiveResolver) now considers
an object to be in scope in a possessive phrase only if the object
has the property canResolvePossessive set to true.  This property is
true by default for all Things and nil by default for all Topics.  In
other words, by default, possessive phrase qualifiers can only be
resolved to physical game world objects, never to abstract topics.

</div>

<!------------------------------- 3.0.6k --------------------------------->
<div class="sepbar"><a name='306k'></a>3.0.6k</div>
<p><b><i>Released August 17, 2003</i></b>
<p>

<div class=firstentry>

The new TopicEntry method isMatchPossible() tries to guess whether or
not the TopicEntry can be matched by any input currently.  This
question is unanswerable in general, because it's asking if there
exists any input, out of the infinite set of possible inputs, that
will match the topic entry.  However, the TopicEntry subclasses use
heuristics to provide an answer that's right in most cases.  In
particular, the ASK and TELL entries consider themselves matchable if
any of their matchObj objects are either known to the player character
or are simply in scope; the GIVE and SHOW entries are considered
matchable if any of their matchObj objects are in scope; and YES, NO,
and special topic entries are always considered matchable.  If a game
creates a custom matchTopic() method, it might want to customize
isMatchPossible() to match the custom match condition.

<p>The SuggestedTopic method isSuggestionActive() uses this new
method to hide suggestions that aren't currently matchable.  This
provides an important benefit for the most common cases: topics won't
be suggested until the player character knows about them.  This
avoids showing suggestions for things the player shouldn't even
have heard of yet.

<p>To facilitate this change, isSuggestionActive() now takes an
additional argument, giving the list of in-scope objects.  This
avoids the need to repeatedly compute the scope list when scanning
a large list of suggested topic objects, which is important because
the scope calculation is complex and can be time-consuming.

</div>

<!------------------->
<div class=entry>

Some important terminology for TopicEntry objects has been changed:
where we formerly referred to a TopicEntry as "known," we now refer to
it as "active" instead.  The old terminology implied that TopicEntry
objects model NPC knowledge; this was misleading, though, because the
availability of a TopicEntry often depends on PC knowledge as well as
NPC knowledge, or what the NPC <i>wishes</i> to reveal rather than
what the NPC actually knows, or various other things.  The new
terminology removes the implication that NPC knowledge in particular
is being modeled.

<p>This change requires new names for several TopicEntry properties:
isKnown is now isActive; checkIsKnown is now checkIsActive; and
topicGroupKnown is now topicGroupActive.

<p>Game code that uses TopicEntry objects will have to rename isKnown
to isActive in the object definitions.  The other renamed properties
might have to be changed as well, of course, but these are less likely
to appear in game code.

</div>

<!------------------->
<div class=entry>

The travel precondition mechanism has been tweaked a little to make it
more flexible for handling nested-room situations.  In the past, each
travel connector was responsible for providing a precondition applied
whenever an actor traversed the connector, via the travel connector's
actorTravelPreCond(actor) method.  This formerly returned the
actorStanding precondition.  While this was appropriate in most cases,
since it ensured that the actor wasn't sitting in a chair or anything
like that, it didn't make for easy customization for specialized nested
rooms or other unusual situations.

<p>The change is that TravelConnector.actorTravelPreCond(actor) now
returns a new precondition, actorTravelReady, instead of
actorStanding.  The actorTravelReady precondition abstracts the travel
condition by letting the actor's immediate location handle it.  In
particular, it calls three new BasicLocation methods to carry out the
precondition: isActorTravelReady(conn), tryMakingTravelReady(conn),
and notTravelReadyMsg.  By default, these methods do exactly what
actorStanding does: they require the actor to be standing up before
travel.  However, a location can override any or all of these.  For
example, a particular nested room might want to use a command other
than "stand up" to get the actor out of the nested room in preparation
for travel; the nested room could override tryMakingActorTravelReady()
in this case to carry out the desired implied command.

<p>Note that the travel connector to be traversed is an argument to
the first two of the new methods.  This allows the actor's current
location to impose different requirements on travel via different
connectors.  For example, it might be necessary to climb down from a
ladder before leaving via any connector except for a window high up on
the wall, which can only be reached when on the ladder.

</div>

<!------------------->
<div class=entry>

The new Action method cancelIteration() lets you tell cancel further
iteration of the current action, if multiple objects are involved in
the action.  You can call this method on the current gAction object
during the 'check' or 'action' phases of execution.  Once the method
is called, the action will complete the execution cycle for the
current object as normal, but it will then act as though the current
object were the last object of the command.

<p>Note that this new method does <b>not</b> have any effect on the
execution of the command for the current object; in particular, it
doesn't interrupt the execution flow the way 'exit' and the like do.
Instead, this method simply sets a flag in the current Action object
telling it to ignore any additional objects it would otherwise
iterate over.  If you want to jump out of the execution cycle in
addition to canceling further iteration, simply use 'exit' (or one of
the similar signals) after calling this method.  Note also that this
method obviously can't cancel the iteration for any prior objects in
the iteration.

</div>

<!------------------->
<div class=entry>

In the status-line and menu modules, there were some unnecessary
"flush" operations (on banners and on the main window).  Most of these
were placed before "sizeToContents" calls on banners, which is
unnecessary because that operation automatically flushes the
underlying output stream anyway.  These extra calls were not only
unnecessary but were also undesirable, because the explicit flush
operations always update the display immediately in addition to
flushing internal text buffers.  This made the display flicker
annoyingly at times.  The extra flushes have been removed, which
makes the display updating faster and eliminates the flicker in
the common cases covered by the changes.

</div>

<!------------------->
<div class=entry>

When a MenuLongTopicItem is part of a series of "chapters" (as
indicated by the isChapterMenu property), and the user navigates
directly from one chapter to the next, the menu system keeps the
banner configuration for the chapter display throughout the change
to the new chapter.  In the past, the menu system removed the banner
and then immediately restored it, which caused some visual flicker.
This change eliminates the flicker during the chapter change.

</div>

<!------------------->
<div class=entry>

The English implicitAnnouncementGrouper implementation now uses
pronouns, where appropriate, to refer to repeated objects when it
groups a series of announcements.  It frequently happens that the same
object appears more than once when a series of implied actions is
performed; this new phrasing makes the announcement text shorter and
makes it read more naturally.  For example, rather than saying "first
unlocking the door, then opening the door", we'll now say "first
unlocking the door, then opening it".

</div>

<!------------------->
<div class=entry>

The implicit action announcement mechanism now phrases the
announcement for a failed action a little differently than for a
successful action.  When an action fails, the message now reads
"(first trying to ...)".  The old phrasing was a little awkward at
times, because the announcement describes the action as being
performed, and then the (usually) very next message says just the
opposite, that the action wasn't performed at all because it failed.
Depending on the wording of the failure message, the combination could
even be misleading on occasion, since the suggestion in the
announcement that the action was performed could lead to a player
assuming that the failure message must refer to something else.

<p>To enable this change, the interface to the libMessages method
announceImplicitAction() has changed slightly.  The method now takes a
"context" parameter, which is an object of class
ImplicitAnnouncementContext The context contains information on the
format of the message to be generated.

<p>Also, the implicitGroupTransform internally scans for failure
messages that apply to implied action announcements, and rewrites the
implied action announcements into the new format when failures are
noted.

<p>Finally, the implicitAnnouncementGrouper object implementation in
the English module does some additional grouping, to render a series
of "trying" messages as readably as possible.  When a series of
consecutive "trying" messages appears, the grouper combines them under
a single "trying" phrase, as in "first trying to unlock the door and
then open it."

</div>

<!------------------->
<div class=entry>

Several small internal changes have been made in the English library
module.

<p>First, the new method getInfPhrase() returns a string giving the
full action description in infinitive form.  This returns a phrase
such as "open the box" or "unlock the door with the key".  The verb is
always in the infinitive form, but note that the English infinitive
complementizer, "to", is not part of the returned phrase; this is
because an infinitive is used without a complementizer in certain
contexts in English, such as with auxiliary verbs (such as "might" or
"should").

<p>Second, the new method getVerbPhrase(inf, ctx) returns the full
verb phrase in either the infinitive form ("open the box") or the
present participle form ("opening the box").  In English, the two
forms are equivalent except for the verb ending, so the code to
generate both forms can be easily consolidated into a single routine.
The subclasses of Action override getVerbPhrase() as needed to provide
appropriate phrasings.  The context object 'ctx' is optional; if it's
not nil, it should be an instance of the new class
GetVerbPhraseContext.  If the context object is provided, the routine
uses it to keep track of pronoun antecedents for the verb phrase; the
returned verb phrase will use a pronoun if one of its objects matches
the current antecedent, and the routine will set the antecedent in the
context for the next verb phrase that uses the same context.  The
context is useful if you're generating a series of verb phrases that
you're going to string together into a single sentence; by using
pronouns to refer to repeated objects, the sentence will be shorter
and will read more naturally.

<p>Third, the implementation of getParticiplePhrase() now simply
calls getVerbPhrase() in all cases.

<p>Fourth, the routine formerly called verbInf() has been renamed to
getQuestionInf(), to better describe its purpose.  This routine
doesn't return the full infinitive form of the verb, but rather
returns an infinitive form specifically for an interrogative in which
one of the verb's objects is the interrogative's unknown.  The old
name was always misleading, but the addition of getInfPhrase() would
have made the name even more confusing because of the similarity of
the names.

</div>

<!------------------->
<div class=entry>

In the routine that tries to free up space in an actor's hands by
moving objects into a "bag of holding," objects with no encumbering
bulk are now never moved.  In the past, objects were moved in
descending order of encumbering bulk, so objects with zero bulk were
typically ignored; however, if there weren't enough bulky objects
present, it was possible for the routine to try moving bulkless items.
Since worn items have no encumbering bulk by default, this meant the
routine sometimes removed worn items and moved them to the bag, which
was pointless.

</div>

<!------------------->
<div class=entry>

The new class FloorlessRoom, a subclass of Room, makes it easier to
build rooms that represent locations without conventional floors.
Anything dropped in the room is described as falling and vanishing
below, since there's no floor for it to land on.  You can control
where dropped objects land using the bottomRoom property; by default,
this is nil, which means that dropped objects simply disappear
from the game.

</div>

<!------------------->
<div class=entry>

The Room class no longer requires the room's floor to be represented
by the first element of the roomParts list for the room.  Instead, the
new method roomFloor returns the room's floor object; this method
finds an object of class Floor in the roomParts list and returns it,
or nil if there no object of class Floor in the list.  This change
eliminates the fragility caused by the former convention.

</div>

<!------------------->
<div class=entry>

A new mechanism provides more consistent handling when objects
are dropped into a room.  The new mechanism is used in the library
to handle the DROP and THROW commands, both of which can result in
an object being dropped into the enclosing room.  The mechanism is
extensible, so library extensions and games can add their own actions
that drop objects into the room.

<p>Whenever an object is to be dropped into the enclosing room, the
DROP and THROW commands first find the drop destination using the
existing getDropDestination() method.  Then, they invoke the new
receiveDrop(obj, desc) method on the drop destination object.  In most
cases, the drop location is the enclosing room, so the enclosing
room's receiveDrop() method is usually the one that will be invoked.

<p>The receiveDrop() method is responsible for carrying out the
effects of dropping the object, including any game-state changes (such
as moving the dropped to its new location) <i>and</i> reporting the
results of the action.

<p>In most cases, the effects won't vary according to which command
was used to discard the object.  This is the reason that there's only
one receiveDrop() method, rather than separate methods for DROP,
THROW, and any library extension or game-specific verbs.  By using a
common routine to handle all means of discarding an object, the game
only has to implement any special handling once.

<p>However, the <i>message</i> will almost always vary according to
the command, for the simple reason that the message needs to
acknowledge what the actor did to discard the item in addition to the
effects of dropping it.  This is the main reason the 'desc' argument
is provided: it's a special "drop descriptor" object that lets you
find out what command was used.  You could also look at gAction to
find the Action being performed, but the descriptor object makes your
job a lot easier by providing some convenience methods for building
report messages.

<p>The descriptor object is of class DropType.  This class has two
important methods.  First, standardReport() displays the "normal"
report for the action.  For DROP, this is simply "Dropped."  For
THROW, this is a message of the form "The ball hits the desk, and
falls to the floor."  You can use the standard report when your
receiveDrop() method doesn't do anything out of the ordinary and thus
doesn't require a special report.  Second, getReportPrefix() returns a
string that gives the <i>start</i> of a sentence describing the
action.  The returned string is a complete main clause for a sentence
-- but it has no ending punctuation, so you can add more to the
sentence if you like.  The main clause will always be written so that
the object being dropped will be the logical antecedent for any
pronouns in subsequent text, which lets you tack on a string like
this: ", and it falls to the floor."

<p>Rather than building a message from the report prefix provided by
the descriptor, you are free to build a completely custom message, if
you prefer.  To do this, you could use 'modify' to add your own method
to each DropType subclass in the library, and then call this method
from your receiveDrop().  Alternatively, you could use ofKind() to
check what kind of DropType descriptor you got, and show custom
messages for the ones you recognize.

</div>

<!------------------->
<div class=entry>

Thing.stopThrowViaPath() now simply calls throwTargetHitWith() by default.
When an object interrupts a projectile's course, the result is exactly as
though the projectile had been successfully thrown at the interrupting
object, so the separate implementations were redundant.

</div>

<!------------------->
<div class=entry>

finishGame() now resets the sense context.  This ensures that if the
event that triggered the end of the game happened while a blocking
sense context was in effect, the finish options are still listed.
(Since the finish options involve direct interaction with the player,
they obviously shouldn't be displayed in any NPC sense context.)

</div>

<!------------------->
<div class=entry>

Thing now has a constructor, which calls initializeThing().  This ensures
that any Thing objects that are created dynamically (with 'new') are
initialized in the same manner as objects defined statically.

</div>

<!------------------->
<div class=entry>

The library's handling of RESTART has been changed slightly to correct
a problem that cropped up under certain unusual circumstances.  The
old handling reset the VM within the Restart action execution method,
and then threw a RestartSignal to tell the main loop to re-enter the
game from the beginning.  This approach had a subtle flaw: if any
dynamically-created objects were referenced from an intermediate stack
frame in the code that initiated the restart, those objects were
retained through the VM reset because they were still accessible via
the stack.  These objects then had a chance to remain visible to an
object loop, such as those that run during the library
pre-initialization.  The Restart action handler now simply throws the
RestartSignal to the main loop, and the main loop now performs the VM
reset.  This ensures that the stack is reset to initial conditions
before the VM reset occurs, which in turn ensures that only those
dynamic objects that should survive the reset do survive the reset.

</div>

<!------------------------------- 3.0.6j --------------------------------->
<div class="sepbar"><a name='306j'></a>3.0.6j</div>
<p><b><i>Released August 2, 2003</i></b>
<p>

<div class=firstentry>

The new class DistanceConnector is a specialized subclass of
SenseConnector that allows two (or more) locations to be connected,
but at a distance.  This is handy for situations such as divided rooms
(where we use two or more Room objects to model a single large
physical location), and for cases where two rooms are open to one
another (such as a balcony overlooking a courtyard).

</div>

<!------------------->
<div class=entry>

The new class Vaporous is a subclass of Intangible designed for
insubstantial but visible objects, such as fire, smoke, and fog.
This class works a lot like Intangible, but it has a visual presence,
and it specifically allows the commands Examine, Smell, and Listen To;
in addition, it allows the commands Look In, Look Under, Look Behind, Look
Through, and Search, and responds to these with "You just see (the
object)."

</div>

<!------------------->
<div class=entry>

The Lister class no longer sets the 'seen' attribute of objects it
lists, because this attribute is now more generally handled in the
main room description routines (per the change in meaning of 'seen'
in 3.0.6i).  As a result, the Lister.markAsSeen method has been
removed.

</div>

<!------------------->
<div class=entry>

A new macro, gSetKnown(obj), marks an object (usually a Thing or a
Topic) as known by the player character.  This is simply short-hand
for obj.setKnownBy(gPlayerChar, true), for convenience.

</div>

<!------------------->
<div class=entry>

The EventList object has been enhanced slightly to accept property
pointer entries.  A property pointer entry is interpreted as a
property to invoke on the EventList itself, with no argument.  This
allows writing complex steps as separate properties of the EventList
object, and then referring to them from the script by property
pointer.

<p>In addition, the ScriptEvent class has been eliminated.  Instead,
simply use Script objects in an event list.  So, when an object
appears in an event list, the EventList class now invokes the
object's doScript() method.  This makes it easy to build event lists
recursively.

<p>The new EventList subclasses CyclicEventList and StopEventList
provide new pre-defined options for the behavior of an event list
after visiting all elements.  The new subclass SyncEventList provides
a list that synchronizes its state with another list.

<p>The TextList, StopTextList, and SyncTextList classes are now
simple subclasses of CyclicEventList, StopEventList, and
SyncEventList, respectively.

<p>A new EventList method, scriptDone(), is invoked by doScript()
after it processes the script's current step.  By default, this
method simply invokes advanceState() to advance the event list to
its next state.  Subclasses can override scriptDone() so that it
does not advance the script's state, or does something else in
addition.

<p>The new EventList subclass ExternalEventList overrides scriptDone()
so that the method does nothing.  This makes it easy to create an
event list that is driven externally; that is, the event list doesn't
advance its state when doScript() is invoked, but only advances its
state in response to some external processing that calls
advanceState() directly on the event list object.

</div>

<!------------------->
<div class=entry>

The Room class now provides a dobjFor(Examine) that replaces the
Examine action with a Look action.  This means that if a Room object
has ordinary vocabulary words defined, and the player types EXAMINE
(room), the command will automatically be treated as though the
player had typed LOOK AROUND.

</div>

<!------------------->
<div class=entry>

The new class IndirectLockable is a subclass of Lockable that
can be used for situations where a lockable object cannot have
its locked status directly manipulated by LOCK and UNLOCK commands.
The reply to LOCK and UNLOCK can be customized via the object's
cannotLockMsg and cannotUnlockMsg properties.

</div>

<!------------------->
<div class=entry>

The Lockable class now handles the 'objUnlocked' precondition a little
more subtly.  The class now keeps track of whether or not the player
knows the object to be locked; the status is assumed to be unknown
initially.  When the player doesn't know the status, the Open action
does <b>not</b> apply an objUnlocked precondition, but instead disallows
the action in the check() routine.  When the status is known, the
objUnlocked precondition is applied as before.  Whenever the Open
action fails in the check() due to the object being locked, the
status is taken to be known for subsequent attempts.

<p>This change makes the precondition handling a little more
intelligent.  When the player doesn't know the status beforehand, an
Open command will simply fail with the discovery that the object is
locked.  This usually makes more sense than attempting to unlock the
object automatically with an implied Unlock command, because if the
object isn't already known to be locked, there's no reason to try to
unlock it.  When the status is known, however, it makes sense to
perform the implied Unlock.

<p>Objects whose lock status is visibly apparent can be marked as such
with the lockStatusObvious property.  This property is nil by default;
an object whose lock status can be visibly observed should set this to
true.  When this property is set, the lock status is <i>always</i>
known, since we'll assume that actors will simply look at the lock and
observe the status.  In addition, when this property is set, we'll add
the locked/unlocked status at the end of the object's 'Examine'
description (we'll add "It's currently locked" or "It's currently
unlocked").

</div>

<!------------------->
<div class=entry>

A new class, TravelWithMessage, can be mixed (using multiple inheritance)
with TravelConnector or a subclass of TravelConnector to create a connector
that shows a message as it's traversed.  This is slightly more flexible
than using TravelMessage, since TravelMessage can't usually be mixed with
other TravelConnector-derived classes.

</div>

<!------------------->
<div class=entry>

A new TravelConnector property, stagingLocation, gives the location
in which a traveler must be located prior to traversing the connector.
In the past, the connector simply assumed the traveler needed
to be in the connector's direct location; this new property allows
this condition to be customized.  At times, the connector might be
inside an intermediate container, for example, in which case the
staging location might be a container of the container.  By default,
the staging location is the connector's location, so connectors that
don't override stagingLocation will have the same behavior as before.

</div>

<!------------------->
<div class=entry>

A new Thing method, roomLocation, returns the 'self' if the object
is capable of serving as a location for actors, or the nearest
container that is a roomLocation otherwise.

<p>The Passage travel connector class now uses the other side's
container's roomLocation as the default destination of the passage,
rather than the other side's immediate container, as it did in the
past.  This makes it much easier to create passages that model
non-trivial containment relationships, such as holes in walls, since
an intermediate container (between the Passage and the enclosing Room
or NestedRoom) will no longer create any confusion in performing the
travel.

</div>

<!------------------->
<div class=entry>

The NoTravelMessage class can now multiply inherit from Script, for
convenience in defining message lists.  If you want to provide several
different messages to choose from when the connector is traversed, you
can make your connector object inherit from TextList as well as
NoTravelMessage, and the travelDesc() will automatically invoke the
script to show a message.

</div>

<!------------------->
<div class=entry>

<p>If the travel connector has a non-nil location, the TravelConnector
class's connectorTravelPreCond method adds a precondition that the
connector must be touchable.  This ensures that characters won't be
allowed to traverse connectors that are visible but on the other side
of a window, for example, or connectors that are out of reach.

</div>

<!------------------->
<div class=entry>

The travel notification protocol has been changed very slightly.  The
travel connector's noteTraversal() method is now invoked from within
the Traveler.travelerTravelTo() method rather than the TravelVia
handler in the connector.  This change means that noteTraversal()
is called just before the traveler is actually moved, and in particular
that it occurs <i>after</i> all of the other travel notifications
(beforeTravel, actorTravel, and travelerLeaving).  This is generally
the more desirable ordering for the notifications, because it puts
the connector's reaction closest to the actual traveler movement.
If you want the connector to do something special before any of the
other notifications, you can override the action() handler
in the connector's dobjFor(TravelVia) so that it performs the special
code and then inherits the base class handling.

</div>

<!------------------->
<div class=entry>

When an actor travels through a connector that leads to a location
with a posture other than the actor's original posture, the new
location now sets the actor's posture directly, rather than via a
nested action.  For example, if a travel connector leads to a chair,
then traversing the connector will move the actor into the chair and
set the actor's posture to 'sitting', without activating a nested Sit
action.  In the past, the nested Sit action would have been used
instead.  This change is in BasicLocation.travelerArriving(), which
sets the new actor's posture via a call to Actor.makePosture().

<p>This change is generally desirable because we usually want arrival
by travel connector to be self-contained; we don't want it to appear
as though the character walked to the new location and only then
performed a SIT ON THE CHAIR command (say).  It's worth noting,
however, that any side effects of the usual way of getting into the
new location's posture will be skipped.  Therefore, when linking a
travel connector into a nested room with a non-standing posture, you'll
need to consider any side effects you'd want to trigger, and trigger
them explicitly on the travel connector itself.

</div>

<!------------------->
<div class=entry>

The new Actor method scriptedTravelTo() simplifies coding of scripted
travel for an actor.  This routine is suitable for cases where an NPC
is to perform a series of scripted travel actions, where each room
along the way is scripted in advance.  This routine is <i>not</i>
suitable for goal-seeking NPC's, because it can only perform travel to
a location adjacent to the actor's current location, and because it's
"omniscient" (it doesn't take into account the actor's knowledge of
the the map, but simply considers the actual map).  For cases where
an NPC is to visit a scripted series of locations, this is a convenient
way to accomplish the travel, since it requires specifying only the
destination of each step of the travel.

</div>

<!------------------->
<div class=entry>

The class SecretDoor is now based on BasicOpenable as well as
ThroughPassage.  The class previously didn't have BasicOpenable
anywhere among its superclasses, which prevented its open/closed
mechanisms (initiallyOpen, isOpen, makeOpen) from working
consistently with other types of doors, which are all based
(indirectly) on BasicOpenable.

</div>

<!------------------->
<div class=entry>

The new ThroughPassage subclass PathPassage is a specialization for
cases such as outdoor walkways, paths, and streets.  The key
difference between the standard ThroughPassage and the more
specialized PathPassage is that path passages are not considered
enclosed, so the descriptions for arrival and departure via a path
take this into account.  In the English messages, we describe travel
on a path as being "via" the path rather than "through" it.  In
addition, the English parser accepts "take" as a synonym for "enter"
or "go through."

<p>To handle this new class, TravelMessageHandler and its subclasses
have a new pair of methods, sayArrivingViaPath() and
sayDepartingViaPath(), for generating travel messages related to
paths.


</div>

<!------------------->
<div class=entry>

The new method Actor.actorTravel(traveler, connector) complements
beforeTravel() and afterTravel().  This new method is called on the
actor who <b>initiated</b> the travel (that is, the actor performing
the command, if any); it's called after the beforeTravel()
notifications are sent to nearby objects.  This method is provided for
symmetry with the beforeAction/actorAction/afterAction set.

</div>

<!------------------->
<div class=entry>

The AccompanyingState.accompanyTravel() method has been changed slightly.
The first parameter is now a Traveler object, which might be an Actor but
could also be another kind of Traveler, such as a Vehicle.  This allows
the game to determine whether the NPC is to accompany actors when they
travel on vehicles or in other indirect ways.

<p>In addition, the class's beforeAction() method, which responded to
the initiating actor's travel, has been changed to a beforeTravel()
method.  This takes advantage of the more precise kind of notification
offered by beforeTravel().  In particular, using this method avoids
unnecessary attempts to accompany an actor who attempts a travel command
that doesn't actually result in travel (because the connector doesn't
go anywhere, for example).

</div>

<!------------------->
<div class=entry>

If a travel connector is located inside a nested room, the
preconditions for traversing the connector now correctly move the
character to the nested room prior to the travel.  In the previous
library version, the enclosing room tried to add its own precondition
requiring the traveler to be in the outer room, which was incorrect.

</div>

<!------------------->
<div class=entry>

The Follow command now provides better feedback to the player in
certain cases.  When the player has previously observed the target
actor departing, but from a different location than the player's
current location, the Follow command will now respond with the message
"You didn't see which we he went" (rather than "You can't do that from
here" as it did in the past).

</div>

<!------------------->
<div class=entry>

An Actor's executeTurn() method, and all of the methods it invokes
(the Actor's idleTurn() and the ActorState's takeTurn(), for
example), now run within a valid "action environment," just like
fuses and daemons started doing in 3.0.6i.  In addition, the
executeTurn() method sets up a visual sense context for the actor,
ensuring that any output displayed in the course of the actor's turn
is displayed only when the actor is visible to the player character.
(It is presumed that the effects of any action that an actor performs
are visible if and only if the actor is visible.  This is just the
default case, though: the game is always free to set up a separate
sense context, using callWithSenseContext(), whenever necessary.)

<p>To facilitate this change and make it easier to override an actor's
per-turn processing, the main handling for an actor's turn is now in
a new method, executeActorTurn().  The executeTurn() method simply sets
up the action environment and then invokes executeActorTurn().  In most
cases, subclasses that need to specialize the per-turn processing should
override executeActorTurn() rather than executeTurn(), since this will
let the override run in the action environment.

</div>

<!------------------->
<div class=entry>

The optional initial "look around" that the runGame() function
performs is now executed within an "action environment," just like
fuses and daemons started doing in 3.0.6i.  This allows the initial
room description to refer to gActor and gAction, which some library
methods do implicitly.

</div>

<!------------------->
<div class=entry>

callWithSenseContext() now uses "lazy evaluation": rather than
immediately calculating the effect of the new sense context, the
routine now simply notes that it has a new context, and defers
calculating the effects of the new context until the effects actually
need to be known.  This makes it very inexpensive to set up a new
sense context in cases where the context won't actually be needed for
anything, which is frequently the case in daemons, fuses, and the
standard per-turn processing for NPC's.  This can save a substantial
amount of time when a game has numerous background events if, as is
typical, most of the background events don't generate any output on a
given turn.

</div>

<!------------------->
<div class=entry>

The new macros actorStateDobjFor(action) and actorStateIobjFor(action)
make it convenient to delegate an actor's processing for an action to
the actor's current ActorState object.  These are defined in adv3.h,
and work analogously to asDobjFor(action) and asIobjFor(action).  Using
these macros involves two steps.  First, in the Actor, write a short
handler for the action that uses the macro to delegate to the state
object:

<p><pre>
  bob: Person
    // ... other definitions ...
    dobjFor(AttackWith) actorStateDobjFor(AttackWith)
  ;
</pre>

<p>This sets up the "bob" Actor object so that the handling for
AttackWith, with bob as the direct object, will be delegated to bob's
current ActorState object.  Second, just write a normal dobjFor() handler
in each of the ActorState objects associated with bob:

<p><pre>
  + bobFighting: ActorState
    dobjFor(AttackWith)
    {
      action() { "Bob puts up a fight..."; }
    }
  ;
  + bobCowering: ActorState
    dobjFor(AttackWith)
    {
      action() { "Bob just hides in the corner..."; }
    }
  ;
</pre>

</div>

<!------------------->
<div class=entry>

The withActionEnv() function now takes an addition parameter giving
the Actor object to use as the gActor value while running the
callback.  In the past, this function always used the player character
Actor (given by gPlayerChar); the new parameter allows other actors to
be used instead.

</div>

<!------------------->
<div class=entry>

The withCommandTranscript() function now returns the result of the
callback function, rather than the transcript object created to run
the callback.  Callers who still need the transcript object as the
result can simply return gTranscript from the callback function
itself, as this value will then be passed up as the return value from
withCommandTranscript().

</div>

<!------------------->
<div class=entry>

The attentionSpan property of an InConversationState object can now be
set to nil to indicate that there is no attention span limit for the
NPC.  Setting attentionSpan to nil will prevent the NPC from ever
ending the conversation by virtue of being ignored for too long.

</div>

<!------------------->
<div class=entry>

The standard SpecialTopic template (in adv3.h) now allows defining a
list of strings (for the textStrings property) in place of a single
response.  The standard TopicEntry, SpecialTopic, and YesNoTopic
templates now make the response/response list entry optional, allowing
the rest of the templates to be used even if a custom method is
needed to handle the response.

</div>

<!------------------->
<div class=entry>

A new DefaultTopic subclass, DefaultAnyTopic, matches all of the
different sorts of topic interactions: ASK, TELL, GIVE, and SHOW.
This is especially useful for default handling in conversation nodes
(ConvNodes) where you want catch all topics not otherwise handled.

</div>

<!------------------->
<div class=entry>

The new TopicEntry property isConversational lets a TopicEntry
specify whether or not the response is "conversational."  A
conversational response is one that involves some kind of interaction
with the NPC.  This property is true by default, but some response
objects will want to set it to nil to indicate that the response
doesn't involve any conversation with the NPC.  For example, a
response like "You don't think he wants to discuss that right now" is
non-conversational, because it doesn't involve any exchange with the
NPC.

<p>When isConversational is nil for the response object that's found
for a conversation command, a ConversationReadyState will <b>not</b>
enter its in-conversation, but will simply show the response and
remain in the conversation-ready state.  This means that there will
be no "greeting" exchange for these responses.

</div>

<!------------------->
<div class=entry>

The new ConvNode method canEndConversation(actor, reason) lets a node
prevent a conversation from ending.  'reason' is an enum indicating
what is triggering the attempted termination: endConvBye if the player
typed BYE; endConvTravel if the other actor is leaving (i.e., the player
typed a travel command); or endConvBoredom if we're terminating the
conversation on our own because our attentionSpan has been exceeded.
This method can cancel the operation that attempted the termination
simply by returning nil; the method should display an explanation
when returning nil, to let the player know why the command is being
canceled.

<p>In related changes, ConvNode.endConversation() and
ActorState.endConversation() now take 'reason' codes rather than
'explicit' flags.  This gives the methods full details on why the
termination is occurring.

</div>

<!------------------->
<div class=entry>

The new AgendaItem class provides a simple new mechanism for handling
cases where you want to model an NPC in terms of motivation.  Each
actor has an "agenda," which is a list of AgendaItem objects.  On each
turn, the actor's ActorState object (in the takeTurn method) will look
at the agenda list, to see if any items are ready to execute.  If
there's an item that's ready to execute, the ActorState will execute
the first one that's ready.

<p>Each AgendaItem object has a method called isReady, which indicates
whether or not the item is ready to execute.  An actor will only execute
an agenda item once it's ready.  The invokeItem method contains the code
that actually carries out the agenda item's action.

<p>By default, an agenda item is removed from the actor's agenda list
when it's executed.  However, if the item's stayInList property is true,
then the item will not be removed on execution.  This property lets you
handle agenda items which the actor will try repeatedly, until some
other code determines that the goal has been achieved and removes the
item from the actor's agenda.

<p>You must nest AgendaItem objects within their actor, using the "+"
notation.  This associates the AgendaItem objects with the actor, but
it doesn't add them to the actor's agenda list.  You must explicitly
add agenda items to the actor's agenda list by calling the actor's
addToAgenda() method.  Agenda items must be explicitly added because
an actor's motivation typically will change dynamically as the game's
events unfold.

</div>

<!------------------->
<div class=entry>

Autonomous NPC conversation continuation processing has been moved
from InConversationState to the base ActorState.  This allows actors
that don't use greeting protocols to nonetheless use stateful
conversations.

<p>To accommodate this change, the default takeTurn() method in
ActorState now preforms more processing.  If the actor has an active
ConvNode, then this takes precedence over any other default processing
for the actor's takeTurn() method.  If the actor hasn't engaged in
conversation on the same turn, we invoke the ConvNode to continue the
conversation under NPC control; otherwise, we do nothing more.  If
there's no ConvNode, we process the actor's "agenda."  If there's no
ConvNode, and the actor has no agenda items that are ready to execute,
and the ActorState inherits from Script, then we invoke the script.
This structure means that a stateful conversation takes precedence
over everything, and an agenda item takes precedence over state-level
background activity.

</div>

<!------------------->
<div class=entry>

In the Actor class, the TellAbout and AskAbout handlers now include
the "canTalkToObj" precondition by default.  This ensures that the NPC
being addressed can actually hear the other actor, to disallow
conversations in cases such as when the two actors are too far apart
to hear one another.  The HELLO, GOODBYE, YES, and NO commands now all
make the same check as well, in the sayToActor() method.

<p>Similarly, ConversationReadyState now makes the same check before
going through a greeting.  If the initating actor can't talk to the
target actor, the enterConversation() method says so and uses 'exit'
to terminate the command.  This prevents strange situations from
arising commands that don't require the canTalkToObj precondition.
(SHOW TO works this way, because the actors don't necessarily have to
be able to talk to each other to use SHOW TO; we could show a note to
an NPC on the other side of a sound-proof window, for example.)

</div>

<!------------------->
<div class=entry>

The new TopicEntry subclass InitiateTopic provides an easy way of
making an NPC initiate conversation based on simulation objects in the
environment.  To make an NPC trigger a conversation, call the actor's
initiateTopic(obj) method, where 'obj' is the simulation object you
want to use to key the conversation.  This will find an InitiateTopic
object in the actor's topic database matching the given object
('obj'), and show its response text.  One easy way to use this is to
initiate conversation based on the NPC's current location: just create
InitiateTopic objects keyed to those locations where you want the NPC
to say something special, and add a line like this to the ActorState's
takeTurn() method:

<p><pre>
  getActor().initiateTopic(getActor().location);
</pre>

</div>

<!------------------->
<div class=entry>

The "topic inventory" list shown by the TOPICS command is no longer
enclosed in parentheses by default.  The parentheses are still included
when the topic inventory is shown implicitly (by a TALK TO command or
a &lt;.topics&gt; tag, for example).

</div>

<!------------------->
<div class=entry>

The new ConvNode property limitSuggestions allows a ConvNode to
indicate that suggested topics from the broader conversation context
should not be included in a topic inventory listing.  This is useful
for times when the ConvNode won't allow the player to stray from the
subject, such a a ConvNode that only allows a YES or NO answer to a
question.  In these cases, set limitSuggestions to true.  The property
is nil by default, which causes topic inventory listings to include
not only any suggestions defined within the ConvNode, but also any
defined in the active ActorState or in the Actor itself.

</div>

<!------------------->
<div class=entry>

The new Actor.scheduleInitiateConversation(state, node, turns) method
lets the game set up an NPC to start a converation at the next opportunity
after the given number of turns has elapsed.  If 'turns' is zero, then
the conversation can start on the next turn on which the NPC hasn't
been targeted for conversation by the player; if 'turns' is one, the
player will get at least one more turn before the conversation can start,
and so on for higher 'turns' values.  The important thing is that the
conversation can only start on a turn on which the NPC isn't targeted
with a conversational command (ASK, TELL, etc).  The Actor checks its
list of pending conversations on each turn in its takeTurn() method,
before invoking the current state's takeTurn() method.

</div>

<!------------------->
<div class=entry>

In the previous version, if Actor.initiateConversation() was called
from within the player character's turn (in an NPC's beforeAction()
handler responding to a player character action, for example), and
the ConvNode had a "continuation" message (defined in
npcContinuationMsg or npcContinuationList), the first continuation
message was incorrectly shown on the same turn.  This no longer
occurs; the continuation message won't be shown until the next turn
at the earliest.  ("At the earliest," because a continuation message
won't be shown on a given turn if the player character addresses a
conversational command to the NPC on that turn.)

</div>

<!------------------->
<div class=entry>

When an actor continues a conversation of its own volition (using
npcContinueMsg or npcContinueList) in a ConvNode, if the continuation
routine actually displays any text, then the ConvNode will
automatically set the player character and the initiating NPC to be in
conversation with one another.  This ensures that any subsequent
conversational command from the player will have the initiating NPC as
the default interlocutor.

</div>

<!------------------->
<div class=entry>

In the past, the REPLAY QUIET command didn't display any acknowledgment,
and improperly left all subsequent text in bold-face.  This has been
corrected.

</div>

<!------------------->
<div class=entry>

ActorState.greetingsFrom now delegates to a method of the same name
in Actor; this makes it easier to change the default greeting for a
simple actor without a state object.

<p>Along the same lines, ActorState.showGreetingMsg has been removed,
and replaced with Actor.defaultGreetingResponse.  The method has been
moved to Actor because of the change to greetingsFrom, and the method
has been renamed for consistency with the similar pattern for the
other conversation command default message methods (for ASK, TELL,
etc) in Actor.

<p>Along the same lines, ActorState.goodbyeFrom now delegates to a
method of the same name in Actor by default.  A new Actor method,
defaultGoodbyeResponse, displays the default message, for consistency
with the naming of the similar methods for other conversation
commands.

</div>

<!------------------->
<div class=entry>

Two new ConversationReadyState methods have been added:
enterFromByeMsg and enterFromConvMsg.  These are provided for
convenience as single-message complements for enterFromByeList and
enterFromConvList, respectively.  By default, these simply invoke
their respective list scripts.

</div>

<!------------------->
<div class=entry>

VocabObject has a new feature that allows an object's vocabulary to
be divided into "strong" and "weak" tokens.  Weak and strong tokens are
the same as far as the parser is concerned, and are entered into the
dictionary as usual.  The difference is that a weak token can only
be used to refer to an object in combination with one or more strong
tokens.  That is, if the player enters a noun phrase, and the noun
phrase matches all of the vocabulary for a given in-scope object,
the object will match the noun phrase only if one or more of the
words in the noun phrase is a strong token for the object.

<p>The purpose of this new feature is to make it easy to define extra
vocabulary for an object that the parser accepts for an object
without creating any new ambiguity.  This comes up in situations
where you simply want to create additional synonyms for an object, as
well as in cases where an object is most strongly identified in terms
of its relationship to something else.  For example, you might have a
location that contains a couple of doors, one to a house and the
other to a shed.  You could use adjectives ("house door" and "shed
door") to differentiate the doors, but it might be more natural to
use a prepositional phrasing, such as "the door of the house" and
"the door of the shed."  If you also have a house and a shed object,
though, this phrasing would create unwanted ambiguity with those
objects.  This is where weak tokens come in.  If you define "house"
and "shed" as weak tokens for the respective door objects, the parser
will never take those words alone to refer to the doors, so there
will be no ambiguity with the house and shed objects themselves; but
the parser will still allow "house" and "shed" to refer to the doors,
as long as they're used in combination with the strong token "door".

<p>Weak tokens are defined per-object (they're not global).  Each
object that has weak tokens keeps a list of its weak tokens in its
'weakTokens' property.  In the basic VocabObject.matchName()
implementation, the object checks the noun phrase to see if it
consists entirely of weak tokens, and rejects the match if so.

<p>When you define an object, you can define weak tokens in one
of two ways.  If you define 'noun' and 'adjective' (etc.) properties
directly, simply define a 'weakTokens' property containing a list of
strings giving the object's weak tokens.  If you use the
vocabulary initialization string, simply enclose each weak token
in parentheses.  For example:

<p><pre>+ Door 'front door/(house)' 'front door of house'
  "The door is badly weathered. "
;
</pre>

</div>

<!------------------->
<div class=entry>

VocabObject.matchName() and matchNameDisambig() now invoke a new
method, matchNameCommon(), to carry out their common handling.
This change facilitates the weak-token feature mentioned above.
In most cases, when a game needs to override an object's name
matching test, it should override matchNameCommon(), since this
method provides the common handling for normal matching and
disambiguation matching.  Games can still override matchName()
and/or matchNameDisambig() individually, but it's only necessary
to do so when you want to use different rules for normal matching
and disambiguation matching.

</div>

<!------------------->
<div class=entry>

The English parser's handling of quoted string literals as adjectives
has been improved slightly, but the changes will require some small
adjustments to any games currently using literal adjectives.

<p>Instead of allowing any adjective to be quoted, the parser now
only matches quoted strings that are specifically designated as
"literal adjectives" in an object's vocabulary.  To designate an
adjective as a literal adjective, you can either enclose the
adjective in double-quotes in the vocabulary initializer string, or
you can explicitly define the word using the 'literalAdjective'
part-of-speech property instead of the normal 'adjective'
part-of-speech.  For example, you could define an elevator button
for the lobby level like so:

<p><pre>+ Button '"L" button' 'L button' "It's a button labeled &lt;q&gt;L.&lt;/q&gt; ";
</pre>

<p>This change makes the parser stricter about which words it accepts
as quoted adjectives, but it also allows the parser to be more
flexible about requiring the quotes.  In particular, the parser now
accepts all of the following forms for the button defined above: "L"
button, button "L", L button, and button L.  In the past, the parser
was unable to accept the last of these, because without the quotes,
it wasn't able to tell that the unquoted "L" was meant as a literal
adjective.  Now that the "L" is defined in the dictionary as a
literal adjective, it's no longer necessary for the player to quote
the word for the parser to recognize it as a literal adjective, so
the parser is able to accept the form with the literal adjective
following the noun.

<p>Note that this change also involves a subtle change to the special "*"
vocabulary wildcard token.  In the past, if the string '"*"' (that is,
an asterisk enclosed in double-quotes) appeared as an 'adjective'
dictionary entry for an object, then that object matched any quoted
string used as an adjective in player input.  Now, this effect is
obtained by using the string '*' as a 'literalAdjective' dictionary
entry for an object.  This change has no effect at all on the way you
write vocabulary initializer strings, since you still enclose the
asterisk in quotes in that string; however, if you're defining a
'literalAdjective' list directly for an object, you now must drop
the quotes and add a word entry consisting of simply the asterisk.

</div>

<!------------------->
<div class=entry>

The English parser now accepts pronouns as responses to
disambiguation questions.  (The disambigListItem(noun) rule now
matches completeNounPhraseWithoutAll rather than qualifiedNounPhrase,
as it did in the past; the new sub-production matches pronouns, which
qualifiedNounPhrase does not.)

</div>

<!------------------->
<div class=entry>

In the English parser rules, the command "T <i>topic</i>" is now
accepted as a short-cut for "TELL ABOUT <i>topic</i>."  Together with
the "A <i>topic</i>" shortcut for ASK ABOUT, this can greatly reduce
the amount of typing a player has to do in a game that has a lot of
ASK/TELL character interaction.

</div>

<!------------------->
<div class=entry>

In the English parser rules, the Hello action now accepts "hallo"
as equivalent to "hello" or "hi", and also accepts "say" with any
of these variations.

</div>

<!------------------->
<div class=entry>

A new Action method, callAfterActionMain(obj), allows a game to register
an object for invocation at the end of the current action.  This is
only meanginful when used on the current gAction object, since it
registers for notification of completion of the current action.
When the current action is finished - including the iteration over
all of the objects involved in the action - the action invokes
the afterActionMain() method of each registered object.

<p>This new method is especially useful for adding a "summary" of an
action that involves multiple objects.  Each individual object's
action handler (an action() method in a dobjFor() block, for example)
can register a handler object to receive notification when the
overall command is finished.  A given object can be registered only
once - redundant registrations are simply ignored - so each
individual iterated object doesn't have to worry about whether or not
other iterated objects will register the same handler.  Then, at the
end of the action, the handler will be invoked; it can determine what
happened in the action, and do something based on the end result.
For example, the handler could scan the transcript (gTranscript) for
certain types of reports, and add a summary message based on the
reports, or could even replace some of the individual reports with a
summary.  The handler could also take addition action based on the
overall end results; for example, in a GIVE TO command, a handler
could look at the full set of objects successfully given, and decide
that the combination is sufficient to allow the recipient to give the
donor something in return.

</div>

<!------------------->
<div class=entry>

A new CommandTranscript method, summarizeAction(), can be used with
the new callAfterActionMain() system to generate a summary of an
action that involves multiple objects.  summarizeAction() scans
through the transcript, looking for runs of two or more reports for
the current action that match criteria specified by the caller (via a
callback function).  For each run of two or more consecutive
qualifying reports, the method removes those reports, along with their
corresponding multi-object announcements, and replaces the last of the
reports with a single "summary" report generated by the caller (via
another callback function).  This method lets you turn a transcript
like this:

<p><pre>   gold coin: Bob accepts the gold coin.
   gold coin: Bob accepts the gold coin.
   gold coin: Bob accepts the gold coin.
</pre>

<p>into something like this:

<p><pre>   Bob accepts the three gold coins.
</pre>

<p>This sort of summary isn't straightforward to generate in general,
and the library makes no attempt to apply it generically.  In specific
cases where you can control the range of possible results, though,
this can be a powerful way to improve the game's output by describing
an iterated action as though it were a single logical unit.

</div>

<!------------------->
<div class=entry>

Phrases involving quantities ("five coins") and "all" with a plural
("all coins") are now resolved a little more consistently and
intuitively, from a player's perspective.  First, phrases involving
quantities are now always disambiguated in the same manner as
singular phrases, and then the required number of objects is chosen;
in the past, disambiguation filtering was not as consistent.  This
change ensures in particular that "collectives" are properly filtered
in or out; the old mechanism sometimes missed collectives because it
sometimes skipped the normal disambiguation filtering.  Second,
"all"-plus-plural phrases are now resolved to all matching objects,
rather than to only the most logical subset of matching objects, as
was the case in the past.  This means that a command applied to "all
coins" really is applied to all coins that are present, even those
for which the action isn't currently valid.

<p>To implement these changes, NounPhraseProd has a new method,
getVerifyKeepers(), that the disambiguation filtering methods call to
reduce the list.  The default NounPhraseProd definition of the method
does the traditional filtering that the disambiguation filter did,
which keeps just the most logical subset of the results.
AllPluralProd overrides this method to keep everything in the list,
and QuantifiedPluralProd overrides the method to select a subset with
the desired number of entries.

</div>

<!------------------->
<div class=entry>

<p>The CollectiveGroup object by default no longer matches a noun
phrase that specifies a quantity ("take five coins" or "take both
coins"; or any singular phrase, since a singular phrase specifies a
quantity of one).  Collective groups are designed to stand in for
a completely collection of in-scope individuals, not for arbitrary
subsets of the individuals, so when a quantity is specified we must
fall back on iterating over a selected subset of the individuals.

<p>To implement this change, the filterResolveList() method now takes
two additional parameters: one giving the quantity specified in the
noun phrase, if any, and another giving the role played by the object
(DirectObject, IndirectObject, etc).  When the noun phrase specifies
a quantity, the new parameter will be set to an integer giving the
quantity specified.  If the noun phrase is unspecific about the
quantity (as in "take coins" or "get all coins"), then the quantity
parameter will be nil.

<p>Note that the isCollectiveAction() method now takes an additional
parameter as well, giving the role in the action played by the object
being resolved (DirectObject, IndirectObject, etc).  This allows
differentiating the handling based on both the action and the role
played in the action.

<p>Custom CollectiveGroup objects <i>can</i> represent specific
quantities of objects, from the player's perspective, if desired.  For
example, a game might want to create a CollectiveGroup that represents
a quantity of money, rather than dealing with the individual coins
making up the quantity.  To do this, the CollectiveGroup object must
override the filterResolveList() method, and must set the "quant_"
element of its own ResolveInfo entry to an integer giving the number
of <i>grammatical</i> objects it represents.  The CollectiveGroup must
keep track of what it's representing somehow; the best way to do this
is to create a new instance of the CollectiveGroup itself, and store a
property in the new instance giving the quantity represented by the
collective.  Note that using CollectiveGroup objects in this manner
is tricky; you'll need to code action handlers for the custom
CollectiveGroup object so that they correctly take into the account
the quantity represented by the group object.

</div>

<!------------------->
<div class=entry>

The ownershipAndLocationDistinguisher has been refactored into two
separate distinguishers: ownershipDistinguisher and locationDistinguisher.
Each of these new distinguishers is very similar to the old combined
distinguisher, but the ownershipDistinguisher gives priority to
ownership, regardless of the containment relationship.  The library
classes that define distinguishers now use both of these, with
the ownership distinguisher applied first.

<p>The purpose of this change is to ensure that ownership will be
used as a distinguishing feature whenever possible, before the parser
falls back on location.  The old combined distinguisher could only
use ownership in the limited case where the owner and immediate
location were the same, because it couldn't otherwise be sure that it
would be able to distinguish multiple objects with the same owner but
different locations.  By separating the ownership and location
distinguishers, we first try to identify objects purely by ownership;
when this fails, we fall back on the old approach of identifying by
immediate location in preference to owner.

<p>To support this change, the English methods for owner-or-location
names (aNameOwnerLoc, theNameOwnerLoc, countNameOwnerLoc) now take
a parameter indicating whether to use ownership or location as the
first priority in generating the name.  When ownership takes priority,
these methods will show the name with a possessive form of the owner
regardless of the containment relationship between the object and its
owner.

</div>

<!------------------->
<div class=entry>

Possessive qualifiers (such as "bob's" in "bob's chair") are now
resolved in a special resolution context that allows referring to
owners that aren't in scope for the purposes of the phrase being
qualified (such as the "chair" in "bob's chair").  A possessive
phrase is now considered in scope if it's in scope for the phrase
being qualified <b>or</b> it's known to the actor performing the
command.  This allows possessive phrases to be used to refer to
objects that are present, and which are known to belong to an
actor, even if the actor itself isn't present.

</div>

<!------------------->
<div class=entry>

When the parser generates a disambiguation prompt, and the prompt
distinguishes objects by possessives ("which match: bob's match or
your match?"), the parser automatically sets the pronoun antecedents
for "him" and/or "her" to the people mentioned in the prompt.  This
allows the player to answer with "his" or "hers" (or "his match"),
referring back to the person or people mentioned in the message.

</div>

<!------------------->
<div class=entry>

The parser error messages that display literal text entered by the
player (such as the message for unrecognized punctuation marks, and
the message for unknown words) now HTML-ify the user's text.  This
ensures that any markup-significant characters (such as "&lt;" and
"&amp;") are converted into HTML sequences that display the
corresponding characters.

</div>

<!------------------->
<div class=entry>

A bug in the English parser's rule for phrases like "anything in the box"
caused run-time errors when the word "anything" alone was used as a noun
phrase.  This has been fixed.

</div>

<!------------------->
<div class=entry>

In the hint system, the new Goal methods openWhenTrue and closeWhenTrue
can be used to define arbitrary conditions that open and close the goal.
These new general-purpose conditions supplement the more specific
conditions (openWhenSeen, openWhenAchieved, etc.); the goal will be
opened if <i>any</i> of the openWhenXxx conditions are met, and will
be closed when any of the closeWhenXxx conditions are met.

<p>The new Goal property openWhenDescribed lets you specify that the goal
should be opened when the referenced object is described (usually with
EXAMINE).  This is good for goals where the existence of a puzzle isn't
made apparent until the full description of an object is viewed.  The
new property closeWhenDescribed correspondingly closes the goal when
the referenced object is described.

</div>

<!------------------->
<div class=entry>

The RESTART command no longer resets the commandSequencer to the
"no-command" state, as it did in the past.  This change corresponds to
the change in commandSequencer start-up state effected in 3.0.6i.

</div>

<!------------------->
<div class=entry>

The English grammar now accepts '1' as a synonym for 'one' or 'any' in
singular indefinite noun phrases, such as "take 1 coin."  (In the
past, the grammar omitted this alternative.)

</div>

<!------------------->
<div class=entry>

The new class SecretFixture is designed for objects that are needed in
the internal implementation but are not meant to be manipulated
directly by characters.  This is a simple subclass of Fixture; the
main difference is that a SecretFixture is hidden from "all," to help
prevent direct references to it in commands.

</div>

<!------------------->
<div class=entry>

In the English grammar, a new production named singleNounOnly can be used
where a single noun (rather than a list of nouns) is <i>structurally</i>
required.  The singleNoun production itself will structurally match a
list of nouns, but considers such matches semantically invalid.  In
contrast, singleNounOnly won't even structurally match a noun list.

<p>The firstCommandPhrase(withActor) rule now uses the new singleNounOnly
production to match the actor phrase.  This eliminates the structural
ambiguity of certain types of invalid input that were able to cause
unbounded memory consumption with the old rule.

</div>

<!------------------->
<div class=entry>

The menu system no longer shows a border in full-screen menu windows.
(When a menu takes up the whole game window, a border is superfluous,
since there's no other window requiring separation.  Removing the
border slightly but noticeably improves the appearance of a full-screen
menu.)

</div>

<!------------------->
<div class=entry>

The Decoration class now gives Examine commands a reduced "logical
rank" (of 70) for disambiguation purposes.  This means that if the
player enters an Examine command, and the vocabulary for the direct
object matches a Decoration object and a non-Decoration object, the
non-Decoration object will be chosen ahead of the Decoration.  It's
usually desirable to treat Decoration objects as second-class citizens
for disambiguation purposes, because they're usually meant to stay in
the background as much as possible.

</div>

<!------------------->
<div class=entry>

The standard Actor handlers for the Give and Show actions now produce
more sensible messages for giving or showing something to oneself.
(The old message was the generic "you do not respond"; the new message
is "Giving [or showing] that to yourself won't accomplish anything.")

</div>

<!------------------->
<div class=entry>

The base definition of the method filterResolveList() has been moved
from Thing to VocabObject.  The parser calls this method on objects
that match vocabulary in player input, so it more properly pertains to
VocabObject than to Thing.  (In practice, this is important in some
cases when Topic objects match player input, because Topic objects
descend from VocabObject but not from Thing.)

</div>

<!------------------->
<div class=entry>

The cached scope list in Resolver and its subclasses is now better
encapsulated, to make it easier to subclass Resolver.  In particular,
the "scope_" member is referenced only in the method cacheScopeList(),
objInScope(), and the new method getScopeList().  This means that a
subclass can dispense entirely with the cached scope list (and the
"scope_" member), as long as the subclass implements objInScope() and
getScopeList() to return mutually consistent results.  A subclass
can alternatively override cacheScopeList() to use a different set
of rules to obtain and cache the scope list.

<p>Along similar lines, TAction.initResolver() now calls
cacheScopeList() to initialize its cached scope list, rather than
doing so directly.  This allows TAction subclasses to customize the
scope rules in exactly the same way that subclasses of Resolver can
customize scope.  Likewise, TopicResolver.filterAmbiguousNounPhrase()
now calls objInScope() rather than accessing the "scope_" list
directly.

</div>

<!------------------->
<div class=entry>

The new Achievement method addToScoreOnce() makes it a little easier
to do score book-keeping in the common case of achievements that are
scorable only once.  This method adds the achievement to the score,
with a given number of points, but only if the achievement has never
been scored before; if the achievement has been scored before, the
method does nothing at all.  This makes it unnecessary to keep track
of any separate status to avoid scoring the same action more than
once.  (Some achievements are meant to be repeatable; this method
wouldn't be useful in such cases, obviously.)

</div>

<!------------------->
<div class=entry>

The complexMultiTransform report transformer is now a little more
liberal in determining when to add visual separation between reports
when an action is iterated over multiple objects.  In the past, visual
separation (i.e., a paragraph break) was added only when implicit
command announcements were present.  Now, visual separation will be
added any time the report group for an individual object in the
iteration consists of more than one report, or a report has a single
message with text over 60 characters in length.  This new, more
liberal policy is designed to add visual separation essentially any
time an individual object's result message is non-trivial, since
multi-object messages become hard to read when they're all jammed
together, unless each individual message is very short.  The new
policy errs on the side of adding too much visual separation, which on
balance seems to do considerably less harm to readability than too
little separation.

</div>

<!------------------->
<div class=entry>

The handling of OOPS responses has been improved slightly.  In
particular, when the player uses an OOPS command to correct an error,
the new text that results from applying the OOPS substitution is now
run through the normal pre-parsing sequence.

<p>In the past, an OOPS command itself was run through the normal
pre-parsing steps, but the new command resulting from applying the
OOPS replacement text was <i>not</i> pre-parsed.  This resulted in
incorrect behavior in certain certain rare cases.  One noticeable
example was when a SpecialTopic was active.  Because SpecialTopics
rely on pre-parsing to match their special command templates, and
because the corrected text after the OOPS wasn't pre-parsed, it was
effectively impossible to use OOPS to correct a typo in a command
intended to match a SpecialTopic.  The new OOPS handling ensures that
pre-parsing is run as normal on the new command resulting from
applying an OOPS correction.

</div>

<!------------------->
<div class=entry>

When the player enters a command that matches an active SpecialTopic,
the library now treats this as a conversational action directed to the
interlocutor, as though the player had typed an ASK or TELL command.
This is important in cases where the actor has background actions that
it performs based on the absence of an explicit conversational
interaction from the player on any given turn, such as showing
ConvNode continuation messages.

</div>

<!------------------->
<div class=entry>

ASK FOR commands are now handled uniformly with other conversational
commands (ASK ABOUT, TELL ABOUT, GIVE TO, etc).  In particular, these
commands are now routed to the ActorState for handling, and can be
handled using the new AskForTopic class, which works along the same
lines as GiveToTopic and ShowToTopic.

</div>

<!------------------->
<div class=entry>

The library now automatically sets the antecedent for the appropriate
pronouns to refer to a responding actor, any time a TopicEntry is used
to generate response text.  This ensures that the player can use a
pronoun on the next command to refer to the last actor who generated a
conversational message.

</div>

<!------------------->
<div class=entry>

The new method Actor.setPronounObj(obj) makes it easier to set a
simulation object as the pronoun antecedent for commands targeting the
given actor.  (In the past, only the setPronoun() method was
available, which took a list of ResolveInfo objects.  When the game or
the library needs to set the pronoun directly, it's often easier to
set it directly in terms of simulation objects, without creating a
ResolveInfo list.)

</div>

<!------------------->
<div class=entry>

The new classes SimpleNoise and SimpleOdor make it easier to define
Noise and Odor objects for the common case that a noise/odor is just
a background part of the room description that (1) doesn't require
ongoing "daemon" announcements, and (2) doesn't need any
differentiation among the different types of descriptive messages.
These classes simply use the "desc" property as the default for all
of the descriptive messages, and are marked as "ambient," to avoid
automatic inclusion in the room description.

</div>

<!------------------->
<div class=entry>

The Throw command now works properly when throwing something at
oneself.  (In the past, throwing something at oneself incorrectly
tried to treat the actor as the drop location of the throw; it now
correctly treats the actor's location as the drop location.)

</div>

<!------------------->
<div class=entry>

The new NOTE verb accepts an arbitrary literal as its object; the
command doesn't do anything except acknowledge the input.  The purpose
of the command is to allow the player to enter arbitrary notes into
the session transcript as she plays the game.  Players might want to
make such notes for their own later reference, but this command is
especially useful for play-testing, because it gives play-testers
a very easy way of pointing out bugs or making comments directly in
the session transcript where they apply, and at the moment they occur
to the player.

</div>

<!------------------->
<div class=entry>

A library bug caused a run-time error if an attempt was made to remap
from a direct object handler (a dobjFor) to an intransitive action
(an action with no objects).  Remapping to intransitive actions will
now work properly.

</div>

<!------------------->
<div class=entry>

The RealTimeDaemon class had a couple of problems that prevented it
from working properly.  For one thing, it wasn't based on RealTimeEvent
as it should have been; for another, it didn't reset its next firing
time when fired.  These problems have been corrected.

</div>

<!------------------------------- 3.0.6i --------------------------------->
<div class="sepbar"><a name='306i'></a>3.0.6i</div>
<p><b><i>Released June 15, 2003</i></b>
<p>

<div class=firstentry>

The commandSequencer now starts in "before-command" mode, rather than
in "no-command" mode.  This allows any introductory text displayed
before the first command to use the normal command sequencing tags.

</div>

<!------------------->
<div class=entry>

The "seen" property of Thing has been changed slightly in meaning.  In
the past, this property was set to true only when an object was
specifically listed as a portable item in a room description.  Now,
the property is set to true whenever a room description is displayed
from the player character's perspective, and the object is visible to
the player character.  The important difference is that
<b>unlisted</b> items, such as 'Fixture' and 'Heavy' items, or items
with special descriptions, will be marked as seen as soon as their
containing rooms are described.

</div>

<!------------------->
<div class=entry>

Due to a bug in the previous version, the REPLAY command only worked
when one of its qualifiers (REPLAY QUIET or REPLAY NONSTOP) was used;
just plain REPLAY didn't work.  The plain REPLAY command now works
correctly.

</div>

<!------------------->
<div class=entry>

The gameinfo.t module has been removed from the base system library.
In its place, the GameID class has been extended to write the GameInfo
data file automatically during pre-initialization.  If the game defines
a GameID object, then the library automatically writes a gameinfo.txt
file, using values from the GameID object.  Refer to the comments
in modid.t for the GameID class.

</div>

<!------------------->
<div class=entry>

Actor.setConvNode() now accepts a string giving the name of a
ConvNode, as an alternative to a reference to a ConvNode object.  In
the past, only the object reference was accepted.  Passing in a
string naming a ConvNode now has the same effect as passing a
reference to the ConvNode itself.

</div>

<!------------------->
<div class=entry>

The new Actor method initiateConversation() makes it easier to code
an NPC initiating a conversation.  This method takes an ActorState
object to use as the NPC's new state, and a ConvNode (which can be
specified by the string name of the ConvNode) to use as the initial
conversation node.

<p>In addition, the new ConvNode method npcGreetingMsg is defined to
display the initial conversational exchange in an NPC-initiated
conversation.  Any ConvNode used in an initiateConversation() call
must either override npcGreetingMsg to define a greeting message, or
define an npcGreetingList property as a TextList containing a list
of greeting messages.

</div>

<!------------------->
<div class=entry>

The new ConvNode method npcContinueMsg is defined to display a
conversational "continuation" message from the actor.  This method
lets the NPC continue a conversation of its own volition if the player
character doesn't do so.  This method is invoked on each turn when the
ConvNode is active, <i>and</i> the player didn't enter a
conversational command on that turn.  The method is invoked during the
actor's takeTurn() daemon processing.  To define a continuation
message, you can either define npcContinueMsg as a double-quoted
string with the message, or you can define npcContinueList to a
TextList subclass containing a list of continuation messages.

<p>If you don't override npcContinueMsg or npcContinueList, there will
be no NPC-initiated continuation message.  If you do provide a
continuation message, then the ConvNode stays active by default.  You
can use the &lt;.convnode&gt; tag within the continuation message's
text to switch to a new ConvNode, just as in a topic response message.

</div>

<!------------------->
<div class=entry>

The commandSequencer now starts in "before-command" mode, rather than
in "no-command" mode.  This allows any introductory text displayed
before the first command to use the normal command sequencing tags.

</div>

<!------------------->
<div class=entry>

The Yes and No topic classes (YesTopic, NoTopic, YesNoTopic) had a
number of bugs that prevented them from working properly.  These
classes should now work correctly.

</div>

<!------------------->
<div class=entry>

A new template for DefaultTopic makes it easier to define these
objects.  The DefaultTopic template accepts simply a response string
(double-quoted), or a list of response strings (single-quoted).

</div>

<!------------------->
<div class=entry>

A bug in the AltTopic mechanism prevented intermediate AltTopics in
nestings more than one level deep from being properly selected.  This
is now fixed.

</div>

<!------------------->
<div class=entry>

In the English-language module, the miscWord production now accepts
'#'-prefaced numbers and quoted strings.  This provides more
flexibility for inputs in things like topic phrases.

</div>

<!------------------->
<div class=entry>

The AccompanyingState class didn't use the correct test for a travel
action in its beforeAction() method, which prevented the class from
carrying out its accompanying travel role at all.  This has been
corrected.

</div>

<!------------------->
<div class=entry>

ActorState.obeyCommand() generated the wrong default message.  This
is now fixed.

</div>

<!------------------->
<div class=entry>

ConvNode had a couple of problems that caused run-time errors or other
strange behavior when activating a ConvNode that had no associated
SpecialTopics.  These have been fixed.

</div>

<!------------------->
<div class=entry>

Fuses and daemons (including real-time events and prompt daemons) now
run automatically in a standard Action environment.  This means that
you can call essentially any library code without having to worry
about whether or not it will need to access gAction or gTranscript.
In the past, fuse and daemon code was called with no Action
environment in effect, which made it necessary to either limit the
library calls made within the fuse or daemon, or to explicitly set up
an action environment (using withActionEnv(), for example) before
invoking library code.  This added a lot of unnecessary complexity
to fuse/daemon code.  Now that these routines are always invoked with
a valid Action environment, these restrictions have been lifted.

</div>

<!------------------->
<div class=entry>

The withActionEnv() method now takes an additional argument, giving the
specific Action class to use for the dummy action object in effect during
the callback.

</div>

<!------------------->
<div class=entry>

The senseContext object's pushSenseContext() and popSenseContext() have
been removed; they've been replaced with a new withSenseContext() method.

<p>In addition, the callWithSenseContext() function has been changed
to eliminate the argument list parameter; instead, callers should use
anonymous functions when the code to be invoked requires arguments.
(This is the way the rest of the library already used the function in
most cases anyway, so this change simply cleans up some old code
that's no longer needed.  Most games won't need to call this function
directly, so this is unlikely to affect any existing game code.)

</div>

<!------------------->
<div class=entry>

The INSTRUCTIONS command now operates either in menu or in-line mode,
not both.  In the past, the menu format supplemented the in-line format,
but this was redundant and complicated the user interface.

</div>

<!------------------------------- 3.0.6h --------------------------------->
<div class="sepbar"><a name='306h'></a>3.0.6h</div>
<p><b><i>Released June 7, 2003</i></b>
<p>

<div class=firstentry>

Several major enhancements to the Actor class have been added.
These changes are described in more detail in the comments in the
library sources files, and in a new series of technical articles on
the <a href='http://www.tads.org'>tads.org</a> web site, <a
href='http://www.tads.org/howto/t3actor.htm'>Creating Dynamic
Characters in TADS 3</a>.  We'll summarize the changes here, but you
should refer to the articles for full details.

<p><b>WARNING!  Due to the extensive scope of these new features,
there's a good chance that they'll undergo some changes as we gain
experience with them.  Be aware that game code that uses these features
might have to be changed to accommodate library changes in future updates.
</b>

<p>A new class, ActorState, makes it easier to create characters that
exhibit multiple behaviors.  The Actor class has been changed to work
with ActorState; most of the methods involved in describing an actor's
physical state and in interacting with an actor are now delegated from
the Actor class to the ActorState object.  The idea is that most of
the parts of an actor that need to vary according to the actor's
behavior have been moved to the new ActorState object; this means that
adding a new behavior to an actor is a matter of defining a new
ActorState object for the actor.

<p>Several subclasses of ActorState have also been created.  These
include ConversationReadyState and InConversationState, which are used
to make an actor explicitly enter, maintain, and exit a conversation;
HermitActorState, for times when an actor is unresponsive; and
AccompanyingState and AccompanyingInTravelState, which allow an NPC to
travel with another character as part of the character's own turns.

<p>A new "topic database" system makes it easier to manage
conversational interactions, by creating individual objects that
represent responses to ASK, TELL, GIVE, SHOW, and other interactions.
The TopicDatabase class is used to store an actor's responses; Actor
and ActorState inherit from TopicDatabase, so you don't normally
create instances of this class directly.  The TopicEntry class
represents a response; several subclasses, including AltTopic,
AskTopic, TellTopic, AskTellTopic, GiveTopic, ShowTopic,
GiveShowTopic, YesTopic, NoTopic, DefaultTopic, and SpecialTopic are
used to create the individual responses.

<p>The conversationManager object and the ConvNode class are used
to manage "threaded" conversations.  A threaded conversation is one
where an actor keeps track of what has been said before, and responds
according to the context of the conversation.

<p>The SuggestedTopic class and its subclasses let you maintain a
"topic inventory," which is a mechanism that automatically suggests
topics to the player.  This is an optional mechanism that you can
use in various ways; you can use it as a sort of hint system, and
you can use it to guide threaded conversations.

</div>

<!------------------->
<div class=entry>

Two library modules have been renamed: 'hints.t' is now 'hintsys.t',
and 'menus.t' is now 'menusys.t'.  Since these modules are included in
most projects using the library file (adv3.tl), this shouldn't require
any changes to any game code or project makefiles.  The new names
better reflect that these modules define the hint and menu systems,
respectively, rather than actual hints or menus.

</div>

<!------------------->
<div class=entry>

A new function, withActionEnv(func), makes it possible for daemon
code to create a simulated Action environment.  Some code relies upon
there being a current Action object and an active command transcript
object; these objects are normally only available while executing a
command, which made it difficult to call code that depends on this
command environment from within a daemon.  This new function makes it
easy to call such code from within daemons and other non-command
contexts.  The function sets up a dummy Action object and a default
command transcript, then invokes the given function; the function can
do anything that can be done during normal Action processing.

</div>

<!------------------->
<div class=entry>

Openable now shows any special descriptions of the contents of an
object that are revealed when the object is opened (via an OPEN
command).

</div>

<!------------------->
<div class=entry>

The English module now includes some needed customizations to the
TopicAction class.  These were missing in the past, which caused
incorrect messages to be generated in some cases involving this
type of action.

</div>

<!------------------->
<div class=entry>

The new class RoomAutoConnector is a subclass of RoomConnector that
can be mixed in to any BasicLocation subclass to make the room usable
directly as a connector to itself.  Room inherits from this class (it
formerly inherited from RoomConnector and overrode part of the
interface; the overrides are no longer necessary because they're
contained in RoomAutoConnector itself now).  In particular,
RoomAutoConnector can be mixed in to any NestedRoom object's
superclasses to make the nested room usable as a connector to itself.

</div>

<!------------------->
<div class=entry>

The new notification methods beforeTravel(traveler, connector) and
afterTravel(traveler, connector) are invoked just before and after a
traveler travels via travelerTravelTo().  These notifications are sent
to each object connected by containment to the traveler;
beforeTravel() is called on each object connected by containment to
the traveler in its old location, and afterTravel() is called on each
object connected by containment in the new location.

<p>These notifications are more precise than using beforeAction() and
afterAction() with the TravelVia pseudo-action, because these actions
are only called when travel is actually occurring.  TravelVia will
fire notifications even when travel isn't actually possible.

<p>A beforeTravel() method can veto the travel action using "exit".
The notification is invoked before the travel is actually performed,
and even before a description of the departure is produced.

</div>

<!------------------->
<div class=entry>

<p>The method Actor.trackFollowInfo() is now invoked from
Actor.beforeTravel() rather than directly from
traveler.travelerTravelTo(), as it was in the past.  This change
makes the follow-tracking a lot less "special," in that it uses the
general before/after travel notification system rather than a
separate, purpose-built notification system.  Note that this change
means that any actor object that overrides beforeTravel() must
inherit the base class implementation if the actor wants to be able
to follow other actors.

</div>

<!------------------->
<div class=entry>

The default travel precondition calculations have been changed
slightly to allow connections between top-level rooms to be placed
inside nested rooms.  This allows, for example, a window that can
only be reached when standing on a desk, or a secret passage from
inside a wardrobe.  The main changes are that TravelVia doesn't
automatically require the traveler to be in the outermost room, but
in the room containing the outbound connector; and travel between
top-level rooms that leaves the traveler inside a nested room (as
would happen when climbing through the window from outside and ending
up on the shelf) now provides a normal arrival message.

<p>First, BasicLocation.roomTravelPreCond() no longer does anything;
the method is still present so that rooms can override it as desired,
but it doesn't do anything by default.  In the past, this method
unconditionally added a precondition requiring that the traveler be
in the outermost room; we don't want to apply that condition, since
the required starting location of the traveler depends on the
outbound connector, not the room.

<p>Second, TravelConnector.connectorTravelPreCond() now adds a
requirement that the traveler be in the connector's location, if the
connector has a location.  This ends up having the same effect as
BasicLocation.roomTravelPreCond() in cases where explicit connectors,
such as doors and passages, are situated in the top-level room.

<p>Third, RoomAutoConnector.connectorTravelPreCond() overrides the
inherited version, and instead requires that the traveler be in the
"appropriate" starting location.  This provides the same effect as
the old BasicLocation.roomTravelPreCond(), but with an enhancement.
The "appropriate" location is defined as the nearest enclosing
location (enclosing the traveler) that has a directional connection
("north = xxx", etc) leading to the room.  In most cases, rooms are
connected directly to one another only at the top level; in such
cases, the directional connection will be found in the traveler's
outermost room, so the effect will be exactly as it was with the old
system.  But here's the enhancement: in cases where the directional
connector is defined leading out of a nested room, this will
correctly find the nested room as the starting location.

<p>Note that NestedRoom objects <b>cannot</b> by default be used as
direct targets of directional connectors, because they're not based
on RoomConnector.  It seems highly unlikely that it would ever be
useful to connect a nested room directly to a directional connector
(i.e., "east = wardrobe") - some kind of explicit connector (a door,
or a passage, or something) seems desirable in almost every case,
just from the perspective of game geography.  In the event that a
direct directional connector is required, though, simply include
RoomAutoConnector in the superclass list for your specific nested
room.

<p>Fourth, the methods travelerArriving() and travelerLeaving() have
been moved from Room to BasicLocation.  This produces the proper
travel messages for any travel between top-level locations, even when
the travel starts or ends in a nested location.

</div>

<!------------------->
<div class=entry>

BasicLocation.travelerArriving() now enforces the defaultPosture
setting for the location.  The default posture is enforced via a
nested command before the arrival message is displayed.  This makes
it easier to create locations with restrictions on posture, such as a
low crawl where you can only sit or lie down.

<p>Note that if all goes well, there won't be any mention of the
action for the player character (because the successful nested action
will result in a default report, which will be suppressed due to the
non-default message for the room description); so the new posture
will simply be reflected in the description of the new location.
Generally, all should always go well in these cases, since the actor
will already be located within the location and merely has to change
posture.  If you want to explain why the posture change is necessary,
you can override travelerArriving() for the location, display an
explanation, then inherit the default.  An appropriate message would
be something like "The ceiling is so low you have to lie down."

</div>

<!------------------->
<div class=entry>

The semantics of TravelConnector.getDestination() have been changed
slightly.  First, the method now takes a traveler rather than an
actor, since connectors are always traversed by travelers.  (A
traveler might in fact turn out to be an actor, of course, but it
could also be something else, such as a vehicle.)  Second, the method
is now required to return the destination, and the destination must be
stable for the duration of the turn up to the point where the travel
actually occurs.

<p>To allow for connectors that are affected by traversal (for
example, a connector that randomizes its destination each time it's
used), the new method noteTraversal() must be called whenever the
connector is actually traversed.  This method can change the connector
state as needed for the traversal.  Note that game code should
generally never need to call noteTraversal(), as the library
dobjFor(TravelVia) action implementations do this automatically as
needed.  This method is provided for games to override as needed.

</div>

<!------------------->
<div class=entry>

The base TAction and TIAction classes no longer require that any of
the target objects of the command define an action() method for the
verb.  Instead, the classes now merely require that at least one of
the target objects defines any of action(), check(), or verify().  If
none of the target objects defines any of these methods for the verb,
then the verb will automatically add an "illogical" status during the
verify phase.

<p>The purpose of this check is to ensure that the command has
<i>some</i> sort of handling.  If the game adds a new verb, but never
defines any handling at all for the new verb for some object, then
without this check, there would be no handling at all if the player
attempted to apply the verb to that object.  The old check tested for
the existence of an action() handler, but this was overly
conservative, since an object could have fully handled the verb in its
verify() or check() handler.  The new test allows for this by allowing
the action to proceed if any sort of handler (check, verify, or
action) is defined for an object involved in the command.

</div>

<!------------------->
<div class=entry>

A new property, globalParamName, has been added to Thing.  This lets
you define a substitution parameter string (for "{xxx}" sequences)
that can be used at any time to refer to the object in message text.
Once you define an object as having a global parameter name, you can
use that name to refer to the object in {xxx} sequences, even when no
command is active, and even when the object isn't involved in any
command.  This can be especially useful for writing messages that
refer to objects whose names change in the course of the game, such as
actors who are known by one name until introduced, then are known by
another name ("the white-haired man" might become "Bob" after he tells
us his name, for example).

</div>

<!------------------->
<div class=entry>

A new Script subclass, EventList, provides a convenient way of
defining scripts using procedural code in steps without writing a big
'switch' statement in the doScript() method.  The eventList property
contains a list of script step elements.  Each element gives one step
of the script.  An element can be a single-quoted string, in which
case the string is simply displayed; a function pointer, in which case
the function is invoked with no arguments; a ScriptEvent object, in
which case the object's doEvent() method is invoked; or nil, in which
case nothing happens on the step.

</div>

<!------------------->
<div class=entry>

The Actor method getDefaultInterlocutor() has been renamed to
getCurrentInterlocutor(), to better reflect its purpose.  The
conversation model keeps track of the actor we're currently talking
to; conversational commands that aren't directed to a specific actor
(such as ASK ABOUT BOOK) are assumed to be directed to the current
conversational partner.

</div>

<!------------------->
<div class=entry>

A couple of the abstract base classes in the area of Container have
been renamed to better reflect their purposes.  The class formerly
known as BasicContainer is now called BulkLimiter, and the class
formerly known as Encloser is now called BasicContainer.  So, Container
is a BasicContainer, which is a BulkLimiter; Surface is also a
BulkLimiter.  The new name BulkLimiter is more consistent with its
main purpose, which is to constrain the aggregate bulk of its
contents.  The old name "Encloser" was confusingly similar to the
real word "Enclosure," and was vague in conveying how the class
differs from Container; the new name BasicContainer makes it clearer
that this class contains some of the basic abstract functionality
of Container but

</div>

<!------------------->
<div class=entry>

The actor inventory listing mechanism has been reworked to make it a
smarter about the listing format.  When the inventory list is short,
the listing will appear in a single sentence showing both the items
being carried and the items being worn.  When the listing is long,
it's broken up into two sentences, as in the past.  The threshhold for
"long" is set with a property of the new DividedInventoryLister class,
singleSentenceMaxNouns; the default is 7, which means that the listing
will be shown in one sentence if it involves seven items of fewer, two
sentences otherwise.  For example:

<p>
<pre>
  &gt;inventory
  You are carrying a music box, a gold coin, and thirty silver coins,
  and you're wearing a watch and a helmet.

  &gt;inventory
  You are carrying a cardboard box (which contains several LP's, a
  bunch of photographs, and some letters), a rubber chicken, two
  pieces of the Magic Goblet of Forblotsk, and a bowl of chowder.
  You're wearing a pair of flippers, a wool jacket, and a red wig.
</pre>

<p>The list length is determined by capturing the output and counting
the phrase separators.  The English library counts commas, semicolons,
the word "and", and right parentheses to determine the phrase count.

<p>This change slightly affects the Actor class (showInventoryWith now
takes only one lister object), and extensively affects the
InventoryLister class and the WearingLister class and their subclasses
(the English-specific implementations in msg_neu.t).  Games shouldn't
be affected unless they modified these classes.

<p>If you want the old behavior, where the items being worn and the
items being carried were always shown as separate sentences, simply
set DividedInventoryLister.singleSentenceMaxNouns to zero.  If you
want to always use a single sentence no matter what, set the property
to some absurdly high number - 30000, say.

<p>If you'd prefer the more traditional behavior that shows the items
being worn marked "(being worn)" and mixed in with the rest of the
inventory in a single listing, simply change Actor.inventoryLister
to refer to actorSingleInventoryLister.

</div>

<!------------------->
<div class=entry>

The match list for an ALL phrase in player input is now filtered
through the filterResolveList() method of each object in the list,
just as ambiguous noun phrases are.  This allows objects that
substitute for others in resolution lists (such as Collective and
CollectiveGroup objects) to perform the same substitutions in ALL
lists that they would in normal matches.

</div>

<!------------------->
<div class=entry>

The miscWord grammar rules are now defined in en_us.t, rather than
in the language-independent parser.t as they were previously.  This
change is necessary because different languages might have different
token types that are valid in miscellaneous word lists.  (In point of
fact, the English parser defines a special language-specific token,
tokApostropheS, that is now allowed in miscellaenous word lists.)

</div>

<!------------------->
<div class=entry>

The menu system now uses the regular game color scheme as the
defaults; the top "instructions" bar is shown using the status line
color scheme, and the main menu area uses the normal game window color
scheme.  This scheme is the safest default, since it uses only colors
the user has selected (on interpreters that allow the user to select
the color scheme); this ensures in particular that things like
hyperlink colors work well with the menu colors, since presumably the
user will have chosen settings that work well together.  (If not, at
least it's not the game's fault.)  This change means that menus won't
stand out as well from the main game window, since they use the same
color scheme, so the default mode for menus has been changed to the
"full screen" mode.  This new default appearance - full screen, using
normal game and status-line colors - makes menus very unobtrusive,
since they just look like an ordinary game screen.

</div>

<!------------------->
<div class=entry>

The menu system takes advantage of the new MORE-mode banner style
option, by using a separate banner to show "long topic" items.  Since
long text can now safely be displayed in a banner, with the interpreter
providing pagination via MORE prompts as needed, long topics can avoid
taking over the main game window.  This is nice because it leaves the
original game window intact (without any need to clear the screen) after
the user exits from the menu system.

</div>

<!------------------->
<div class=entry>

The MenuItem class has a new property, heading, that specifies the
text to display as the heading of the menu while the menu is active.
By default, the heading is the same as the title, which is the string
displayed in the parent menu's list of items.  The separate property
allows the caption shown while the menu is active to differ from its
title, if this is desired.

</div>

<!------------------->
<div class=entry>

A couple of the English messages for the npcMessagesDirect group have
been recast as quoted statements from the NPC, for consistency with
other messages in the group.  The affected messages are
noMatchDisambig and disambigOrdinalOutOfRange.  In addition,
askDisambig (in the same group) has been tweaked slightly to
accommodate this change.

</div>

<!------------------->
<div class=entry>

The CollectiveGroup class has been split into two classes.  The full
behavior of the old class is now contained in the class
ItemizingCollectiveGroup, which is a subclass of CollectiveGroup.  On
Examine, the CollectiveGroup class no longer shows the itemized list
of collected items, but instead simply shows its own description using
the normal Examine handling.  The itemizing behavior is desirable in
some cases of collective groups, but certainly not all; this change
makes it easy for the game to select whether or not the itemizing
behavior is used.

</div>

<!------------------->
<div class=entry>

If a check() routine (in a dobjFor() or iobjFor() group) terminates
the command with 'exit', the parser now automatically marks the action
in the transcript as having failed.  This is the same thing that the
reportFailure() macro does, so this means that it's never necessary
to use reportFailure() from within a check() handler.  Since the purpose
of check() is to enforce conditions on the action, exiting from the
check() routine necessarily means that the command has failed; this
change takes advantage of that to save games a bit of work.

</div>

<!------------------->
<div class=entry>

A new set of grammar productions provide for third-person reflexive
pronouns in verbs with two noun-phrase slots: "put klein bottle in
itself," for example.  These are mostly intended for conversation,
specifically things like "ask bob about himself," but will work in
general for the rare cases where they might be useful.

<p>The parser resolves a third-person reflexive pronoun by referring
back to the resolved object list for the other noun phrase in the
action.  Verbs taking only one noun phrase don't accept these, as they
make no sense: "open itself" isn't meaningful.  In the basic TIAction,
the order of noun phrase resolution can vary by verb, and the order
of resolution isn't required to match the order of the nouns in the
phrase; in English, at least, a reflexive pronoun in this type of
construction is always anaphoric (i.e., it always refers to a phrase
earlier in the sentence).  This means that the TIAction resolver could
find itself trying to resolve the reflexive phrase first, before it
knows the resolution of the phrase to which the reflexive refers.
To cope with this situation, the resolver notes when this occurs,
provides an empty list for the initial resolution of the reflexive,
and then goes back and re-resolves the reflexive after resolving
the other noun phrase.

</div>

<!------------------->
<div class=entry>

The new Thing property isKnown lets you specify that an object is
known in advance to the actors in the game.  The method isKnownBy(actor)
can be used to test actor knowledge of a Thing: isKnownBy(actor) returns
true if seenBy(actor) returns true, or the isKnown property is set to
true for the object.  The Actor methods knowsTopic() and isLikelyTopic()
now use isKnownBy() rather than seenBy() to determine actor knowledge.

</div>

<!------------------->
<div class=entry>

A few new conversation-related verbs have been added: Goodbye,
Yes, and No.  These are handled similarly to Hello.

</div>

<!------------------->
<div class=entry>

A new Action method, isConversational(issuingActor), determines if an
action is "conversational."  A conversational action is one that
involves the issuing actor saying something, within the game context,
to the target actor, as opposed to an order to the target actor to do
something.  Of the system-defined verbs, Hello, Goodbye, Yes, No, and
TellAbout (with the issuing actor as the direct object) are defined
as conversational.

</div>

<!------------------->
<div class=entry>

The interface of the Actor.obeyCommand() has changed, as has its meaning.
The method now takes two parameters: the actor who issued the command, and
the Action object.  In the past, this method was called with only the
issuing actor as a parameter, because the action was unresolved when the
method was called.  Now, the parser calls this method <i>after</i>
resolving the action and its objects.  This change gives the method
full access to the details of the action, so it can decide to accept
or reject commands based on the actual action being performed.

<p>The parser <i>does not</i> call this method when the action is
"conversational," as indicated by the isConversational() method no the
action.  Conversational methods are not considered to involve an order
to the target actor.  The actual physical action of a conversational
action simply consists of the issuing actor saying something to the
target actor, so even though these actions are phrased as though
they're orders to the target actor, they're really carried out by the
issuing actor, and thus don't require acceptance by the target actor.

<p>The default implementation of this method on Actor calls the
corresponding method on the atcor's current state object.  The
basic state object implementation simply refuses the command, so the
default behavior is the same as it was in the past.

</div>

<!------------------->
<div class=entry>

The TextList subclass formerly known as SlaveTextList has been
renamed to SyncTextList, to better reflect that this list is always
kept synchronized with its associated master list.  The old name
suggested that the connection was one-way, that state changes flowed
only from the master to the slave, when in fact the master and slave
are fully synchronized.  The new name is more suggestive of this
two-way connection.

</div>

<!------------------->
<div class=entry>

A new TextList subclass, StopTextList, provides a minor variation on
the standard text list script.  Once StopTextList reaches its last
message, it will simply stay at the last message forever, repeating
the last message each time the script is invoked.  This is useful for
cases such as a conversation topic where an actor has several things
to say, but once the actor has said each bit, the actor will from
that point on just repeat the last message; the last message would
usually be something like "I've already told you all I know about
it," or could be a summary of what the actor revealed.

</div>

<!------------------->
<div class=entry>

ShuffledTextList features a few enhancements.

<p>First, a new property, firstStrings, can be set to a list of
strings to show sequentially before starting the shuffled strings.
This can be useful in cases where you have some meaningful
information to convey initially, but once those messages have been
displayed, you want to fall back on randomized messages for
atmosphere and variety.  The firstStrings list is shown only once, in
sequential order.  Once the firstStrings list is exhausted, these
strings are never shown again.

<p>Second, the main shuffled list in textStrings can now be shown
sequentially the first time through, if desired.  Set the property
shuffleFirst to nil (it's true by default) if you don't want the list
shuffled the first time through.  Since the strings in the textStrings
list are intended to be shown in random order, in most cases it won't
matter to the author what order is used, and in this sense the order
in which the strings are actually defined is as random as any other
order.  In some cases, it might actually be desirable to have the
strings come out in a certain order the first time through; this lets
you refer back to an earlier message in a later message, for example,
with assurance that the player will have always seen the earlier
message first.  After the first time through the list, the list is
always shuffled and shown again in random order.

<p>Third, the class now takes care to ensure that a message is never
repeated consecutively.  Repeats are normally avoided naturally by
the shuffling: every item is shown once before anything is repeated.
But a consecutive repeat was still possible in one special case,
which is immediately after a shuffle.  Because the order of one
shuffle is independent of the order of the next shuffle, it was
possible for the last element of the previous shuffle to be the same
as the first element of the next shuffle.  The class now suppresses
this case by checking each new shuffle to make sure its first element
doesn't match the last element of the previous shuffle, and choosing
again when necessary.  This change is intended to increase the
apparent randomness by ensuring that the same string is never shown
twice in a row.

</div>

<!------------------->
<div class=entry>

The special description list order has been modified slightly.  If two
objects have the same specialDescOrder value, but one of the two
objects is inside the other, we'll list the outer object first.  So,
specialDescOrder still dominates, but when there's no specialDescOrder
preference, we'll list containers before their children.  In almost
all cases, this produces a more pleasing list order; objects within
other objects will frequently mention their placement in their special
description text, so it's usually better to have seen the containing
item's own special description before we see the containing item
mentioned in a child item's special description.

</div>

<!------------------->
<div class=entry>

A set of new commands makes it easier to record and play back command
scripts, which can be especially useful while writing and testing a
game.  The command RECORD (RecordAction) starts recording a command
script, which saves command input text to a file.  RECORD OFF
(RecordOffAction) turns off the recording starting with RECORD (it has
no effect if no recording is in progress).  REPLAY (ReplayAction)
plays back a command script previously recorded.  RECORD and REPLAY
both accept a filename in quotes on the command line, but this is
optional; if you just type RECORD or REPLAY, the commands will ask you
to select a file using a standard file dialog.

<p>REPLAY has two mutually exclusive options.  REPLAY QUIET plays
back the script without showing any output while the script is running.
REPLAY NONSTOP plays back the script without pausing for MORE prompts.

<p>Because REPLAY is fully redundant with the old "@" syntax, but much
friendlier, the "@" syntax has been removed.

</div>

<!------------------->
<div class=entry>

The new class LocateInParent makes it easy to define a nested object
that's to be located within the enclosing object.  This is a mix-in
superclass, so simply add it to the object's superclass list;
LocateInParent should go ahead of Thing or any Thing subclass in the
superclass list.

</div>

<!------------------------------- 3.0.6g --------------------------------->
<div class="sepbar"><a name='306g'></a>3.0.6g</div>
<p><b><i>Released April 12, 2003</i></b>
<p>

<div class=firstentry>

The default object picker has been improved to better handle cases
where commands are remapped.  Remapping from one object to another is
often used as a convenience to the player, so that the same command
can be applied to any of several related objects with the same
effect.  For example, you might want to set up a jar with a lid so
that OPEN JAR and OPEN LID have the same effect; this could be done
by remapping OPEN LID to OPEN JAR.  Similarly, a house with a door
might remap ENTER HOUSE so that it's handled as ENTER DOOR.  In the
past, cases like these prevented the parser from choosing a default
object, because the parser can only apply a default when there's only a
single object that could make sense - the remappings made several
different objects look equally good superficially, even though the
apparent different possibilities were all going to turn into the same
thing in the end thanks to the remapping.

<p>The parser now keeps track, during the verification process, of
any remapped objects.  The default picker looks at this remapping
information before deciding on a default.  If there are any objects
among the possible defaults that are to be remapped, the default
picker will discard any that are redundant due to the remappings.
For the OPEN JAR/OPEN LID example, the parser would see that OPEN LID
turns into OPEN JAR, and it would thus discard the lid from the list
of possible defaults, since the jar is already in the list.  This
would leave us with just one possibility, so the parser would be able
to apply use it as the default.

<p>The parser will only eliminate a remapped object as redundant
when the remapping matches the object, action, and role of another
object in the list of possible defaults.  If a remapping changes the
verb, the remapped object will only match another object if it's also
remapped to that same new verb.  The verb has to match because the
command could otherwise have a different effect, and thus the two
actions on the same object wouldn't be redundant with one another.

</div>
<!------------------->
<div class=entry>

The asExit() macro has been changed slightly.  You should no longer
uses the ":" syntax to define the direction; instead, simply put
the asExit macro directly after the direction name:

<p><pre>  north asExit(down)
</pre>

<p>This change is intended to make asExit more consistent with
the similarly-named asDobjFor() and related macros.

</div>

<!------------------->
<div class=entry>

The menu system has a few minor changes to make the user interface
more easily customizable.

<ul>
  <li>In HTML interpreters, the top title/instructions bar now shows
   a hyperlink that returns to the parent menu.  The text in this
   hyperlink is controlled by the 'prevMenuLink' property, which
   by default uses the text 'Previous'.

  <li>In HTML interpreters, a hyperlink is shown in topic lists to
   advance to the next topic item.  The text of the hyperlink is given
   by the 'nextMenuTopicLink' property.

  <li>The 'fgcolor' and 'bgcolor' properties now look to the parent
   menu, if there is a parent menu, for their default values.  For
   the top-level menu, the defaults are still the status line colors.
   In most cases, you'll want all of the menus in an entire menu tree
   to have the same appearance, and this change makes it easy to
   accomplish this: simply specify the appearance in the top-level
   menu, and all of the child menus will use the parent menu settings.
   Of course, individual menus can sever this parental dependence simply
   by overriding these properties.

  <li>Two new properties, 'topbarfg' and 'topbarbg', allow each menu to
   specify the foreground (text) and background colors of the top
   title and instructions bar.  By default, these look to the parent
   menu, if there is one; the top-level menu defaults to using the
   inverse of the color scheme of the menu itself.

  <li>The 'indent' property uses the parent's value by default.

  <li>A new property, 'fullScreenMode', lets you indicate that you want
   the menu to take over the entire interpreter window.  By default,
   menus are given just enough space at the top of the interpreter
   window to display their contents.  If 'fullScreenMode' is true,
   though, menus will cover the entire interpreter window.  Full-screen
   mode has the advantage that it's less jumpy than the default
   partial-screen mode, since the partial mode resizes the menu windows
   on each navigation operation to accommodate the new contents.
</ul>

</div>

<!------------------->
<div class=entry>

A new hint menu type has been added: HintLongTopicItem.  This is
simply a MenuLongTopicItem subclass designed for use in hint menus.
(Regular HintLongTopicItem objects don't have the necessary logic for
calculating visibility in a hint menu, so the specialized subclass
should be used for long-topic menus within hint menu trees rather
than the base MenuLongTopicItem type.)

</div>

<!------------------->
<div class=entry>

The library's turn-counter incorrectly counted a command as two turns
if the command's action() handler invoked a nested action which was
then remapped (via remapTo).  Nested actions aren't supposed to count
as separate turns; it was erroneous for the remapping to affect this
one way or the other.  This has been corrected.

</div>

<!------------------->
<div class=entry>

moveInto(nil) now works properly for a MultiLoc object.  (In the past,
this incorrectly caused a run-time error.)

</div>

<!------------------->
<div class=entry>

SensoryEmanation has a new property, isAmbient.  This is nil by default;
if set to true, it indicates that the noise/odor/etc is purely in
the background, so it's not especially noticeable.  Ambient emanations
won't be mentioned when they first become sensed; normally, an emanation
is automatically mentioned whenever conditions change so that it was
not sensed previously but is now.  Ambient emanations will still be
mentioned in explicit intransitive LISTEN/SMELL commands; they simply
won't be mentioned on their own.

</div>
<!------------------->
<div class=entry>

Part of the Container class has been separated into a new lower-level
base class, Encloser.  An Encloser is an object that can enclose its
contents, so that all senses must pass through the encloser's
material when passing in and out of the object.  Encloser has all
of the basic handling for enclosing contents, but not the action
handling.  Encloser is meant for cases where the object's contents
are not to be directly manipulable by the player, via "put in"
commands and the like.  Container is now a subclass of Encloser;
Container defines the suitable action handlers to allow a player
to manipulate the container's contents.

</div>
<!------------------->
<div class=entry>

<p>
A new mechanism in the Actor class makes it relatively easy to set it
up so one or more non-player characters accompany the player character
on travel.  This kind of group travel is especially good for things
like a sidekick character who goes everywhere the player does, and for
tour guides or other escorts who are showing the player character
where to go.

<p>This mechanism is similar to the "follow" mechanism, which makes
one actor attempt to follow another on each turn, but it improves
considerably on regular following by customizing the messages.  Normal
following is a little awkward for explicit group travel of the sort
that one wants with sidekicks and escorts, because the messages are so
generic; the NPC almost seems to be wandering around on its own and
just coincidentally showing up where the PC is.  This new
"accompanying" mechanism accomplishes much the same thing, but smooths
out the messages a bit.  First, rather than having the NPC trailing
along after the fact, the new system sends accompanying NPC's on
ahead; this means that the NPC's don't just wander in later as they do
with normal following.  Second, the message for the NPC's
pre-departure is customized to make it clear that the NPC isn't
departing, but is coming along with you.  Third, on arriving in the
new location, there's a customization hook for describing the NPC's
presence in the new location specially for the group travel; this is
important because it gives us a place to mention that the actor starts
doing whatever it is the actor normally does in the new location.  The
overall effect is that each group travel action is made to look like a
single, integrated action, rather than two generic and unrelated actor
travel actions.

<p>NPC's can also be set to accompany NPC's with the same mechanism,
but it's much less interesting for that, since the main value of the
new mechanism is that it improves the messages for PC-plus-NPC group
travel.  For NPC-plus-NPC group travel, this new mechanism has no
particular advantage over the the simpler "follow" mechanism.

<p>Setting up accompanying travel is relatively straightforward.
You have to specify the conditions under which the group travel occurs,
and you should customize two messages related to the travel.  You
set this all up by overriding methods on the NPC who's going to follow
the lead actor (usually the PC).  The methods to override are as
follows.

<p>First, override the accompanyTravel() method so that it returns
true under the conditions where you want the accompanying travel to
occur.  This method is called each time your NPC is present and sees
another actor attempt a travel action (it's called during your NPC's
beforeAction when the action is a TravelVia).  If you want your actor
to accompany the PC everywhere, simply return true when the action
actor is the PC.  The method also has access to the TravelConnector
involved in the travel, so you selectively accompany an actor for
some destinations but not others, if you wish.

<blockquote>
<b>Warning: the next two parts are likely to be modified soon.</b>
I'd recommend against writing any code that makes customizations using
these features right now.
</blockquote>

<p>Second, define an accompanyDesc method for your actor.  This method
is used instead of the usual actorHereDesc method to describe your
actor in the new location immediately after the group travel is
finished.  It's usually desirable to use a special message to describe
the actor right after the accompanying travel, because you usually
want to convey that the actor is just arriving - not that the actor is
walking in separately from the lead actor, but that the actor is
arriving at the same time as the lead actor.  If you do override
accompanyingDesc, you should override accompanyingListWith to return
an empty list ([]).

<p>Third, you can optionally provide a special TravelMessageHandler
for your actor by overriding getAccompanyingTravelMessageHandler.  By
default, this routine provides a message handler that uses messages
like "Bob goes with you" instead of the usual "Bob leaves to the east"
to describe the departure of your actor.  The normal departure message
isn't appropriate, because the actor isn't just leaving, it's leaving
*with* the lead actor.  The default "Bob goes with you" is better, but
you might still want to override this handler to provide even more
customized messages: "Bob escorts you to the east," or "You drag Bob
with you," or whatever makes sense for the specific situation.

<p>Finally, note that you can use accompanying travel and the regular
following mechanism together.  Regular following can be a useful
fallback for cases you don't want to customize.  Regular following
occurs after the fact, because it occurs on an NPC's turn when the
NPC sees that the actor it's tasked to follow is no longer present.
Accompanying travel, in contrast, happens on the same turn as the
lead actor's travel.  This means that regular following is essentially
overridden by accompanying travel, since it happens first.

</div>

<!------------------->
<div class=entry>

The English parser now accepts quoted strings as adjectives.  Quoted
strings can be used as adjectives in exactly the same way that numbers
can be used, so phrases such as "QU" TILE and BUTTON "G" are accepted.

<p>For the purposes of matching vocabulary in the dictionary, quoted
adjectives are simply treated as though the quotes weren't present.
So, "QU" TILE is treated exactly the same as QU TILE.  This means you
don't have to worry about the quotes when defining your vocabulary
words.

<p>There is an additional bit of special treatment for quoted strings.
The special vocabulary word '"*"' (that is, an asterisk within
double-quote characters) serves as a wildcard for any quoted string.
If an object defines this special wildcard as an adjective among its
vocabulary words, then that object will match <i>any</i> quoted string
as an adjective.  This is the equivalent of the '#' wildcard string
for numeric adjectives.

<p>String-as-adjective phrasing is implemented using the new
production literalAdjPhrase.  This new production is now used
wherever numberPhrase was formerly used in the role of an adjective
in noun phrase rules.  literalAdjPhrase matches numbers, '#' number
phrases, and quoted strings.

</div>

<!------------------->
<div class=entry>

In travel.t, there were formerly a couple of TravelConnector
subclasses that handled action synonyms for TravelVia using
asDobjFor(TravelVia).  These have been changed to use
remapTo(TravelVia) instead.

<p>The asDobjFor() approach had the drawback that the action
synonyms didn't ever generate TravelVia actions proper, but
simply called the TravelVia handlers internally; so, for example,
beforeAction() routines wouldn't ever see a TravelVia action
being performed.  The new remapping approach is better because
it means that every possible action on these objects that
involves travel will go through an actual TravelVia action.
This allows beforeAction() and similar routines to be assured
that they can catch all travel actions by looking for TravelVia
alone, eliminating the need to worry about synonym actions that
could cause travel.

</div>

<!------------------->
<div class=entry>

A couple of new classes simplify a few tasks involving entry
and exit portals.  Exitable is a new class that's similar to
Enterable, but provides Exit instead of Enter as its main
action.  EntryPortal and ExitPortal are just like Enterable and
Exitable, respectively, but add support for GoThrough actions.

</div>

<!------------------->
<div class=entry>

Added finishOptionFullScore, to make it easy for the game to
offer the player the option of seeing the full score at completion.

</div>

<!------------------------------- 3.0.6f --------------------------------->
<div class="sepbar"><a name='306f'></a>3.0.6f</div>
<p><b><i>Released March 23, 2003</i></b>
<p>

<div class=firstentry>

It's now less dire for gPlayer.location to be set to nil.  In the
past, setting gPlayer.location to nil caused an infinite error loop,
because the status line code dereferenced gPlayer.location without
checking for nil, which caused an error, which aborted the current
turn, which started a new turn, which tried to update the status
line, and around we went.  It's still not completely valid for
gPlayer.location to be nil; this change just removes the infinite
error loop, which makes it a little easier to deal with this problem
arising during programming and testing.

</div>

<!------------------->
<div class=entry>

Changed Thing.dobjFor(Remove) to remap to RemoveFrom (asking for an
iobj).  Wearable now overrides Remove to map it to Doff.  It makes
more sense in general for "remove foo" to mean "remove foo (from
something)" rather than "doff foo"; only when "foo" is an article of
clothing does the "doff" interpretation usually apply.

</div>

<!------------------->
<div class=entry>

Added the new TravelConnector property isConnectorListed.  If this
property is nil, the connector is suppressed from generated exit
lists (such as the status line exit list, and "you can't go that way"
messages).

</div>

<!------------------->
<div class=entry>

Added a new class, UnlistedProxyConnector, that acts as a proxy for
an underlying connector, but is unlisted.  The idea is to make it
easy to add an exit that acts exactly like another connector, but is
suppressed from exit lists.

</div>

<!------------------->
<div class=entry>

Added a macro, asExit(), that can be used to define an
UnlistedProxyConnector that links to another direction exit.

</div>

<!------------------->
<div class=entry>

Integrated Stephen Granade's menu system (menus.t) with the main
library.

</div>

<!------------------->
<div class=entry>

Added an on-line adaptive hint system (hints.t).

</div>

<!------------------->
<div class=entry>

Added the new class RestrictedContainer.  This is a Container
specialization that makes it easy to define containers that only
accept certain objects as contents.  In the basic implementation, the
allowable objects are simply enumerated as a list of objects; but
this can be easily overridden for other methods of determining which
objects are allowed.

</div>
<!------------------->
<div class=entry>

Added the new class SingleContainer, and the associated new
precondition objEmpty.  SingleContainer is a specialization of
Container that only allows a single object to be in the container at
a time; this is suitable for things like sockets and receptacles.
SingleContainer places the objEmpty precondition on the PutIn action;
the objEmpty precondition simply requires that the subject object is
empty, and tries implicit TakeFrom actions on the contents to
accomplish this.

</div>
<!------------------->
<div class=entry>

In en_us.t, changed typographicalOutputFilter.eosPattern to ignore
any run of HTML tags between sentence-ending punctuation and a
following space.

</div>
<!------------------->
<div class=entry>

The main implicit action processor now uses the more abstract
"allowed in implicit" test on the verify results, rather than merely
checking for "dangerous" results.  This will allow results flagged as
"non-obvious" to cancel implied actions, as they should.  (A
non-obvious command should never be done implicitly, because implicit
commands are specifically for actions that are obvious intermediate
steps toward the explicitly stated command.)

</div>
<!------------------->
<div class=entry>

Openable and Lockable have been cleaned up slightly.  A new class,
Linkable, has been added for objects that can be paired in
master/slave relationships; Openable and Lockable are now based on
Linkable.  This removes some duplicated code for managing the
masterObject relationship.  In initialization, Linkable checks for a
master object loop (where each object points to the other as the
master) and break such loops by arbitrarily selecting one as the
master.  Also, we have reduced the number of times we have to refer
to masterObject by relying on isOpen/isLocked/makeOpen/makeLocked to
defer to the master.  Also, the initiallyOpen/initiallyLocked
initializations are now handled in initializeThing() rather than in
isOpen/isLocked.

<p>Another new class, BasicOpenable, provides the basic state
management for openable objects (which can optionally be linked
in pairs to maintain the same status across the pair) but doesn't
provide any of the verb handling of Openable.  This can be used
for objects that want to maintain open/closed state using the
usual method names, but which don't respond to direct player
open/close commands.

<p><b>IMPORTANT:</b> Objects based on Openable and Lockable must
<b>not</b> initialize their open status with isOpen or their locked
status with isLocked.  Instead, initialize the status with
initiallyOpen and initiallyLocked, respectively.  Also, be sure
you never set isOpen or isLocked directly; instead, call makeOpen()
and makeLocked() to effect these status changes.

</div>
<!------------------->
<div class=entry>

Changed Passage slightly to rely on isOpen/etc more to manage the
masterObject relationship.

</div>
<!------------------->
<div class=entry>

Added a parameter to Direction.defaultConnector() giving the location
from which travel is being attempted.  This allows the direction to
customize the default connector according to the type of location.

</div>
<!------------------->
<div class=entry>

Added a new property, isShipboard, to Thing.  By default, if we have
a location, we use the location's isShipboard setting, otherwise we
return nil.  Rooms aboard ships can set this to true to indicate that
shipboard directions make sense here.

<p>In ShipboardDirection.defaultConnector, if the source location or
any container has 'isShipboard' set to true, then we now use noTravel
as the default connector rather than noShipTravel, as the latter is
meant to convey that shipboard directions make no sense in
non-shipboard locations.

<p>Added a ShipboardRoom mix-in class that defines isShipboard to true.

</div>
<!------------------->
<div class=entry>

Changed the way that VerifyResultList determines if an action is
allowed at all or allowed as an implicit command.  In the past, this
calculation did what the "most disapproving" result in the list said
to do; this wasn't quite right, because approval is essentially a
separate axis from the "disapproval" order, despite the name.  In
reality, the "disapproval" order is the message priority order, and
the actual determination of approval depends on there being
no disapprovers.  So, to determine approval, we now scan the full
result list and require that every result approves; a single
disapproval, no matter where it appears in message priority order,
constitutes disapproval.

</div>
<!------------------->
<div class=entry>

In the English module, added a new token type for numbers specified
with a leading pound sign (as in "#2 pencil" or "room #101").  These
are treated essentially the same as numeric adjectives.  These match
vocabulary for just the underlying numbers, not including the pound
signs, so vocabulary should be specified simply as '2 pencil' and
'101 room'.  (In other words, do <b>not</b> include a pound sign in
vocabulary words; just use the number as with ordinary numeric
adjectives, and the parser will match the number with or without the
pound sign).

</div>
<!------------------->
<div class=entry>

The TravelVia check() condition in Passage no longer uses isOpen as
its test.  Instead, it calls the new abstract condition method,
canActorTravel(), passing the current actor as a parameter.  This
makes it easy to allow some actors to pass and not others, and to
test for conditions other than isOpen.  By default, canActorTravel()
simply returns isOpen, so this doesn't change the default behavior.

<p>Along the same lines, Door.connectorTravelPreCond() now calls
a separate method, getDoorOpenPreCond(), to obtain the door-is-open
precondition object.  By default, this returns a doorOpen precondition
(wrapped with an ObjectPreCondition for 'self'), so the default behavior
hasn't changed.

</div>
<!------------------->
<div class=entry>

In the past, when an NPC was following another actor, and the actor
being followed moved into a nested room within the current room, we
generated a redundant message:

<p><pre>&gt;stand on platform
Okay, you are now standing on the platform.
Bill stands on the platform.
Bill follows you onto the platform.
</pre>

<p>
The redundant "Bill follows you" has been eliminated.

</div>
<!------------------->
<div class=entry>

The reporting mechanism now processes sets of implicit action announcements
to make them more readable and more easily understood.  In the past,
each implicit action was shown separately; when one implicit action
triggered another, this could make for somewhat confusing displays.
For example, in the Platform Room in sample.t, if the PC is sitting on
the blue chair and wants to get up and sit on the red chair, we formerly
generated a transcript like this:

<p><pre>&gt;sit on red chair
(first standing on the red platform)
(first getting off of the blue platform)
(first standing)
Okay, you're now sitting on the red chair.
</pre>

<p>To the uninitiated, this looks backwards: shouldn't we stand up,
then get off the blue platform, then get on the red platform, and then
sit on the red chair?  Of course, that's what's actually happening,
and in its own way the transcript above reflects this: the second
"first" applies to the first "first": it's saying "before you can
stand on the red platform, you first have to get off the blue
platform."  Likewise, the third "first" applies to the second "first,"
to say "before you can stand on the red platform, you have to stand up
first."  In other words, the implied reports are nested recursively.
The recursive structure isn't represented visually, though, so it's
not evident whether one of the later "firsts" refers to the preceding
"first" or back to the original command line.  It would have been
possible to represent the recursive structure visually, using
indentation or something like that, but this probably wouldn't have
made most people very happy; most non-programmers aren't accustomed to
thinking in terms of recursion and stacks and tree views, and even
programmers might well have found this kind of presentation to be too
obviously mechanistic.

<p>To improve the situation, the transcript processor now features a
new transform, called implicitGroupTransform, that rearranges these
recursive listings into an order that should be entirely
straightforward to anyone, programmer or not.  The new transform also
consolidates these lists into a much more concise and readable format.
The transformer does two things.  First, it "unstacks" recursive lists
of implied action announcements to put them into the chronological
order in which the commands were actually performed; the transcript
has always kept track internally of which announcement is tied to
which action, so the new transformer can merely inspect these records
to determine the action relationships and use this information to
unwind the stack.  Second, the transformer combines each run of
adjacent implied action announcements into a single announcement,
showing a list of the actions performed.  The result is that the
example above now looks like this:

<p><pre>&gt;sit on red chair
(first standing, getting off of the blue platform, then standing on
the red platform)
Okay, you're now sitting on the red chair.
</pre>

<p>This new format should be easier for players to understand,
since it shows implied actions in the order in which they're actually
carried out, eliminating any need to be aware of the recursive
goal-seeking work that the system is doing internally.  Hopefully,
players will also find it more readable and less obviously mechanistic
than the old format.

</div>


<!------------------------------- 3.0.6a-e --------------------------------->
<div class="sepbar"><a name='306ae'></a>3.0.6a-e</div>

<p><b><i>3.0.6e was released March 16, 2003</i></b>
<p>

<div class=firstentry>

For a restore-on-startup operation, if the restore fails, don't simply
start the game from the beginning.  Instead, offer options to START
from the beginning, RESTORE another game, or QUIT, using the same type
of prompt that we use for presenting "finishing" options.

</div>

<!------------------->
<div class=entry>

Add a verb for OOPS typed at arbitrary times, which simply explains
that OOPS can only be used after the parser has pointed out an unknown
word.

</div>

<!------------------->
<div class=entry>

Fix problem using possessive qualifiers in topic phrases.  (The
problem is that we're using the topic resolver to resolve qualifiers
in the topic phrase; we should be using an ordinary object resolver.
Change the topic resolver's qualifier resolver to use the topic
action's direct object resolver by default.)

</div>

<!------------------->
<div class=entry>

Move the pronoun-setting routines (setPronoun, setIt, setHim, setHer,
setThem) into Actor - these shouldn't be global functions since they
need to operate on the current actor.

</div>

<!------------------->
<div class=entry>

In TopicAction, set the pronoun antecedent based on the direct object
phrase immediately during resolution, to allow things like "ask bob
about his book."

</div>

<!------------------->
<div class=entry>

Add a DefineIAction macro, for defining IAction classes.

</div>

<!------------------->
<div class=entry>

Base LiteralAction on IAction, not directly on Action.

Because of this change, rewrite OopsAction to implement its processing
in execAction() rather than doActionMain().

</div>

<!------------------->
<div class=entry>

Refactor the Instructions action into an InstructionsAction base class
and a separate grammar rule, to allow the base class to be referenced
by name from other code.

</div>

<!------------------->
<div class=entry>

Add a banner manager, along the lines of the input and output
managers.  A new BannerWindow class would represent a banner; this
would encapsulate the system banner handle and provide methods that
operate on the banner.  The game should use the BannerWindow methods
to perform all operations on banners, rather than calling the
system-level banner API directly.

The banner manager should provide persistence support, so that the
on-screen banner layout is restored on RESTORE, UNDO, or RESTART.  To
this end, BannerWindow should be an ordinary persistent object, and a
separate set of transient objects should track the current UI state.
On RESTORE, UNDO, or RESTART, the transient tracking list and the
persistent BannerWindow states should be compared, and the actual
on-screen UI state, as represented in the transient objects, should be
brought into line with the saved state.

</div>

<!------------------->
<div class=entry>

Wait to mark an object as 'seen' in Thing.lookAroundWithin() until
just before the method returns, so that any routines called from the
method can check the old 'seen' status.

</div>

<!------------------->
<div class=entry>

Fix gAction reference in Actor.travelWithin() so that it's conditional
on gAction being non-nil.

</div>

<!------------------->
<div class=entry>

Fix takeFromNotInActor message (iobj/dobj are reversed).

</div>

<!------------------->
<div class=entry>

Fix TAction.retryWithMissingDobj() and
TIAction.retryWithMissingIobj() so that they cancel the game time
contribution of their enclosing (replaced) actions.

</div>

<!------------------->
<div class=entry>

Fix touchObj precondition logic so that it realizes when an attempt
to remove an obstruction with a precondition fails.  To do this, keep
track of which obstructions we've tried to remove with implicit
commands, and give up if we encounter the same obstruction more than
once.

</div>

<!------------------->
<div class=entry>

Add &lt;.parser> to msg_neu.t responses for some system verbs (NOTIFY
ON/OFF, EXITS ON/OFF, a few others).

</div>

<!------------------->
<div class=entry>

Assign the IndirectObject role to the literal in a LiteralTAction by
overriding getRoleFromIndex, getObjectForRole, and getMatchForRole.
These are needed to allow remapTo to be used with a LiteralTAction.

<p>
Note that the literal is <b>always</b> in the IndirectObject role,
regardless of whichLiteral, which only specifies the grammatical role
for message generation purposes.

<p>
Likewise, assign the IndirectObject role to the topic in TopicAction.
This will allow remapTo to be used with a TopicAction.

</div>

<!------------------->
<div class=entry>

Rename TopicAction to TopicTAction, parallel to LiteralTAction.

</div>

<!------------------->
<div class=entry>

Add a new TopicAction that takes only a topic as its object, parallel
to LiteralAction.

</div>

<!------------------->
<div class=entry>

Rename whichObject, whichLiteral, and whichTopic to
whichMessageObject, whichMessageLiteral, and whichMessageTopic,
respectively, to make it clearer that these apply only to the roles
played in generated messages, and not to any other roles.

<p>
In particular, the message role only affects the way the object is
used in generating messages based on the verb, such as "what do you
want to open it with?".

</div>

<!------------------->
<div class=entry>

It would be better to interpret "type on typewriter" as having a
missing literal than as having a missing ON phrase (in other words,
we want to interpreter this as TYPE &lt;empty literal&gt; ON TYPEWRITER
rather than as TYPE "ON TYPEWRITER" &lt;on missing object&gt;).

<p>
To do this, add a verb rule for TYPE ON &lt;object&gt;, without any literal
phrase.  For most objects, fail in verification; but when
verification passes, in the action, ask for a missing literal phrase.
(This has the additional benefit that it makes it easy to create
objects that allow generic typing on them, as in TYPE ON COMPUTER,
for situations where the game doesn't want to make the player type
anything specific but still wants to allow the generic act of typing
on the object.)

</div>

<!------------------->
<div class=entry>

<pre>
>ASK BOB ABOUT
what do you want to ask him about?

>BILL
"Ah, yes, , very interesting..."
</pre>

<p>
(The problem is that we're not propagating getOrigText() from the
empty topic phrase match down to the underlying replacement match.)

</div>

<!------------------->
<div class=entry>

<pre>
>ASK BOB
what do you want to ask him about?

>ABOUT BILL
"Ah, yes, about bill, very interesting..."
</pre>

<p>
(The problem is that we need an aboutTopicPhrase production to parse
responses to ABOUT WHAT questions.)

</div>

<!------------------->
<div class=entry>

Add a generic Settable class for things (such as dials) that can be
set to various settings.  Base Dial on Settable.

</div>

<!------------------->
<div class=entry>

Do not override lookAroundWithinDesc() in BasicLocation; instead,
provide an implementation of BasicLocation.roomDesc that simply uses
the 'desc' property to display the room's interior description.
(This allows nested rooms to differentiate more easily between
interior and exterior descriptions, if they want to.)

</div>

<!------------------->
<div class=entry>

Add a new method to Thing, filterResolveList(), to allow "global"
filtering of a noun phrase resolution list.  Call this method from
the parser where we use 'verify' to filter a resolution list.  Unlike
'verify', this new method has access to the entire resolution list;
this allows the method to take action based on which other objects
are in the resolve list.

</div>

<!------------------->
<div class=entry>

Add a new mix-in class, Collective, to serve the purpose of the
former isCollectiveFor(obj) method in Thing.  To create an object
like the matchbook in the sample game, use Collective as an
additional base class.

<p>
Remove the special-cased plural filtering in AllPluralProd and
DefinitePluralProd.  Move this logic instead into Collective's
filterResolveList() implementation.

</div>

<!------------------->
<div class=entry>

Add a new class, CollectiveGroup, to allow creating "abstract"
collective objects.  These differ from regular Collective objects in
that a Collective is actually a simulation object (such as a
matchbook that can hold several matches), whereas a CollectiveGroup
is not a separate object from the player's perspective (so it's never
listed as a separate object in a room's contents listing, for
example).

<p>
Add a new Thing property, collectiveGroup, that allows an ordinary
object to be associated with a CollectiveGroup object.  In
CollectiveGroup's filterResolveList() method, choose to keep either
the individuals (the ordinary Thing objects associated via their
collectiveGroup properties with a CollectiveGroup object) or the
CollectiveGroup in the resolution list, but not both.  By default,
make the selection based on action; subclasses can override as
desired to use other criteria.

<p>
CollectiveGroup can be used to create things like a "money" object
to represent a set of coins and bills, so that a command like "look
at money" can respond with a single description of all of the money
present, rather than iterating over all of the coins and bills
individually.

</div>

<!------------------->
<div class=entry>

Eliminate the actorHereLister.  Instead, handle actor descriptions
using the special description mechanism.  By default, give actors
a higher specialDescOrder, to keep actor special descriptions listed
after other special descriptions.

</div>

<!------------------->
<div class=entry>

Add a new special description control property to Thing,
specialDescBeforeContents; set it to true by default in Thing, but
override it to nil in Actor.  In verbose room descriptions, show
special descriptions in two phases: where we currently show special
descriptions, just before the room's list of portable contents, show
special descriptions only for items with specialDescBeforeContents
set to true.  Then, after we've shown the portable contents list
and any other sensory messages (listen/smell), show the special
descriptions for objects with specialDescBeforeContents set to nil.

<p>
This will allow the traditional ordering, with actor "I am here"
messages placed after the rest of the room description, while keeping
the rest of the special descriptions grouped with the room's main
description.  Most special descriptions belong with the main room
description because they're meant to be extensions of the room
description.  Some special descriptions are not; they're meant to
describe more ephemeral status information, so work better when
grouped with the other status-like messages.  Actors in particular
fall into the latter category, since actors are meant to seem
autonomous, not parts of the rooms they occupy.

</div>

<!------------------->
<div class=entry>

When showing special descriptions of the contents of an object as part
of the object's description, use a new form of the special description
method, showSpecialDescInContentsWithInfo(), and corresponding
specific methods for viewing conditions (showSpecialDescInContents,
showObscuredSpecialDescInContents, showDistantSpecialDescInContents).

<p>
Override showSpecialDescInContents in Actor, so that we can show
the type of description we previously showed using nestedActorLister.

<p>
Remove nestedActorLister and NestedRoom.examineNestedRoomActors().

</div>

<!------------------->
<div class=entry>

Add a default output filter, typographicalOutputFilter, to the main
output stream.  In this filter, convert '--' and '---' sequences to
typographical dashes, and insert an en space at the end of each
sentence.

<p>
The conversion of sentence-ending punctuation compensates for the
elimination of the double-space insertion in the VM-level formatter.
It also improves matters over the old way by making the treatment of
sentence-ending punctuation customizable: the game can replace the
filter method with its own custom conversions.  This allows
customization not only for stylistic variation but for
language-specific conventions as well.

</div>

<!------------------->
<div class=entry>

Add the special {subj} messageBuilder token.  This token simply notes
its target object as the subject of the sentence, for internal
book-keeping purposes, but doesn't actually display anything.

</div>

<!------------------->
<div class=entry>

Add a "log file console" type.  This would act like the main console
or a banner console, in that it would apply the full set of VM-level
output formatting (including text-only HTML interpretation) to the
text sent through the stream, but it would write the output only to a
file, rather than displaying it anywhere.  This would be useful for
capturing output to a file without showing the output at all on the
display; for example, this would make it easy to generate an About.txt
file by capturing the output of the ABOUT command to a file during
preinit, without having the ABOUT output also show up on the screen.

<p>
This would require a new set of VM-level functions in the tads-io set:

<p>
<ul>
<li>logConsoleCreate(filename, charmap, width):
returns a handle to the new console

<li>logConsoleSay(handle, ...): writes the arguments to the
log console; works like say() and bannerSay()

<li>logConsoleClose(handle): closes the console
</ul>

<p>
In addition, add a LogConsole library class to simplify operations
with the log console.  This class can be quite simple; it's just an
OutputStream subclass that implements the writeFromStream method to
call logConsoleSay().

</div>

<!------------------->
<div class=entry>

Add a TopicQualifierResolver subclass of Resolver, specifically for
resolving qualifier phrases in topics.  Use a new instance of this
class instead of the direct object resolver in TopicActionBase.  (The
direct object resolver isn't really appropriate, and doesn't work at
all with plain TopicActions, because they don't have direct object
resolvers at all.)

</div>

<!------------------->
<div class=entry>

Add a new mapping macro, iobjAsDobjFor(), that makes it safe to map
an indirect object handler to a direct object handler in the same
object.  Use this for the mapPushTravelHandlers() macro.

<p>
(The mapPushTravelHandlers() macro essentially wants to decompose the
two-object action into two single-object actions, which isn't safe
with the regular asDobjFor() mapping.  The difference with
iobjAsDobjFor() is that this new routine temporarily makes the
indirect object take on the direct object role, so that the target
dobj handler sees the proper object in the direct object slot.)

</div>

<!------------------->
<div class=entry>

Add a LabeledDial subclass of Dial.  This class accepts arbitrary text
labels as dial stops; the property validSettings contains a list of
strings giving the valid dial stop labels.

</div>

<!------------------->
<div class=entry>

Remove any .t and .tl extensions from adv3.tl and en_us.tl.  (The
extensions are implied by the file types; it makes the library file
more portable to omit the extensions, since the compiler will
automatically apply the default extensions using the appropriate local
conventions when the extensions aren't explicitly included in the
names as they appear in the library files.)

</div>

<!------------------->
<div class=entry>

Get rid of Thing.articleIndef; games should simply override aName
instead when they want to override the default indefinite article
determination.

</div>

<!------------------->
<div class=entry>

Change the way theDisambigName, aDisambigName, and countDisambigName
work.  If name == disambigName, then return the corresponding xxxName
from xxxDisambigName; otherwise, apply the same algorithm to
disambigName that the corresponding xxxName applies to name.  For
example, in aDisambigName, if name == disambigName, simply return
aName; otherwise, apply the indefinite article algorithm to
disambigName and return the result.

<p>
This change will allow disambigName to be overridden without
requiring all of the xxxDisambigName's to be overridden at the same
time, because the xxxDisambigName's will by default apply the
standard algorithms to the modified disambigName.  At the same time,
though, this has the virtue of the original implementation that, in
the common case where disambigName is not overridden, any overrides
to theName, aName, and countName will be used for the corresponding
xxxDisambigName's.  Furthermore, since these are all still separate
methods, objects can still separately override each xxxDisambigName
as needed for cases where the disambigName is customized <i>and</i> the
customized name requires overriding the normal article algorithms.

<p>
While we're at it, add pluralDisambigName, using the same logic.

</div>

<!------------------->
<div class=entry>

Remove the dictionary properties possessiveAdj, possessiveNoun, and
their corresponding grammar.  (These are no longer needed, since we
now have explicit grammar for all of the possessive pronouns in
adjective and noun usages.  At one time, these were used for adding
vocabulary for the player character, but it worked better to use the
grammar and resolver mechanism more explicitly.)

</div>

<!------------------->
<div class=entry>

Rework "'s" handling for literal vocabulary:

<p>
First, remove the special-case tokenizer handling for "'s" words that
appear in the dictionary, so that we handle <b>all</b> "'s" words
uniformly in the tokenizer: all "'s" suffixes are treated as separate
tokens.

<p>
Second, never add "'s" words to the dictionary in initializeVocab().
Instead, define a new dictionary property, adjApostS; when we see a
"'s" word in a vocabulary list, remove the "'s" suffix and add only
the prefix to the dictionary, but add it as an adjApostS instead of
as an adjective.  (For simplicity, don't bother with nounApostS at
all; allow only adjectives as apostrophe-s words.)

<p>
Third, add a new grammar production, adjWord, that accepts either a
single adjective or an adjApostS followed by an apostrophe-s token.

<p>
Fourth, where appropriate, change 'adjective->' grammar rules to use
'adjWord->' instead.

<p>
These changes correct the problem that adding a literal "'s" word to
an object's vocabulary prevented that word from being used as a true
possessive phrase in the grammar.  The old tokenizer rule was that a
word that appeared with an explicit "'s" suffix in the dictionary was
kept intact, rather than split into separate tokens for the root word
and the "'s" suffix.  Since the word was kept intact as a single
token, it couldn't match the grammar rules for possessive phrases,
which only match the separated form.  These changes allow the same
word to be used in either context, since everything is treated the
same way in the tokenizer; even if a word is used as a literal
vocabulary word with a "'s", it'll still be split up during
tokenization.  Even with this change, we can still match explicit
"'s" vocabulary words, thanks to the adjWord grammar.

<p>
Note this has one small potential impact on existing games: if an
object explicitly defines its own 'adjective' property (rather than
using the automatic library initialization), and a word defined in the
adjective list ends in apostrophe-s, then that word must be stripped
of the apostrophe-s suffix, removed from the 'adjective' list, and
added to a new 'adjApostS' list instead.  Similarly, if any vocabulary
words that end in apostrophe-s are dynamically added with
G_dict.addWord(), the apostrophe-s words should be stripped of the
suffix and added under the '&adjApostS' property instead of the
'&adjective' property.

</div>

<!------------------->
<div class=entry>

Add noteLiteral(lst_.getOrigText()) to getVocabMatchList() in
simpleNounPhrase(misc)?  This would make the length of text in a
miscellaneous word list a match selection criterion (less important
than the presence of a misc word list).  This won't change anything in
cases where we want to choose between a match with a misc word list
and one without, as the presence or absence of a misc word list is
more important than literal length, but it will help distinguish
between two matches that both have misc word lists.  Since we prefer a
shorter literal match, this will have the effect of preferring to
match the more structured interpretation, since a shorter misc word
match means a longer grammar match.

</div>

<!------------------->
<div class=entry>

Fix run-time error with "a <phrase>" (the 'inherited' argument list
is wrong in AskAboutAction.getDefaultDobj; the same problem is in
TellAboutAction).

</div>

<!------------------->
<div class=entry>

Rename class Fixed to Fixture.

</div>

<!------------------->
<div class=entry>

Add new class Immovable: this is for objects that aren't fixed in
place obviously or by their very nature (as are Fixtures), but rather
are fixed for some other reason: great weight, hidden fasteners, etc.
This class differs from Fixture in that it disallows actions like
take, move, push, and pull not in the verify() but in the action().

<p>
Add a subclass, Heavy, for objects that are immovable because they're
very heavy.  This is suitable for things like large furniture and big
boulders.

</div>

<!------------------->
<div class=entry>

Remove moveInto() override on Immovable.  (This attempted to be a last
resort to disallow actions that involved trying to move the object,
but it prevented programmatic relocation as well, creating more
problems than it solved.)

</div>

<!------------------->
<div class=entry>

Fix problem with applying AGAIN to a command issued to another actor:
the target actor becomes "busy" and won't accept another command until
a turn passes.  The problem is that we're not accounting for
synchronous actors in the AGAIN processing: we need to tell the issuer
to waitForIssuedCommand on the target actor.

</div>

<!------------------->
<div class=entry>

Fix problem in GiveTo and ShowTo actions: getDefaultIobj calls
inherited() with wrong argument list.

</div>

<!------------------->
<div class=entry>

Fix the parameter list for npcActionMessages.okayTurnTo.

</div>

<!------------------->
<div class=entry>

Make RandomTextList customizable with the percentage of the time a
message is generated at all.  Random message lists are often used for
atmospheric messages, and it's usually better if these messages don't
appear on every single turn.  Add a 'messagePercent' property that
determines the percentage of turns where a message is generated; the
default is 100, which leaves the default behavior as it was (i.e., a
message is generated on every turn).

<p>
In addition, especially with random atmospheric messages, it can get
tedious to see the same messages over and over if you spend a lot of
time in the same area.  It's therefore often the case that we want
frequent atmospheric messages when the player first gets to a
location, but then we want the frequency to drop dramatically after
the player has spent more than a few turns there.  To make this easy
to handle, add a couple of new properties: 'messageReduceAfter' is the
number of times that we want to see messages at the initial frequency,
and 'messageReduceTo' is a new value for 'messagePercent' that we'll
apply after we've generated the messages 'messageReduceAfter' times.
Make these nil by default, which means that there is never a reduction
in the frequency.  Authors can use these properties to generate random
atmosphere messages at high frequency at first, but then drop the
frequency to just an occasional message after the player has been in
the location long enough to get the idea.

</div>

<!------------------->
<div class=entry>

Add a new class, NominalPlatform.  This is a "secret" object: it's not
visible to the player as a separate simulation object, and won't
normally have any vocabulary or appear in any room listings.  The
purpose of this object is to make it easier to describe NPC's as
standing somewhere specific within a room; the author locates an NPC
within the NominalPlatform, and the library will automatically
describe the NPC as standing on the platform: "Bob is here, standing
in the corner."  The author can also customize the display methods for
the nominal platform so that the description is something like
"leaning against the lamppost."

</div>

<!------------------->
<div class=entry>

Add a new property to Thing, specialContentsLister, that lets
individual objects and rooms customize the lister they use to generate
special descriptions.  Set the property by default to
specialDescLister.

</div>

<!------------------->
<div class=entry>

Add a new topicPhrase grammar rule that matches a miscWordList without
badness.  (The normal topicPhrase grammar matches a singleNoun, which
matches a miscWordList, but it does so with badness; we want to add an
explicit rule that matches a miscWordList without badness.)  It's in
the nature of topic phrases to go outside of what's implemented in the
simulation model; we don't want to treat resolvable and irresolvable
topic phrases any differently at the grammatical level, because doing
so can lead to inconsistencies when parsing a verb containing both a
topic and another kind of noun phrase.

</div>

<!------------------->
<div class=entry>

Add gLiteral to adv3.h, analogous to gTopic.

</div>

<!------------------->
<div class=entry>

Change Thing.dobjFor(Attack) so that the default Attack handling is
simply to display the message "it's useless to attack that."  Remove
the askIobjFor(AttackWith).  Specifying a weapon shouldn't be
required; especially for attacks like "hit" and "kick," asking for an
indirect object will seem wrong to a player.  This makes a tiny bit of
extra work for authors when AttackWith is overridden, since Attack
will have to be overridden as well in such cases, but this is probably
worthwhile anyway because it'll encourage authors to make the same
distinction between weapon and weaponless attacks that players are
likely to make in their own minds.

</div>

<!------------------->
<div class=entry>

Move the code from Contents.examineContainerContents into
Thing.examineStatus (actually, into a new method called from
Thing.examineStatus, call it examineListContents).  Get rid of
Surface.examineSurfaceContents.  Ordinary Thing objects should
traverse into their contents during Examine; this shouldn't be limited
to Container and Surface objects.  We need to do this listing in
Thing, because a Thing could contain a component that's a container,
and we want to list its contents when examining the Thing.

</div>

<!------------------->
<div class=entry>

Fix bug in Action.getObjPreconditions: if pre is nil before appending
the catch-all list, we'll get an error.  Check that pre is nil before
appending, and just use the catch-all list by itself if so.

</div>

<!------------------->
<div class=entry>

Change the TravelConnector.describeDeparture() and describeArrival()
interfaces to add a new parameter for the traveler.  Use the traveler
parameter instead of the global gActor.  This makes the travel
routines more flexible, and in particular allows them to be called
from outside of commands (in daemons, for example).  It also will
improve the handling for non-actor travelers (vehicles in particular).

</div>

<!------------------->
<div class=entry>

In RoomConnector.describeDeparture/Arrival, use gPlayerChar rather
than gActor as the point-of-view object in directionForConnector().
The description is being generated for the benefit of the player, so
it should be from the PC's perspective.

<p>
Split off a new method from each of Traveler.describeDeparture and
describeArrival: describeNpcDeparture/Arrival, which is called when
an NPC (or a traveler not involving the PC) is doing the travel.
This will simplify overriding the messages for vehicles and other
special travelers when desired, since the overriding method won't
have to make all of the checks to see if it's the PC doing the travel.

</div>

<!------------------->
<div class=entry>

Run all of the libMessages.sayDeparting/Arriving connector-specific
messages through an intermediate method call in the Traveler; these
new Traveler methods by default are simply be covers for calls to the
libMessages methods.  The purpose of the extra layer of calls through
Traveler is to make it easier for individual Traveler subclasses to
customize the messages on a per-connector-subclass basis.

</div>

<!------------------->
<div class=entry>

'@script.txt' at the command prompt should start reading from the
named script file.  (This should work essentially the same way it did
in tads 2, except that we want to handle this in the library instead
of in the interpreter.)  Also, '@@script.txt' should run the script in
"quiet mode," which is to say that input and output generated while
reading the script are to be suppressed.

</div>

<!------------------->
<div class=entry>

Add some new classes to misc.t for "shuffled" random selections.  A
shuffled selection is a random selection taken from a set of values
that doesn't repeat a selection until we've gone through all of the
values once, like dealing from a shuffled deck of cards.

<p>
ShuffledList: the basic shuffled selection class.  Keeps a list of
values, and returns a randomly selected element on demand.

<p>
ShuffledIntegerList: a specialization of ShuffledList that returns
a randomly selected integer from a given range.

<p>
ShuffledTextList: a subclass of RandomTextList that makes its
selection using shuffling rather than independent random selection.

</div>

<!------------------->
<div class=entry>

Add a point-of-view parameter to Thing.showSpecialDescWithInfo().

</div>

<!------------------->
<div class=entry>

Add a parameter to the following library messages to indicate which
object is being described (the object is needed for things like gender
and number agreement in some languages):

<p>
openMsg, closedMsg, lockedMsg, unlockedMsg, onMsg, offMsg

</div>

<!------------------->
<div class=entry>

Add a parameter to the following library messages to indicate which
actor is being described (the actor is needed for things like gender
and number agreement in some languages):

<p>
statusStanding, statusSitting, statusLying,
statusStandingOn, statusSittingOn, statusLyingOn

</div>

<!------------------->
<div class=entry>

Add a parameter to the various name methods in ThingState (listName,
inventoryName, wornName) providing a list of the objects being shown
in this state.  This is needed for some languages so that the state
description can agree (in gender and number, for example) with the
objects being desribed as being in the state.

</div>

<!------------------->
<div class=entry>

Change the count parameter to the full list in
actorStandingGroupPrefix and the related methods in libMessages.
This will allow the prefix/suffix messages to check any attributes of
the individual objects in the list, such as gender mix, that might
affect the message.

</div>

<!------------------->
<div class=entry>

The INSTRUCTIONS command should not take any turns (make it a
"system" command).  Also, it should not consume any game time on the
real-time clock (which, given the size of the instructions, could be
noticeable).

</div>

<!------------------->
<div class=entry>

Add an extended form of inputManager.getInputLine(), which takes a
new InputDef object to define the input parameters.  Use this new
parameter definitions object to determine what to display to set and
remove the input text style; do this instead of unconditionally using
the <.inputline> style tag.  The InputDef class should use
<.inputline> as the default, of course.  Keep the existing
getInputLine() method, but make it a cover for a call to the new
extended version, setting up an InputDef object representing the
parameters.

</div>

<!------------------->
<div class=entry>

Make "remove" (with a direct object but no indirect object) a fully
separate verb from "doff".  In English, "remove foo" usually means
"doff foo", but it can also have the substantially separate sense of
removing a component of an object.  In the English library module,
provide a default mapping of "remove" to "doff" in Thing, to keep the
default meaning the same.  Making a separate Remove action will allow
this action to be independently overridden per object when it's
desirable to do so.

</div>

<!------------------->
<div class=entry>

By default, don't list anything in the credits for a library module.
We should leave the formatting of the credits fully up to the author.

</div>

<!------------------------------- 3.0.5 --------------------------------->
<div class="sepbar"><a name='305'></a>3.0.5</div>

<div class=firstentry>

Add an optional mainRestore() function, to be provided by the game
and called from the run-time startup code when a saved game is
explicitly selected for restoration at startup (such as by
double-clicking on a saved position file from a GUI desktop, or using
the "-r" option with the command-line interpreter).

</div>

<!------------------->
<div class=entry>

Change runGame() so that it no longer takes the initial player
character parameter.  Instead, callers should always set gPlayerChar
explicitly prior to calling runGame().  (This change makes runGame()
more sensible for cases where a game is restored: since the restore
operation will restore gPlayerChar as part of restoring the rest of
the game's state, it would be redundant to pass gPlayerChar as a
parameter to runGame() only to have runGame() set gPlayerChar to that
value.)

</div>

<!------------------->
<div class=entry>

Fix the bug in EventManager.removeMatchingEvents ('eventMatches' should
be 'cur.eventMatches')

</div>

<!------------------->
<div class=entry>

Add a new output stream method, addOutputFilterBelow(), which adds an
output filter at a given point in the filter stack.

</div>

<!------------------->
<div class=entry>

Remove the "\( \)" escape sequences (for highlighted text).  Authors
should use HTML markups <B> and </B> instead.

</div>

<!------------------->
<div class=entry>

Combine open/closed and contents status listings into a single
message, to make the openable container default description less
choppy.

</div>

<!------------------->
<div class=entry>

Rename maxBulk to bulkCapacity, to make the meaning clearer.
Similarly, rename maxWeight to weightCapacity.

</div>

<!------------------->
<div class=entry>

>put trike in bag. drop bag. ride trike.
(produces a run-time error)

The problem is that we're failing to treat the bag as an invalid
"staging location" on the way to boarding the trike.  Add a routine,
checkStagingLocation, to Thing, and call when moving an actor into a
chosen staging location; this routine should generate an error
explaining why the travel is impossible and terminate the command
with 'exit'.  BasicLocation should override this to allow being used
as a staging location.

</div>

<!------------------->
<div class=entry>

add default Thing handling for 'feel' and 'taste' commands

</div>

<!------------------->
<div class=entry>

<pre>
>close bag; x all in bag
red ball: You cannot see that. [etc]
</pre>
<p>
We're incorrectly resolving the contents of an object for an "all in
x" phrase, even when the contents can't be seen.  We must filter the
resolved objects to include only the visible contents.

</div>

<!------------------->
<div class=entry>

"all in x" doesn't filter for objects hidden from "all" phrases; it
should.

</div>

<!------------------->
<div class=entry>

Standing should be a precondition of "jump".

</div>

<!------------------->
<div class=entry>

The noMatchDisambig and disambigOrdinalOutOfRange messages should use
<.parser> open tags, but not close tags: instead, the <.parser> mode
should be left open, to be closed by the disambiguation re-prompt that
always follows.

<p>
askDisambig should provide an open <.parser> tag if and only if askAgain
is false: this will let the mode flow in from the preceding re-prompt
message from noMatchDisambig or disambigOrdinalOutOfRange.  askDisambig
should always close the <.parser> tag.

</div>

<!------------------->
<div class=entry>

Get rid of parserMessage(), and just use <.parser> tags instead.

</div>

<!------------------->
<div class=entry>

We shouldn't be able to read at brightness 2.  For Readable,
differentiate readability according to brightness and transparency,
as long as a readDesc is defined.  (When no readDesc is defined for
the object, use the default "examine" behavior as usual.)

</div>

<!------------------->
<div class=entry>

Disambiguation: when indistinguishables are involved, answering with
an ordinal applies the ordinal to the full list, rather than the
reduced list offered:

<p><pre>
>take coin
Which coin do you mean, a gold coin, a silver coin, or a copper coin?

>second
Taken. [actually takes a gold coin, since more than one was present]
</pre>
</div>

<!------------------->
<div class=entry>

Add a new option flag, libGlobal.allowYouMeMixing, that controls
whether or not the parser accepts "you" and "me" in commands as
equivalent.  Set this to true by default, since most games will not
have both first- and second-person narrative characters at the same
time, and hence it seems unlikely that it will ever create confusion
if the player can use "you" and "me" interchangeably.  (Having the
option to make the parser strict about this will take care of any
cases where a game actually does have separate first- and
second-person characters present simultaneously.)

</div>

<!------------------->
<div class=entry>

The forwarding scheme isn't quite right.  Replace it.

<p>
First, get rid of dobjForwardTo, iobjForwardTo, remapTIAction,
dobjRemapTI, iobjRemapTI, dobjRemapTIReverse, and iobjRemapTIReverse.

<p>
Second, add a new mechanism that combines the old forwarding and
remapping schemes into a single new system.  Use syntax like so:

<p><pre>
desk: Fixed
  dobjFor(Open) remapTo(Open, drawer)
  dobjFor(Close) remapTo(Close, drawer)
;
</pre>
<p>
The first definition above maps the Open action, when applied to the
desk, to a replacement action of Open applied to the drawer instead.
The second does the same thing for Close.  This replaces the old
dobjForwardTo/iobjForwardTo scheme, so we no longer need forwarding at
all.  The difference with the new remapTo scheme is that we use a
replacement action for the remapping - the remap for Open above is
essentially like using replaceAction(Open, drawer) for the action
definition of Open on the desk.

<p>
Further, consider this syntax:

<p><pre>
lid: Fixed
  dobjFor(Push) remapTo(Open, jar)
  dobjFor(Pull) remapTo(Close, jar)
;
</pre><p>
Here we've remapped not only the object (as we formerly did with
forwarding), but also the action.  The first definition above says
to replace "push lid" with the new action "open jar."

<p>
Next, consider this:

<p><pre>
ninjaThrowingStar: Weapon
  iobjFor(AttackWith) remapTo(ThrowAt, self, DirectObject)
;
</pre>
<p>
In this case, we're doing what the old dobjRemapTIReverse did, but
with considerably clearer syntax.  We're saying that when we resolve
the indirect object of "attack with" and find that it's the throwing
star, we should remap the action to "throw <ninjaThrowingStar> at
<direct object>", where <direct object> is the original direct object
of the AttackWith action.  The important thing about using the
"DirectObject" argument is that it tells us to use the pre-resolved
match tree for the direct object if we haven't yet resolved the direct
object noun phrase - this means that we'll be able to resolve that
noun phrase in the context of the new action (ThrowAt) rather than in
the original action (AttackWith) context.

</div>

<!------------------->
<div class=entry>

Compiler: for each nested object definition, set a property of the
nested object, 'lexicalParent', to point to the lexically enclosing
object.

</div>

<!------------------->
<div class=entry>

Change the default message for talking/asking/etc a random object to
indicate more specifically that it's illogical to talk to the object.

</div>

<!------------------->
<div class=entry>

Add a class for a complex container, for objects that contain objects
in multiple ways.  Examples: a crate that can contain things within
and also have objects placed on top of it; a container with
components.

<p>
The class should treat all of its immediate contents as components,
so it should be based on Thing rather than Container or Surface.  It
should have two additional properties: one for a secret object that
serves as the internal container, and another for a secret object
that serves as the internal surface.  Commands like "put in" and
"look in" should be redirected to the internal container, if one is
defined; "put on" and the like to the internal surface, if present.
The contents lister must specifically show the contents of the secret
internal container and surface as though they were contained directly
by the outer object.

</div>

<!------------------->
<div class=entry>

Change default Thing handling for Push, Pull, Move, MoveWith (dobj),
and MoveTo (dobj), so that verification succeeds with a logicalRank
of 50, and report that there is no effect in the action.  (These
actions all involve physical manipulations that a player might want
to try with any object, so it's better to allow these to pass
verification, so that preconditions can be allowed to proceed rather
than halting before even getting to preconditions.)

</div>

<!------------------->
<div class=entry>

OutOfReach seems to put the object itself (not just its contents) out
of reach.  Add a separate test for reaching 'self'.

</div>

<!------------------->
<div class=entry>

In Actor.canReach, don't make touching our immediate location a special
case - just traverse the sense path to the container as normal.

</div>

<!------------------->
<div class=entry>

<pre>
>look in stove
(First opening the stove)
Opening the stove reveals a loaf of bread.  The stove contains a loaf of bread.
</pre>
<p>
It would be good to remove this redundancy: if we're opening
something implicitly for a look-in command, we shouldn't bother
showing what the opening reveals.  (We can handle this in Openable's
Open action handler: if the action is implied, and the parent action
is LookIn with the same direct object, we can suppress the revelation
message.)

</div>

<!------------------->
<div class=entry>

Suppress default "you see nothing special about it" or "it's an
ordinary x" descriptions when there's a special status message,
such as contents to be listed.

</div>

<!------------------->
<div class=entry>

<pre>
>look in small alcove
You see nothing in it.  A trophy is visible...
</pre>
<p>
(Perhaps if we special description items, and nothing listed, we should
display no message at all.)

</div>

<!------------------->
<div class=entry>

Use tags for line-input modes in commandSequencer, eliminating method
calls.  This should remove the fragile order-of-call issues that we
currently have.

</div>

<!------------------->
<div class=entry>

Should we reformat some messages involving implied commands?  For example:

<p><pre>
>put coin in bag
(first opening the bag)
Opening the bag reveals a keyring. Done.
</pre>
<p>
Perhaps we should put that "done" on a new line - no paragraph separator,
just a new line.  (In general, perhaps when there's a non-default response
from an implied command, we should add an "implied command terminator
separator," which by default would simply be a newline.)

</div>

<!------------------->
<div class=entry>

Rename the English-specific part of the library to make it easier to add
new languages in the future.  In particular:

<ul>
<li>Create a new US English subdirectory of the
adv3 library directory; use ISO 639/3166 codes for the naming
convention, so the US English directory is called en_us.

<li>Move us_eng.t to en_us/en_us.t

<li>Move us_eng.h to en_us/en_us.h

<li>Move msg_neu.t to en_us/msg_neu.t

<li>Add a new library, en_us/en_us.tl.  Move the
English-specific source file inclusions out of adv3.tl and into
en_us.tl.

<li>Include the new en_us.tl library in the
auto-generated makefile for the new-project wizard in Workbench.
(We'll have to add a user preference at some point that lets the user
select the language library to use, rather than using en_us.tl
unconditionally.)
 </ul>

</div>

<!------------------->
<div class=entry>

Add a general IF instructions module (like instruct.t from tads 2)

</div>

<!------------------->
<div class=entry>

Fix nil dereference in transcript processing for ambiguous noun
phrase errors.

</div>

<!------------------->
<div class=entry>

Fix command state management for suffixes so that suffixes are always
generated before the prompt.  (We simply need to display <.commandbegin>
in intput.t before displaying the prompt.)

</div>

<!------------------->
<div class=entry>

Add a new command state, stateNoCommand, for interactive input.  In
this state, don't add any prefixes/separators/suffixes when reading
input.  This should be used for yes/no answers, answers to
end-of-game prompts, and so forth - for anything where we need to
read input interactively in the course of a command.

</div>

<!------------------->
<div class=entry>

Move en_us.t Thing vocabulary initialization code to VocabObject.

</div>

<!------------------->
<div class=entry>

For commands like "put coin with jar," we're asking "what do you want
to put," which is a weird question.  (This happens because we
interpret this as "put coin with jar in missing-np" and then resolve
the iobj first; this asks the usual question, which comes out the way
it does because the dobj tentatively resolves to an empty list since
it is a non-matching phrase.  To solve this, we could use a dummy
entry in the tentative resolution list, to signal that we actually
have a dobj phrase, even if it's not resolvable to anything.)

</div>

<!------------------->
<div class=entry>

It might be nice to catch constructs like this:

<p><pre>
>open door with key
You see no door with key here.
</pre>
<p>
In particular, it might be nice to recognize "&lt;nounPhrase> &lt;prep>
&lt;nounPhrase>" constructs specifically, and flag them as "command not
understood" errors instead of "object not seen" errors.  This could be
handled by adding a "badness" production for np-prep-np structures for
the prepositions commonly used in command phrases; by making this a
badness match, we'll match it as a last resort when we can't find a
valid verb phrase structure.

</div>

<!------------------->
<div class=entry>

Add an extra category of reports, "extraReport", that's used to add
extra information that doesn't replace any default report.  Use this
for the key-found-on-keyring report, since this report is supplemental
to any default Locked/Unlocked report and shouldn't suppress it.

</div>

<!------------------->
<div class=entry>

Move the call to initializeVocab out of Thing.initializeThing, and
instead call initializeVocab directly from adv3LibPreinit.execute()
for each VocabObject.  (This will initialize vocabulary for non-Thing
VocabObjects, such as Topic objects.)

</div>

<!------------------->
<div class=entry>

Add a new inputManager method, promptForMore(), that shows the MORE
prompt, taking care of flushing the transcript and dealing with the
real-time clock.  The method should take an argument specifying
whether or not to freeze the real-time clock; but even if the clock
keeps running, real-time events shouldn't be allowed to occur until
after the user acknowledges the MORE prompt, because otherwise we'd
defeat the purpose of the MORE pause, which is to wait for user
acknowledgment before showing any new output.

</div>

<!------------------->
<div class=entry>

Change the Decoration class so that its generic not-important message
can be overridden simply by changing a property, rather than having
to override all of the Default handlers individually.

<p>
Likewise for Distant and Intangible.

</div>

<!------------------->
<div class=entry>

Add a new 'isTopLevel' property, which determines if an object is a
top-level container within the game world.  Set this to nil by
default for everything except Room objects, where we set it to true.
Use this property in evaluating isIn(nil): for an object with a nil
location, isIn(nil) returns true if and only if the object is NOT
top-level.  This allows isIn(nil) to be used to sense whether or
not the object is part of the game world, recursively considering
the status of the object's containers.

</div>

<!------------------->
<div class=entry>

Remove selfInReach from OutOfReach.

</div>

<!------------------->
<div class=entry>

Fix problem with TravelConnector.verifyTravel(): when this routine is
called, gVerifyResults is not reliably set to a valid list.  In
particular, gVerifyResults must be set to a valid result list from
TravelAction.verifyAction().

</div>

<!------------------->
<div class=entry>

Turn on the sense cache while generating the status line.  Displaying
the status line can involve some substantial sense calculations, so
enabling caching while generating it can improve overall response
time noticeably.

</div>

<!------------------->
<div class=entry>

Fix 'follow wall' (generates nil pointer error)

</div>

<!------------------->
<div class=entry>

Fix 'throw x at wall' (or floor or other room parts - nil pointer error)

</div>

<!------------------->
<div class=entry>

Fix nil pointer error when addressing an ambiguous target actor.

</div>

<!------------------->
<div class=entry>

<pre>
>sit on darker chair
>sit on chair
Which one?
>darker
</pre>
<p>
This is allowed, but shouldn't be - the reply should be "you're
already sitting on the darker chair."  (The problem is that we verify
the lighter chair as okay, and we remember that we verified something
as okay but don't bother remembering what; we need to track which
objects we verify as okay individually.)

</div>

<!------------------->
<div class=entry>

Make searching a surface (or looking in a surface) show the surface's
contents.

</div>

<!------------------->
<div class=entry>

Check bulk when adding a new item to a surface.  (This will fix the
weird inconsistency with chairs that allows you to put an object
on a chair you're sitting on, even if there's not room for you to
sit on the chair when the object is already on it.)

</div>

<!------------------->
<div class=entry>

Reduce the verification logical rank of non-Food objects for >TASTE.

</div>

<!------------------->
<div class=entry>

<pre>
>sit on chair
>look
... You contain a keyring ...
</pre>
<p>
(We shouldn't mention your contents in that manner.  The problem is
that Actor inherits contentsListed from Fixed; Actor should override
contentsListed and set it to nil, since an actor's contents shouldn't
be listed in the ordinary fashion in a room description.)

</div>

<!------------------->
<div class=entry>

Show object contents for EXAMINE and LOOK IN to full depth.

</div>

<!------------------->
<div class=entry>

Searching (or looking in) a room part shows contents as being "in"
it, which isn't appropriate for walls, ceilings, or floors.

</div>

<!------------------->
<div class=entry>

For THROW AT FLOOR, perhaps we should have a message other than
"Dropped" - something indicating the action is more violent than
just setting the object down.

</div>

<!------------------->
<div class=entry>

Make contents listings go to arbitrary depth.  Rather than showing a
separate list for the contents of top-level list items, show the
contents of each item parenthetically, and then recursively add these
parenthetical lists to show all contents.  (Only do this when the
ListRecurse flag is set.)

<p>
Add a new Thing property, contentsListedSeparately, that allows an
object to control whether its contents are listed in the new in-line
style, or as the traditional separate list.  Make this nil by default.

</div>

<!------------------->
<div class=entry>

For "tall" listings, show contents of unlisted top-level items in
separate lists after the main list, just as we do for "wide" listings.

</div>

<!------------------->
<div class=entry>

Remove the need to call showContentsList() separately after showList();
instead, call this automatically from showList() if the ListRecurse
flag is set.

</div>

<!------------------->
<div class=entry>

Throwing destinations aren't working quite right.  Refactor things a
bit: rename getFallDestination() to getHitFallDestination(), and give
it the previous container in the path as a parameter, so that it can
decide whether the object is being thrown from inside or outside (or,
in the case of a multi-location item, the source location).  Make
things drop to the floor in most cases; games can override to make
things fall into intermediate containers when desired.

</div>

<!------------------->
<div class=entry>

Change Actor.standUp to use reportFailure() when already standing.

</div>

<!------------------->
<div class=entry>
<p><pre>
>out
Out of what?
>e
You can't get out of that (the east wall).
</pre>
<p>
It would be nice to treat such responses as new commands.  We could
probably adopt the heuristic that we give the new command
interpretation priority over the noun phrase interpretation of a reply
to this prompt.  Anything that looks like both a syntactically valid
noun phrase and a syntactically valid command probably matches the
noun phrase syntax only because it's extremely abbreviated; the
chances of the verb phrase match being an accident are somewhat less.
In addition, it should be less confusing to the user to treat the
response as a new command when a noun phrase was intended than vice
versa, and it should be fairly obvious how to force a noun phrase
interpretation (adding "the" would do the trick, for example).

</div>

<!------------------->
<div class=entry>

Can we go to arbitrary depth for contentsListedSeparately?  In particular:

<p><pre>
  >i
  You are carrying a duffel bag (which contains a pen cup).  The
  pen cup contains four pens.
</pre>
<p>
Right now, we're not adding that bit about the pens, because we think
we're done with the top-level list, as we've already listed
everything: we scan the duffel, and decide that we don't need to
recurse into it, since it's listed and has in-line listed contents.
What we'd need to do is add another recursive descent to look for
everything that we listed at the second (or deeper) level that has
contentsListedSeparately.

</div>

<!------------------->
<div class=entry>

Tweak the parser's command match-tree ranking mechanism a little, so
that differences in the number of occurrences of a problem are counted
in a second pass, after we've exhausted the possibility of any
differences in the presence or absence of problems.  This will make
slightly better choices in certain cases, such as when we have two
separate noun phrases in the action, and one interpretation treats
only one as ending in an adjective while the other has an adjective
ending in both phrases.

</div>

<!------------------->
<div class=entry>

Add a profiling facility, to gather statistics for performance
optimizations in the library.

</div>

<!------------------->
<div class=entry>

Rename senseInfoList to senseInfoTable, and make it return a
LookupTable rather than a list.  Sense information lists are almost
always used as random-access tables, so we can speed up some
operations by representing these as lookup tables keyed on object.

</div>

<!------------------->
<div class=entry>

Rename connectionList to connectionTable, and make it return a
LookupTable rather than a list.  Since we want only one copy of each
object in the result, it's faster to build this as a lookup table,
where we can determine whether or not an object is already present
much more quickly than we can with a vector.

</div>

<!------------------->
<div class=entry>

<pre>
>e
>put cup in desk
>undo
</pre>
<p>
(Takes back turns through "e".  The problem is that we're marking a
remapped action as a nested action; it's not really nested, because
the original action is completely replaced and will never reach the
execution phase.  Do not mark remapped actions as nested.)

</div>

<!------------------->
<div class=entry>

Add Thing.specialDescOrder to control specialDesc the relative order
of specialDesc listings.

</div>

<!------------------->
<div class=entry>

Change the format of the first-score-notification supplemental
message, which explains how to turn off score notifications: rather
than showing it as part of the same paragraph with the score, start a
new line and show it as a separate notification message.

</div>

<!------------------->
<div class=entry>

Rename UnqualifiedPluralProd to DefinitePluralProd.  In the English
parser, base implicitDetPluralOnlyNounPhrase(main) and
explicitDetPluralNounPhrase(definite) on DefinitePluralProd, since
"books" and "the books" should act the same way in English.

</div>

<!------------------->
<div class=entry>

Simplify the Key and Keyring Attach and Detach handling by using
remapTo() in the keyring: remap "attach x to keyring" to "put x on
keyring" in Keyring.iobjFor(AttachTo), and remap "detach x from
keyring" to "take x from keyring" in Keyring.iobjFor(DetachFrom).
This removes a bunch of code from Key to handle the remapping at its
end - that code all predated the remap mechanism, and can now be
greatly simplified by using the new mechanism.

</div>

<!------------------->
<div class=entry>

Fix a problem in vocabulary initialization: if a hyphen is used as a
placeholder in a vocabWords_ setting, the hyphen is added to the
object's part-of-speech property (it's not added to the dictionary,
but it does show up in the list for the part-of-speech property).  It
should be omitted from the list, since it's not really a vocabulary
word.

</div>

<!------------------->
<div class=entry>

Fix finishOptionUndo so that it can be used in daemons.  This requires
a couple of changes.  First, remove the transcript flush - this is a
relic of the pre-'transient' transcript mechanism and is no longer
needed.  Second, daemons and fuses need to be able to use
TerminateCommandException and the like to exit, so we should catch
command-ending exceptions in the event manager.

</div>

<!------------------->
<div class=entry>

Fix examining sightSize=large objects at a distance.  (The problem is
that Thing.canDetailsBeSensed() is attenuating the ambient light level
for the sense path, which is unnecessary as the SenseInfo already does
this.  canDetailsBeSensed doesn't need to go to so much trouble - any
SenseInfo with trans != opaque indicates the object can be sensed,
since trans will always be set to opaque for objects that cannot be
sensed.)

</div>

<!------------------->
<div class=entry>

Add tok.t to system.tl.  (This file isn't actually necessary to
compile a simple program, which is why it hasn't been in system.tl all
along; but it is necessary for any game based on the library, so on
balance it's probably better to include it in the default library.

</div>

<!------------------->
<div class=entry>

Separate some action-time checks into check() routines:
Container.dobjFor(LookIn); Dial.dobjFor(TurnTo) (this could perhaps
benefit from some 'verify' checking of the literal value as well).

</div>

<!------------------->
<div class=entry>

Add a specialDescLister, and use it for listing special descriptions.
Add a new property of Thing, specialDescListWith, which returns a list
group to use when showing special descriptions; use this new list
group generator in specialDescLister.  This will allow special
descriptions to be grouped when desired, simply by using the standard
list grouping mechanism.

</div>

<!------------------->
<div class=entry>

Add an "isCircularPassage" property to TravelConnector: when this
property of the connector is true, fully describe travel that winds
up in the origin.  (We normally don't bother describing such circular
trips, but sometimes it's desirable to be able to do so.)

</div>

<!------------------->
<div class=entry>

In en_us.t, add askDobjResponseProd=singleNoun for each action that
takes a singleDobj as its direct object.

</div>

<!------------------->
<div class=entry>

In en_us.t, remove the redundant syntax for "walk in/into" and "go
in/into" from VerbRule(GoThrough), as these are already handled by
VerbRule(Enter).

</div>

<!------------------->
<div class=entry>

In en_us.t, use <Q> tags wherever literal quotes are used, rather than
ASCII-34 quotes.

</div>

<!------------------->
<div class=entry>

Convert the parser to use the new Dictionary API.  In the English
parser, install a StringComparator to perform case folding and
truncation matching.  Remove case conversions from the English
tokenizer, as they're not needed with the StringComparator.

</div>

<!------------------->
<div class=entry>

Refactor the travel connector operations so that everything turns into
a TravelVia on its connector.  Handle direction commands ("go north")
by using replaceAction(TravelVia, connector).  This simplifies the
travel verbs, and makes the task of defining travel connectors more
consistent with defining other action handlers.

</div>

<!------------------->
<div class=entry>

Move the travel connector checks for dark-to-dark travel and for
travel barriers into the TravelVia check() handler.

</div>

<!------------------->
<div class=entry>

Rearrange the room description code (lookAroundPov, etc) so that
lookAround can be called on any object.  To do this, move all of the
room description mechanism from BasicLocation into Thing, and work the
NestedRoom code into the Thing code for descriptions.

</div>

<!------------------->
<div class=entry>

Add a return value to basicEventManager.removeMatchingEvents,
indicating whether or not a matching event was actually found.

</div>

<!------------------->
<div class=entry>

Fix getTenativeLiteralText argument mismatches in parser.t when
calling getLiteralText.

</div>

<!------------------->
<div class=entry>

In MessageBuilder.generateMessage(), for the case where we're
substituting '{actor}' but there's no current action, use the current
gActor value if it's not nil, or gPlayerChar if gActor is nil (rather
than always using gPlayerChar - using gActor instead allows a daemon
or other non-action message producer to set gActor to indicate the
actor doing whatever it is that's generating the message).

</div>

<!------------------->
<div class=entry>

In Actor.addPendingAction() and addFirstPendingAction(), take
a resolved object list as the last varargs-list argument, and pass
it to the PendingCommandInfo constructor.

</div>

<!------------------->
<div class=entry>

Hide Fixed objects from "drop all".

</div>

<!------------------->
<div class=entry>

Add some more default verbs: CutWith, Kiss.

</div>

<!------------------->
<div class=entry>

Add RoomPart.isIn().  Consider a RoomPart to be within a given location
if its room part location is equal to or within the given location, or
the inherited isIn returns true.

</div>

<!------------------->
<div class=entry>

Add some more string-quoting styles to the English tokenizer: `like
this', and with typographical ("curly") single and double quotes
(\u2018 and \u2019 for single quotes, \u201c and \u201d for double).

</div>

<!------------------->
<div class=entry>

Add a quotedStringPhrase production type, for rules that explicitly
call for quoted strings (but not unquoted literal text).  Use this
production to build the quoted string rule for literalPhrase.

</div>

<!------------------->
<div class=entry>

Add SAVE, RESTORE, and SCRIPT command variations that take quoted
strings giving the filenames to use.

</div>

<!------------------->
<div class=entry>

Traveler.travelTo in a daemon dereferences gAction - check to see if
gAction is nil, and skip that step if so.

</div>

<!------------------->
<div class=entry>

Change all uses of 'seen' to use the seenBy() and setSeenBy() methods.
Move these from BasicLocation into Thing so that all objects uses them
uniformly.

</div>

<!------------------->
<div class=entry>

Bug: TERSE mode doesn't show full descriptions on first entry.

</div>

<!------------------->
<div class=entry>

Some of the objects shown in the introductory room description aren't
getting marked as seen.  (The problem is that Thing.lookAroundWithin
is using gActor in a few places where it should be using the 'actor'
parameter.)

</div>

<!------------------->
<div class=entry>

Bug: NoTravelMessage is commented as being an apparent connector, but
is implemented as a non-apparent connector.  Leave the implementation
the way it is, but fix the comments, and add a new class that acts the
same as NoTravelMessage but has an apparent connector (call it
FakeConnector, perhaps).

</div>

<!------------------->
<div class=entry>

Rename LiteralAction to LiteralTAction.  Add a new LiteralAction
class that takes only a literal phrase as its object (i.e., no other
direct object), for commands like "say random stuff".

Note that DefineLiteralAction is likewise renamed to
DefineLiteralTAction, and we add a new DefineLiteralAction for
defining an action with only a literal phrase for its object.

</div>

<!------------------->
<div class=entry>

Add a PostUndoObject class, analogous to PostRestoreObject.

</div>

<!------------------->
<div class=entry>

Reduce parse rankings for pronoun phrases vs noun phrases: if a word
is explicitly defined as noun, it probably should be a stronger match
than a pronoun interpretation of the same word.

</div>

<!----------------------------------- 3.0.4 --------------------------------->
<div class=sepbar><a name='304'></a>3.0.4 and earlier</div>

<div class=firstentry>

Consider this command:

<p><pre>
>put ball in asdf
Which ball do you mean, the red ball, or the green ball?

>red
The story doesn't know the word 'asdf'.

>oops box
Which ball do you mean, the red ball, or the green ball?
</pre>

<p>
The issue is that OOPS retries the entire command with an updated
token list, and as a result, the disambiguation work from the first
attempt at resolving the objects is lost for the second iteration.
The reparsing is necessary, since the corrected typo could change
the entire meaning of the command.

<p>
One possible solution: add a resolution pass specifically to catch
unknown words.  Don't do any other resolution on this pass - just
deal with unknown words.  This would ensure that we process OOPS
before we ask any disambiguation questions.

<p>
Another possibility: keep a set of answers to questions, and the
conditions under which the questions were asked.  Clear the list
each time we start a new parsing from scratch, but let the list
survive if we reparse a token list.  Whenever we're about to ask
a question, look to see if the same question has been asked with
the same conditions, and if so, reuse the same response.

</div>

<!------------------->
<div class=entry>

All

</div>

<!------------------->
<div class=entry>

Missing noun phrases: prompt for input when PC gave command

</div>

<!------------------->
<div class=entry>

Missing noun phrases: use a default when possible

</div>

<!------------------->
<div class=entry>

Object announcements: include a preposition when appropriate (announcing
indirect object, announcing direct object with verb taking a preposition:
">dig \n (in the dirt)")

</div>

<!------------------->
<div class=entry>

Pronouns

</div>

<!------------------->
<div class=entry>

Again

</div>

<!------------------->
<div class=entry>

Again: should we use disambiguation information from past commands?
For example:

<p><pr>
>take book
Which book do you mean, the red one, the blue one, or the green one?

>blue
Taken.

>g
</pre>

<p>
Should this 'take blue book' or should it ask...
Which book do you mean, the blue one, or the green one?

<p>
Right now we use the literal tokens from the original command, so we
ask the disambiguation question again.  This is exactly what we want
in cases with indistinguishables:

<p>
<pre>
You see five silver coins here.
>take coin
Taken.
>g
Taken.
</pre>

<p>
But in cases where we have distinguishable objects, we probably want
the resolved objects, not the words.

<p>
We probably want to distinguish this way: if we had indefinites or
indistinguishables, resolve again from the original text.  Otherwise,
use the original resolution.

</div>

<!------------------->
<div class=entry>

disambiguation: we're not keeping the full list properly in cases of
indistinguishables:

<p>
<pre>
>take coin
Which coin, a gold coin, or a silver coin?

>coin
Which coin, the silver coin, or the gold coin?
</pre>

<p>
The second time around, the cardinality of the full list should not change,
so we should be asking the same question as the first time.

</div>

<!------------------->
<div class=entry>

Preconditions

</div>

<!------------------->
<div class=entry>

We need 'touchDobj' and 'touchIobj' preconditions - use these for all
objects that require that the object be physically manipulated by the
actor but not necessarily held.  These are required to deal with things
like the contents of a closed transparent container, where an object
can be in scope but cannot be manipulated.

<p>
As part of this, we need to find a way to say what object blocks a
sense path opaquely, so that we can say why we can't touch something
that we can see.  There are two main cases: containers are in the way,
and connectors are in the way.

</div>

<!------------------->
<div class=entry>

Bag of holding: when an actor's hands are full and the actor is trying
to take something, pick a held object and try to find a bag of holding
for it.  First, check the object's preferredHolder property - this
gives an object or class that the object prefers as its bag of holding.
If the actor is holding such a holder, move the object to the holder.
If we can't find any affinity, look for any object the actor is holding
of the generic BagOfHolding class.

<p>
Examples of specialized bags of holding: wallet, key ring, purse, duffel
bag.

</div>

<!------------------->
<div class=entry>

Formatting: where does the blank line come from before an implicit
message for a single command?

</div>

<!------------------->
<div class=entry>

use disambiguation filter even for indefinites, so we pick the best
possibility if there are objects of different likelihoods

</div>

<!------------------->
<div class=entry>

"The red one" should work for exclusion lists.  It should probably also
work in general - although 'one' should bind more tightly to an actual
name, in the absence of a name it should serve as a generic noun.

</div>

<!------------------->
<div class=entry>

"drop coins" - should we consider only the ones we're carrying?  In other
words, should we run verification and include only the logical ones?
Probably - if there are some logical and some not logical, apply the
command only to the logical ones; otherwise, apply the command to all
of them.

</div>

<!------------------->
<div class=entry>

"take both coins" - really wacky

</div>

<!------------------->
<div class=entry>

"take two gold" should work (i.e., quantified ending in adjective)

</div>

<!------------------->
<div class=entry>

consider:

<p>
<pre>
>take both coins
Which two (of five gold coins or three silver coins) do you mean?

>two gold
You don't see that many coins here.
</pre>

<p>
The problem is that we disambiguate with the reduced match list.

</div>

<!------------------->
<div class=entry>

<pre>
>take coin
Which coin, gold, silver, or copper?

>all but copper
</pre>

<p>
no worky - might even be a gram prod bug, since we seem to have a weird
firstToken/lastToken value in these cases

</div>

<!------------------->
<div class=entry>

"take books except red" - disambiguation of the exclusion list should be
limited in scope to the resolved plural list.

</div>

<!------------------->
<div class=entry>

"take books except silver" - "You see no silver here" - this should
ignore the missing object.

</div>

<!------------------->
<div class=entry>

"take coins except copper" - the 'copper' should implicitly be plural
rather than indefinite so that we skip all of the copper coins if there
are several

</div>

<!------------------->
<div class=entry>

<pre>
>take gold coin, gold coin
gold coin: Taken.
gold coin: You're already carrying the gold coin.
</pre>

<p>
When we have multiple equivalent items in scope, and we mention several
items in a list, we should pick separate equivalent instances for each
mention.

<p>
This should apply to disambiguation responses, too:

<p>
<pre>
>take coin
Which coin do you mean, a gold coin or a silver coin?

>gold, gold
</pre>

</div>

<!------------------->
<div class=entry>

"take any ball except green" - takes the green if there's nothing else
left

</div>

<!------------------->
<div class=entry>

add verification for pre-conditions - objHeld, for example, would boost
the likelihood for a held object

</div>

<!------------------->
<div class=entry>

add the new pre-execution check as a separate phase (checkXxx?)

</div>

<!------------------->
<div class=entry>

output capturers - one at a time

</div>

<!------------------->
<div class=entry>

add object affinities for bag of holding

</div>

<!------------------->
<div class=entry>

key ring - not just a bag of holding, but automatically adds items
as they're picked up when the key ring is in inventory

</div>

<!------------------->
<div class=entry>

Key ring messages: we should check for a non-default report, and if there
is no non-default report we should include more details: "You take the
key and put it on the keyring."

</div>

<!------------------->
<div class=entry>

Probably should have an objDirectlyHeld precondition.  This one would
be used for commands that physically move an object; objHeld would
continue to be used for commands that merely need to do something
with an object.  So, "put x in y" would require that x is directly
held, while "unlock x with y" would only require that y be nominally
held.  For objDirectlyHeld, we'll make the implicit command silent
if the object is being indirectly carried, so that we don't get weird
things like this:

<p>
<pre>
>i
You are carrying a paper bag.  The paper bag contains a key.

>drop key
(First taking the key)
Dropped.
</pre>

</div>

<!------------------->
<div class=entry>

If there's no doXxx, fail verification with a generic Illogical('you
can\'t do that').

</div>

<!------------------->
<div class=entry>

For travel: shouldn't we have a verify phase for moving the actor?

</div>

<!------------------->
<div class=entry>

need to export propNotDefined in a system file

</div>

<!------------------->
<div class=entry>

take key: if it started on the keyring, we should take it off the
keyring

</div>

<!------------------->
<div class=entry>

Travel connectors

</div>

<!------------------->
<div class=entry>

Fix 'i tall' listings to show contents with a better format

</div>

<!------------------->
<div class=entry>

Move senses to a separate module.

</div>

<!------------------->
<div class=entry>

<pre>
>get coin
Which coin, a gold coin, a copper coin, or a silver coin?

>coin
Which coin, a copper coin, a silver coin, or a gold coin?
</pre>

<p>
The re-ordering on the second round is weird - we should keep the order
stable if we can.

</div>

<!------------------->
<div class=entry>

<pre>
>get ball
Which ball, red or green?

>blue
You don't see that here.
</pre>

<p>
The error shouldn't be "you don't see that here" - it should be more
like "that's not one of the choices you were offered."  However, it
would be better to widen the scope again to the real scope, rather
than failing.

</div>

<!------------------->
<div class=entry>

Add maxWeight and weight enforcement

</div>

<!------------------->
<div class=entry>

Move pre-conditions to the objects.  Keep the verb preconditions as
well, but verb-specific pre-conditions should never mention the
objects.

</div>

<!------------------->
<div class=entry>

Mark objects for which we've displayed descriptions, for topic scoping

</div>

<!------------------->
<div class=entry>

Add "module ID" objects, for library extensions.  The "credits" command
should run through the module ID's and show a credit for each one.

</div>

<!------------------->
<div class=entry>

Make styles into objects

</div>

<!------------------->
<div class=entry>

Fuses and daemons

</div>

<!------------------->
<div class=entry>

Need to apply logical tests again after running preconditions.  (Try
this: "put rusty key on keyring" - it'll pick up the key for the
'held' precondition, which will put the key on the keyring, but then
the explicit put-on-keyring command will succeed, which it shouldn't.)

</div>

<!------------------->
<div class=entry>

Generalize the showList mechanism to allow for other types of
hierarchies besides contents to be shown.  Use the lister interface
to virtualize the hierarchy traversal.

</div>

<!------------------->
<div class=entry>

Use the generic showList mechanism for the full score lister, rather
than using a specialized lister that does essentially the same thing.

</div>

<!------------------->
<div class=entry>

Score change notifications: add daemon that senses score changes and
notifies between turns.

</div>

<!------------------->
<div class=entry>

Do not count the time taken for implicit commands.

</div>

<!------------------->
<div class=entry>

Add a "message generation context" that determines what is generating
messages.  This object must be sensible to the player character for
messages to be generated.  For convenience, define a callWithMessageContext
function that establishes the context, invokes a callback, then restores
the enclosing context.

<p>
When establishing a new context, we check to see if the generator is in
scope in the given sense.  If not, we hide messages; if so, we show
messages.

<p>
A nested context should actually be considered a context switch,
because we don't want an enclosing hiding context to hide an enclosed
showing context.  For example, if we are generating messages with
sight scope for Lloyd, and we have a nested context where Lloyd is
saying something and so we now are in hearing scope for Lloyd, we
want the nested context to show its messages if in fact Lloyd is in
hearing scope even if Lloyd is not in sight scope (maybe the player
character and Lloyd are in contact over a walkie-talkie).

</div>

<!------------------->
<div class=entry>

NPC messages: only show if NPC is in sight of PC (using message generation
context)

</div>

<!------------------->
<div class=entry>

Use message generation context for fuses and daemons.  Allow events to
be created with a context object and sense object; whenever an event
is executed, establish the context for the duration of the event's
execution.

</div>

<!------------------->
<div class=entry>

try this: bob, n. z. s. / n. z

<p>
We should see bob leaving on his third queued move, but we don't for
some reason.

</div>

<!------------------->
<div class=entry>

Do we really want to remove the objects directly involved in a command
from the beforeAction and afterAction processing?  It seems like it's
an unnecessary inconsistency.

</div>

<!------------------->
<div class=entry>

Should consider directing report messages to the pc/npc message
objects.  This would more readily allow separate messages for
reporting the results of pc and npc commands (for example, "Taken" vs
"Bob takes the book").  This is probably trivial, since we already
have the pc/npc message generator division anyway; we probably just
need to use it rather than verbMessages for generating report
messages.  (If there's really a good reason to have a separate
verbMessage object, maybe we should have a per-actor verbMessages
object, the way we do with the default library messages generator.)

</div>

<!------------------->
<div class=entry>

Missing blank line between commands on parser failures:

<p>
<pre>
>bob, n. get silver coin.
>n
</pre>

</div>

<!------------------->
<div class=entry>

In room descriptions, list actors separately.

</div>

<!------------------->
<div class=entry>

Don't let the room lister include actor inventory listings with the
main room contents listing.

</div>

<!------------------->
<div class=entry>

Footnote system

</div>

<!------------------->
<div class=entry>

Add an initExamineDesc, to parallel initDesc when an object is
in its initial position and is explicitly examined.

</div>

<!------------------->
<div class=entry>

Check changes in object bulks for effects on containers.  If a
container doesn't allow a change in child bulk, fail the command
that attempted the change.  (For example, in a stretchy bag,
putting a new object into the bag should be disallowed if doing
so would make expand the bag so much that the bag would be too
large for its own container.)

</div>

<!------------------->
<div class=entry>

Stretchy bags, that conform to their contents (in the sense that
the bulk changes according to its contents)

</div>

<!------------------->
<div class=entry>

Use normal command result reports (especially ReportFailure) in
precondition checks.

</div>

<!------------------->
<div class=entry>

For target of "put in", elevate likelihood for an item being held.

</div>

<!------------------->
<div class=entry>

implement save/restore

</div>

<!------------------->
<div class=entry>

implement restart

</div>

<!------------------->
<div class=entry>

implement undo

</div>

<!------------------->
<div class=entry>

For undoing commands to NPC's, show the NPC as part of the command
being undone: "undoing one command: bob, go north".

</div>

<!------------------->
<div class=entry>

Add '\{' and '\}' (push/pop formatter state) output sequences.

</div>

<!------------------->
<div class=entry>

Implicit commands should not set antecedents.

</div>

<!------------------->
<div class=entry>

"Take All" should include the non-fixed contents of fixed containers
and surfaces within the room.

</div>

<!------------------->
<div class=entry>

Status line

</div>

<!------------------->
<div class=entry>

Footnotes: add FOOTNOTE MEDIUM mode, which shows new footnote
references but hides references to footnotes that have already
been read.  This helps cut down on unnecessary clutter, since
a footnote reference is unlikely to be of much interest once
it's been read, assuming that footnotes are always extra
information that isn't required to finish the game.

</div>

<!------------------->
<div class=entry>

Weird:

<p>
<pre>
>get large red ball, small red ball and drop them
[works]

>get asdf red ball, small red ball and drop them
Don't know the word 'asdf'

>oops large
...you see no drop them here
</pre>

<p>
Why does it pick out the right interpretation normally but can't
on a token reparse?

</div>

<!------------------->
<div class=entry>

Add an "unobvious" verification mode that allows the command but will
not be accepted as a default.

</div>

<!------------------->
<div class=entry>

Decorations

</div>

<!------------------->
<div class=entry>

Add dobjCheck, iobjCheck, dobjGen, iobjGen equivalents

</div>

<!------------------->
<div class=entry>

Add a default mechanism for listing the inventory of an actor as
part of the actor's description.  ("Bob is carrying...wearing...").

</div>

<!------------------->
<div class=entry>

Add a sorter method to the list group object, for simple control over
the sorting order

</div>

<!------------------->
<div class=entry>

Add input font switch when reading a command

</div>

<!------------------->
<div class=entry>

When defaulting a direct object of a two-object command, include the
verb's participle form in the default message:

<p>
<pre>
>ask about watch
(asking Bob)
</pre>

<p>
Most default messages are meant to be tagged onto the end of the
command line, but when we're adding a direct object to a two-object
verb, the added object goes in the middle of the command and hence
the default phrase doesn't sound right when tagged onto the end of
the command line.  By adding the participle form of the verb, we
make it clear that the default message stands alone as a new sentence
(or sentence fragment, anyway) and is not meant as a missing
continuation of the original command text.

</div>

<!------------------->
<div class=entry>

"show iron key" - since the missing phrase form of this command has
badness, this ends up being interpreted as "show key to iron", which
is silly.  For command forms like this with two objects and no
preposition, we should probably add a non-badness single-object
grammar that asks for the missing prepositional phrase.  How we
select the misisng-object phrasing over the two-object interpretation
is unclear, though.

</div>

<!------------------->
<div class=entry>

Parameterize the amount of time it takes for an actor to give an
order to another actor.

</div>

<!------------------->
<div class=entry>

try 'inflate raft and put it in bottle' - we don't get a blank line
before the 'put it in bottle' response, presumably because it has
an implicit command first

</div>

<!------------------->
<div class=entry>

Floor/ceiling/walls for indoor rooms, ground/sky for outdoor rooms

</div>

<!------------------->
<div class=entry>

Traverse the sense path for throwing an object at another object, and
make the projectile land in the appropriate place when an intervening
object prevents the throw from finishing.

</div>

<!------------------->
<div class=entry>

Keep track of multiple logical results, and make comparisons based on
the whole list.  Distinguish different reasons (using 'key' values)
for different logical results with the same ranking.

<p>
The idea is that if we have two objects that are both ranked the same
way on one axis but are distinguishable on another axis, we want to
consider the axis on which they're distinguishable.  For example, if
we type "put silver coin in jar," and one jar is open and the other
is closed, we want to pick the one that's open.  At the same time,
they'll both be ranked as equivalently logical on the basis that
neither is held by the actor.  We don't want the being-held status to
override the open status, but we likewise don't want the open status
to override the being-held status if both are open but only one is
being held.  The solution is to ignore the equivalent being-held
status when both objects have this same value, and to ignore the
equivalent open status when both have the same value, but still
consider these attributes when they differ.

</div>

<!------------------->
<div class=entry>

Provide suitable default implementations for about 1.0e+6 verbs

</div>

<!------------------->
<div class=entry>

"re-route" syntax - see, for example, keyring.iobjFor(AttachTo).
Use asDobjFor and asIobjFor:

<p>
<pre>
   iobjFor(AttachTo) asIobjFor(PutOn)
</pre>

</div>

<!------------------->
<div class=entry>

For travel: actorStanding pre-condition that automatically extricates
the actor from chairs and the like.  We must catch dangerous conditions
in the verifier.

</div>

<!------------------->
<div class=entry>

For missing iobj's, allow preposition in response:

<p>
<pre>
>dig in dirt
What do you want to dig in it with?

>with shovel
</pre>

</div>

<!------------------->
<div class=entry>

Type/enter string/number on object

</div>

<!------------------->
<div class=entry>

Type/turn to unquoted string?

</div>

<!------------------->
<div class=entry>

In a two-object action, when assuming one object or the other, and
then asking for the other, we should show the defaulted one before
prompting:

<p>
<pre>
>ask
(Bob)
What do you want to ask him about?
</pre>

</div>

<!------------------->
<div class=entry>

For disambiguation, never pick a 'not obvious' over an illogical, because
a 'not obvious' essentially counts as an illogical for the purposes of
picking objects.

</div>

<!------------------->
<div class=entry>

It might be good to eliminate the redundant default announcement in
cases like this:

<p>
<pre>
>ask
(asking Bob)
What do you want to ask him about?

>watch
(asking Bob)
</pre>

</div>

<!------------------->
<div class=entry>

It might be good to eliminate the participle when asking for a direct
object of a two-object verb and the indirect object is not yet known:

<p>
<pre>
>ask
(asking Bob)
</pre>

<p>
It would be better as simply

<p>
<pre>
>ask
(Bob)
</pre>

</div>

<!------------------->
<div class=entry>

Turn x to string/number

</div>

<!------------------->
<div class=entry>

Dials (turn, turn to)

</div>

<!------------------->
<div class=entry>

Buttons (push)

</div>

<!------------------->
<div class=entry>

Switches (turn on, turn off)

</div>

<!------------------->
<div class=entry>

Levers (pull, push, move)

</div>

<!------------------->
<div class=entry>

Doors

</div>

<!------------------->
<div class=entry>

In the dark: should be able to list items you're holding by touch.

</div>

<!------------------->
<div class=entry>

In the dark, 'look at' should indicate that it's the darkness that
prevents an in-scope item from being inspected.

</div>

<!------------------->
<div class=entry>

In the dark, inventory should do something better than say "you're
empty-handed".

</div>

<!------------------->
<div class=entry>

Climbables (such as stairs).  These should probably just be travel
connectors that go up and down.

</div>

<!------------------->
<div class=entry>

Check scope for preconditions - make sure we don't apply a command
to an object not in scope by way of a precondition implicit command.
For example, if you type "go north" in the dark, and there's a closed
door that you can't see, you shouldn't be able to open the door by
way of the travel precondition.

</div>

<!------------------->
<div class=entry>

<pre>
>go through passage
>again
</pre>

<p>
This somehow keeps the old passage in scope.  Must need to check
scope again for 'again'.

<p>
(The problem is that the last action is hanging on to its cached
resolver scope lists.  We simply need to drop the old resolvers
so that we start the new command with new resolvers.)

</div>

<!------------------->
<div class=entry>

climb up/climb down verbs

</div>

<!------------------->
<div class=entry>

make sure we have makeOpen, makeClosed, makeLocked, makeUnlocked, etc. -
in other words, encapsulate these types of state changes the same way
moveInto encapsulates containment changes

</div>

<!------------------->
<div class=entry>

Add an "inaccessible" verification failure - this would be more
disapproving than any "illogical" level and would be used for
"it's too dark" and "you can't reach that" types of failures.

</div>

<!------------------->
<div class=entry>

The pre-condition execution sequence should probably be like this:

<p>
<pre>
  for (pass = 1 ; pass <= 2 ; ++pass)
    run all verifiers
    for each precondition
      run this precondition, allowing implicit commands on pass 1 ONLY
    if no implicit commands were executed
      break
</pre>

<p>
This would ensure that side effects of an implicit command are re-tested
through previous preconditions.  Each precondition would only be allowed
to run its implicit command on pass 1 because this would prevent
infinite loops from conflicting preconditions - on pass 2, if the
condition isn't met by now, we'll assume it's not going to be, so
we'll simply fail the command.

</div>

<!------------------->
<div class=entry>

"actor, give x to me" should be handled as though it were "ask actor
for x", via a replacement command.

</div>

<!------------------->
<div class=entry>

actors: shouldn't allow taking possessions in general

</div>

<!------------------->
<div class=entry>

Dark rooms: limit travel to adjacent lit locations?

</div>

<!------------------->
<div class=entry>

Explicitly inherit base class vocabWords_ in initializeVocab() in
us_eng.t.

</div>

<!------------------->
<div class=entry>

touch/feel verbs

</div>

<!------------------->
<div class=entry>

Add verb "listen" (both transitive and intransitive)

</div>

<!------------------->
<div class=entry>

Add verb "smell" (transitive and intransitive)

</div>

<!------------------->
<div class=entry>

Enterables

</div>

<!------------------->
<div class=entry>

keys and doors: add options for boosting likelihood for keys:

<ul>
<li>
on the first successful use of a key, automatically boost the
likelihood for future disambiguation using the key if an option is
set (this might be the default option)

<li>
if the author wants the player character to know from the outset
which key goes with a door, the author can add the key to the
lockable's knownKeyList - this can be useful for games with obvious
key associations or key associations known from the outset to the
player character (for example, if the PC has a key to their own
house, the ought to know what the key opens)
</ul>

</div>

<!------------------->
<div class=entry>

locks and keys

</div>

<!------------------->
<div class=entry>

lockable doors

</div>

<!------------------->
<div class=entry>

Automatic key rings for unlocking doors - an "unlock" command with no
indirect object automatically searches for a keyring in the actor's
inventory, and automatically searches for a key on the keyring.

</div>

<!------------------->
<div class=entry>

keyring: need to implicitly take keyring if not held when trying it

</div>

<!------------------->
<div class=entry>

keyrings: message on success should be something like:

<p>
(trying each key on the keyring, you find that the iron key unlocks the door)

</div>

<!------------------->
<div class=entry>

keyring search: when we already know the correct key, we should just
default it rather than search the keyring for it

</div>

<!------------------->
<div class=entry>

implicit commands that use 'replace' should inherit original implicit
status (try 's' from the stair bottom - we get an "unlocked" report
for the replaced 'unlock door' command)

</div>

<!------------------->
<div class=entry>

For Fixed, indirect the illogical messages through properties, to
allow easier customization.

</div>

<!------------------->
<div class=entry>

Whenever any message appears before a room description in a command
sequence, show a blank line before the room description.  This applies
especially to travel, but is generally desirable for any command that
shows a room description.

</div>

<!------------------->
<div class=entry>

Put iron key in duffel; unlock iron door - won't default the iron
key, because the keyring takes precedence by virtue of being held.

<p>
The problem is that the objHeld precondition is applying a likelihood
of 80 because the iron key isn't held, and the held keys are getting
100's.  Maybe we need to reduce the likelihood of any other keys or
keyrings when the known key is present, but this seems like a poor
special-case hack for a problem that is likely to arise in other
contexts.

<p>
To solve this, add a 'priority' to logical results.  Use low priority
for precondition rankings, because these are inherently of lower
importance than unique attributes of the objects themselves.

</div>

<!------------------->
<div class=entry>

Add an 'exit only passage' to be used as the receiving end of things
like trap doors, chutes, and so on.

</div>

<!------------------->
<div class=entry>

Message travel connectors: simple connector that shows a message as the
connector is traversed.

</div>

<!------------------->
<div class=entry>

preserve the case of tokens in literal phrases

</div>

<!------------------->
<div class=entry>

Light/dark changes should be noted at the end of each turn.

</div>

<!------------------->
<div class=entry>

Light/dark changes should be noted before/after each daemon is
dispatched.

</div>

<!------------------->
<div class=entry>


<pre>
>move me to
What do you want to move it to?
</pre>

<p>
Could we substitute "yourself" for "it" somehow?

</div>

<!------------------->
<div class=entry>

Trap doors - in particular, the arrival message should indicate that the
trap door automatically slams shut after the actor arrives.

</div>

<!------------------->
<div class=entry>

Possessives - "take his box", "take bob's box"

</div>

<!------------------->
<div class=entry>

possessives - problem with disambig:

<p>
<pre>
>get key's jar
Which key's do you mean...
</pre>

<p>
That should just be 'which key do you mean', not 'which KEY'S'

</div>

<!------------------->
<div class=entry>

possessives - plurals

</div>

<!------------------->
<div class=entry>

possessives - five of bob's keys

</div>

<!------------------->
<div class=entry>

possessives - bob's keys except the green one

</div>

<!------------------->
<div class=entry>

get all of bob's keys except the rusty and iron ones - even when this
is just one key, we should announce it as though it were a multiple
object (so we need to set some flag)

</div>

<!------------------->
<div class=entry>

possessives:

<p>
<pre>
>bob's
unknown word ''s'
</pre>

</div>

<!------------------->
<div class=entry>

possessives - problem with disambig:

<p>
<pre>
>get key
Which key do you mean...

>get bob's key
The word ''s' is not necessary...
</pre>

<p>
The problem would seem to be that we don't handle 's in disambig
responses and treat it as an unknown word.

</div>

<!------------------->
<div class=entry>

<pre>
>look under me
You see nothing unusual under you.
</pre>

<p>
We should make that second 'you' into 'yourself' instead.  In general,
can we change an objective case use of an object already used in the
nominative should to a reflexive instead?

</div>

<!------------------->
<div class=entry>

possessives - disambig response should allow 'bob's' as a choice,
even if it's not offered

</div>

<!------------------->
<div class=entry>

possessives - "get keys except bob's" - need special grammar for
just a possessive in this context

</div>

<!------------------->
<div class=entry>

<pre>
>bob, x key
Which key?

>quit
This command cannot be directed to another character...
</pre>

</div>

<!------------------->
<div class=entry>

Distant items

</div>

<!------------------->
<div class=entry>

Finish topic-verb implementation

</div>

<!------------------->
<div class=entry>

Consider:

<p>
<pre>
>lock door
(first closing the iron door)
(with the iron key)
Locked.
</pre>

<p>
The defaulted indirect object is misleading.  This should instead be:

<p>
<pre>
>lock door
(with the iron key)
(first closing the iron door)
Locked.
</pre>

<p>
The problem comes from the fact that "Lock" has an objClosed
precondition for keyed lockable; "Lock" doesn't need this
precondition, because "LockWith" has it.  Removing the precondition
will get the ordering right.

</div>

<!------------------->
<div class=entry>

truncated adjectives seem worse than unknowns in ranking:

<p>
<pre>
>type hello on typewri
</pre>

</div>

<!------------------->
<div class=entry>

do not filter the 'all' list with hideFromAll when looking for default
objects

</div>

<!------------------->
<div class=entry>

<pre>
>get iron key
You take the key and attach it to the keyring

>get keys
brass key: You take and attach...
rusty key: You take and attach...
iron key: Taken.
</pre>

<p>
It's irritating that the last one is taken off the keyring.  Should
we leave items out of plurals when we have multiple logical items of
different logicalness?  (This isn't a completely academic problem,
since you could in practice have a couple of new keys in a room that
you want to pick up, without detaching keys you already have on the
keyring.  One easy way to solve this would be to use a different
command for detaching from the keyring - require 'take key off
keyring', and say Illogical('if you want to take the key off the
keyring, say so'); but this could be irritating when you just want to
take the key off the keyring.

</div>

<!------------------->
<div class=entry>

follow: should replace command with actual command used for last
observed travel; alternatively, reproduce the preconditions and
verification for the travel via the connector

</div>

<!------------------->
<div class=entry>

Player character vocabulary - either add switchPlayer to fiddle with
the dictionary, or have some other way to route 'me' and 'my' to the
current player character (using matchName, for example).

</div>

<!------------------->
<div class=entry>

Move travel preconditions into the connectors after all.  Just create
an openDoor precondition type that is instantiated with a specific
door to open, rather than attaching it to a command object.

</div>

<!------------------->
<div class=entry>

send bob into dark. follow bob into dark, then:

<p>
<pre>
>follow bob
Bob is right here.

>bob, u
You see no bob here.
</pre>

</div>

<!------------------->
<div class=entry>

<pre>
>bob, n
>g
</pre>

<p>
We're not checking to see if the actor is still in scope.

</div>

<!------------------->
<div class=entry>

<pre>
>n. open door.
>close door and sit down
</pre>
--> endless loop - weird problem with token indices for 'sit down' part
of grammar tree.  The token indices for the second predicate are for
the entire command, strangely, so we think we need to parse the entire
phrase again and again.

<p>
This has something to do with the empty dobj noun phrase.  Same thing
happens with 'close door and open' (which also has an empty dobj),
but not with 'close door and look' (which takes no dobj) or 'close
door and sit down on floor' (which has a non-empty dobj).

</div>

<!------------------->
<div class=entry>

when changing sensory contexts, don't flush output; instead, consider
sensory context when queueing reports, so that we simply don't queue
a report unless it's visible in the sense context

</div>

<!------------------->
<div class=entry>

when a door closes from the other side, show a message about it

</div>

<!------------------->
<div class=entry>

Status line messages for nested rooms, sitting, lying

</div>

<!------------------->
<div class=entry>

Standing needs to be able to specify what you're standing on in some
cases, such as platforms.  Is it only the floor that won't?

</div>

<!------------------->
<div class=entry>

when standing, make sure we move actor to room

</div>

<!------------------->
<div class=entry>

when sitting/standing, make sure we do all the necessary work of
travelTo

</div>

<!------------------->
<div class=entry>

Chairs, beds (make Room not Fixed? or make a deeper base class for
BaseRoom, with Room: Fixed, Room?)

</div>

<!------------------->
<div class=entry>

sit/lie on floor: actor doesn't actually need to stand first, if the
actor is already sitting/lying in the room.  In other words, if we're
just changing from sitting to lying or vice versa, and not changing
containers, we don't need an intermediate standing state.  We need
something like standing-or-in-obj instead.

</div>

<!------------------->
<div class=entry>

sit/lie/stand on - when checking that we can enter a nested room, make
sure we're in the immediate container of the nested room

</div>

<!------------------->
<div class=entry>

sit/lie: need to configure prep for 'on' vs 'in' (since we 'sit on'
some things but 'sit in' other things, and likewise for 'lie on'
vs 'lie in')

</div>

<!------------------->
<div class=entry>

sit on floor, then sit on chair -> no intermediate 'stand'.  This might
not be important, since it won't involve actual movement, but it's a
little weird, and it would be nice to make it consistent with the real
nested rooms.

</div>

<!------------------->
<div class=entry>

'sit on floor' doesn't work if run from a doubly-nested room (or deeper)

</div>

<!------------------->
<div class=entry>

sit on armchair, then stand on dais: "already standing on the dais".
Need to deal with an implied command that effects the change required
of the main command.

</div>

<!------------------->
<div class=entry>

Might want a precondition for travel more general than 'standing',
to allow for standing in vehicles and on platforms

</div>

<!------------------->
<div class=entry>

list actors in a nested room when describing the room

</div>

<!------------------->
<div class=entry>

maximum seating capacity for a chair

</div>

<!------------------->
<div class=entry>

in box: try 'e': "you can't do that from the main platform".

</div>

<!------------------->
<div class=entry>

in box: in the dark, should probably have the enclosing room in scope

</div>

<!------------------->
<div class=entry>

in box: when closed and we have light, definitely should have the
enclosing room in scope

</div>

<!------------------->
<div class=entry>

in box: should not be able to try to get out of box when we can't
sense beyond the box - it should serve as top-level location for
the purposes of the implied actions in this case

</div>

<!------------------->
<div class=entry>

When in box, and box is closed, list contents of box as top-level
contents of room.

</div>

<!------------------->
<div class=entry>

Listing room contents should show contents of fixed items to any
depth.  The first-level contents of anything not listed should by
default be listed.

</div>

<!------------------->
<div class=entry>

Vehicles

</div>

<!------------------->
<div class=entry>

traveling - don't use actorStanding, but use travelerReady instead.
If the traveler is an actor this turns into actorStanding (or whatever
is appropriate for the actor); for a vehicle it's probably nothing, but
could be used to check for things like the doors being closed on a car
or seatbelts being fastened.

</div>

<!------------------->
<div class=entry>

Vehicles: when PC is riding, we get no description of the new room

</div>

<!------------------->
<div class=entry>

Vehicles: put tricycle on platform; get on tricycle; ride tricycle:
we don't seem to move the tricycle off the platform first.

</div>

<!------------------->
<div class=entry>

Vehicles: departing should use definite article

</div>

<!------------------->
<div class=entry>

Vehicles: departing doesn't list riders (presumably they're out of
scope by the time the departure message is generated; need to save
sense info or something)

</div>

<!------------------->
<div class=entry>

sample game: implement 'ride tricycle'

</div>

<!------------------->
<div class=entry>

sample game: when getting on tricycle, mention how to ride it

</div>

<!------------------->
<div class=entry>

Put x on floor: if we're in a nested room with a drop location that
isn't the main room, we'll perform a "drop" in the nested room.  Should
actually move to outermost room if possible.  (Maybe we need to leave
the nested room as a precondition.)

</div>

<!------------------->
<div class=entry>

Vehicles: need a convenient way to put up vehicle barriers, so that
you can walk through a door but not ride through, and vice versa

</div>

<!------------------->
<div class=entry>

'follow me' mode for an actor

</div>

<!------------------->
<div class=entry>

recognize (in input) reflexive pronouns referring to target actor
(bob, examine yourself)

</div>

<!------------------->
<div class=entry>

Allow things to be placed out of reach from within nested rooms
(canReachFromRoom).

</div>

<!------------------->
<div class=entry>

change from LangThing to 'modify Thing', etc.

</div>

<!------------------->
<div class=entry>

change "bob, tell me about x" into "me, ask bob about x"

</div>

<!------------------->
<div class=entry>

'push/move dobj to iobj' - for things like building staircases ('push
crate to window').  Synonyms might include 'push/move/put dobj under iobj'.

</div>

<!------------------->
<div class=entry>

Fix follow problem: "bill cannot stand in closed box" is reported
even though we're out of range of the sense.

</div>

<!------------------->
<div class=entry>

Allow some types of nested rooms (platforms, booths) to be their own
follow locations, so we can follow an actor into such a room

</div>

<!------------------->
<div class=entry>

Might want to keep pronoun antecedents per actor.  When an issuer
gives a command to a target, the target should copy all of the
antecedents from the issuer.

</div>

<!------------------->
<div class=entry>

for 'in' and 'out', by default ask for a direct object if there's
no evident travel connection for the direction

</div>

<!------------------->
<div class=entry>

remove all preconditions from noTravel, as we know travel will not occur
and hence don't need to meet any conditions

</div>

<!------------------->
<div class=entry>

'push obj north' (and other directions)

</div>

<!------------------->
<div class=entry>

for "follow", track actors in vehicles as well as the vehicles
themselves

</div>

<!------------------->
<div class=entry>

'draggable' class, implementing a general framework for pushing
objects from one room to another

</div>

<!------------------->
<div class=entry>

add a push-travel barrier that works like the vehicle barrier, but
for traveling while pushing objects

</div>

<!------------------->
<div class=entry>

Change the barrier mechanism so that barriers are listed on the connector,
rather than being part of the connector.  This is needed because the
connector is in many cases directly addressable - putting the barrier
in front of the connector as a proxy connector doesn't work when you
can reach the connector directly, making an end run around the barrier.

</div>

<!------------------->
<div class=entry>

Change the listing mechanism so that showList is a method of the
ShowListInterface class, to simplify argument lists.

</div>

<!------------------->
<div class=entry>

Handle nested grouping.  Use this for equivalents in groups.

</div>

<!------------------->
<div class=entry>

For group listings, don't add a group when there's only one group due
to equivalence.  We currently say this, which is awkward: "the jar
contains two coins (two copper coins)."

</div>

<!------------------->
<div class=entry>

Equivalent listings - eliminate as a separate special case and simply
list equivalents using a listing group.  Add an Equivalent Group
which implements a simple listing group for equivalents; by default,
the group simply shows the count.

</div>

<!------------------->
<div class=entry>

For our silver/gold/copper coins in the sample game, make sure the
grouping mechanism can list like this: "eight coins (three silver and
five gold)".  Note that the names in the parens leave off "coins" and
just list the number and adjective.

</div>

<!------------------->
<div class=entry>

Move all of the lister objects into the messages module, and eliminate
the secondary indirection through the libMessages object.  Simply make
the lister itself part of the messages module, and put the messages
directly in the lister.

</div>

<!------------------->
<div class=entry>

Get rid of the unnecessary list flags LIST_WORN and LIST_INVENTORY,
replacing them with parameterization at the listing method level
instead.

</div>

<!------------------->
<div class=entry>

Use the generic list mechanism to list actors in a room.  By default,
each actor simply lists separately, but it should be possible to
group actors using the normal listing group mechanism ("Bob and Bill
are at their desks", for example).

</div>

<!------------------->
<div class=entry>

Can we make the disambig list use the normal listing mechanism?
<no, probably not worth it>

</div>

<!------------------->
<div class=entry>

Add a "specialDesc", similar to initDesc but for more general purposes.
specialDesc should turn into initDesc when initDesc is applicable.

</div>

<!------------------->
<div class=entry>

add "the former" and "the latter" as disambiguation responses

</div>

<!------------------->
<div class=entry>

For nested rooms, break out the "staging location" test from
checkActorReadyToEnterNestedRoom into a separate routine.  Use a
list of possible staging areas given by a separate property for
easier overriding.

</div>

<!------------------->
<div class=entry>

For nested rooms, use a separate "exit destination" property for the
destination of a GetOutOf action, rather than assuming that we always
move to the enclosing location.

</div>

<!------------------->
<div class=entry>

Add a "high nested room" that can't be entered except from particular
staging areas due to height.  These is a fairly trivial
specialization: first, don't solve the problem using implicit
commands unless the actor has already solved it before; second, the
default failure message is something like "you can't enter that from
here; it's too high up."

</div>

<!------------------->
<div class=entry>

Rename the '*predicate*' production classes to '*command*'

</div>

<!------------------->
<div class=entry>

Base all command (formerly predicate) classes on a common CommandProd
base class

</div>

<!------------------->
<div class=entry>

Add a resolveAction method to the command classes.  This method
retrieves the action from the command.  In English, this simply
retrieves the 'predicate' match tree object, which is always based on
action; other languages, especially those that use case markers
rather than word order to encode phrase-role information, can
customize this behavior appropriately for their grammatical systems.

</div>

<!------------------->
<div class=entry>

When scanning command parse matches, we can immediately eliminate
any match for which resolveAction fails to find a valid action.

</div>

<!------------------->
<div class=entry>

Use separate listers for room/object contents lists and inventory lists.
Use separate show-list-item methods for inventory items.

</div>

<!------------------->
<div class=entry>

For keyrings, show contents of keyring in room/object/inventory contents
as a sublist:  a keyring (attached to which are an iron key and a bronze
key)...

</div>

<!------------------->
<div class=entry>

Allow queuing pending actions for an actor, not just token lists.
Make it possible to insert a pending action at the beginning of the
queue (for continuation actions).

</div>

<!------------------->
<div class=entry>

Use a separate listing flag (isListedInInventory) for inventory
list inclusion.  For actors, make this true by default, even though
actors are not listed in room descriptions.

</div>

<!------------------->
<div class=entry>

Dispenser and Dispensable, for matchbooks and the like

</div>

<!------------------->
<div class=entry>

Collective objects for cases like "book of matches" and "matches" -
when we type "take matches," we should interpret this as the book of
matches (i.e., "matches" == singular) rather than as the individual
matches ("matches" == plural).

</div>

<!------------------->
<div class=entry>

Matches - flammable objects that are self-igniting

</div>

<!------------------->
<div class=entry>

Matchbooks

</div>

<!------------------->
<div class=entry>

Include a checksum in saved state files, and check at start of load.
This will help avoid attempting to restore a file that was corrupted.

</div>

<!------------------->
<div class=entry>

Add a tentative pre-resolution pass, for the later-resolved object of
a two-object action, that runs before the resolution of the
earlier-resolved object.  Don't perform full resolution on this pass;
specifically, don't count any problems against the ranking results,
and don't ask for help interactively.

<p>
Make use of this information in 'verify' routines for the
earlier-resolved objects when applicable.  For example, for "take
<dobj> from <iobj>", we resolve the indirect object first, so we
don't know the final dobj resolution when resolving the iobj; so, use
the tentative information so that we can rule an iobj illogical if
there's no tentative dobj inside the proposed iobj.

</div>

<!------------------->
<div class=entry>

Might want to clean up the other-object business in askMissingObject
and related routines.  This scheme doesn't feel properly generalized.
For that matter, we might want to rethink the whole scheme so that
it's subclassed by and handled in the action classes, rather than
parameterized, since the parameterization scheme seems hokey and
brittle.

</div>

<!------------------->
<div class=entry>

Remove the otherObjectList and otherObjectWhich stuff when we've
cleaned up the corresponding code.  This information should now be
available via the tentative resolution lists instead.

</div>

<!------------------->
<div class=entry>

When lighting a match as part of an implied command, reduce the burn
time by one turn - this ensures that lighting the match as part of
another action won't artificially extend the match's burn time.

</div>

<!------------------->
<div class=entry>

candles, torches, oil lanterns - flammable objects that must be lit with
another item, such as a match

</div>

<!------------------->
<div class=entry>

defaults: when there are two or more equivalent items that could be
used as defaults, pick one arbitrarily

</div>

<!------------------->
<div class=entry>

for implied transfers into a bag of holding, put the indirect object
of "take from" last in the affinity list

</div>

<!------------------->
<div class=entry>

for implied transfers into a bag of holding, other things being equal,
transfer the least recently acquired object first

</div>

<!------------------->
<div class=entry>

food items

</div>

<!------------------->
<div class=entry>

Change the logic of checkActorInStagingLocation so that it doesn't
assume that we can reach a staging location just because we're
indirectly in the location.  Instead, add a "choose staging location"
method so that rooms can override the staging location chooser with
appropriate special-case code when needed.

</div>

<!------------------->
<div class=entry>

Add issuing actor and target actor parameters to resolveAction(), so
that the resolver can tell what reflexive pronoun phrases mean.  (In
many languages, reflexive constructions are structurally part of some
predicates, and affect the meaning of the predicate, so the identity
of the speaker and of the subject must sometimes be known to
correctly determine the interpretation of the predicate structure.)

</div>

<!------------------->
<div class=entry>

sample game: reject just plain "match" in the matchbook's matchName

</div>

<!------------------->
<div class=entry>

touch scope: include contents of matchbooks and keyrings, so that
these can be used even in the dark

</div>

<!------------------->
<div class=entry>

Add an associated odor and sound property to each Thing.  This points
to an object that encapsulates the object's sensory emanations.  Always
add these objects to scope when the associated objects are in scope,
with the same properties.

<p>
Make "listen to x" and "smell x" defer to the associated objects.

<p>
For scoping, a sound or smell doesn't have to place the main object
in scope, but rather can just put the intangible sensory emanation in
scope.  For example, if an alarm clock is buzzing, the 'buzzing
sound' object would be in scope but not the alarm clock itself.  (On
the other hand, some sounds, like a ringing phone, might be
sufficiently distinctive as to place the main object in scope.  But
for those cases we can simply associate the sound/smell with the main
object.)

</div>

<!------------------->
<div class=entry>

We need different odor/sound descriptions for different situations:

<p>
<pre>
>listen to phone
It's ringing.
<i>==> phone.soundDesc</i>

>listen to ring [phone visible]
It's coming from the phone.
<i>==> sound.soundWithSource</i>

>listen to ring [phone not visible]
It sounds like a phone.
<i>==> sound.soundWithoutSource</i>

>look [phone visible]
...
The phone is ringing.
<i>==> sound.soundHereWithSource</i>

>look [phone not visible]
...
You can hear what sounds like a phone ringing.
<i>==> sound.soundHereWithoutSource</i>
</pre>

</div>

<!------------------->
<div class=entry>

Don't open a footnote when the PC isn't seeing the text with the
footnote reference.

</div>

<!------------------->
<div class=entry>

Add sense emanations to inventory displays.

</div>

<!------------------->
<div class=entry>

For sound/smell objects, add options to control ongoing announcements
of sensory emanations:

<ul>
<li>always show on room description, or only show on
explicit "look" descriptions (and corresponding sense commands -
"smell", "listen")

<li>show every n clock ticks

<li>show every n clock ticks for m iterations, then go
to a secondary message every p clock ticks (for something like "the
phone is still ringing").
</ul>

</div>

<!------------------->
<div class=entry>

Room descriptions should be differentiated according to whether we're
explicitly looking or merely entering a new room.

</div>

<!------------------->
<div class=entry>

When a noise's or odor's source is not visible, and the object is
examined (via "examine", or via "listen to" or "smell" or whatever),
it might be desirable in many cases to show the <i>apparent</i> source,
which is to say the visually opaque obstructor, and describe the
sound/odor as coming from inside/outside/behind/whatever the
obstructor.

<p>
The obstructor can be easily found with
gActor.findOpaqueObstructor(sight, obj) (where 'obj' is the noise or
odor object).  Once the obstructor is found, we'll have to generate
an appropriate message, which will require a new method parallel to
obs.cannotReachObject(obj) - perhaps we could call it
obs.describeSoundObstructor(obj) etc - which would display "The
ringing seems to be coming from inside the box" and the like.

<p>
This entire mechanism would not be used when the obstructor itself
cannot be seen, such as in the dark.

</div>

<!------------------->
<div class=entry>

Consider:

<p>
<pre>
>look
...
You can hear what sounds like a phone ringing.

>listen to ring
It sounds like a phone.

>x phone
You don't see any phone.
</pre>

<p>
It would be better if that last line were:

<p>
<pre>
>x phone
You can hear a phone ringing, but you can't see it.
</pre>

<p>
To deal with this, adjust the touchObj and objVisible preconditions
so that it provides better feedback for an object that can be heard
but not seen.

</div>

<!------------------->
<div class=entry>

Write a common main() that most games will use, with appropriate
hooks for showing the introductory text and so on.  Or, perhaps
better, write a standard initialization routine that the game's
main() can call.

</div>

<!------------------->
<div class=entry>

Provide an author-configurable option to process multiple orders to
NPC's synchronously - so, if you say "bob, go north, get all, go
south", the PC doesn't get a command line prompt again until Bob
finishes the whole set of commands.

</div>

<!------------------->
<div class=entry>

It might be worth considering making the disambiguation responses for
&noMatchDisambig and &disambigOrdinalOutOfRange more interactive.
Currently, if you give an invalid response to a disambig question,
you get an error and no chance to retry.  Something like this might
be more intuitive:

<p>
<pre>
>take ball
Which ball, the red ball, or the green ball?

>third
There weren't that many choices - did you mean the red ball, or the
green ball?

>orange
That wasn't one of the choices - did you mean the red ball, or the
green ball?
</pre>

<p>
However, if the response looks like a valid response but doesn't give
us a match, and it also looks syntactically like a valid new command,
treat it as a new command.

</div>

<!------------------->
<div class=entry>

Generic script objects:  an object for which we call a method automatically
each turn it's active.  We'd keep a counter that we'd automatically advance
on each call.  We should probably use this generic object to implement
text lists.

</div>

<!------------------->
<div class=entry>

Generic text lists:  an object that encapsulates a list of messages
to display, one per turn.

<p>
Text lists should be linkable to a common counter object, so that the
lists are synchronized on the same counter.  This lets you have separate
lists for each room, but keep the timeline in each list the same.

<p>
It should be possible to associate a text list object with a room instead
of coding the room's text list in-line in the room.

</div>

<!------------------->
<div class=entry>

Room text lists:  a list of atmosphere messages we cycle through while
the player is in the room.  This should be totally automatic, so you
just program the list and the library automatically sets up a daemon
to run through the messages.

</div>

<!------------------->
<div class=entry>

When describing an object, show the special descriptions for any contents
of the object, just as we would list them in room descriptions.  This
lets us see the special descriptions for contents, without having to
write any additional descriptive code in the container.

</div>

<!------------------->
<div class=entry>

consider:

<p>
<pre>
>take coin
Which coin, silver or gold?
</pre>

<p>
We should probably keep the copper one in the list.  In particular,
we probably shouldn't remove an item from consideration for
disambiguation just because it's less likely - once we've determined
that the noun phrase is ambiguous, we should offer all logical
matches, even when they're less likely.

</div>

<!------------------->
<div class=entry>

consider:

<p>
<pre>
>take coinc
Which coin...?

>take tricyc
The word 'tricyc' is not necessary in this story.

>take tricyc
Taken.
</pre>

<p>
For some reason, truncated words are treated as misspellings when they
appear in disambiguation responses.

</div>

<!------------------->
<div class=entry>

Can we cache sense information to speed up resolution a bit?  In
particular, we should be able to cache sense information during the
noun phrase resolution and verification steps, since these do not
normally involve any game state changes; once execution begins,
though, caching should be turned off.  (This is probably the optimal
set of trade-offs: on the one hand, the game and library should
never have to worry about cache invalidation - the library only needs
to turn caching on before starting the parsing phase and then turn
caching off before beginning the execution phase of a command; on
the other hand, we should derive substantial efficiency from caching
during the parsing phase, because this phase in particular tends to
evaluate a lot of sense information.

<p>
(Experimental code has been added, conditionally compiled based on
the SENSE_CACHE macro.  We'll leave it on for the time being to get
some experience with it to see how well it works.)

</div>

<!------------------->
<div class=entry>

Preparsing

</div>

<!------------------->
<div class=entry>

Just-out-of-reach containers.  Create a container type that puts its
contents in the distance for 'touch' purposes.  This can be used for
things like items on the ceiling.  We'll need a way to make this vary
depending on the source object, so that, for example, something could
be out of reach for an actor standing in the room but in reach if the
actor stands on a desk.

</div>

<!------------------->
<div class=entry>

When using 'again' with a command that had an interactive
disambiguation response, the response 'that wasn't one of the
choices' is not appropriate since the player doesn't get to respond.

</div>

<!------------------->
<div class=entry>

cache touch paths (and canTouch information) the same way we cache
sense paths

</div>

<!------------------->
<div class=entry>

For OutOfReach containers, we shouldn't be able to touch the
container itself, since not only the contents but the container
itself is meant to be out of reach.  To do this, add a PathTo
traversal for the last item in a path (and while we're at it, add the
symmetrical PathFrom for the first item in the path), and in
OutOfReach's checkTouchViaPath, treat PathTo the same as PathIn.

</div>

<!------------------->
<div class=entry>

'down' from a platform should be 'get off platform' by default

</div>

<!------------------->
<div class=entry>

add 'debug' verb (to break into the debugger)

</div>

<!------------------->
<div class=entry>

Real-time events: on save/restore, adjust system clock basis to keep
everything in sync

</div>

<!------------------->
<div class=entry>

Real-time events: design a class for the events

</div>

<!------------------->
<div class=entry>

Real-time events: integrate with the scheduler and command reader

</div>

<!------------------->
<div class=entry>

Real-time events: when an interruption occurs, catch any output and
automatically cancel the interrupted input

</div>

<!------------------->
<div class=entry>

Fix problem with quoted strings in literal phrases (as in 'type
"hello" on typewriter')

</div>

<!------------------->
<div class=entry>

Fix problem with 'throw': it's illogical to throw something at an
object within the object being thrown

</div>

<!------------------->
<div class=entry>

Change all of the exclusion list phrases to terminalNounPhrase rules -
otherwise, when they exclude everything, they get misinterpreted as
((all but x and y) and z) which turns into (z and z).  Everything with
a 'but' should turn into a terminalNounPhrase, just like the plain
'all but &lt;list&gt;' rule.

</div>

<!------------------->
<div class=entry>

Make 'me' symmetric with 'yourself' in the grammar.  In particular,
'me' should refer to the issuing actor, which is not necessarily the
player character.

</div>

<!------------------->
<div class=entry>

fix problem with "yourself, jump"

</div>

<!------------------->
<div class=entry>

For chairs and the like, we might want to consider an object owned
by an actor if the actor is occupying the object (so, "bob's chair"
is the chair bob is sitting on).

</div>

<!------------------->
<div class=entry>

When taking an item, reduce the likelihood that an item being carried
by another actor is the one being taken.

</div>

<!------------------->
<div class=entry>

Provide a way of distinguishing lit and unlit equivalents in a list.
Likewise for worn and unworn objects.  Should probably add another
list group object after the equivalent grouper, and in this object
we should provide one group for lit objects and another for unlit.
The desired output is something like this:

<p>
<pre>
  You are carrying three matches (one lit), two flashlights (one
  providing light).
</pre>

</div>

<!------------------->
<div class=entry>

Move the inheritNext into the behavior as the default native 'inherit'
instruction.  Remove inheritNext from library source files.

</div>

<!------------------->
<div class=entry>

the dagger shouldn't show up in the 'x desk' description when the
dagger's initial message is still being shown

</div>

<!------------------->
<div class=entry>

Add macros to make grammar rules for predicates easier to read.

</div>

<!------------------->
<div class=entry>

Improve the module names (adv3g -> parser.t, adv3v -> verbs.t, etc)

</div>

<!------------------->
<div class=entry>

provide .t3m, .tdc for sample game with proper directory set-up

</div>

<!------------------->
<div class=entry>

accept 'all &lt;adj&gt;' and the like

</div>

<!------------------->
<div class=entry>

build the #include file list in Workbench automatically when creating
a project, and when explicitly asked via a new command "scan source
files for #include"

</div>

<!------------------->
<div class=entry>

compiler: warn on finding a backslash outside quoted text in front of
anything but a newline

</div>

<!------------------->
<div class=entry>

Add a simpler, more structured way to add a single paragraph break.
Use a new pseudo-tag, "<.p>", to indicate a paragraph break; process
this tag just before writing output to the console.

</div>

<!------------------->
<div class=entry>

All library input functions should coordinate with command reports to
turn off output capturing.

</div>

<!------------------->
<div class=entry>

Add a finishGame() function offering restart/restore/undo/quit options

</div>

<!------------------->
<div class=entry>

Build a proper set of Workbench sample games

</div>

<!------------------->
<div class=entry>

Freeze the real-time clock while we're waiting for inputFile results,
while we're saving/restoring a file, and while we're waiting for an
inputLine when real-time events are not allowed.  All of these should
be considered to be outside the normal real-time flow of the game,
so none of them should consume any game real-time.

</div>

<!------------------->
<div class=entry>

In showList: mix groups and singles in the original order of lst,
rather than displaying groups and then singles separately.  This is
important because we're not preserving the original ordering when
the list is sorted and it has subgroups.  We can't guarantee
that we'll preserve the sorting order, of course, since grouping
could put together items that weren't consecutive in the sorting
order, so let grouping prevail when there's a conflict; but when
possible, keep the order the same.  To do this, we should have
a single loop that traverses the original lst; for each item, if
it's a single, show the single, otherwise show its group.  Only
show the group for the first item in the group; once we match a
group, mark the group as used so we don't show it again.

</div>

<!------------------->
<div class=entry>

'+' should consistently concatenate individual items from a
collection on the right-hand side, whether the right-hand side is a
list, vector, or array

</div>

<!------------------->
<div class=entry>

'+' and '-' should work with an Array as the left-hand side

</div>

<!------------------->
<div class=entry>

Delete class Array.  We'll have to change the function object stuff
to use Vector instead of Array.

</div>

<!------------------->
<div class=entry>

Make Vector+val and Vector-val return new objects - do not modify the
original vector in place

</div>

<!------------------->
<div class=entry>

add Vector.appendAll() - appends list elements in-place; maybe
Vector.removeValue() and Vector.removeAllValues() to do '-' in-place

</div>

<!------------------->
<div class=entry>

LookupTable.forEach: remove the 'key' argument to make its interface
the same as everything else's.

</div>

<!------------------->
<div class=entry>

Everything with a forEach: add a forEachAssoc(key, val) method alongside
forEach.

</div>

<!------------------->
<div class=entry>

for Openable, if the object isn't transparent looking in, implicitly
open the object for "look in"

</div>

<!------------------->
<div class=entry>

Iterators: add getCurVal and getCurKey methods.

</div>

<!------------------->
<div class=entry>

Fix bug: 'listen' or 'smell' shows no response when there are things
that nominally have Noise/Odor associations, but none of the Noise/Odor
objects actually has anything to say at the moment.

</div>

<!------------------->
<div class=entry>

Dictionary: add a way to iterate over the entries in the dictionary.

</div>

<!------------------->
<div class=entry>

For inputManager.inputLineBegin and inputLineEnd, use a new style tag
"<.inputline>" rather than coding "<font face=tads-input>" directly.
This makes it easier for a game to customize the input font setting.

</div>

<!------------------->
<div class=entry>

Add access to the "restore code" (the second argument passed to
restoreGame()) for PostRestoreObject instances by adding the value as
a class property of PostRestoreObject.

</div>

<!------------------->
<div class=entry>

Change the Thing template that ends with "desc" @location to end
instead with @location "desc" (i.e., reverse the desc and location
property order).  Since "desc" can be lengthy, putting the location
first will make the template more readable.

</div>

<!------------------->
<div class=entry>

Add before/after command separation messages in libMessages, to allow
for finer-grained control over the formatting of command responses.

</div>

<!------------------->
<div class=entry>

Check dark travel before checking any barriers - move the call to
gActor.checkDarkTravel into the TravelConnector methods that call
gActor.travelTo, since this must be called as a separate phase before
the travel connectors do any of their other work.

</div>

<!------------------->
<div class=entry>

Make Illogical() the most illogical ranking, and make IllogicalNow()
slightly less illogical (i.e., invert the old ordering of Illogical
and IllogicalNow).

</div>

<!------------------->
<div class=entry>

Add Action.setMessageParam(), to allow message processors to set
their own special message parameters that they can use in expansion
text.  This would be better than constructing messages partially with
the "{it obj/him}" mechanism and brute-force string concatenation,
because it would allow the concatenated bits to participate in the
same processing steps, such as reflexive pronoun conversions.

<p>
Add a macro (gMessageParams) to simplify the syntax for adding new
message parameters.

</div>

<!------------------->
<div class=entry>

"x me" doesn't work in dark (target actor of a command should always
be in scope)

</div>

<!------------------->
<div class=entry>

Remove 'actorResolved' check from execCommandTokens - this check is
vestigial (it stopped being necessary when we started pulling out the
actor phrase after resolution and re-parsing the rest of the command),
and makes it impossible to have multiple levels of indirection, as in
"tell bob to tell bill to go north".

</div>

<!------------------->
<div class=entry>

Refactor FirstCommandProdWithActor (parser.t) to move the actor resolution
stuff into a separate CommandProdWithActor that FCPWA inherits from.

</div>

<!------------------->
<div class=entry>

<pre>
>bob, get ball
Which ball?

>z
Bob waits...
</pre>

<p>
The "z" should have a default target of the player character, not Bob.

</div>

<!------------------->
<div class=entry>

Allow things like "tell bill to tell bob to go north".  In particular,
fix execCommandTokens so that it doesn't assume that only one actor can
be resolved per command.

</div>

<!------------------->
<div class=entry>

Keep first-on-line information in the PendingCommandInfo.  (This requires
changing the interfaces to all of the Actor routines that create pending
command info objects: addPendingCommand, addFirstPendingCommand,
addPendingAction, addFirstPendingAction.)

</div>

<!------------------->
<div class=entry>

Add a noun-list grammar rule for singleNoun, so that if we match a
noun list in a place where a single noun is grammatically required,
we can generate an appropriate message rather than failing to match
grammar.

<p>
Symptoms fixed: "ask bob and bill about box" -> "you see no bob and
bill here"; "give coins to bob and bill" -> "you see no coins to here".

</div>

<!------------------->
<div class=entry>

Add a point-of-view argument to BasicLocation.lookAround, so that a
room can be described from a point of view other than the actor doing
the looking.

</div>

<!------------------->
<div class=entry>

Fix: paragraph break in response to getting out of white box while
the box is closed (in the platform room).  (The last report -
"Okay..." - is displayed on the same line as the beeper noise.)

</div>

<!------------------->
<div class=entry>

Can we make every kind of noun phrase production derive from a common
NounPhraseProd base class?

</div>

<!------------------->
<div class=entry>

Allow multiple actors per command line, tads2-style, as in "bob, go
north. look. bill, go south."  (In tads 2, a new actor can be
specified after a period.)  However, only allow this in "synchronous"
mode, where the issuing actor waits for all commands to NPC's to
complete before taking another turn; in asynchronous mode, do not
allow mid-command target actor changes, because it's too confusing.

</div>

<!------------------->
<div class=entry>

Fix problem in touchObj precondition: we assume that we can find a
valid touch path, so we traverse the path without checking to see if
we got a nil path.  In some cases (such as when the target object is
in a location not sharing any common container with the actor), there
is no touch path at all, so we need to deal properly with this
possibility.

</div>

<!------------------->
<div class=entry>

Fix visual command separation for 'undo' after a multi-command line,
and for a multi-undo command line.

</div>

<!------------------->
<div class=entry>

Modify/replace/delete grammar rules.  Add new syntax:

<p>
<pre>
  modify grammar production(tag): <new-grammar-rule>:
    <property-list>
  ;
  replace grammar production(tag): <new-grammar-rule>: <class>
    <property-list>
  ;
</pre>

<p>
To make this workable, the "production(tag)" names of grammar match
objects must be unique; change the compiler to enforce uniqueness of
these names.

<p>
Also, change VerbRule to include a tag: VerbRule(tag).  This will
allow modify/replace to be used with VerbRule(tag) definitions to
replace library verb grammar rules.

</div>

<!------------------->
<div class=entry>

Add a mechanism for remapping a two-noun-phrase action to a different
action after resolving first object.  For example, allow mapping
ATTACK x WITH THROWING STAR to THROW THROWING STAR AT x.

<p>
To do this, add a new pair of properties to TIAction: remapDobjProp
and remapIobjProp; define these properties using the same template
style as the rest of the properties in DefineTIAction.  Add a new
remapTIAction() macro that can be used from within a remap() method
to remap a command.

<p>
Note that only the first-resolved object can be remapped, because the
whole point is to effect the remapping before resolving the
second-resolved object, so that the second-resolved object can be
resolved using the rules of the new action rather than of the
original action.

</div>

<!------------------->
<div class=entry>

In BasicLocation.lookAround, remove the point-of-view object from
the list of objects to be described, rather than removing the actor.

</div>

<!------------------->
<div class=entry>

Move the grammar convenience macros (VerbRule, SingleDobj, etc) out
of adv3.h and into us_eng.h - these are all specific to the English
verb grammar, so they should be in the English-specific definitions
rather than the language-independent definitions.

</div>

<!------------------->
<div class=entry>

If a Daemon is created with an interval of zero or less, it'll put
the scheduler into an infinite loop invoking the daemon, because the
daemon will be permanently schedulable.  Force the interval to at
least 1 on creation.

</div>

<!------------------->
<div class=entry>

Add a lookAround() method to Thing, to generate a description from
the point of view of the Thing.  This is necessary to allow things
like remote cameras.  This method should call the container's
lookAroundPov() method (which must also be added to Thing) with the
point of view set self; this algorithm will eventually reach the
innermost room-like object, which will display the appropriate
room-like description.

</div>

<!------------------->
<div class=entry>

Add a PAUSE command, to stop the real-time clock for games that
use real-time events.

</div>

<!------------------->
<div class=entry>

Add a grammar notation that specifies a match for one of several
vocabulary properties.  With the '&lt;prod&gt;' grammar that was being
kicked around for a while, the notation '<noun | adjective>' was
appealing, but without the angle brackets, it's not obvious what the
equivalent syntax would be.

<p>
Use angle-bracket notation, even though we don't use it for
individual tokens:  &lt;nounM nounN nounF&gt;

</div>

<!------------------->
<div class=entry>

Add an explicit 'grammar' declaration with no matchable rules, so that
production names can be declared without actually creating rules for
them.

</div>

<!------------------->
<div class=entry>

make 'inherited' after 'delegated' more consistent with the regular
inheritance behavior (in particular, the relatively new dynamic
inheritance search algorithm will fail to find a class related to
'self' in the delegatee's superclass tree, so there will be nothing
to inherit; ideally, we'd have an 'inheritance target' in the stack
frame in addition to 'self')

</div>

<!------------------->
<div class=entry>

NestedRoom.getTravelConnector refers to gActor.  The reason the method
looks at gActor is that it wants to check if the actor can see the
containing room, so that it can get the connector from the containing
room.  Add an 'actor' parameter to getTravelConnector(), so that we
can specify an actor explicitly and thus ask for travel connectors
outside of turn execution contexts.

</div>

<!------------------->
<div class=entry>

SouthwestAction is missing from action.t

</div>

<!------------------->
<div class=entry>

noTravelIn, noTravelOut, noTravelDown - these need to override
isConnectorApparent to return nil.

<p>
Add redirectTravelIn, etc, which do show isConnectorApparent = true.

</div>

<!------------------->
<div class=entry>

Add newActionObj alongside _newAction: the new function takes a
pre-created action instance, rather than creating a new instance
itself.

</div>

<!------------------->
<div class=entry>

Add a getBestMatch() method to ResolvedTopic to retrieve the
top-ranking object.  By default, provide an implementation that simply
returns an arbitrary object from the strongest match list.  Games and
library extensions could customize this to use a different topic
picker mechanism as desired, but providing a decent default
implementation would help authors get started without having to worry
about coding their own topic framework if they didn't want anything
specific here.

</div>

<!------------------->
<div class=entry>

Add a PreRestartObject, analogous to PreSaveObject, to allow any special
actions to be performed before a restart.

</div>

<!------------------->
<div class=entry>

execCommandTokens should probably switch the sense context upon
discovering a target actor different from the issuing actor, before
actually starting to execute the command.

</div>

<!------------------->
<div class=entry>

Move all of the output management into discrete OutputStream objects.
Associate filters, notifiers, capturers with individual streams.  By
default, create one stream for the main text and another for the
status line.

<p>
<b>NOTE:</b> This change affects all of the notifier, filter, monitor, and
capturer function interfaces.  All of these formerly global functions
are now methods of the OutputStream class.

</div>

<!------------------->
<div class=entry>

Regarding touch path calculation (see e.g. touchObj precondition):
should we be finding a touch path to an object in a separate location
not connected by containment, but connected by a SenseConnector?

</div>

<!------------------->
<div class=entry>

Fix basicScoreChange reporting for changes of 1 (or -1) points: use
singular "point".

</div>

<!------------------->
<div class=entry>

change the T3 Workbench .tdc format to use .t3m files

</div>

<!------------------->
<div class=entry>

vmrun: respond to Ctrl+Break to break into debugger

</div>

<!------------------->
<div class=entry>

"parse-debug" command: accept the command without the "on" or "off"
specifier, and simply invert the current mode.

</div>

<!------------------->
<div class=entry>

Add a nounMultiList production alongside nounList.  Use this
production in matching singleNoun, rather than using the regular
nounList, so that we don't create spurious additional matches for the
degenerate single noun phrase form of nounList.

</div>

<!------------------->
<div class=entry>

For bags of holding, check (in Container.tryPuttingObjInBag) to make
sure that the object being moved into the bag actually fits, and
don't even try if it won't.  This will avoid spurious attempts and
failures to move things in to a bag of holding implicitly after the
bag becomes full.

</div>

<!------------------->
<div class=entry>

Refactor the CommandProd-based productions in parser.t to move the
methods into new classes, and base the defined grammars on the
classes.  This will facilitate adding new commandPhrase grammar rules
by allowing the existing behavior to be re-used via inheritance.

</div>

<!------------------->
<div class=entry>

Add a new Actor property (revertTargetActorAtEndOfSentence) that, when
set, tells the parser to consider target actor designations ("bob, go
north...") in effect only until the end of a sentence.  When the
property is set to true, switch the target actor back to the original
issuing actor at the end of each sentence.

</div>

<!------------------->
<div class=entry>

As a convenience, add a new StyleTag subclass, HtmlStyleTag, for tags
with different renderings in HTML and plain text modes.

</div>

<!------------------->
<div class=entry>

Add some new style tags:

<ul>
<li>&lt;.a&gt; - for &lt;a&gt; text (and use it for
all links we generate)

<li>&lt;.statusroom&gt; - for the room name portion of
the status line

<li>&lt;.statusscore&gt; - for the score/turn count
portion of the status line
</ul>

</div>

<!------------------->
<div class=entry>

Add inputManager methods getKey() and getEvent() that provide covers
for inputKey() and inputEvent(), respectively, the integrate with the
real-time manager and the reports gatherer in the same manner as
inputLine.

</div>

<!------------------->
<div class=entry>

Don't use [badness] to reduce the priority of ordinal lists in
disambiguation responses; instead, use the ranking mechanism to give
ordinals a lower ranking than noun/adjective interpretations.

</div>

<!------------------->
<div class=entry>

Fix looping problem with answering 'g' to disambiguation queries.
(Don't store the response to a disambiguation query until after we
actually know that the input is an answer to the query, as opposed to
a new command.)

</div>

<!------------------->
<div class=entry>

Do not notify sense path in moveInto() when traveling.  (Travel uses
the separate TravelConnector mechanism, which doesn't necessarily map
directly onto sense connections; we don't want to attempt to notify
sense connections of travel because we don't actually use them for
travel.)

</div>

<!------------------->
<div class=entry>

When disambiguating interactively, if the response isn't in the full
list, check to see if it's in the full scope list.  This allows for
cases where the player really wants to try a command on something
that we decide isn't logical - it's better to let the player try than
to deny that the object is among the possible choices.

<p>
We should test the scope list as a second pass rather than allowing
the full scope on the first pass.  So, we should try first as we do
now, limiting scope to the narrowed ("logical") list; then, if that
fails, we should try again with the full scope list.

</div>

<!------------------->
<div class=entry>

Add an equivalent of the tads 2 "->" syntax: this syntax allowed
routing messages for one object to another object.  For example, if
we wanted to route "open desk" to "open drawer", we would put "doOpen
-> drawer" in the desk.  Define a new macro:

<p>
<pre>
  dobjForwardTo(Open, drawer)
</pre>

<p>
This is used <i>in place of</i> a dobjFor().

<p>
(This was from Phil Lewis, who suggested "reroute" as the name and
also suggested a slightly more general format: dobjReroute(drawer,
Open).  It might also be useful to be able to specify the verb to
forward separately, so that you could handle a verb with both a
different verb and different target object, but the action is
probably the same in most cases, so it seems more convenient to be
able to omit it.)

</div>

<!------------------->
<div class=entry>

In roomSmellLister (and roomListenLister), add a custom isListed
method that checks a new property of the target object,
isSmellListedInRoom (isSoundListedInRoom in the case of Noise
objects).  Set these properties to true by default.  Add an isListed
override to smellActionLister (and listenActionLister) that simply
returns true.  This change allows an Odor/Noise to list in response
to a >SMELL or >LISTEN without also showing in the normal room
description, as it would by default.

</div>

<!------------------->
<div class=entry>

Propagate the results of an action up to callers by returning the
CommandReportList.  Actually, we'll have to return a list of
CommandReportList objects, since one CommandReportList is generated
per iteration for an iterated action.  The aggregate list could be
stored in a CommandResults object, which could provide high-level
analysis methods (e.g., isFailure()) to interpret the action results.

<p>
To do this, return a CommandResults object describing the command
reports list from newAction(), nestedAction(), and so on.

</div>

<!------------------->
<div class=entry>

Provide a way of specifying a subclass of CommandReportList to use
when executing a new or nested command.  To do this, callers use
a new function that takes a particular CommandReportList subclass
to use while calling a callback:

<p>
<pre>
  result = withCommandReportsClass(
      MyCommandReportList, {: nestedActorAction(bob, SitOn, chair) });
</pre>

</div>

<!------------------->
<div class=entry>

In the tokenizer, if a word with a "'s" suffix explicitly appears in
the dictionary with the "'s", do NOT make the "'s" into a separate
token - keep the whole string with the "'s" as a single token.  This
allows for cases where the grammar has a literal token with a "'s"
suffix, and where vocabulary words (such as adjectives) are
explicitly defined with "'s" suffixes.

</div>

<!------------------->
<div class=entry>

In TravelConnector, allow for a single barrier rather than a list
of barriers.  If the travelBarrier property is not a Collection of
some kind, treat it as a single TravelBarrier.

</div>

<!------------------->
<div class=entry>

Add a OneWayRoomConnector to make it easier to define a connector
that connects one room to another but not vice versa.f

</div>

<!------------------->
<div class=entry>

Add checkTravelConditions() to TravelConnector.  Call this from
checkTravelBarriers().  By default, this does nothing; instances
can override it to apply special conditions to the travel in lieu
of creating a separate TravelBarrier object when the conditions
don't need to be re-used in other connectors.

</div>

<!------------------->
<div class=entry>

Fix indentation problem for grouped items in INVENTORY TALL lists.

</div>

<!------------------->
<div class=entry>

Hide intangibles from 'all' by default.  Noises and odors should
probably be included in 'all' for LISTEN/SMELL.

</div>

<!------------------->
<div class=entry>

When trying to put objects into a bag of holding to make room to take
a new object, don't even try moving an object that contains the bag
of holding (because doing so will just fail with a message "the <bag
of holding> is already in that").

</div>

<!------------------->
<div class=entry>

Need a better way to say "the one in the room" than showing the room
name, because that's not useful in input.  Should say something
like "the match on the floor".

</div>

<!------------------->
<div class=entry>

Once everything in a disambiguation list is a basic equivalent, we
could use the 'name' of the objects to display the prompt, rather
than using the input text.

</div>

<!------------------->
<div class=entry>

In Thing.initializeEquivalent, deal with the possibility that we have
a base class with a separate equivalent grouper.  Create a separate
grouper for the subclass by testing to see if equivalentGrouper is
defined <i>directly</i> by the class object.  If there is an inherited
grouper, we must create our own separate grouper for the subclass,
AND we must take the superclass grouper out of the listWith for the
subclass (since it will inherit the base class listWith by default).

</div>

<!------------------->
<div class=entry>

In action.t around line 1532, when we're adding the UnclearDisambig
flag, we might want to suppress the flag if the object we selected
and the objects we rejected are basic equivalents of one another.
This avoids weird situations such as

<p>
<pre>
  >light match
  (the match)
</pre>

<p>
when we have one match we're holding and another in the matchbook:
we choose the one we're holding over the one in the matchbook because
of the must-be-holding precondition to lighting a match, but mentioning
which one we're choosing is weird because it doesn't tell us anything.

</div>

<!------------------->
<div class=entry>

<pre>
>drop match
Which match, one of your matches, or the match in the matchbook?

>my match
Which match, one of your matches, or the match in the matchbook?
</pre>

<p>
...etc.  The problem is that we're taking "my match" to mean any
match in my possession for parsing purposes, whereas we differentiate
holding from indirectly owned.  Ideally, we'd prefer to treat "my
match" as "the match I'm holding directly" when it's ambiguous.

</div>

<!------------------->
<div class=entry>

Add a disambigName property, and use it instead of the ordinary name
when generating disambiguation prompts.  (We'll need aDisambigName,
theDisambigName, and countDisambigName as well to round out the set.)

</div>

<!------------------->
<div class=entry>

Add "x in y" grammar.

</div>

<!------------------->
<div class=entry>

Add a mechanism for distinguishing equivalents with different states:

<p>
<pre>
  Which candle to you mean, the lit candle or the unlit candle?

  -but not-
  Which wax do you mean, the unlit candle or the seal?
  -which should just be
  Which wax do you mean, the candle or the seal?
</pre>

<p>
Use this mechanism to create a base class for light sources.  We
can use this for things like matches and candles.  The disambig
name for an object is "lit x" or "unlit x", so we add the adjective
"lit" or "unlit" according to state.  Check the adjective in parseName.

<p>
Use this same mechanism to specify by owner when owner is a
distinguishing factor - "which gas mask do you mean, yours, or
teeterwaller's?"

<p>
To do this, associate with each object a list of "distinguisher"
objects.  A candle might include the "lit" distinguisher object, and
probably all objects would include the "owner" distinguisher.  We'd
make a list of all of the distinguishables in common to the set of
equivalents, then run through the common set.  For each one, we'd ask
the distinguisher if the list of equivalents we have is
distinguishable via this distinguisher.  The "lit" distinguisher
would return true if the objects were all in different "lit" states,
and the "owner" distinguisher would return true if all had different
owners.  We'd stop at the first distinguisher that can tell all of
the objects apart.  The distinguisher would give us the method to
call in each of the objects to list its distinguishing name - the
"lit" distinguisher would call the litName property, for example,
which would display "the lit candle" or "the unlit candle"; the
"owner" distinguisher would display "yours" or "teeterwaller's".

<p>
The response would have to be handled by the normal disambiguation
response mechanism, so the objects would have to conspire with the
distinguisher to have the proper adjectives.  This is easy, though,
because the objects are the ones displaying the adjectives in the
first place when they show the disambiguation list.

<p>
If we find no distinguisher that can tell all of the items apart,
we'd look for one that can tell at least some of the items apart, and
phrase it like this: "the lit candle, or one of the unlit candles".
If they select one of the ones indistinguishable with this
distinguisher, we'd iterate, and maybe pick it up with a separate
distinguisher next time.

<p>
If none of the distinguishers can tell any of the objects apart, we'd
simply choose one arbitrarily like we do now.

<p>
<pre>
>take candle
Which candle do you mean, the lit candle, or one of the unlit candles?

>unlit
Which do you mean, your candle, or one of Bob's?

>bob's
(arbitrarily picking one of bob's several unlit candles)
Taken.
</pre>

<p>
Note that for ownership distinctions, need to offer a way to refer to
unowned objects:

<p>
<pre>
>get candle
Which candle do you mean, Bob's, or the other one?
<i>-or-</i> Which candle do you mean, Bob's, or another one?

<i>[responses would include...]</i>
>another / another one / another gold coin / one of the others
 / one of the other gold coins / other / the other / the other one
 / the other gold coin / other gold coin
</pre>

</div>

<!------------------->
<div class=entry>

Hide actors from 'all' for all verbs by default.

</div>

<!------------------->
<div class=entry>

For "put in" and "put on", use roughly the same strategy as "take"
for generating the "all" list: include only objects that are directly
in the actor's location, or in fixed objects in the actor's location,
as "take" does, but also include objects that the actor is directly
holding.  Keep the same iobj/in-iobj exclusions.

</div>

<!------------------->
<div class=entry>

Break up TravelConnector.checkTravelConditions() into two separate
methods (canTravelerPass(traveler) and explainTravelBarrier(traveler)),
just like TravelBarrier.

</div>

<!------------------->
<div class=entry>

Fix Thing.normalizePath() so that it makes two separate passes over
the list.  It should apply the PathThrough tranformation first, then
the PathPeer transformation as a second pass.  (Performing both
transformations both on a single pass can cause PathThrough
transformations to be missed, because the PathPeer changes the list in
such a way that the PathThrough transformation doesn't recognize a
needed change.  The PathThrough condition could alternatively be
modified to recognize PathPeer operations, but it's easier to do
things in two passes.  Note that doing PathThrough first is safe,
because it only adds to the list - it never drops any operations that
the PathPeer transformation looks at.)

</div>

<!------------------->
<div class=entry>

Add distance differentiation for 'examine' descriptions (and for
'listen') and 'smell' descriptions as well).  Specifically, add
distantDesc and obscuredDesc, and call them from basicExamine
according to the current point of view.  Add corresponding methods for
'listen' and 'smell' descriptions.

</div>

<!------------------->
<div class=entry>

Add automatic state listing to the equivalent grouper.  Use a new
Thing method, getState, that returns a ThingState object.  Use this
object to group equivalents by state and to show the state of each
item.

</div>

<!------------------->
<div class=entry>

Use the ThingState object to provide the ordinary status description
of an object.

</div>

<!------------------->
<div class=entry>

Use ThingState to provide automatic matchName() filtering by state.
Add a property to ThingState, stateTokens, that lists tokens that
can only be used in noun phrases referring to an object in the state.

</div>

<!------------------->
<div class=entry>

Integrate Steve's exit lister package into the library.

</div>

<!------------------->
<div class=entry>

It would be nice to have a sorting order for the directions, so we
list in a more canonical order: north, south, east, west, northeast,
northwest, southeast, southwest, up, down, in, out.

</div>

<!------------------->
<div class=entry>

When two exits have the same destination, list them together: "south
(or out) to the front yard".

</div>

<!------------------->
<div class=entry>

Don't show exits to dark rooms in the dark.

</div>

<!------------------->
<div class=entry>

In listing exits from a dark room, maybe we should show exits leading
to rooms with light, since travel would be allowed to those locations.

</div>

<!------------------->
<div class=entry>

Change the way we figure out if travel from a dark room to an
adjoining lit room is possible.  Add a separate TravelConnector
method that specifically determines if the connector itself is
visible to a given actor in a given origin location when the origin
location is dark.  By default, make a connector visible from a dark
location when the destination room is lit.  This will provide the
customary behavior (i.e., dark-to-dark travel is prohibited, but
dark-to-light is allowed on the theory that some of the light from
the destination leaks through to the origin, making the connection
itself self-illuminating and thus visible even in the dark origin
room), while more clearly articulating the rule by making the
visibility of the connector the explicit factor in determining
whether or not the travel is allowed, and also providing a clean way
to override the default heuristic for visibility of the connector for
particular connections that should use a different rule.

</div>

<!------------------->
<div class=entry>

Add an option to show available exits in the status line (using
a terse display that just lists the direction names).

</div>

<!------------------->
<div class=entry>

Make Surface.PutOn behave like Container.PutIn with respect resolving
the indirect object using the tentative direct object list: if
everything in the tentative direct object match list is already on
the indirect object, flag the indirect object as illogical.

</div>

<!------------------->
<div class=entry>

Sense Event Model:  Create a new class, SensoryEvent, that can be used
to trigger transient sensory events that actively notify interested
observers of their occurrence.

</div>

<!------------------->
<div class=entry>

Add convenience macros for remapTIAction that define the full remapping
for a dobj or iobj to another action, with the same or reversed noun
phrase order:

<p>
<pre>
  dobjRemapTI(OpenWith, UnlockWith)
  dobjRemapTIReverse(FillWith, PutIn)
  dobjRemapTIReverse(ThrowAt, AttackWith)
</pre>

</div>

<!------------------->
<div class=entry>

examineSpecialContents should probably differentiate according to POV
and sight viewing conditions.

</div>

<!------------------->
<div class=entry>

Change CommandReportList to a SimpleOutputCapturer.  We don't actually
want to process any notifiers or monitors when capturing report results,
because we turn them into a report list that can be reordered.  We want
to wait until we actually display the reports to notify anything of the
output.

</div>

<!------------------->
<div class=entry>

<pre>
>i
You are carrying three matches (one lit), and a matchbook (which
contains two matches).

>x match
Which match do you mean, an unlit match, or the lit match?

>an unlit match
(the match)
The match is an ordinary match.
</pre>

<p>
It would be better not to make an arbitrary choice here, unless they
explicitly said "any unlit match".  We should have another go at
asking for detail in this case.

</div>

<!------------------->
<div class=entry>

Add TITLEs to &lt;A HREF&gt;'s in system messages.

</div>

<!------------------->
<div class=entry>

Exit lister: if we have multiple exits from a location with nil
destination names, we are incorrectly grouping them as though they
had the same destination name.  The result is that we only see one
such exit in an EXITS list.  Destinations with nil destination names
should be treated as unknown destinations.

</div>

<!------------------->
<div class=entry>

Sort adv3.tl alphabetically (except for 'modify' order dependencies).

</div>

<!------------------->
<div class=entry>

Add Dan Schmidt's hyphen-converting output filter to output.c

</div>

<!------------------->
<div class=entry>

Add Dan's Thing.canBeSeenBy, Thing.canBeSeen, etc.  (These are
convenience methods, especially for canBeSeen and its like, which
operate on the player character, saving a little typing by making
'gPlayerChar' implicit.)

</div>

<!------------------->
<div class=entry>

Add Dan's Event.delayEvent, removeEvent methods

</div>

<!------------------->
<div class=entry>

Add an event manager method that cancels an event based on the
obj/prop combination, to save work for cases where this uniquely
identifies the event (this way, the author doesn't have to go to the
extra trouble of saving the Event object reference if the event can
be uniquely identified without it).

</div>

<!------------------->
<div class=entry>

Add a "mass" or "collective" noun property, for objects that refer to
collections of large numbers of smaller parts, or continuously-measured
quantities: "some popcorn", "some water".  (Is there anything that this
changes besides changing aName to "some <name>"?  Should think about it.)

</div>

<!------------------->
<div class=entry>

Add a lower-level base class for Switch, OnOffControl, that keeps
track of the on/off state and accepts "turn on" and "turn off".
Define the additional switch-specific verbs ("switch" and "flip")
only in the Switch subclass - this allows for adding on/off behavior
without making something look exactly like a light switch.

</div>

<!------------------->
<div class=entry>

Add a GO BACK command to return to the most recent location (if the
connector in was reversible).

</div>

<!------------------->
<div class=entry>

Keep track of the last "interlocutor" for each actor; this is actor
last addressed in a targeted command ("bob, go north"), or the last
actor in a conversational command - ASK ABOUT, TELL ABOUT, SHOW TO,
GIVE TO.  For the conversational commands, if the actor is left out
(ASK ABOUT GOLD, TELL ABOUT STORM), use the performing actor's most
recent interlocutor as the default, if the interlocutor is still
within talking range.

</div>

<!------------------->
<div class=entry>

Create a subclass of Actor, UntakeableActor, for an actor that can't
be taken or moved.  Define an additional subclass, Person, to
represent human characters, and provide some custom "fixed" messages
for it.

</div>

<!------------------->
<div class=entry>

Ensure that the SCORE and FOOTNOTE modules are completely modular,
so that they can simply be omitted from the build if not required.

</div>

<!------------------->
<div class=entry>

Get rid of libMessages.openBracket and closeBracket; instead, add
a style tag, <.parser>...<./parser>.

Also, add <.notification>...<./notification> for notifications
(score changes, FOOTNOTE instructions, etc.).

</div>

<!------------------->
<div class=entry>

Change withBrackets() to parserMessage(), for better documentary
effect.

</div>

<!------------------->
<div class=entry>

Simplify the menagerie of output filters, notifiers, monitors,
and capturers, reducing everything to a single type (filter).
Enforce stacking of filters.

</div>

<!------------------->
<div class=entry>

Get rid of the paragraph suppression immediately following input.
Instead, use the command sequencer to display the appropriate kind
of separation.

</div>

<!------------------->
<div class=entry>

Rename CommandReportList to CommandTranscript, and rename
gCommandReports to gTranscript.

</div>

<!------------------->
<div class=entry>

Add resolved object arguments to Actor.addPendingAction,
Actor.addFirstPendingAction.

</div>

<!------------------->
<div class=entry>

Rearrange arguments to Actor methods addPendingCommand,
addPendingAction, addFirstPendingCommand, addFirstPendingAction to
move the firstInSentence flag first.  This will keep everything
consistent with the rearrangement necessitated by adding the varargs
resolved object list to addPendingAction and addFirstPendingAction.

</div>

<!------------------->
<div class=entry>

When a command is applied to several objects, and processing the
command for some of the objects involves implied subcommands, set
off the results for the objects with implied subcommands visually,
by putting an extra paragraph break before and after each result
for an object with implied subcommands:

<p>
<pre>
PO Box: Taken.
red ball: Taken.

iron key:
(First putting the red ball in the duffel bag to make room)
Taken.

blue test booklet: Taken.

brass key:
(First putting the red book in the duffel bag to make room)
Taken.

gold coin: Taken.
gold coin: Taken.
</pre>

</div>

<!------------------->
<div class=entry>

Use a new style tag, <.commandsep>, for command separation,
eliminating the method call commandSequencer.startNewCommand().
Using a tag instead of a method call will work better with text that
doesn't reach the output stream immediately (for example, text that
is queued into a command transcript during command results display).

</div>

<!------------------->
<div class=entry>

In Thing.construct(), initialize the new object's vocabulary words and
add them to the global dictionary.

</div>

<!------------------->
<div class=entry>

Add information on the connector back, if known, to the EXITS display:

<p>
<pre>
  Obvious exits lead north, back to the east, and south to the den.
  ...north; east, back to the living room; and south, to the den.
</pre>

</div>

<!------------------->
<div class=entry>

For NPC's, the announcement/result format for implied commands should
probably be changed.  In particular, we should probably just treat NPC
implied actions as full separate commands:

<p>
<pre>
>bob, north
Bob opens the door.

Bob departs through the door.
</pre>

</div>

<!------------------->
<div class=entry>

For NPC's, don't allow interactive defaulting for an implied command.

</div>

<!------------------->
<div class=entry>

For NPC's, if an implied command fails, we should fail with an indication
that the NPC needs to perform the implied command:

<p>
<pre>
>bob s
Bob must open the door before he can do that.

>bob, open door
Bob must unlock the door before he can do that.
</pre>

</div>

<!------------------->
<div class=entry>

Get rid of gCommandReportClass and withCommandReportsClass.  Instead,
add a parameter to _newAction() to specify the transcript class to
use.

</div>

<!------------------->
<div class=entry>

Add a new BasicLocation method, getRoomPartLocation(part), which
returns the immediate container of the given room part, as perceived
in that location.  Top-level rooms would generally just return 'self'
if they have the room part, nil if not.  Nested rooms would generally
pass this up to their containers, because they don't have room parts
themselves in most cases.  Nested rooms with their own room parts
would handle it themselves.

</div>

<!------------------->
<div class=entry>

"x floor" - should list objects that are on the floor; likewise for
other room parts (walls, ceiling).  Use a separate listing test
(isListedInRoomPart(part)) to allow objects to opt out of being
listed specifically in such cases.

<p>
For special descriptions, add a "room part location" property - this
is a purely advisory property used only for finding contents of the
floor and so on.  When we "x floor", show special descriptions only
for objects whose roomPartLocation is the floor of interest.

</div>

<!------------------->
<div class=entry>

Re-enable the transcript after prompting for interactive resolution
(reading an OOPS response, a disambiguation response, etc).

</div>

<!------------------->
<div class=entry>

Add a method to Action to swap the roles of the tentative objects,
for use with the 'verify' forwarding for TIAction remapping.  Add a
call to this method to the dobjRemapTIReverse/iobjRemapTIReverse
macros before they forward their 'verify' calls.

</div>

<!------------------->
<div class=entry>

When an action is remapped, and we need to announce an object (such
as a defaulted object), announce the <i>entire</i> action, not just the
object.  For example:

<p>
<pre>
>fill bucket
(dipping the bucket into the river)

>fill bucket
(pouring the coffee into the bucket)
</pre>

<p>
This is important because the normal announcements are worded with the
intention of being tacked onto the end of what the player typed; when
the action is remapped, the action we're actually executing is different
from what the player typed, so phrase fragments that are intended to be
added to what the player typed are no long applicable.

</div>

</body>
</html>