Presenting the ADV3 vs ADV3Lite Option to Newcomers

Hey all.

I have a question there that may become obvious after I’ve read the documentation but rather than color my perspective, I thought I’d ask here first.

Let’s say you are planning to get people involved in TADS 3. They have no prior experience with it so any concerns of how “complex” it is will not be operative for them initially. So in starting out, if someone asks “Should I use ADV3 or ADV3Lite?” …

How would you answer that question?

Having learned a lot of different libraries in a lot of different language contexts, here’s what I know I would want to have answered as soon as possible:

• What’s the benefit of the going the “lite” route versus the “non-lite” route? (People tend to associate “lite” with a “lesser” version.)

• If I go the “lite” route, what am I giving up from the “non-lite” route?

• If I go the “non-lite” route, what am I giving up from the “lite” route?

• Can I easily switch between them if I change my mind?

To me, I think these kinds of questions need to be front and center when a choice like this is offered and ideally without the person having to wade through too much material before they make their decision.

The intention is that adv3Lite would be a good choice for people starting out, but it’s hard to generalize, since different people are looking for different things.

The summary at http://users.ox.ac.uk/~manc0049/TADSGuide/adv3Lite.htm is meant to give some indication of that. I’m not sure how one could say much more than that without getting excessively bogged down in detail that wouldn’t mean much to the enquirer in any case. But perhaps you need to ask someone else who’s tried both libraries?

That depends what you mean by “easily”. Game code written for one library won’t work in the other without quite a bit of conversion, so switching between adv3 and adv3Lite for a WIP that was already well in progress would be non-trivial, to say the least, but it would be substantially less work than switching between TADS and Inform, say.

And that was the original intention, though as adv3Lite has developed the “lite” label has arguably become less appropriate (although it remains true that adv3Lite has a simpler class hierarchy than adv3 and omits some adv3 features, it also has some features that adv3 doesn’t). At this point I’m a little reluctant to change the adv3Lite name, though, even if it arguably isn’t the most appropriate, since I get the feeling it’s beginning to become quite well known (and it still expresses something of what adv3Lite is about).

