TADS Revision History

Recent Changes to TADS

#### Index to Versions

- Version 2.5.9
- Version 2.5.8
- Version 2.5.7
- Version 2.5.6
- Version 2.5.5
- Version 2.5.4
- Version 2.5.3
- Version 2.5.2
- Version 2.5.1
- Version 2.5.0

#### Organization of this Page

This page is a list of recent changes to TADS, arranged chronologically: changes are grouped by release, with the most recent release listed first. Each release incorporates all new features and corrections of each prior release unless otherwise stated.

#### Generic and Platform-Specific Changes

Since version 2.2.6, the TADS change log has been divided into two separate files: one for "generic" changes that apply to TADS on all types of computers and operating systems, and one for changes that apply only to specific platforms. This file contains the generic release notes. Platform-specific release notes are in a separate file for each platform:

> Changes specific to MS-DOS and Windows

#### Multimedia vs. Text-Only Interpreters

These release notes sometimes refer to the "character-mode" or "text-only" TADS Interpreter. This is meant to distinguish the traditional TADS Interpreter, which can only display text, from the multimedia interpreters such as HTML TADS and HyperTADS, which can display graphics as well as text. The traditional TADS Interpreter has a graphical user interface on some systems, such as the Macintosh, so it's not really a character-mode application on those systems; nonetheless, we still refer to it here as the character-mode Interpreter simply to make it clear that we're not talking about one of the multimedia versions.

#### Older Revisions

To keep the size of this page under control, changes are listed here only for the most recent several versions of TADS. Older release notes are in separate files:

- Generic changes from version 2.2.3 through 2.4.0 are in TADSV240.TXT.
- DOS-specific changes from version 2.2.3 through 2.4.0 are in TADSV240.DOS.
- For DOS, all revisions from 2.0 through 2.1.0 are available in the file TADSV200.DOS; those from 2.1.1 through 2.2.2 are in TADSV222.DOS.
- Similar files are available for other platforms; please refer to your platform-specific release notes for details.

Because the older revision history files are quite large and are static (they are, after all, historical), they're not included in the normal TADS distributions, but you can download them from the Interactive Fiction Archive via the internet at ftp://ftp.ifarchive.org/if-archive/programming/tads2/manuals/ (note that ftp.ifarchive.org is the new home, effective August 2001, of the former ftp.gmd.de archive).

### Version 2.5.9

Released on September 12, 2004

