Adv3Lite

What is adv3Lite?

Adv3Lite is an alternative library for TADS 3, an interactive fiction (aka "text adventure") authoring system. The library is the part of the system that provides the parser (the bit that interprets and executes player commands) and the world model, as opposed to the TADS 3 language, which provides a substantial set of intrinsic functions in addition to the set of constructs normally found in a computer language.

Adv3Lite aims to provide a library that's easier to use than the adv3 library which comes standard with TADS 3, but which is almost as powerful and expressive. Adv3Lite misses out the bits that most games don't really need (like postures, room parts, and multiple light levels) while adding in some other bits that are often more useful (like scenes and regions, "borrowed" from Inform 7). Adv3Lite also cuts down drastically on the complexity of the adv3 class hierarchy (there are lots of classes to learn about in adv3!) while maintaining much of their functionality.

One area adv3Lite absolutely doesn't skimp on is the conversation system, which does everything the adv3 one can and more. At the basic level it's very similar to adv3's, but for more advanced conversational work it's more flexible and can do quite a few things that adv3's can't.

In sum, adv3Lite is an alternative library that's easier to learn and easier to use that adv3, but doesn't compromise on the functionality most commonly needed to write interactive fiction.

Where can I get adv3Lite?

The most recent version of Adv3Lite (2.1.1) can be downloaded from GitHub. The download comes as a zip file which you'll probably want to expand under the extensions folder of the TADS 3 folder containing your game code etc. (under the Documents folder in a Windows installation; not the TADS 3 folder under the Programs directory).

Who should use adv3Lite?

Potentially, adv3Lite may be of interest to anyone who wants to write interactive fiction. More particularly, it is designed for people who want to use the TADS 3 language but who are put off by the complexity of the adv3 library, or for people who know the adv3 library but may want to try something different.

Some people who may be particularly interested in giving adv3Lite a try might include:

1. Existing TADS 2 users who want the power of the TADS 3 language and, perhaps, its conversation system, but who feel daunted by the complexity of the adv3 library.
2. Existing TADS 3 users who'd like to try a variant of TADS 3 with much of the complexity removed and some additional features added.
3. Anyone thinking of learning TADS 3, but especially people who are discouraged by the (experienced or reputed) complexity of the TADS 3 (i.e. adv3) library.
4. Anyone wanting to try out different IF authoring systems in order to compare them and/or make a choice between them.

None of this is meant to suggest that people shouldn't use (or shouldn't try) the adv3 library that comes as standard for TADS 3. For some people and some games (particularly those that make good use of its full feature set) it may be just the thing to use. But for other users and other games, it's possible that adv3Lite could be a better choice.

How is adv3Lite related to adv3/TADS 3?

Adv3Lite is written in TADS 3 to be used to write TADS 3 games. In many ways writing interactive fiction with adv3Lite is quite like writing it with adv3, as you can see from the Cloak of Darkness example. But under the surface there are a lot of differences.

For one thing, adv3Lite is based on the Mercury parser, written by Mike Roberts as the basis for an alternative TADS 3 library. The Mercury parser is a bit easier to customize than the parser that comes with adv3. It also includes some neat new features, such as:

• Doers: these are a little like Instead rules in Inform 7, in that they can interrupt the course of an action to stop it in its tracks or make it do something quite different. Like I7 Instead rules, Doers can be applied to specific actions with specific objects under specific circumstances, and are automatically sorted so that more specific Doers take precedence over less specific ones.
• The vocab property. The vocab property in adv3Lite allows you to define several properties of a Thing all at once. For example, if you want to create an object called 'velvet cloak' that can also be referred to with the adjectives 'dark', 'handsome', 'black' and 'satin' and the noun 'garment', with adv3 you'd have to define the vocabWords property as 'velvet dark handsome black satin cloak/garment*cloaks garments' and the 'name' property as 'velvet cloak'; in adv3Lite you just need to define the one vocab property as 'velvet cloak; dark handsome black satin; cloak'.
• A Q object that allows game authors to query the world model, or to override aspects of (particular how things are sensed in) the world model with their own Special objects.
• The ability to define messages in-line through DMsg() and BMsg() objects and then customize them through CustomMessage objects, thus largely removing the need to hive off library messages into a separate language-specific file where they're defined apart from the code that uses them.
• A definition of over 200 irregular English verbs for use in message parameter substitutions, so game authors can write strings like "{I} {take} {the dobj}" or "{The subj dobj} {falls} to the ground." (Regular verbs are dealt with in a manner similar to that in adv3, e.g. "{I} open{s/ed} {the dobj}. "). The English library also recognizes most common irregular English plurals and most common exceptions to the use of a or an before a consonant or vowel.