I suppose the counter-question your question raises in my mind is whether presenting the adv3/adv3Lite option to newcomers is that much different from presenting the TADS/Inform/various other systems option. To be sure the newcomers might quickly see that Adrift or Quest take rather different approaches from TADS or Inform, but how is the newcomer to get the information to choose between TADS 2, TADS 3, Inform 6 and Inform 7? (Of course newcomers do make a choice, but where would you start if someone asked 'Which IF authoring system should I use?). Or, to pose that counter-question in a totally different way, what other information do you (or does anyone else) think would help newcomers make the choice between adv3 and adv3Lite?

I appreciate your question was posed in terms of getting people involved in TADS 3, but then the prior question is (at least, the one that’s exercising me), how will such people even get to know of adv3Lite’s existence, unless they happen across it being discussed on this list? I suspect in practice most newcomers will gravitate to adv3 because it’s what comes as standard with TADS 3 and they’ll either be unaware of adv3Lite or wary of its unofficial status - but perhaps I’m wrong about that?

In any case, I’m open to suggestions on all these issues!

I am that person you are talking about.

I am a newcomer to both IF authoring and TADS3. I started learning TADS-heavy, but quickly found out it was somewhat complex.

My particular trigger was the transcript—from the get go, I wanted to know how I could personalize the default messaging displayed by the system. The deeper I dug, the more complex it appeared, and then I found the lite package. I spent maybe a week or two on the non-lite package; I’ve been digging into the lite package for several weeks now and am now neck deep in coding my first game.

There is no going back for me.

Lite means a lot of the overburden has been removed, not the functionality, as best I can tell.

The two libraries are similar in most respects, different enough in some that toggling back and forth will, I believe, be a bit of a chore.

But I see no reason to do so, especially for someone (like me) who has no investment in the earlier library. The lite library seems to be a full-featured development tool. I have yet to encounter something that I have to compromise on because I’m using the lite package.

Thanks for the responses.

So realistically the value add of adv3lite, at least at one level of looking at it, is it reduces the “complexity” of adv3. Whether or not that reduction matters is, of course, dependent on whether or not someone finds adv3 to be complex enough to be frustrating.

It’s also said that adv3lite has a few things that adv3 does not but, of course that may or may not matter depending on the perceived value of those things, I suppose. Whether adv3lite, in some cases, offers different functionality entirely or just a different way of expressing existing functionality is not entirely clear to me yet.

What I look for when presenting to newcomers is whether something is a reaction to something else. Anything called “lite” tends to be a reaction to something “heavy.” I see now that the idea of adv3lite has become more an alternative library than a purely “lite” version of the existing one.

So, for example, in the Ruby world if someone asks me if they should use Sinatra or Padrino for server development, I basically can say that (simplistically) use Sinatra if you want no conventions or patterns enforced at all; use Padrino if you want the MVC convention and pattern enforced on you. It tells you pretty simply what you’re getting or not getting. Sinatra, however, is not “Padrino-lite” by any means. Another example is when someone asks what WebSocket server implementation to use. Well, you can use mod_pywebsocket, Jetty, Socket.IO, and Gateway. In all cases, these different implementations have clear reasons why they are different, usually capable of being stated in a relatively concise way – none of them, however, being a “lite” version, per se.

Eric: to answer your counter-question, you said: “What other information do you (or does anyone else) think would help newcomers make the choice between adv3 and adv3Lite?”

That’s the rub. I have no idea why one would choose the other right now beyond the fact that someone might find the adv3 library “too complex.” But that, as we know, is a value judgment that will differ among people and it also presupposes a conclusion. So the only way it seems to know if adv3lite is what you need is to try adv3 and see if it is, in fact, too complex for you. The only compelling argument I could see to actually start with adv3lite was if it offered compelling functionality that adv3 simply did not (similar to how I might choose to use Padrino over Sinatra simply because of the built-in MVC aspects that I may desire and not want to rewrite on my own).

Thanks for the input, guys. Having used adv3 in the past, I’ve never found it too complex so I’m probably not the best audience for adv3lite but I’ll give it a shot. As always Eric, your work on documentation is much appreciated.

That’s part of it, certainly. Of course not everyone finds adv3 complex enough to be frustrating, but it seems pretty clear from what various people have said over the years that some peopke do. The phrase “alienating complexity of the library” (which may have come from Steve Breslin) comes to mind. And the first person to suggest that adv3 might be too complex and in need of a simpler alternative for some people was none other than Mike Roberts, who proposed the creation of a “Mercury” library as an alternative; see http://tads3.livejournal.com/1202.html and http://tads3.livejournal.com/8152.html (in the second of which Mike describes adv3 as “a big scary monolith”. Ironically, as you’ll see from the first of these, it was none other than I who originally expressed scepticism along lines not a million miles from yours!

Adv3Lite builds on the work Mike had already done for Mercury (but takes it in a direction different from what Mike seems to have had in mind).

Perhaps part of what adv3Lite is trying to achieve might better be described as “ease of use” rather than “reduced complexity”; of course this too is a subjective judgment but I have tried to address some of the frustrations I’ve occasionally noticed some people express with some aspects of adv3.

Well, it depends on whether someone is planning on writing a game that makes use of those features. But there are some features, like the set of built-in debugging commands that adv3Lite has and adv3 lacks, that I’d have thought most game authors would want. Others, such as Scenes and Regions and the built-in GO TO command will, of course, depend on what a particular game author wants for his/her game.

It’s a bit of each (as well as a substantial amount of existing functionality expressed in pretty much the same way). Some of the different functionality is mentioned just above.

It’s certainly a subjective judgment, and of course it will differ among people. That’s why I tried to be careful not too say anything as simplistic as “adv3 is too complex, therefore you should use adv3Lite instead.” Adv3 is unlikely to appear “too complex” to someone who has already mastered it. It also isn’t “too complex” for a game that actually requires all its functionality. If, for example, you were planning to write a game that made substantial use of postures and/or room parts adv3 would almost certainly be the better choice.

I’m certainly not a believer in “one size fits all” when it comes to IF authoring systems. But that cuts both ways; for some people adv3Lite may be a better fit than adv3.

I’m not sure what you mean by “it also presupposes a conclusion”. The only conclusion "presupposed " is that some people may find adv3 “too complex”; but that’s based on the observation that some people seem to have found adv3 too complex in the past. To suppose that other people will in the future is thus surely a valid inductive argument whose presuppositions only David Hume could complain about!

I suppose you could say that would be the only compelling argument, in the sense of a “knock-down” argument. Of course part of the problem then is that many newcomers may not actually know what “compelling functionality” they actually need. I’ve attempted to provide comparisons of the main functionality differences between adv3 and adv3Lite in various places ad nauseam, but I appreciate that such comparisons may mean little to people new to authoring IF.

Of course, you could equally turn your statement around and say “So the only way it seems to know if adv3 is what you need is to try adv3Lite and see if it is, in fact, insufficiently complex for you.”

That said, I’m becoming increasingly uneasy about the use of “complexity” as a one-dimensional comparitor between adv3 and adv3Lite. If one is forced to state in simple terms what the difference between adv3 and adv3Lite is, then “complexity” may be forced to act as a convenient metonym, but the reality is a bit more - er - complex than that! .

I’m quite sure not everyone finds adv3 “too complex”. For what it’s worth, I don’t either. That said, adv3Lite can be convenient to work with even for people who are happy with adv3 (at least, so it seems to me).

Thanks for your input, and thanks for being willing to give adv3Lite a go. I’ll be interested to hear in due course how you get on with it.

Exactly. I agree. That was sort of the point I was eventually going towards.

As an example from another domain, if you’ll forgive me droning on, consider if someone asks: “Why should I use the jQuery library over just using JavaScript directly? I mean, jQuery really is JavaScript, isn’t it?”

People will often say “Well, jQuery helps deal with the complexity.” So concisely it means I can do this in jQuery:

$('#timestamp');

versus this in ‘pure’ JavaScript:

var container = document.getElementById('timestamp');

Actually, one could argue that the “complexity” of the latter is actually making the code a bit more clear in terms of what’s going on. So a better example (maybe?) to make the point is that this in jQuery:

$('#timestamp').addClass('format'); $('#timestamp').removeClass('format'); $('#timestamp').toggleClass('format');

can replace this in ‘pure’ JavaScript:

[code]var timestamp = document.getElementById(‘timestamp’),

hasClass = function (el, cl) {
var regex = new RegExp(‘(?:\s|^)’ + cl + ‘(?:\s|$)’);
return !!el.className.match(regex);
},

addClass = function (el, cl) {
el.className += ’ ’ + cl;
},

removeClass = function (el, cl) {
var regex = new RegExp(‘(?:\s|^)’ + cl + ‘(?:\s|$)’);
el.className = el.className.replace(regex, ’ ');
},

toggleClass = function (el, cl) {
hasClass(el, cl) ? removeClass(el, cl) : addClass(el, cl);
};

addClass(timestamp, ‘format’);
removeClass(timestamp, ‘format’);
toggleClass(timestamp, ‘format’);[/code]

The point here being that it is demonstrable and empirical what “complexity” means in this example but also while allowing that complexity does not necessarily mean “hard to understand” but rather is speaking to the nature of the code necessary to achieve a desired effect, only one aspect of which might be quantity. At a glance, though, it is at least somewhat obvious why you might want to use jQuery over pure JavaScript. It’s an abstraction layer.

So, for example, one statement you say here: “If, for example, you were planning to write a game that made substantial use of postures and/or room parts adv3 would almost certainly be the better choice.”

That’s an important point but, yeah, if someone doesn’t know ahead of time if they are or are not going to want to use postures or room parts, it’s hard for them to make that call. But that comment also highlights that there are clear operational differences between the two libraries – and those differences may matter. So if someone was to read that statement, they may wonder: “Well, what else would make adv3 ‘almost certainly the better choice’? Conversely, what makes adv3lite ‘almost certainly the better choice’?” That’s what I meant by my initial questions. Granted, this also depends on the audience. Anyone with good programming background – when confronted with two libraries – is going to ask the questions I’m asking, hoping to get answers before they invest tons of time in one library or the other. Someone without such experience may just see “lite” and figure “lite” equates with “easier” and go with that one.

All this said, with any luck I’ll be better able to form more cogent thoughts after playing around a bit. My guess is I’ll probably want to do two relatively comprehensive examples in both libraries and show the differences (and trade offs?) between each.

I also got the impression that we were probably more or less in agreement. My responses were more in the nature of attempts to clarify (and to think out loud) than to disagree.

Indeed so. But at the risk of just going round in circles here, those are in part the kind of questions I attempt to answer in outline at http://users.ox.ac.uk/~manc0049/TADSGuide/adv3Lite.htm. I’m not sure how else I could answer it for someone yet to try either library in a way that wouldn’t involve excessive detail. Perhaps you’ll be able to advise on that when you’ve done your own comparison!

There are subtler differences that, I think, would only become apparent with use, and where it might in any case come down to subjective preference.

For example, whereas in adv3 you have to define both the vocabWords property and the name property on every Thing, in adv3Lite you normally combine them in a single vocab property, which avoids the need to type the words making up the name of the object twice. Also, adv3Lite can generally deduce plurals for itself, so unless they’re highly unusual and irregular they don’t need to be defined explicitly. So, for example, where in adv3 you might define:

redBall; Thing 'big red bouncy ball*balls' 'red ball'
   "It's a big red bouncy ball. "
;

The equivalent definition in adv3Lite would be:

redBall; Thing 'red ball; big red bouncy'
   "It's a big red bouncy ball. "
;

Which, over a substantial number of objects, is arguaby a worthwhile saving in typing (and duplication).

As a second example, there’s no SuggestedTopic classes in adv3Lite, since adv3Lite assumes that any TopicEntry with a name property defined is meant to be suggested. So where in adv3 you’d need to define:

+ AskTopic, SuggestedAskTopic @tLightouse
   "<q>What can you tell me about the lighthouse?</q> you ask.\b
    Bob shifts uncomfortably on his feet. <q>The troubles,</q> he begins,
   <q>No, you don't want to know about that, you really don't,</q> "
 
   name = 'the lighthouse'
;

In adv3Lite this would become:

+ AskTopic @tLightouse
   "<q>What can you tell me about the lighthouse?</q> you ask.\b
    Bob shifts uncomfortably on his feet. <q>The troubles,</q> he begins,
   <q>No, you don't want to know about that, you really don't,</q> "
 
   name = 'the lighthouse'
;

Which is just that much less typing. (Before you ask, if that had been an AskTellTopic, adv3Lite would have suggested it as “you could ask…”, but the game author could override that).

Incidentally, adv3Lite is rather smarter than adv3 at working out what topics are available to suggest at any one point in time, so you don’t need to define limitSuggestions on ConvNodes and the like, and you shoudn’t get the problem that can arise in adv3 where a topics are incorrectly suggested or not suggested because of the complecxity of the arrangement.

But these kind of differences are all rather subtle, and not at all easily captured in a sound-byte that’s likely to be meaningful to someone who hasn’t tried out at least one if not both of the two libraries we’re comparing.

Incidentally, while we’re basically agreeing that “complexity” is far from being an ideal measure here, part of what I originally had in mind with the term was the complexity of the class hierarchy. which at least for simulation object classes (excluding TopicEntry types) is rather less extensive in adv3Lite than in adv3. So, for example, adv3Lite doesn’t define any subclasses of Room, Actor or ActorState (one simply uses those base classes), and although there are classes that multiply inherit from TravelConnector in adv3Lite one can often use the base TravelConnector class where in adv3 one would have to use one of its several subclasses that have been eliminated from the adv3Lite library. I appreciate that there’s a trade-off here, since in many cases what was done with different classes in adv3 is done with different properties in adv3Lite; what is in part being addressed is some people’s perception that the adv3 class hierarchy is overly complex. (To some extent, then, adv3Lite is a bit like adv3 shifted slightly in the direction of Inform 7).

That would be great. I look forward to seeing what you come up with.

I’ve been giving this issue a bit more thought in the run up to the next release. Another way of approaching it may be in terms of scalability, by which I mean scalability within adv3Lite rather than between adv3Lite and adv3.

I’ll start from this:

The next release of adv3Lite will come will a small set of extensions, including extensions to implement postures and room parts, so that if someone were starting to write a game in adv3Lite and found that they really did need these particular features, they wouldn’t be stuck or compelled to port what they’d done so far to adv3. The point of making them extensions rather than part of the library, however, is that game authors who choose to use them have to make a conscious decision to do so; these features thus won’t clutter up games that don’t really need them (probably the majority of games) and don’t present themselves as something the newcomer to adv3Lite has to learn in order to master the system.

So, as from the next version, adv3Lite will come with a library divided into three parts: the core module, optional modules and extensions (previous versions up to now already have the bipartite division into core and optional modules). The difference from adv3 here is that far more of the adv3Lite modules are optional (the library design is less tightly coupled so it’s possible to exclude more modules from the build and still have a compilable/runnable game).

In its minimal form, with only the core modules, adv3Lite is genuinely a lite version compared with adv3. It is still possible to write a game of sorts in it (a brief demonstration is attached for anyone who’s interested), but many features that IF authors might typically expect are missing; it might be roughly equivalent to writing a piece of interactive fiction in Inform 6 (or possibly TADS 2) without any extensions, and is thus clearly ‘lite’ in relation to adv3 (or, indeed, to Inform 7).

One can add in more functionality, and arguably ease of use, by adding in (or rather, not excluding) whichever of the optional modules is needed; if one includes them all (or rather opts out of none of them) one will end up with a system that is no longer ‘lite’, since it is comparable in scope to adv3 (and Inform 7), although with a slightly different feature set. If you used adv3Lite with all the library modules plus all the extensions, you’d have something that certainly wasn’t ‘lite’ any more. There’d still be some adv3 features missing, or less fully implemented, but not many, and even fewer that most people would miss, and they’d be more than compensated for by the additional features adv3Lite has over and above adv3.

Thus, adv3Lite is (at least in one sense) only truly ‘lite’ in its minimal version, or its minimal version plus a few of the most generally useful optional modules. What this does allow, however, is a more gentle learning curve for those who want it, since in principle one could start by learning the core modules only and still be able to write some sort of game before going on to look at the rest of the library. How useful this is in practice will depend on circumstances. Someone coming with a reasonably well-formed idea of what game they want to create probably won’t be satisfied with the core modules alone (most authors’ ambitions seem to extend beyond what core adv3Lite will readily provide), but someone who first wants to learn the basic skills of writing IF, or who plans to devise a course for others to do so in some kind of educational context, may find core, minimal adv3Lite a good starting point, particularly since what is learned can subsequently be applied to scaled-up adv3Lite.

I could have presented core, minimal adv3Lite as adv3Lite, and the applicability of the ‘lite’ label would then have been obvious. But I took the view that such a minimal system would be seen as too restrictive for modern IF and would quickly come to be seen as little more than a toy, or at least as a clear retrograde step from other authoring systems. Hence the expansion at an early stage from adv3Lite as truly ‘lite’ to adv3Lite as more truly alternative.

There is a second sense in which adv3Lite remains ‘lite’, even in its fuller version, but this sense is perhaps better expressed by ‘streamlined’ rather than ‘lite’. This is the attempt to remove some unnecessary complexity by reducing the number of classes employed (especially for simulation objects), cutting out the more arcane aspects of sense-passing, and trying to simplify some common tasks, all without significant loss of functionality. Adv3Lite thus aims at relative ease of use even in its less than truly lite form; whether it achieves that aim only time will tell.
Trollbridge.zip (8.18 KB)