Introduction and Overview

This manual is intended to explain the main features of the adv3Lite library, an alternative library for use with the TADS 3 Interactive Fiction system. If you need help with the TADS 3 language, or other aspects of TADS 3 such as using the compiler, please refer to the TADS 3 System Manual, or start by working through the Tutorial. The present manual assumes at least basic familiarity with the TADS 3 language.

The adv3Lite library is intended as a simpler alternative to the adv3 Library for use with TADS 3. Some time ago Mike Roberts announced plans for an alternative library, to be called Mercury, which might provide a less demanding route into using TADS 3 than the highly complex adv3 library that comes as standard. More recently he released what he had written of the Mercury library so far — which consisted mainly of the parser and a few basic classes to use the parser with — and suggested that it might be used as the basis of other library projects. In the meantime I had been dabbling with implementing a minimalistic alternative library for TADS 3 but had devised only a fairly primitive parser for it. I therefore decided to try to combine the existing Mercury code with what I had already done, and it is this that forms the basis of the current adv3Lite project.

For various reasons I then decided to move beyond the plan to produce an absolutely barebones IF library, partly because the existing Mercury code invited more, and partly because in practice I perceived most people would want more than a totally minimalistic library to write games in. The resulting adv3Lite library has thus ended up being a lot more than barely minimalistic; while it removes many of the complexities of the adv3 library it also adds a number of features (mainly inspired by Inform 7) which will hopefully prove useful to game authors. I had considered not including any support for NPCs at all, on the basis that implementing NPCs in any worthwhile way was necessarily complex and thus beyond the scope of a minimalistic library, but once I moved beyond the ideal of minimalism I decided that support for NPCs would be desirable. Quite apart from anything else, the fact that a game does not require a particularly sophisticated physical world model does not at all entail that it does not want to deal with life-like NPCs. In addition, I had some vague ideas for a conversation system, inspired by but not identical to that of adv3, that I wanted to try out. This somewhat experimental conversation system has therefore been incorporated into the adv3Lite library.

Although adv3Lite has thus become more complex than I originally envisaged, I have nevertheless more or less stuck to many of the design principles I started out with. These include:

• The library should be as modular as possible, making it as easy as possible to exclude parts that aren't needed for a particular game.
• The library should be significantly simpler than adv3, for example omitting features such as postures, room parts, complex sense passing, multiple light levels, and the transcript.
• As part of that simplification, the list of classes needed to implement a game, especially classes representing physical objects, should be drastically reduced. In the adv3Lite library just about any object (including Containers, Surfaces, and even the Player Character) can be implemented as Things. Some specialized classes (such as Door, Key and, of course, Room) are also necessary, but I've tried to keep them to a minimum (while also making it possible to use many of the adv3 classes such as OpenableContainer, Surface and the like if desired). Of course, more sophisticated effects will nevertheless require the use of a greater range of classes.
• The adv3Lite library should be reasonably similar to, but not slavishly identical or compatible with the adv3 library, so that people familiar with adv3 should find it reasonably easy to learn, and people coming to TADS 3 could use adv3Lite as a stepping-stone to getting to grips with the more complex adv3 library.
• Where wheels really don't need reinventing, some parts of the adv3 library would be incorporated into adv3Lite more or less unchanged. This includes the various EventList types, AgendaItems for Actors, and the mechanisms for menus, hints and scoring. It also includes the code for certain routine system actions such as saving and restoring games.
• Where convenient shortcuts could be offered to game authors, these have often been incorporated; for example short-cut methods for remapping actions to other objects or hiding items behind or under other items.

In addition to this, I have tried to keep (and build on) as much of the Mercury code as possible, particularly where it offers features that struck me as particularly neat, or easier to use that the adv3 way of doing things. The result is that adv3Lite will be partly familiar and partly unfamiliar to users of the adv3 library. Some of the key differences are noted below:

1. Many object definitions that would require the use of different classes in adv3 can be achieved by defining properties on Thing. For example, a container object could be defined as a Thing with a contType of In. Many of the more "traditional" adv3 classes are nevertheless also still available for authors who prefer to use them, but they consist of shallow definitions which simply define the appropriate properties of Thing.
2. The adv3Lite library defines only one class of Room.
3. The adv3Lite library adds an additional stage — report — to the preCond, remap, verify, check and action familiar from adv3. Also, the check stage halts the action if it displays anything; there is no need to use the exit macro (and it's better not to).
4. The common Thing and Room templates are subtly different. In particular the Thing template defines only one single-quoted string property (vocab) which defines both the name and the vocabWords in one go.
5. The adv3Lite library comes with a built-in spelling corrector, courtesy of the underlying Mercury code.
6. Direction properties on Rooms can be methods, single-quoted or double-quoted strings, in addition to Rooms, Doors and another TravelConnector objects as in adv3.
7. The adv3Lite library implements Inform 7 style scenes.
8. The adv3Lite library includes pathfinding and a GO TO DESTINATION action.
9. The adv3Lite library allows rooms to be grouped into regions (a little like Inform 7, except that adv3Lite regions can overlap).
10. Locks and Keys are handled rather differently; in particular, in adv3Lite it's the keys that keep track of what they lock and unlock.
11. The adv3Lite library included a number of built-in debugging commands such as PURLOIN, GO NEAR and EVAL.
12. The adv3Lite library allows optional (under player control) colouring of exits that lead to unvisited destinations.
13. The adv3Lite library defines an Actor class and an ActorState class but no subclasses of either (you just use Actor and ActorState).
14. The adv3Lite Library defines several additional kinds of TopicEntry in addition to those familiar from the adv3 library; additional types include SayTopic, QueryTopic, TalkTopic, DefaultAgendaTopic, NodeInitiateTopic, HitTopic and KissTopic.
15. The adv3Lite library does not define a SuggestedTopic class. A TopicEntry can still be suggested, however; you simply define its name property.
16. There is no transcript in the adv3Lite library. Double-quoted strings (or strings displayed with the say() function) mostly go straight to the screen. The library does, however, buffer some output (e.g. implicit action reports) to create some of the same effects that the adv3 transcript was used for, and the report() stage of action processing makes it very easy to display a summary report of the same action carried out on a number of items (e.g. TAKE ALL).
17. Although most of this complexity should be hidden from the game author most of the time, there are several more stages between parsing and executing a command. The Parser created a Command object (corresponding to each complete player command). The Command object then calls a Doer object for each set of objects involved in the Command, and (by default), the Doer object then executes the appropriate action for that set of objects. This structure broadly comes from the Mercury code. It is worth keeping in adv3Lite in part because it is allows game authors to create custom Doer objects which are potentially a very straightforward way of handling special cases.
18. There is no option for real-time processing in adv3Lite.

Most of these differences will be explained in more detail later in this manual.

IMPORTANT NOTE: The adv3Lite library needs TADS 3.1.2 (or greater) to compile. If you're not using TADS 3.1.2 (or greater) please make sure you update to the latest version of TADS before attempting to use the adv3Lite library.

Finally, I'd like to thank Mark Engelberg for looking over earlier forms of this documentation and library code, and for offering many valuable suggestions, most of which have been incorporated. I'd also like to thank Jerry Ford for his 'discovery' tool which generated the CSV file of library messages now included with the adv3Lite documentation and also inspired me to add a Messages tab to the Library Reference Manual. I'd also like to thank Jerry for his indexing tool which inspired my own efforts to create a tool to index this manual; both the tool and the index are now complete. And, of course, I'd to thank Mike Roberts for providing the Mercury code on which adv3Lite is based and the adv3 library from which adv3Lite borrows liberally, for making it easier to create a new adv3Lite project for Workbench, and for helping sort out a number of puzzling parser problems. Indeed, without Mike's work on TADS 3, the adv3Lite library would not be possible at all.