Learning TADS 3 with adv3Lite (and an adv3Lite upgrade)

Authoring TADS
1

One of the reasons for developing in adv3Lite was to provide an easier route for people wanting to learn TADS 3 (since adv3Lite has a less complex class hierarchy). But learning TADS 3 involves learning the language (and some other elements of the system such as at least some of the intrinsic classes) as well as the framework library that provides the parser, world model and other such necessities for writing IF. The original release of adv3Lite (an alternative to the adv3 that comes standard with TADS 3) came with a manual that provided detailed information about the new library, but assumed knowledge of the TADS 3 language (and related system features). Subsequent releases gradually included a tutorial that didn’t assume this knowledge, and that provides one way in for new users learning the system from scratch. This tutorial will suit new users who primarily want to learn by doing (by being walked through the creation of three sample games) but may not suit those who prefer a more theoretical or systematic approach.

To meet the parallel need in adv3, I some time ago wrote an additional book for the TADS 3 documentation set called Learning TADS 3. I have now completed an adaptation of this book for use with adv3Lite called (not surprisingly) Learning TADS 3 with Adv3Lite.

This now forms part of the documentation set of the new release of adv3Lite, version 0.91, which is now available from https://dl.dropboxusercontent.com/u/58348218/adv3Lite/adv3Lite091.zip. The update additionally contains a few bug fixes and feature tweaks; for details consult the change log.

The update also substantially overhauls the directory structure of the documentation, so if you have an existing version of adv3Lite I recommend uninstalling (i.e. deleting) it before installing the new version (otherwise you may end up with both versions of the documentation muddled up together). The new-style documentation can also be viewed on line.

1 Like
2

Congratulations, it’s a really nice work. I’ve just noticed a little typo on page 18 - backslash in triple quoted string.

cannotGoThatWayMsg = '''You\'d just end up in a corner! '''
This avoids the need to type the awkward backslash (\) character before
the single...

page 203 - ahouldNotAttackMsg

3

Thanks for pointing out the typo. I’ll correct it for the next release.

4

Incidentally, in case anyone wants to know a bit more about what adv3Lite is or who/what it’s intended for, there’s a page devoted to it at http://users.ox.ac.uk/~manc0049/TADSGuide/adv3Lite.htm, which may answer some of your questions.

5

After reading the description, I have to say, I’m impressed with what you’ve done! At the moment I’m not planning to sit down and write a game … and if my plans change, I already have one started using adv3. But it appears to me you’ve made a lot of very sensible decisions.

Regions and scenes – yay!

One thing I’m curious about (though not quite curious enough to download and read the docs, at least not this afternoon) is whether cmdDict.addWord() and cmdDict.removeWord() are retained or have an adv3Lite equivalent. Those are often useful, I find.

6

Yes, they have an equivalent (addVocab, replaceVocab, removeVocabWord), see chapter 10.2 in Learning TADS 3 with adv3Lite.

7

Excellent! And thanks!

I’m most impressed by the updates to the docs. (Well, the library updates are appreciated, too, but I’ve been updating incrementally as you posted fixes, so the fixes that impact me the most I already have.)

I’ve been struggling a bit to get a handle on NPC conversations, and the adv3lite-specific docs are most appreciated. I just read chapter 14, Non-Player Characters, in the Learning TADS 3 with adv3Lite, and it was a big help.

Prior to getting this update, I took a stab at some supplemental reference docs of my own, extracting NPC and conversation related properties and methods from the 9.0 release of the Adv3Lite Library Manual in order to aggregate the information that is sprinkled around in the official docs, to make it more accessible. I find that, when I need a specific bit of information while writing code, having to dig through unindexed docs to be tedious and disruptive. Yes, I know, the manual is indexed, and that too is greatly appreciated; but still…I find it useful to have this kind of data isolated in a reference supplement.

I might not have taken the time to do that if I had the new, lite-specific updated docs.

But maybe I would. I think they are still useful adjuncts to your docs.

If you’re interested in what a newbie still struggling to learn the system found to be helpful, I’ve zipped up my collection of supplements and am attaching it here.

On my system, I keep the collection in a localhost Apache web server, so I just zipped up the htdocs directory. You don’t need a web server, though, just unpack to a directory and use your web browser to open the index.html in htdocs.

I started by copying and pasting from your manual into an OpenOffice spreadsheet, then exported in a variety of formats. I’m still experimenting to find the format that is most useful and convenient, that’s why there are so many options for each document.

Jerry
adv3lite_supplemental_docs.zip (365 KB)

8

This is undoubtedly the most complex part of the system, so you’re probably in good company!

It’s a while back now, but I recall feeling similarly overwhelmed when I first encountered the adv3 conversation system (which is when it was first made available). My reaction was not dissimilar in that I went and constructed a quick-reference chart for it that could fit on two sides of A4 (or letter-size, I guess!). If it’s any comfort to you it did all (or mostly) become second-nature eventually, but I can still sympathize with how it must seem to a newcomer (and conversation is one area where adv3Lite is certainly not simpler than adv3).

Thanks; I’ll take a look when I can. Right now I need to catch up on the backlog to documenting changes made since 0.91. (Yes - already!). Learning TADS 3 came with a set of ten sample mini-games that could be read in conjunction with some of the exercises or on their own as heavily-commented sample code illustrated aspects of the system. The task I’ve set myself for adv3Lite 0.92 is to port those sample games to adv3Lite for use with Learning TADS 3 with Adv3Lite. I’ve done two so far, and every now and again I come across something that’s a bit awkward to implement in adv3Lite, so I’m making the odd feature tweak/addition as I go along. For example adv3Lite currently has no BagOfHolding class, and though it’s not exactly something every game needs, it would be a pain to have to implement it from scratch if your game needed it, so I’m now adding one for version 0.92. Or, as another example, working with the sample mini-game that does just about everything I could think of with Containers, I realized that adv3Lite is currently a bit inconsistent about what it does with items behind and beneath objects that are moved, so I’ve been taking steps to sort that out (while also adding a couple of flag properties to let game authors control the behaviour in such cases). All this now needs adding to the Manual!

I keep telling myself that adv3Lite must be nearly done, but somehow there always seems more to do!

9

Does anyone know if Learning is available in html? It would make it somewhat easier for me to browse on mobile.

10

@George

I’ve just done an automatic conversion from the odt file which you can download from LearningT3Lite.xhtml. It’s all one xhtml file and the table of contents is broken, but the text is readable, it that’s any use to you.

3 Likes
11

Thanks Eric! Yes that will do until I get back to my laptop.

Edit: I just discovered that apps like KoReader and Moon Reader can text reflow PDFs. It’s not ideal but it does make reading PDFs in portrait view nicer.