- The "file safety" levels have changed slightly to provide better security against malicious game programs. First, level 2, which formerly provided global read access but no write access, now instead provides read/write access to the current working directory only (the game isn't allowed any access to files outside of the working directory). Second, the default safety level is now level 2. In the past, level 1 (read from any file/write to current directory only) was the default, which left open the possibility that a game could access data outside of the working directory. A malicious game could conceivably have exploited this by, for example, secretly copying sensitive data to the game directory for later use by a coordinating network worm, or by encoding the data in a hyperlink (displayed in an HTML-enabled game) that takes the player to a spyware site when clicked. The new default setting should effectively eliminate these risks by barring access to any files outside of the working directory.
- A bug in the compiler sometimes caused crashes when the "preinit" function called certain built-in functions, particularly for file manipulation. The problem was somewhat random, and tended to show up on some machines and not others, because it depended on memory conditions left over from other programs. The problem showed up for several people when they included the "gameinfo.t" module in their games, because that module writes a text file during preinit. The bug has now been fixed.
- An interpreter bug was capable of corrupting list values during game execution under very rare conditions. The bug only showed up when assigning a value to an indexed element of a list (either directly or via the "+=" or "-=" operators) at just the right moment to trigger garbage collection, and only then when the list happened to be situated in memory in just the right way. The bug was more likely to occur with small "heap" memory settings (the "-mh" option); with the large default heap of most current interpreters, the bug almost never showed up. The bug was also quite unlikely to occur except in games that perform unusually heavy list processing. The bug manifested itself in unpredictable ways, ranging from spurious run-time errors to interpreter crashes. This has now been fixed. Note that most games that were likely to trigger the bug in the past will now instead cause a "heap overflow" error; this error is valid, and indicates that the game exhausted the available memory for processing list and string values. If a heap overflow does occur while running a game, try increasing the heap size using the "-mh" command-line option when you run the game.
- An inconsistency in the command parser has been fixed. In the past, the parser didn't properly take into account whether responses to missing object prompts were singular or plural. This caused some subtle differences between typing a full command and piecing a command together with missing object prompts. In particular, the parser didn't announce the object names for a plural response, and didn't check rejectMultiDobj. This has been fixed, so the parser's behavior is now consistent for missing object responses.
- In the past, the parser incorrectly treated THEM as plural even when it referred to only one object, so it checked with rejectMultiDobj in these cases. This is undesirable in some cases, especially when the single object being referred to is an object whose name has plural usage. The parser now treats THEM as singular when it refers to just one object.

### Version 2.5.8

Released on June 12, 2004

- In adv.t, THROW AT now uses a new method, throwHitDest, to determine where the thrown object lands. This method is called for the actor's current location; by default, it simply returns 'self', so a thrown object simply lands in the actor's current location. This is the same behavior as in the past. However, the special 'theFloor' object overrides this to return the current room. This corrects a problem that occurred when the player sat on the floor and then threw something: because the object formerly ended up in the actor's location, the object landed in the 'theFloor' object, at which point the object became inaccessible. This change ensures that a thrown object will never be moved into 'theFloor', but will always land in the actor's actual room location. As a side benefit, the new method also makes it possible to customize the location where objects land when thrown from within a nested room.
- When running in HTML mode, the default parser error message 1 ("I don't understand the punctuation %c") now includes an "\H-" sequence before the message to ensure that the unrecognized character is displayed literally if it's an HTML markup-significant character (such as '<' or '&'). It also shows an "\H+" sequence after the message to restore HTML mode. In the past, if the player entered a markup-significant character while the interpreter was in HTML mode, the HTML parser could become momentarily confused, leading to strange output.
- The new parser hook parseDefaultExt() extends the parseDefault() function. The new function takes two additional parameters, giving the actor and deepverb object involved in the command; the new parameter list is parseDefaultExt(actor, verb, obj, prp). If the game defines parseDefaultExt(), then the interpreter ignores parseDefault() and calls parseDefaultExt() instead. If the game does not define parseDefaultExt(), but does define parseDefault(), the interpreter uses parseDefault() as it used to, which ensures that existing games will continue to run unchanged. You can use the new extended version of the function if you need the actor and/or verb information in displaying the default object message; this is useful in some non-English languages where a default object name's noun phrase must be inflected according to its usage in the command.
- The new parser hook preparseExt() allows the game to inspect and optionally change text the player types in response to parser questions: disambiguation queries, requests for missing direct or indirect objects, and OOPS typo-correction opportunities. The new function's parameter list is preparseExt(actor, verb, str, typ), where 'actor' is the actor performing the command, 'verb' is the deepverb object, 'str' is a string containing the exact text the player typed in, and 'typ' is an integer giving the type of query the player is responding to. The meaning of 'typ' is the same as the that of the type codes passed to commandPrompt() and commandAfterRead(). The function can return a new string, which the parser will use to replace the text the user typed; true, to proceed with the original text the user typed; or nil, to treat the user's text as a brand new command, bypassing the special interpretation as a response to the parser's question. The game doesn't have to define the preparseExt() function; it's purely optional, so existing games will not be affected.
- When the interpreter looks for external resource bundles (*.rsN files), it now looks for the files using lower-case and upper-case suffixes (in other words, it looks for both *.rs0 and *.RS0, and likewise for digits 1-9). Lower-case suffixes are tried first, then upper-case. This change makes the naming system more flexible on systems with case-sensitive file systems, such as Unix; for systems such as Windows and Macintosh that have case-insensitive file systems, this change will have no effect.
- A bug in the parser made it impossible to use numeric adjectives in certain phrasings. In particular, if a given word was defined in a game as both a noun and an adjective, but the word was defined only as a noun for a given object that takes a numeric adjective, then the phrasing noun number didn't match the object. For example, if the word "switch" was defined as a noun for a given numbered switch, but "switch" was defined as an adjective for some other object, then "switch 5" didn't match the switch even if "5 switch" did. This has been corrected.
- The compiler now checks for missing symbols before running the 'preinit' function, and skips running preinit if any symbols are undefined. In the past, the compiler called preinit even if some symbols were undefined; if preinit itself called any undefined functions or invoked methods of undefined objects, this sometimes led to misleading error messages. The compiler will now simply point out the missing symbols, and skip running preinit entirely.
- The compiler now allows filenames up to 255 characters to appear in the source file names in debugging records. In the past, the limit was 127 characters. Important note: due to a bug, older interpreters cannot properly handle .gam files compiled with debugging information with path names over 127 characters. Attempting to load .gam files with debugging information containing long source file names will cause unpredictable results. Since some users might still have older interpreter versions, we strongly advise against releasing games compiled with debugging information. That is, you should never release a game that you compiled with the "-ds" or "-ds2" options.
- In the past, if the game code called a function or method, using the return value of another function or method as an argument, and the other function or method didn't actually return any value for the argument, the results were unpredictable; in some cases, this even caused the interpreter to crash. The interpreter is now more careful about checking for these cases; when they occur, the interpreter now automatically adds 'nil' values for the missing arguments. This should ensure that errant code won't crash the interpreter, without breaking any existing code with "asymptomatic" instances of this error.
- The default "file safety level" for the command-line interpreters is now set to 1, which allows reading files from anywhere on the disk, but allows writing files only to the current working directory. This protects against malicious game authors attempting, for example, to modify your operating system's files. You can manually override this to use a more permissive or more protective level using the "-s" option.
- External functions are now obsolete and can no longer be used on any platform. One of the nice things about running games with a system like TADS is that you don't have to worry as much about viruses and other malicious code when playing downloaded games, since games run in the interpreter environment rather than as native code. The external function feature made it possible for games to call out to native code, though, so a malicious author could have used external functions to do damage to a user's system. Removing this feature eliminates this security loophole. External functions were only supported on a few platforms to start with, and they never caught on with authors, probably because they were difficult to use and had serious drawbacks (such as complete unportability). Since no one has ever had much use for this feature, and because of the potential security vulnerability, we've decided that there's no reason to keep it around.
- In the past, the compiler did not accept 'self' as an element in a list, even in contexts where 'self' was otherwise valid. The compiler now does accept 'self' as a list element in method contexts.
- A bug in the interpreter sometimes made the result of the subtract-and-assign operator ("-=") incorrect under certain circumstances: specifically, the problem occurred when the left-hand side was a local variable, the local variable contained a list value, and the list value did not contain the value on the right-hand side of the operator. In some such cases, a run-time error occurred; in some others, the wrong value was assigned to the local variable. This has been corrected; when the value on the right side is not in the list, the list value in the local is simply left unchanged.
- Due to a bug, the compiler sometimes crashed if you used a "break" and "continue" statement in an invalid context (i.e., outside of a "while", "for", "do", or, in the case of "break", a "switch" statement). This has been corrected; the compiler now simply flags these as errors, but shouldn't crash.

### Version 2.5.7

Released on September 22, 2002

- The new system information code __SYSINFO_INTERP_CLASS returns information on the "class" of interpreter currently running. This returns one of the following codes:
  - __SYSINFO_IC_TEXT: a text-only, character-mode interpreter, such as an MS-DOS or Unix interpreter. These interpreters use a single, fixed-pitch font, and support the text-only HTML subset.
  - __SYSINFO_IC_TEXTGUI: a text-only interpreter on a graphical platform, such as MacTADS or WinTADS. These interpreters behave essentially identically to character-mode text-only interpreters, so from the game program's perspective there is no practical difference between this and character-mode interpreters.
  - __SYSINFO_IC_HTML: a full HTML-enabled interpreter on a graphical platform, such as HTML TADS on Windows or HyperTADS on Macintosh. These interpreters can display text and graphics, use multiple fonts, and interpret the full HTML TADS markup language.
- The travel system in adv.t has been enhanced slightly to allow rooms to differentiate their travel behavior for travel by the player character vs. travel by non-player characters. The new properties actorNorth, actorSouth, actorEast, actorWest, actorNE, actorNW, actorSE, actorSW, actorUp, actorDown, actorIn, and actorOut are now called when an NPC attempts travel; these properties correspond to the traditional properties north, south, east, west, and so on, and the only difference is that the new properties are called when NPC's travel. The traditional properties are still called for all player character travel. By default, each of the new actorXxx properties simply returns the value of the corresponding traditional property: so actorNorth by default simply returns the value of (self.north). This means that if you don't want to differentiate NPC travel from PC travel, you need do nothing at all; but if you want a particular travel direction from a particular room to work differently for an NPC than it does for the player character, you simply need to override actorNorth (or whichever direction you want to customize) in that location. Thanks to Tommy Nordgren for suggesting this enhancement.

### Version 2.5.6

Released on June 1, 2002

- The new system information code __SYSINFO_TEXT_COLORS tests for text color support. Currently, only the HTML interpreters support text colors; the text-only interpreters have no text color support. The return value indicates the level of support available:
  - 0/nil - no text color support
  - 1 - parameterized color names only (TEXT, STATUSTEXT, etc.)
  - 2 - the eight ANSI colors (white, black, red, blue, green, yellow, magenta, cyan) are supported for the text foreground color, but the background color cannot be set
  - 3 - the eight ANSI colors are supported for text foreground and background colors
  - 4 - full RGB colors are supported, foreground and background (the HTML interpreters generally return this code)
- The new system information code __SYSINFO_TEXT_HILITE tests for text highlighting support. This returns 1 if the interpreter is capable of rendering highlighted text (i.e., text within "\( \)" sequences, or text in HTML <B> sequences) with a distinctive appearance, 0 or nil if not. Most interpreters are capable of showing highlighting, except when running in "plain" mode or when using a terminal or display device that has no ability to show different text colors or styles.
- The new system information code __SYSINFO_OGG tests for Ogg Vorbis audio format support. systemInfo(__SYSINFO_OGG) returns 1 if the Ogg Vorbis format is supported by the interpreter, 0 if not.
- The new system information codes __SYSINFO_MNG, __SYSINFO_MNG_TRANS, and __SYSINFO_MNG_ALPHA test for basic MNG (animated image) suport, MNG transparency support, and MNG alpha-channel support, respectively. These are analogous in meaning to the PNG information codes.
- The interpreter now includes the name of the external resource (.rsn) file in error messages that result from errors reading these files. In the past, the interpreter did not indicate which specific file was causing the problem, which made it difficult to track down where the problem was. (The non-specific error message worked fine in the days before external resource files, when everything was always in the single .gam file, but the new, more specific diagnostic information is important now that a game's resources can be put in several separate files.)
- In adv.t, `basicMe.moveInto(room)` now calls a new method, `room.meIsMovingInto(self)`, whenever the `basicMe` object being moved is the current player character (i.e., `self` is the object that `parserGetMe()` returns). A default implementation of `meIsMovingInto(meActor)` has been added to `room`; this default implementation does nothing. Finally, an overriding implementation of `meIsMovingInto(meActor)` has been added to `theFloor`; this implementation sets `theFloor.sitloc` to the player character actor's previous location. The purpose of all of this new mechanism is to ensure that `theFloor.sitloc` is properly set to the player character's prior location whenever the player character is explicitly moved into `theFloor`. In the past, `theFloor.sitloc` was set whenever the player character moved to `theFloor` via a "sit on the floor" command from the player, but wasn't set when the object was moved to `theFloor` through other means. The `theFloor` object uses the `sitloc` property to remember the location that originally contained the actor before sitting on the floor; this is needed because `theFloor` is a floating item and thus doesn't have an actual location of its own.
- In adv.t, the various `hider` subclasses (`underHider`, `searchHider`, `behindHider`) now check to see if they were never hiding anything to start with, and issue an appropriate message if so. In the past, if an object was defined using one of the `hider` subclasses, but no other object was ever hidden inside the `hider`, looking in/under/behind the object generated an erroneous message, of the form "You find , which you take." Now, when the list of hidden objects is initially empty, the generated message is simply "You find nothing under (the object)."
- The `parserDictLookup()` function can now be called from within `init()`. In the past, this function caused a run-time error if called while `init()` was running; this has been corrected.
- Fixed a problem in parserGetObj(PO_ACTOR) that caused the incorrect actor to be reported between the time `preinit` was called and the time `preCommand` was called. During this window, if a command was the first command on a new command line, and the command line didn't start with a target actor ("bob, ..."), then parserGetObj(PO_ACTOR) incorrectly returned the actor from the previous command. This no longer occurs; the function now correctly returns the current "me" object in such cases.
- Fixed a problem in the output formatter that caused problems with displaying a series of quoted spaces ('\ ' sequences) in some situations, especially on platforms with proportionally-spaced display fonts such as the Mac. This has been corrected.
- The compiler no longer treats any characters in the "extended" character set (i.e., characters with character codes outside the ASCII range 0 to 127) as whitespace. In the past, the compiler on some platforms treated certain extended characters as spaces, which sometimes caused problems for authors working in non-English languages. The compiler has no knowledge of the attributes of any localized character sets (the compiler's character set translation mechanism does not provide attribute information, only set-to-set mapping information), so it was incorrect of the compiler to assume anything about which extended characters represented whitespace characters. This problem manifested itself most apparently when a string containing extended characters spanned several lines of source; if the compiler mistook any of the leading characters on continuation lines for whitespace, it would remove them, resulting in incorrect text displayed at run-time. This has been corrected; the compiler now treats all extended characters as non-whitespace characters.
- Fixed a problem in the `execCommand()` built-in function that caused various problems ranging from data value corruptions to interpreter crashes. The problem appeared when `execCommand` was used to execute a command that terminated with an `exit` or `abort`, and then only when certain combinations of operations on local variables followed. The problem has been corrected.
- Fixed a compiler bug that caused an infinite loop when parsing certain nested `switch` statements. A `switch` containing string constant `case` labels nested within another `switch` with string constant `case` labels sporadically caused this problem. This has been corrected.
- Fixed a problem in the compiler that caused the `contents` lists of objects to be initialized improperly in certain cases. In particular, if an object's `contents` list was used during execution of the `preinit` function, any object that inherited a `location` value equal to the given object was omitted from the given object's `contents` list, when clearly the object should have been included in the list. This only affected `preinit`, and then only when a `contents` that should have contained an object with an inherited location was referenced from within the `preinit` function. This has been corrected; inherited `location` values are now properly handled when `preinit` is executing.
- The compiler and interpreter must sometimes create temporary files for internal memory management purposes. On certain systems (in particular, DOS, Windows, and Unix), TADS determines a suitable directory location to store any needed temporary files by looking in the environment for variables called TEMPDIR, TMPDIR, TEMP, and TMP (in that order), and using the value of the first such variable it finds as the temporary directory path. In past versions, if the path found in this manner was invalid, the interpreter or compiler would usually terminate with an error message that wasn't very helpful in tracking down the problem. In most cases, the error message was "unable to open swap file." This has been changed; now, if the temporary path obtained from the environment variables is invalid, TADS ignores the path and simply creates any necessary temporary files in the current working directory.
- A number of messages in adv.t now use format strings ("%you%" and the like) where they didn't before but should have, to facilitate games written in styles other than second-person. Thanks go to Bennett Standeven for catching these.
- Fixed a problem that caused interpreter crashes under rare circumstances for interpreters that could play more than one game in a single session (such as the HTML TADS interpreter). If the interpreter loaded a game that used the "output filter function" feature, and then that game was terminated and another game was loaded into the same interpreter session, and the new game didn't use its own output filter function, results were unpredictable, and interpreter crashes sometimes occurred. This has been corrected. (This problem did not affect most platforms, because most interpreters terminate when the game being executed terminates.)
- Fixed an interpreter problem that caused the "`new`" operator to generate a run-time error in some unusual situations. In particular, if the constructor modified a property of the object containing the method that invoked the `new` operator (directly in its own code, or in any code it invoked), then the error "TADS-5: attempting to reallocate a locked object" appeared sporadically. This has been corrected.

### Version 2.5.5

Released on September 27, 2000

- In adv.t, a comment in listcontgen() has been fixed to reflect that it's actually part of the "tall" listing rather than the "wide" listing.
- In adv.t, in moveableActor.travelTo, if the actor's previous location was nil, a run-time error occurred. This has been corrected.
- In adv.t, in thing.thatdesc, the plural form has been changed to display "those" rather than "them"; this provides a better parallel to the singular display ("that").

### Version 2.5.4

Released on June 17, 2000

#### New systemInfo() flags for PNG transparency

Two new systemInfo() flags have been added to test for support of certain features of the PNG image format:

- __SYSINFO_PNG_TRANS: tests for PNG transparency support. Some newer versions of the HTML interpreter support PNG transparency, which allows parts of a PNG image to be designated as transparent so that the background shows through. systemInfo(__SYSINFO_PNG_TRANS) returns true if transparency is supported when displaying PNG images, nil if not. This will never return true under interpreters that don't support PNG images at all. Note that this flag indicates only simple transparency support, which allows pixels to be designated as fully opaque or fully transparent, and does not imply support of full alpha blending; some interpreters (such as the Windows HTML interpreter 2.5.4) support only simple transparency but not alpha blending.
- __SYSINFO_PNG_ALPHA: tests for PNG "alpha blending" support, which allows individual pixels of a PNG image to be designated as partially transparent. Currently, none of the interpreters support alpha blending in PNG images; this flag has been added for possible future use.

#### Bug Fixes

- A bug in the compiler caused a crash under certain unusual conditions when the program defined a symbol as an object, and the symbol was already defined as a property or function. Most of the time, the compiler reported an error ("redefining symbol as object"), but in some cases the compiler crashed. This has been corrected.

### Version 2.5.3

Released on April 16, 2000

This version contains no changes to text-only versions of TADS; the only changes are in HTML versions.

### Version 2.5.2

Released on March 27, 2000

#### Index of Changes

- Parser recognizes isThem
- New scoreFormat() Function
- New systemInfo() Capability Codes
- Bugs Fixed

#### Parser recognizes isThem

The parser now recognizes the `isThem` property for the purposes of deciding on the pronoun to display when prompting for an indirect object. In the past, the parser only recognized the `isHim` and `isHer` properties, and used the pronoun "it" if neither of these properties were consistently defined for the objects matching the direct object. The parser now uses the pronoun "them" if the matching objects all have `isThem` set to `true`.

For example:

       >throw pants
       What do you want to throw them at?

#### New `scoreFormat()` Function

The way that adv.t displays the status line has been changed slightly to simplify coding of special formats. A new function, `scoreFormat()`, is now responsible for formatting the string to display in the right half of the status line. `scoreFormat()` takes the current score and the current turn counter as arguments, and returns a string to display in the right half of the status line. The default implementation in adv.t simply returns a string consisting of the score, a slash ("/"), and the turn count, which provides the same format that adv.t has traditionally used for the status line.

The existing function `scoreStatus()` now calls `scoreFormat()` to generate the display. In addition, the code in `room.statusLine` that generates the HTML version of the status line now calls `scoreFormat()` as well. This makes `scoreFormat()` the single point in adv.t where the right half of the status line is formatted.

The advantage of this new mechanism is that you can customize the display of the right half of the status line for both text-only and HTML-enabled games simply by replacing the `scoreFormat()` function.

Of course, HTML-enabled games are not limited to using the traditional status line display; if you want a completely custom status line display when running under an HTML-enabled interpreter, you can replace adv.t's `room.statusLine` and generate your own <BANNER> display. The new `scoreFormat()` mechanism, however, is convenient when you simply want to customize the right half of the status line, but still use the traditional single-line status format.

#### New `systemInfo()` Capability Codes

The `systemInfo()` function accepts several new capability codes that let you discover whether the system is capable of following URL-style <A HREF> hypertext links in HTML-formatted text. The new codes are:

- `__SYSINFO_LINKS_HTTP` - checks if the system can follow HTTP links to display web pages. HTTP URL's start with "`http:`".
- `__SYSINFO_LINKS_FTP` - determines if the system can follow FTP links, which start with "`ftp:`".
- `__SYSINFO_LINKS_NEWS` - determines if the system can follow news links to Usenet newsgroups, which start with "`news:`".
- `__SYSINFO_LINKS_MAILTO` - determines if the system can follow mail links to send email; these links start with "`mailto:`".
- `__SYSINFO_LINKS_TELNET` - checks if the system can follow telnet links, which start with "`telnet:`".

For example, suppose you want to display a link to a web page you've created for your game, so that players can check for updates and hints on your web site. You can use `__SYSINFO_LINKS_HTTP` to check the user's TADS interpreter for HTTP link capability; if the interpreter can follow HTTP links, you can show your link with a friendly display, and fall back on spelling out the URL when the interpreter can't directly follow the link.

       "You can check for updates to this game at ";
       if (systemInfo(__SYSINFO_LINKS_HTTP))
           "<A HREF='http://www.mysite.com/mygame.htm'>my web site</A>";
       else
           "my web site (http://www.mysite.com/mygame.htm)"
       ". This site also has hints and some background
       information about the game. ";

#### Bugs Fixed

- For a verb defined with the `[disambigDobjFirst]` flag, the parser called the indirect object's `verIoVerb` method incorrectly in cases where the player omitted an indirect object, causing the parser to try to find a default indirect object. For example, suppose you were to make the following definitions:

        waveVerb: deepverb
             verb='wave'
             sdesc="wave"
             prepDefault = atPrep
             ioAction(atPrep) = [disambigDobjFirst] 'WaveAt'
        ;
        modify thing
             verDoWaveAt(actor) = {}
             verIoWaveAt(actor, dobj) = {}
             ioWaveAt(actor, dobj) = { "Nothing special happens. "; }
        ;

  In the past, if you typed a "wave" command with no indirect object, as in "wave flag," the parser incorrectly invoked the `verIoWaveAt` method with only one argument, causing a run-time error. This no longer occurs; the parser consistently calls the `verIoVerb` method in these cases with the correct number of arguments.

- In past versions, the `parserTokenize()` built-in function did not work properly when the input text contained a quoted string; in particular, the text of the quoted string was not included in the list. This has been corrected; the tokenized list now correctly includes the quoted string, enclosed in double quote marks (following the same rules as `preparseCmd()`). The same problem affected the token list passed to `parseUnknownVerb()`; this has been corrected as well.
- If the `preparse()` or `preparseCmd()` functions executed an `exit`, `exitobj`, or `abort`, the interpreter displayed an error message (such as "'abort' statement executed"). This was mostly harmless; these types of statements are generally not needed within `preparse()` and `preparseCmd()`, because these functions use return codes rather than `exit` and the like to control further processing. However, certain built-in functions perform `abort` operations implicitly; in particular, the `parserReplaceCommand()` function uses `abort` to start processing the new command immediately. To enable the use of such built-ins in `preparse()` and `preparseCmd()`, the interpreter no longer displays an error message when `exit`, `exitobj`, or `abort` are used in these user functions.
- In the past, the `parserResolveObjects()` built-in function did not correctly handle unknown words; in particular, the function did not display any message if the noun phrase contained an unknown word, even when the "silent" parameter was nil. This has been corrected. Now, when "silent" is nil, the function handles unknown words by displaying the normal error message ("I don't know the word..."), then prompting the player for a new command. If the player responds with "oops" (or "o") followed by another word, the function returns the new result code `PRSERR_OOPS_UPDATE`, with the corrected version of the noun phrase string as the second element. Refer to the Parser Manual for details.
- A problematic interaction between `parseUnknownVerb()`, and `parserReplaceCommand()` has been corrected. In the past, if `parserReplaceCommand()` was used within the `parseUnknownVerb()` function, and the parser called `parseUnknownVerb()` because of an unknown word in the command, the parser incorrectly deferred processing the replacement command until after checking to see if the player tried to use OOPS to correct the unknown word. This is undesirable, because in this case the game has already provided the replacement command, so there is no reason to give the player a chance to use OOPS. This has been corrected.
- Due to a bug, the parser did not correctly set the `PRSFLG_ENDADJ` flag for some objects when calling the `disambigDobj` and `disambigIobj` methods. The parser omitted the flag when a noun phrase ended in an adjective, and the vocabulary word involved was only defined as an adjective (in other words, the word was never defined as a noun or plural for any object in the entire game). This has been corrected. (Thanks to Amir Karger for helping to track down this problem.)
- A parser bug caused a strange response message in certain cases. If the player answered a disambiguation question with a special word (such as "it" or "her"), the parser displayed a `preparse`-style special word code in the response, as in "I don't see any R book here." This has been corrected; the parser now displays an improved message ("I don't see any such book here").
- A bug in the compiler caused a crash under certain obscure circumstances. If a symbol was defined as a property or an object, and then later in the source code a function definition appeared using the same symbol name, the compiler sometimes crashed. This has been corrected.
- A compiler bug caused the incorrect method to be called at run-time in a certain situation. If code in an object used `pass` or `inherited` to inherit code in a base class, and the base class was an object that had been modified with the `modify` keyword, and the method being inherited had been replaced with the `replace` keyword within the modifying class, the system did not correctly call the replaced version of the method. This has been corrected.
- In past versions, the compiler accepted a `case` label in a `switch` statement with `self` as the value. Since `self` is not a constant, this type of `case` label has never been legal, and at run-time the code after the "`case self:`" label was never executed; however, the compiler should not have accepted the construct in the first place. The compiler now displays an error when it encounters a "`case self:`" label in a `switch` statement.
- In the `basicMe` class in adv.t, the `ioGiveTo` method generated an incorrect message. This has been corrected.
- The inventory listing code in adv.t (in the `iVerb` object) produced an incorrect display ("You are carrying.") when the player character was carrying only items marked as unlistable (`isListed = nil`). This has been corrected.
- The `thing` class in adv.t now has default verification methods for the verbs "attach x to y," "detach x," and "detach x from y." These default verification methods each simply display the message "There's no obvious way to do that."
- In the past, the text-only interpreter did not correctly suppress certain markup sequences (in particular, BR, TAB, and HR) that appeared within <TITLE> and <ABOUTBOX> tags. All text, including these markups, is now properly suppressed within TITLE and ABOUTBOX sequences.

### Version 2.5.1

Released on September 21, 1999

#### Index of Changes

- New Parser Hook: parseAskobjIndirect()
- New Parser Hook: prefixdesc
- New built-in function: resourceExists()
- New defined() Codes
- New parserGetObj() Codes
- Filename-to-URL Conversions in tadsrsc
- cantReach with Multiple Objects
- Changes to inputkey()
- Changes to adv.t
- Bugs Fixed

#### New Parser Hook: `parseAskobjIndirect`

A new parser hook, named `parseAskobjIndirect()`, has been added to provide more control over the message that the parser uses to ask the player to supply an indirect object when none is provided in the command but the verb requires one. This new function supplements the existing `parseAskobj()` and `parseAskobjActor()` functions.

Refer to the TADS Parser Manual (version 2.5.1) for details on this new parser hook.

#### New Parser Hook: `prefixdesc`

The parser now calls a new method, called `prefixdesc`, to display the object name prefix that comes before the execution results for each object in a command with multiple direct objects. This new method effectively replaces the existing `multisdesc` mechanism. Refer to the TADS Parser Manual (version 2.5.1) for details on this new parser hook.

#### New built-in function: `resourceExists()`

A new built-in function, `resourceExists()`, allows you to determine whether a named resource (such as a JPEG image or an MP3 audio file) can be loaded. This function takes as its single argument a string giving the name of a resource to find; the function returns true if the resource can be loaded, nil if not. The function returns nil if the interpreter is simply not capable of loading resources at all (the text-only interpreters thus always return nil for this function), or if the resource can't be found. The function returns true only if the interpreter is capable of loading resources at all, and the resource is available.

If you're writing a multi-media game for the HTML interpreters, but you also want your game to work on text-only systems, you can use this function for finer control over the presentation on the text systems; you might, for example, want to provide additional text to make up for missing graphics or sounds. You can also use this function if you're planning to distribute your game in different subset versions in order to provide players with different options for download and install sizes; if you make some of your graphics optional (by bundling some into a separate ".RSn" resource file, for example), you can use `resourceExists()` to detect at run-time which resources the player has chosen to install, and customize the presentation accordingly.

Here's an example that checks to see if a JPEG image is available for display:

        if (!resourceExists('images/title.jpg'))
        {
           // the title graphic isn't available - display a text version
           ...
        }

#### New `defined()` Codes

The `defined()` function, which tests an object to determine whether it defines or inherits a given property, provides a new "flags" argument that lets you get more specific information about the property definition. The new third argument is optional; if provided, it can be one of the following values, defined in adv.t:

`DEFINED_ANY` | This is the default, and has the same effect as omitting the flag argument. The function returns true if the object defines or inherits the property, nil if not.
`DEFINED_DIRECTLY` | The function returns true only if the object directly defines the property. If the object doesn't define the property at all, or merely inherits the definition from a superclass, the function returns nil.
`DEFINED_INHERITS` | The function returns true only if the object inherits the property. If the object doesn't define the property, or defines the property directly rather than inheriting it from a superclass, the function returns nil.
`DEFINED_GET_CLASS` | The function returns the class where the property is defined. If the object directly defines the property, the function returns the object itself. If the object inherits the property from a superclass, the function returns the superclass from which the property is inherited. If the object doesn't define or inherit the property, the function returns nil.

For example, to determine if the object `redBook` directly defines `verDoTake`, you could use this code:

       if (defined(redBook, &verDoTake, DEFINED_DIRECTLY))
          "verDoTake is overridden directly in redBook. ";

#### New `parserGetObj()` Codes

The `parserGetObj()` function now accepts several new code values to get additional objects. These new code values are defined in adv.t:

`PO_IT` | Get the object that the word "it" refers to in player commands. This is nil if there is not "it" object.
`PO_HIM` | Get the object that the word "him" refers to in player commands.
`PO_HER` | Get the object that the word "her" refers to in player commands.
`PO_THEM` | Get the list of objects that the word "them" refers to in player commands. This is an empty list if "them" doesn't refer to anything at the moment.

These new codes are used in the same manner as the original ones. For example, to get the object that the word "him" currently refers to, you'd write this:

       local himObj;

       himObj := parserGetObj(PO_HIM);

#### Filename-to-URL Conversions in `tadsrsc`

The resource bundling tool, `tadsrsc`, in the past did not convert filenames entered with explicit paths to URL notation. This problem only affected individual filenames entered with explicit paths (i.e., files in subdirectories); the tool correctly converted paths to URL notation when adding entire directories to a resource file, and also worked when adding individual files that were in the current directory and thus didn't need an explicit path.

Instead of storing resource names in URL notation, the resource tool stored the actual filenames in local file system notation. This didn't work with HTML TADS, because the HTML resource loader requires image and sound resources to be named using URL notation.

This problem has been corrected; the resource tool now converts all paths used in resource filenames to URL notation.

#### `cantReach` with Multiple Objects

When the player refers to an object that is visible but is not reachable (an item within a closed transparent container, for example), the parser calls the object's `cantReach` to display a message explaining why the object is not accessible. This has not been changed, but the multiple-object prefix mechanism has been.

In the past, when the command had multiple unreachable objects, the parser called the object's `sdesc` method, then displayed message 200 (":"). This has been changed. Now, the parser uses the same mechanism that it does for any other multiple-object listing prefix: for each object, before calling `cantReach`, the parser calls the object's `multisdesc` method then displays message 120 (":").

This minor change is for consistency; in particular, the change allows the game to override multiple-object prefix displays in a uniform manner for all types of these displays.

#### Changes to `inputkey()`

The `inputkey()` built-in function now returns certain keys more consistently and portably. The codes that `inputkey()` returns vary by platform according to what keys are available on the keyboard. In addition, in the past, the function mapped certain keystrokes to high-level functional codes in different ways on different platforms; this corresponded to the differing ways that platforms used certain keyboard keys.

The return codes from `inputkey()` are now somewhat more consistent. The Escape key now returns the string `'[esc]'` on most platforms that provide such a key, and the "control" keys now return `'[ctrl-X]'` for almost all of the control keys on most platforms. In the past, the escape key didn't return anything on most platforms, and control keys frequently were mapped to other functions (for example, on Unix, the Ctrl-E key returned `'[end]'`, since this key is used on Unix TADS interpreters to move the cursor to the end of the line when entering a command).

A few new command keys have been added. The full set of command keys is shown below. The exact assignment of these keys varies by platform, as it has in past versions, and any given platform might support only a subset of these keys.

`[up]` | Up arrow
`[down]` | Down arrow
`[right]` | Right arrow
`[left]` | Left arrow
`[end]` | End of line
`[home]` | Home
`[del-eol]` | Delete to end of line
`[del-line]` | Delete line
`[del]` | Del (delete character)
`[page up]` | Page up
`[page down]` | Page down
`[top]` | Top of file
`[bottom]` | Bottom of file
`[fN]` | Function key N (N is replaced by a number, 1 through 10)
`[tab]` | Tab
`[word-left]` | Word left
`[word-right]` | Word right
`[del-word]` | Delete word
`[bksp]` | Backspace
`[esc]` | Escape
`[ctrl-X]` | Control-X (X is replaced by a lower-case letter: Control-C is `[ctrl-c]`)
`[alt-X]` | Alt-X or Meta-X (X is replaced by a lower-case letter: Alt-F is `[alt-f]`)

#### Changes to adv.t

- Added verifier methods to class `thing` to accomodate the verbs `screwVerb` and `unscrewVerb`. All of these verifier methods simply stop the command with a default failure message (variations on "You see now way to do that"). The new methods are:
  - `verDoScrew`
  - `verDoScrewWith`
  - `verIoScrewWith`
  - `verDoUnscrew`
  - `verDoUnscrewWith`
  - `verIoUnscrewWith`
- The `fopen()` built-in function's `'r+'` mode did not correctly create a new file when the file being opened did not previously exist, as it is documented to do. This has been corrected; if no file exists, the `'r+'` mode creates a new file, otherwise it opens the existing file, keeping its contents intact.
- The `moveInto` method in the `basicMe` object in adv.t now works properly when the object is not the current player character. `moveInto` now uses the default handling inherited from `Actor` when the object is not the current player character; this is important for games that switch among different player character objects.
- The `ioGiveTo` method in `basicMe` in adv.t now uses format strings (such as "%You%"), so that it adapts properly when the object is not the current player character.

#### Bugs Fixed

- Format strings (such as "%You%") can now be used from within the `endCommand()` function. In the past, the actor setting that the output formatter uses to translate format strings was forgotten before the parser called `endCommand()`, even though the parser still had the necessary information internally. The output formatter now keeps track of this information until after `endCommand()` returns, which allows you to use format strings from within `endCommand()`.
- Fixed a parser bug: Executing `exit` within `preCommand()` did not have the documented effect of skipping all of the remaining objects in the command, but simply skipped the first object in the command. `exit` in `preCommand()` now correctly skips the entire object list for the command.
- Fixed a parser bug: An object defined with the same leading substring six characters or longer in multiple adjectives sometimes appeared more than once in a disambiguation query ("Which book do you mean, the yellow book, or the yellow book?"). This same type of problem was fixed in most cases in version 2.4.0, but one type of the problem remained; this has now been fixed.
- Another bug, related to the bug above, was fixed. In some cases, when the player responded to a disambiguation query with multiple objects, the parser would ask the disambiguation question again with every object in the entire game, whether accessible to the player or not, in the list of possible objects. This has been corrected.
- Another parser bug was fixed: If a word referred to more than about 200 objects, the parser displayed a double error message (specifically, "The word 'foo' refers to too many objects.I don't see any foo here."). This has been corrected; only the first message ("too many objects") is displayed now.
- Fixed a bug in adv.t: the `listcontgen()` function, when the "recursive" flag was set, incorrectly tried to evaluate `itemcnt()` with an object rather than a list, causing a run-time error. This has been corrected.
- The parser's handling of situations where an "again" command is impossible due to object deletion has been improved. In the past, if an object involved in the previous command was deleted, and the player typed "again," the parser would respond with parser message 26 ("There's no command to repeat"). The parser now responds with the more suitable message 27 ("You can't repeat that command").
- The parser now properly restores the text of the player's original command words for the direct and indirect object when the player repeats a command with "again." In the past, the parser did not retain the text of the previous command's words, so `objwords()` returned empty lists when the game attempted to retrieve the object words during execution of a repeated command. This inconsistency has been corrected.
- The `parseNounList()` function returned an incorrect word index value in the first element of its return list in two cases: when the noun phrase did not match any objects; and when there was no noun phrase present. In both of these cases, the returned index value had a value one less than the correct value. This has been corrected.
- Fixed a problem that occasionally caused a crash when the player entered a command containing an ampersand ("&") when the game was running in HTML mode.
- Fixed a parser bug that occasionally caused a crash when the player responded to a disambiguation prompt ("which book do you mean...") with "him" or "her."

### Version 2.5.0

Released on July 10, 1999

#### Index of Changes

- preCommand()
- postAction() and endTurn()
- inputdialog()
- inputline()
- New restore() return codes
- Extended askfile() interface
- switchPlayer()
- Inventory Wide and Tall
- nestlistcont()
- listcontgen()
- basicMe.travelTo changes
- movableActor.travelTo changes
- New compiler debug record format (-ds2)
- Parser bug fixes
- Debugger bug fixes
- Compiler bug fixes

#### New pre-execution processing: `preCommand`

At the start of the execution phase, before calling `verbAction()` for the first direct object in the command, the parser invokes the new function `preCommand()`:

      preCommand(actor, verb, dobj_list, prep, iobj);

The "actor", "verb", "prep", and "iobj" parameters are objects giving the actor, verb, preposition, and indirect object in the command, respectively. The "dobj_list" parameter is a list of the direct objects in the command, in the same order as they appear in the command.

This function can use `exit` to skip to fuses and daemons, or it can use `abort` to cancel the command entirely, in which case the parser will skip directly to the `endCommand` function (see below). If this function simply returns, the parser continues processing the command as normal.

#### New end-of-turn processing: `postAction` and `endCommand`

In past versions of TADS, it wasn't possible to add special event processing at the end of a turn. The closest approximation was to put processing in a fuse or daemon, but this approach has several drawbacks: no information is available in a fuse or daemon on the last command executed, and it is not possible to specify the order of execution of fuses and daemons.

Two new parser hooks provide for structured event handling at the end of a turn. The first hook, the `postAction` function, lets you write code that the parser calls immediately after the "action" method, and before any fuses or daemons. The second hook, the `endCommand` function, lets you write code that the parser calls at the end of a turn, just after running all of the fuses and daemons for the turn.

The parser calls `postAction` once for each object in a command with multiple direct objects, just after it calls the "action" method for the object. If the command is terminated early with `exit`, `exitobj`, or `abort`, the parser invoked `postAction` immediately after the `exit`, `exitobj`, or `abort` statement executes. The parser calls `postAction` with the following arguments:

        postAction(actor, verb, dobj, prep, iobj, status);

The first five parameters specify the current command; any of the objects except "actor" and "verb" can be nil. The "status" parameter has the same meaning as the return codes from the `execCommand` built-in function; it can be one of the following values, defined in adv.t:

`EC_SUCCESS` | The command executed successfully, which indicates that everything up through and including the command's "action" method (`verb.action`, `dobj.doAction`, or `iobj.ioAction`, as appropriate).
`EC_EXIT` | An `exit` statement was executed.
`EC_EXITOBJ` | An `exitobj` statement was executed.
`EC_ABORT` | An `exit` statement was executed.

The `postAction` function returns no value.

The parser invokes the `endCommand` after all of the fuses and daemons have finished running at the end of a turn. This function is called once per command, not per object; in a command with multiple direct objects, this function is called only once, just as fuses and daemons are called only once for the entire command.

The parser calls `endCommand` as follows:

        endCommand(actor, verb, dobj_list, prep, iobj, status);

The "status" parameter has the same meaning as the status code parameter to `postAction`. The other parameters have the same values as they did in the call to `preCommand` that the parser makes at the start of the execution phase for the command.

`endCommand` is always invoked at the end of a turn. If an `abort` statement is executed in the course of a turn, the parser skips directly to `endCommand`, because `abort` skips the daemons and fuses. This means that `endCommand` is executed at the end of a turn even when fuses and daemons are skipped.

The `endCommand` function returns no value.

#### New built-in function `inputdialog()`

A new built-in function, `inputdialog()`, lets you ask the player a multiple-choice question. On graphical systems, inputdialog() displays a system dialog box, and lets the user respond by clicking a button. On text systems, this function displays a textual prompt and lets the user respond with the keyboard.

`inputdialog` takes the following parameters:

        inputdialog(icon, prompt, response_list, default_idx, cancel_idx)

The "icon" parameter indicates which icon, if any, to display. The icon will only be displayed on graphical systems; text-only systems ignore this parameter. These icon constants are defined in adv.t:

`INDLG_ICON_NONE` | Do not use any icon.
`INDLG_ICON_WARNING` | Show a "warning" icon. This indicates a potential or minor problem. (On Windows, this displays an exclamation-point icon.)
`INDLG_ICON_INFO` | Show an "information" icon. This indicates to the user that the dialog is being displayed to inform them of the status of an operation. (On Windows, this displays an icon with a small letter "i" in a circle.)
`INDLG_ICON_QUESTION` | Show a "question" icon. This indicates that additional information from the user is required. (On Windows, this displays a question-mark icon.)
`INDLG_ICON_ERROR` | Show an "error" icon. This indicates that a problem has occurred. (On Windows, this displays a stop-sign icon.)

The "prompt" parameter is the message string to display. For graphical systems, this message is displayed in a dialog box; for text systems, it's simply displayed on the terminal.

The "response_list" is a list of strings giving the valid responses. Each entry in the list is a string giving one possible response. On graphical systems, one button is displayed in the dialog for each response string; the response string is the button's label. On text systems, the responses are displayed to the player after the prompt string.

Each string in the response list can optionally include an ampersand character ("&") before the character that serves as a keyboard short-cut for the response. The ampersand is not displayed in the button label or response list displayed to the player. For example, the response list string '&Yes' makes the "Y" key a short-cut for the button, which is labeled "Yes" in the dialog. On some systems the short-cut key will be indicated visually in the dialog; on Windows, for example, the "Y" in the "Yes" button would be underlined to indicate that the letter "Y" is the short-cut for the button. If no ampersand appears in a response list item, the item has no short-cut.

On text-only systems, the keyboard short-cut will be indicated visually by enclosing the short-cut letter in parentheses when dispalying the list of possible responses to the player. If a response item has no short-cut key, the player must enter a sufficiently long leading substring of the response item so that the response is unambiguous with the other valid responses.

Each element of the list can be a number, rather than a string. If an element is a number, it specifies that the button should use a pre-defined standard label. You should use standard labels when possible, because these labels will follow local system conventions and will be localized to the player's language settings; these labels are read from external resources on platforms with appropriate operating system support, so they can be localized easily. To select a standard label, use one of the following values, defined in adv.t:

`INDLG_LBL_OK` | "OK", or local system or language equivalent
`INDLG_LBL_CANCEL` | "Cancel"
`INDLG_LBL_YES` | "Yes"
`INDLG_LBL_NO` | "No"

The strings shown above do not necessarily reflect the actual button text that the player will see, because the actual label will vary by platform and by language. Whatever label is displayed, though, will convey to the user the same meaning.

You can also select an entire standard set of buttons, rather than specifying each button individually. If the response_list parameter is a number, rather than a list, it indicates that a standard set of buttons is to be used, selected from a pre-defined list. The advantage of using one of these pre-defined button sets when possible is that the buttons will automatically follow local system conventions and be localized to the player's language settings, on platforms with appropriate operating system support. To select a pre-defined button set, use one of the following values, defined in adv.t, for the response_list parameter:

`INDLG_OK` | The dialog will display an "OK" button, properly localized.
`INDLG_OKCANCEL` | The dialog will display an "OK" button and a "Cancel" button, properly localized.
`INDLG_YESNO` | The dialog will display an "Yes" button and a "No" button, properly localized.
`INDLG_YESNOCANCEL` | The dialog will display a "Yes" button, a "No" button, and a "Cancel" button, properly localized.

The "default_idx" parameter gives the index in the response list of the default response. If the user presses the "Return" key, or performs any other action appropriate to the system user interface that by local convention accepts the default response to a dialog, this response will be used. The first list entry is at index 1. Pass nil in this parameter if there is no default response, in which case TADS will require the user to select a specific button. (Note that, on some systems, passing nil for this parameter will not make a noticeable difference; on Windows, for example, one of the buttons will always have keyboard focus, so pressing the Return key will always select one of the buttons.)

The "cancel_idx" parameter gives the index in the response list of the cancellation response. Most GUI systems have a standard way of cancelling a dialog; the Escape key has this effect on Windows, for example, as does the Command-Period key combination on the Macintosh. If the user performs the appropriate system-specific action to cancel the dialog, this response is used. The first list entry is at index 1. Pass nil in this parameter if there is no cancel response, in which case TADS will not allow the player to cancel the dialog.

The dialog returns the index of the response that the player selects: 1 for the first response in the response list, 2 for the second entry in the list, and so on. For the standard response lists (`INDLG_YESNO` and so on), the response are in the order described for the constant name: `INDLG_YESNO` has a "Yes" button at index 1 and a "No" button at index 2, for example.

Here's an example of using this function.

        ret := inputdialog('What would you like to do next?',
                           ['&Restore', 'Re&start', '&Quit'],
                           nil, 3);
        switch(ret)
        {
        case 1:
          /* restore a game... */
          break;

        case 2:
          /* restart the game */
          restart();
          break;

        case 3:
          /* quit */
          quit();
          break;
        }

On a graphical system, this would display a dialog with the message text "What would you like to do next?", and three buttons: one with the label "Restore", one with the label "Restart", and one with the label "Quit". If the user presses the "R" key, the "Restore" button would be selected; if the user presses "S", the "Restart" button would be selected; if the user presses "Q", or cancels the dialog (by pressing the Escape key on a Windows machine, for example), the "Quit" button would be selected.

On a text-only system, TADS would display this text on the terminal, on a new line (TADS would output a "\n" sequence to start a new line):

        What would you like to do next? (R)estore/Re(s)tart/(Q)uit >

TADS would then wait for the player to enter a line of text (as with the `input()` built-in function). If the player enters one letter, TADS would check the letter against each response's short-cut, and return the one that matches. If the player enters more than one letter, TADS would check the string against the leading substring of each possible response; if the string matches one of the responses unambiguously, TADS would return that response. If the player enters something invalid or ambiguous, TADS would redisplay the prompt and await another response.

`inputdialog()` has certain limits. The prompt string can be no longer than 256 characters. There can be no more than ten responses, and the total length of the text in all of the responses must not exceed 256 characters. In addition, to ensure portability, you should choose a reasonably short label for each button; some systems use buttons of a fixed size, so a long label name might not fit in the available space on some systems. Whenever possible, use a single word for each button label.

#### New `inputline()` function in adv.t

A new function, `inputline()`, is defined in adv.t. This function is a simple cover for the built-in function `input()`, with the additional feature that `inputline()` switches to the "TADS-Input" font when the game is running in HTML mode. This means that the text that the player enters during an `inputline()` has the same appearance as the text entered on a normal command line.

Note that the `input()` function does not switch to the "TADS-Input" font itself, because if it did, you'd have no way to override this behavior. Rather than forcing input text to be displayed in the "TADS-Input" font, the `input()` function leaves it up to the game author to determine how input text should look. In most cases, you should use `inputline()` rather than calling `input()` directly, to ensure that the player's input has the normal command line appearance. In some cases, however, you might wish to use a specific appearance for input text, rather than using the default setting; in these cases, you should set your own font choice, then call the `input()` function directly, since it won't change the appearance from what you choose.

#### New `restore()` return code

The `restore()` built-in function's return code has been changed. In the past, this function returned nil to indicate success, and true to indicate failure. The return value is now a number; different values are returned for different error conditions, which makes it possible to provide better information to the player about the specific problem that caused the operation to fail.

The new return values, defined in adv.t, are:

`RESTORE_SUCCESS` | Success
`RESTORE_FILE_NOT_FOUND` | The file to be restored does not exist (or could not be opened for some other reason).
`RESTORE_NOT_SAVE_FILE` | The file is not a valid saved game.
`RESTORE_BAD_FMT_VSN` | The file was saved by an incompatible version of the TADS Interpreter
`RESTORE_BAD_GAME_VSN` | The file was saved by a different game, or by a different version of the same game.
`RESTORE_READ_ERROR` | An error occurred reading the file. This could indicate that the file was corrupted, or that the physical medium containing the file is damaged.
`RESTORE_NO_PARAM_FILE` | No parameter file has been specified. This is returned only when `restore(nil)` is called to attempt to load the file specified by a start-up parameter; it indicates that there is in fact no parameter file to load.

For compatibility, `RESTORE_SUCCESS` is defined as 0, and all of the other values are non-zero. In most cases, this should allow existing code (that assumes the nil/true return value) to continue working without changes, since `if (restore(fname))` will continue to have the same effect with this change. Only code that explicitly compared the return value to nil or true will need to be changed.

The code in adv.t that calls `restore()` has been updated to reflect this change, and uses the additional information to display a more precise message when an error occurs.

#### Extended `askfile()` Interface

The `askfile()` built-in function's interface has been extended.

A new, optional fourth argument lets you specify additional flags to the `askfile` function. The possible flag values, defined in adv.t, are:

`ASKFILE_EXT_RESULT` | Return extended result codes (described below). If this flag is provided, the function returns extended results; if this flag is not specified, the function returns the traditional results.

In order to specify the new flag value argument, you must specify the prompt type and file type arguments as well; if you omitted the prompt or file type argument, the `askfile` function would not be able to tell that you meant the last argument as the flags value.

If you omit the flags argument, `askfile` uses a default value of zero, which makes the function behave the same as in past versions. Because older code never specifies a flags value, the function will always behave compatibly with past versions when called from older code.

Traditionally, `askfile` returned a string on success, or nil for any type of failure; this didn't permit the caller to determine exactly what kind of failure occurred, and in particular did not allow the caller to distinguish between an actual error and the player cancelling the file selector dialog. When `ASKFILE_EXT_RESULT` is specified, the function will return additional information that allows the caller to distinguish these cases.

When the `ASKFILE_EXT_RESULT` flag is specified, `askfile` returns a list that contains two elements. The first element is a number which indicates the status of the file selection; the second element is a string if a file was successfully chosen, or nil if not. The possible values for the first element of the returned list, defined in adv.t, are:

`ASKFILE_SUCCESS` | A file was successfully chosen. The second element of the list contains a string giving the chosen filename.
`ASKFILE_FAILURE` | An error occurred prompting for a filename. This usually indicates that the file selector dialog could not be shown for some reason (insufficient memory, for example).
`ASKFILE_CANCEL` | The user canceled the file selector dialog. On the Macintosh, for example, this means that the user clicked the "Cancel" button. This indicates that the user does not wish to proceed with whatever operation is in progress, so the operation should be aborted. Since the user explicitly chose to cancel the operation, the program should not indicate that an error occurred, but simply that the operation will be terminated in accordance with the user's request.

All code in adv.t that calls `askfile` has been updated to use the new extended results information, so that it can provide more appropriate responses when the user cancels a file selector dialog.

Here's an example, from the "restore" command's implementation in adv.t, of using the new extended results.

        local savefile;

        savefile := askfile('File to restore game from',
                            ASKFILE_PROMPT_OPEN, FILE_TYPE_SAVE,
                            ASKFILE_EXT_RESULT);
        switch(savefile[1])
        {
        case ASKFILE_SUCCESS:
            return mainRestore(savefile[2]);

        case ASKFILE_CANCEL:
            "Canceled. ";
            return nil;

        case ASKFILE_FAILURE:
        default:
            "Failed. ";
            return nil;
        }

#### New `switchPlayer()` function in adv.t

The standard library file adv.t provides a new function, `switchPlayer`, that you can use to switch the player character to a new actor. This function uses the built-in function `parserSetMe()` to change the parser's internal player character record, and in addition performs some book-keeping work that's necessary when switching to a new player.

Call `switchPlayer()` with one argument: the actor object that is to become the new player character.

First, `switchPlayer()` adds the outgoing player character object to its room's contents list, and removes the new player character object from its room's contents list. By convention in adv.t, the active player character is never in its location's contents list, but other actor objects are. Since the outgoing object is switching from being the active player object to an ordinary actor, it must be added to its room's contents list; likewise, since the new object is changing from an ordinary actor to the player character, it must be removed from its location's contents list.

Second, `switchPlayer()` removes the vocabulary words "me" and "myself" from the outgoing player character object, and adds these vocabulary words to the incoming player character. This way, these words always refer to the current player character.

If your game is based on adv.t, you should use `switchPlayer()` to change to a new player character object, rather than calling `parserSetMe()` directly, to ensure that the adv.t conventions for the active player character object are maintained through the change.

Thanks to Scott Starkey for his help defining this function.

#### New adv.t verbs: inventory wide, inventory tall

The standard library file adv.t defines two new verbs: "inventory wide" and "inventory tall." These verbs let the player control the inventory display format. "Inventory wide" displays the player's inventory in the traditional paragraph-style format. "Inventory tall" displays the inventory in a single-column format, showing one object per line, and showing the contents of each object indented one tab stop from its container.

Once the player enters an "inventory tall" or "inventory wide" command, subsequent "inventory" commands (without a format specified) will default to the format of the previous command. The traditional "wide" format is the initial setting, but you can change this in your game by setting `iVerb.useInventoryTall` to `true` in your `init` function.

#### New `nestlistcont()` function in adv.t

The standard library file adv.t has a new function, `nestlistcont()`, that displays a listing of an object's contents in a nested single-column format. This function can be used to display "tall" inventory listing, rather than the paragraph-style "wide" listings that adv.t normally displays.

`nestlistcont()` takes two arguments: the object whose contents are to be listed, and a number giving the initial indenting. The function indents the contents of the given object by the given number of tabs. For each object contained in the given object that has a contents list of its own, the function displays that object's contents indented one additional tab level, and so on for their contents.

`nestlistcont()` displays an object's contents only if the object's contents are visible, using the normal visibility rules. If the object's contents are not visible, this function has no effect. Furthermore, the function displays the contents of objects it displays only for those objects whose contents are themselves visible.

Thanks to Kevin Forchione for providing this addition to adv.t.

#### New `listcontgen()` function in adv.t

To support the `nestlistcont()` function, adv.t includes another new listing function, `listcontgen()`. This function is a general-purpose lister that provides the functionality of the traditional `listcont()` function as well as the new `nestlistcont()` function, which are essentially the same except for the display format.

`listcontgen()` takes three parameters:

      listcontgen(obj, flags, depth);

The "obj" parameter is the object whose contents are to be listed, or simply a list of objects to display. "flags" specifies a set of flag values, defined in adv.t:

`LCG_TALL` | Show a "tall" listing, with one item listed per line. If this flag is specified, each line will be indented by the number of tab stops given by the "indent" parameter. If `LCG_TALL` isn't specified, the function shows a "wide" paragraph-style listing, with the items separated by commas.
`LCG_CHECKVIS` | Checks the visibility of the contents of "obj" before listing the contents. If "obj" is a list, this flag is ignored. If this flag isn't specified, the function lists the contents of "obj" without checking to see if they're visible.
`LCG_RECURSE` | Show a recursive listing. If this flag is specified, the function lists the contents of each item it displays. The recursive call uses the same "flags" value and increments the "indent" depth by one. If this flag isn't specified, the function doesn't show the contents of the objects it lists.

Note that `listcontgen()` allows you to produce an object listing for lists other than contents of objects. If you pass a list in the "obj" parameter, the function lists the items in the list using the same formatting that it would for a contents list. This allows you to display a contents-style listing for some collection of objects other than a contents list.

#### `basicMe.travelTo` changes

In adv.t, the `basicMe.travelTo` method now checks to see if "self" is actually the active player character object; if not, the method inherits the `travelTo` processing for a regular actor, rather than using the special behavior for the current player character. This change facilitates using `basicMe` as a base class for defining player character objects in a game with more than one player character.

#### `movableActor.travelTo` changes

In adv.t, the `movableActor.travelTo` method uses an improved algorithm for determining when to show the "leaving" and "arriving" messages for the actor. The new algorithm considers the actor's visibility to the player, before and after the move, in determining whether to show the messages; the old algorithm considered only the immediate container of the actor and of the player, which produced the wrong results when the actor was moving between locations that are both visible to the player, such as a nested room. In addition, the new algorithm handles obstacles (such as doors) properly.

Thanks to Kevin Forchione for providing this improved implementation.

#### New compiler debug record format

A new compiler option, `-ds2`, tells the compiler to generate a new style of debugging information designed to work with the Windows HTML TADS Debugger (part of TADS Workbench). If you're running your game with the Windows debugger version 2.5.0 or later, you must compile with the `-ds2` option. If you're using an older version of the Windows debugger, or you're using the debugger on another platform (DOS, Unix, Mac), you must continue to use the original `-ds` option as before.

#### Parser bug fixes

The following player command parser bugs have been fixed:

- Fixed a parser bug that caused an infinite loop (which caused the game to lock up) if a game defined the same vocabulary word as both an adjective and a plural.
- Fixed a parser bug involving `disambigDobj` and `disambigIobj`. When these methods returned a list of objects that was still ambiguous, the parser's default question ("Which noun-phrase do you mean...") didn't format the list of possibilities correctly; in particular, extra commas and "or"'s sometimes appeared at the end of the list. This has been corrected.

#### Debugger bug fixes

The following debugger problems have been corrected:

- Fixed a debugger problem that caused single-step execution to skip past a line containing a disabled breakpoint.
- Fixed a problem in the debugger that caused a sporadic crash when displaying a stack traceback where a function in the stack trace had a string argument value, and the string was over about 40 characters long. This bug affected all versions of the debugger, but was most noticeable on the Windows HTML version, because the Windows debugger builds a stack traceback every time it takes control (on hitting a breakpoint, for example, or after single-stepping a line of code).
- In certain cases, the debugger showed the current source line (and breakpoints) off by a couple of lines from where it should have been. This happened when the source file had one or more lines that were exactly 97 characters long, and had DOS-style line termination (CR-LF newline sequences). (This was actually a bug in the compiler and not the debugger, but it showed up most visibly using the debugger.) This has been corrected.

#### Compiler bug fix

This version corrects an obscure compiler bug that caused `preinit` to execute incorrectly under certain circumstances. This bug occurred when `preinit` called a method in an object, and the method modified a list-valued property of the object, and the property was defined earlier in the object than the method (i.e., the property's definition in the source file preceded that of the method). In such cases, the compiler's behavior was unpredictable; sometimes it ran correctly, sometimes it stored incorrect values in the list, and sometimes the compiler crashed. This problem should no longer occur.