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:

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

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:

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.


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