Additionally, the adv3Lite library has a number of features not found as standard in adv3, such as:

• Built-in pathfinding with a built-in GO TO command that lets players navigate with commands like GO TO KITCHEN as an alternative to using compass directions.
• A number of built-in debugging commands (such as PURLOIN and GOTO to magically snatch any portable object or teleport anywhere on the map; note GOTO is different from GO TO).
• Scenes (that work very similarly to scenes in Inform 7, i.e. allowing game authors to divide up their games by time as well as space).
• Regions: these are a bit like Regions in Inform 7, but more flexible (regions in adv3Lite can overlap, for example). Regions can be used to group rooms for a variety of purposes.
• SenseRegions: these are a special kind of Region providing sensory connections between the rooms they encompass (they thus replace the adv3 SenseConnector/DistanceConnector mechanism).
• The ability to define the direction property of a Room as a method or string as well another Room or TravelConnector object.
• Automatic grouping of objects in various situations. For example, if you issue a command like TAKE ALL, the parser will respond with "You take the red ball, the brown bag, the old pencil and three gold coins" rather than listing each item separately on a new line in the form "red ball: taken". Items with identical names are automatically grouped in room listings and elsewhere, e.g. "You see three gold coins here" rather than "You see a gold coin, a gold coin and a gold coin here." (Adv3 can be made to do all this, but in adv3Lite you don't need to make it do it; it just happens).
• Greater modularity: more of the adv3Lite library modules can be excluded from games that don't need them than is the case with adv3. For example, if your game doesn't have any NPCs you can exclude the actor.t module (since the player character can be defined simply as a Thing). You could also, for example, exclude actor.t if you wanted to replace it with your own version to handle conversation and the like in a totally different manner.
• An enhanced conversation system, which includes the functionality provided by the SayQuery and TCommand extensions as standard, allows games to track NPC knowledge of what they have been told separately from what has been revealed to the Player Character, and allows greater flexibility in the handling of Conversation Nodes, Greeting Protocols and the like. The SayQuery features allow SpecialTopics to be used anywhere (not just in Conversation Nodes) and extend the range of questions from "ASK ABOUT" to include "ASK HOW/WHAT/WHY/WHEN/WHO/WHETHER/IF"; the TCommand features allow game authors to specify what objects a CommandTopic must match as well as what Actions.
• Built-in help for new players, including the ability to detect and correct some common badly-formatted commands and to offer additional help to new players if they seem to be struggling.

What does adv3Lite leave out?

The "Lite" suffix may suggest to people that adv3Lite is simply adv3 with lots of bits taken out. Hopefully we dispelled that misapprehension above, but adv3Lite does leave some things out of the adv3 library. In particular it leaves out many of the bits that aren't used much and/or which tend to complicate things unnecessarily for the majority of games. Examples of adv3 features adv3Lite leaves out include:

• Postures (tracking whether actors are standing, sitting or lying down). This feature certainly adds to the detail of the world model, but it's seldom all that necessary for game play or storytelling, and can create quite a bit of unwanted complication.¹
• Room parts (adding four walls, a floor and a ceiling to every indoor location etc.). This is quite a nice feature of the adv3 library and does ensure that the game responds to commands involving things like walls and ceilings that are implicitly present, but again it often doesn't add much to game play in practice, and can lead game authors into customizing room part objects just because they're there without actually adding all that much to the finished product. Adv3Lite does provide a default ground object in every location, however, principally so that the parser can refer to objects on the ground in disambiguation queries (e.g. 'Which do you mean, the coin on the table or the coin on the ground?').¹
• The transcript. This is a seemingly neat feature of adv3 that allows the grouping of implicit action reports and so forth, but it can be very tricky for game authors to manipulate, and can lead to unexpected difficulties in displaying stuff to the screen. In adv3Lite the features for which the transcript is mainly useful (grouping implicit action reports, for example) are handled by other means, and for the most part output goes straight to the screen (via a number of filters).
• Different lighting levels. While tracking the brightness of objects from 0 to 4 has its uses in the adv3 library, it's more than many games need, so adv3Lite just as an isLit property (it also has a visibleInDark property to do what a brightness of 1 does in adv3).²
• A lot of the complex sense-passing stuff, including the provision for additional senses (which is hardly ever used), different sensory media and different levels of attenuation. While theoretically adding to the sophistication of the world model, in practice all of this is overkill for most games. Adv3Lite does, however, retain the ability to establish sense connections between rooms, albeit by using SenseRegions rather than SenseConnectors.
• Real-time processing (a feature hardly ever used in practice in adv3).
• A large number of library classes, especially those directly involved in implementing the world model. This gives the adv3Lite user fewer classes to learn and remember, without much loss of functionality. This is achieved in part by making it easier to customize the behaviour of objects through properties; for example you can make a Thing behave like a Container simply by defining its contType property as In (although the adv3Library does retain the Container class for the convenience of game authors).
• Many default status messages such as "It's closed" or "It's locked" automatically appended to the description of various objects. Often these can feel like adv3 trying to be too helpful, since they seldom read well, but can be difficult to remove or control. In adv3Lite game authors have to add such pieces of status information themselves if they want them, but that gives game authors full control and makes it easier to incorporate them into more flowing prose; a gain overall.

In addition, adv3Lite tries to be a bit more simple-minded about how it implements certain aspects of the command-execution cycle, for example (though the use of a Command class partly offsets that). This may make certain areas of the library a bit easier to navigate when tracing a succession of method calls.

Overall, then, the "Lite" suffix is intended to signal ease of use rather than a lightweight feature set. But if you still find the "Lite" in adv3Lite off-putting, try turning the '3' round to make an 'E'; not so much adv3Lite as advElite!

¹ However, if you want room parts, postures in your game, adv3Lite comes with extensions that allow you to add them.

² However, if you want various different lighting levels in your game, adv3Lite comes with an extension that allow you to add them.

Scalability

Adv3Lite is scalable in the sense that many of the modules in the library are optional, so if you want to start from something simpler with the option to add more complexity later, you can. There's even an option to create a new game with a cut-down version of the library called adv3Liter, a true 'lite' version. If you do so, you can still add in any additional optional modules you need.

To get a feel for the difference this makes, you may like to compare the source code for two implementations of the same small game (called "Trollbridge"), one using adv3Litest (the minimal version of the library) and the other using full adv3Lite. In the case of this simple game it's possible to do nearly everything in adv3Litest that you can do in full adv3Lite; in a more sophisticated game (one with complex NPCs or sense-passing between rooms, for example), this would not be the case.

There are three main reasons why someone might want to use adv3Litest rather than the full adv3Lite:

1. If you are learning the system for the first time, especially if you're new to IF authoring systems, you'll find that adv3Liter is considerably less to learn than the full system. You could, for example, learn adv3Liter without needing to refer to Parts III and V of the Adv3Lite Library Manual at all, and perhaps using only the first half (Chapters 1 to 6) of the Adv3Lite Tutorial. Some people may find this a gentler way in.
2. You may be writing a game that doesn't need all the features of adv3Lite. If your game doesn't have any NPCs (or only very simple ones), doesn't require access from one room into another (except by travelling), and/or is something of an old-school game that could readily be written in Inform 6 (say), then adv3Liter may be all you need.
3. You may prefer to start from a minimum and add in the extra modules you need as and when it turns out you need them, rather than start with the full set and exclude those optional modules that you don't need or which are getting in your way. This may particularly be the case if your game is a bit out of the usual and you want to provide alternative implementations for the features covered in the optional modules and/or an alternative set of features.

Starting from adv3Litest gives you less to learn, but less functionality. It may meet your needs, or you may find yourself in danger of reinventing several wheels. There is more to learn in full adv3Lite, but there are also many more ready-made solutions available for you to write your game. You can compromise between the two by excluding unwanted optional modules from full adv3Lite or adding in whichever ones you need to adv3Liter.

There is also an intermediate option between adv3Lite and adv3Litest, called adv3Liter, which may be a more practicable choice for users who don't need the full power of adv3Lite but wish to use many of the conveniences it provides over adv3Litest.

Where can I find out more?

There are several places you can go to find out more about adv3Lite.

You may want to start by looking at an adv3Lite implementation of the Cloak of Darkness game (a standard tiny game used to compare different IF authoring systems). Discussions or questions about adv3Lite sometimes pop-up on the intfiction TADS forum. Finally you might want to take a look at the adv3Lite wiki on GitHub.

To find out more about TADS 3 the place to start is www.tads.org.