A new, easy-to-learn library for TADS3

There’s a fascinating conversation from TADS’s own Mike Roberts over at http://community.livejournal.com/tads3/1202.html about creating an easy-to-learn-and-use alternative to TADS3’s built-in library, a library sizeable enough that it has its own name and acronym, “adv3”.

The conversation is restricted to livejournalers, so I’ll quote Mike’s opening salvo here before putting in my two cents:

I’m not a user of TADS (2 or 3 – but not for a lack of trying), but observe a few rough corners after working elbow-deep in Inform’s.

  1. Inky made the observation that simulating darkness isn’t really needed nowadays, and I agree. We have a larger contingent of sight-impaired players to whom darkness-as-impediment is a joke. Inform has something like 5 Activities dedicated to what is, at the most basic, a boolean property on a room. Talk about swatting a fly with a Buick.

  2. Inform’s library irritates me in that it doesn’t keep sight & sound differentiated. Just because an NPC is trapped in a container doesn’t mean the player can’t talk to them, but it’s a pain in Inform. The built-in conversation actions are geared toward seeing/touching, not hearing. Sense-passing has been important to TADS, and dialogue depends on one of those senses.

  3. TADS’s strong suit is having some sort of dialogue system that’s ready to go. I think that’s crucial for any I-F system worth its salt, and while I understand Inform’s hands-off approach, I would definitely want that even in a pared-down library.

  4. My personal WIP uses command history, and I code normal inform stuff using “if we have Xed the Y” all the time, which is basically the same thing. Except TADS’s is more generalized – one could imagine the equivalent of “if we have Xed the Y after Xing the Z” as being built-in to TADS. Such if-statements are crucial to adapting text to player agency.

  5. Anything that understands more of what the player enters. See Aaron Reed’s Inform extensions regarding a kinder, smarter parser hand. Parsing possessives is an oft sticking point for Inform coders – especially since they theoretically are just a hint to disambiguation routines.

  6. Inform’s LOOK command has always seem too large and opaque to me. Jeff Nyman wrote a tutorial that only dealt with it, IIRC. Aaron Reed called for a modification to LOOK I enshrined in the Mentioned In Room Description extension. I don’t know how complicated TADS’s LOOK is, but, yeah.

  7. Working with writers, I see a common pattern of they wanting a piece of text to appear right around time X in any plausible method. I recently had an issue in that I wasnt’ supposed to have NPC follow the PC, but the NPC should deliver important quip Q 2 turns after NPC#2 said something to PC & NPC, but if the PC immediately left before the 2-turn timer triggered then he’d miss it. So the writer says ‘well it’s ok to follow a little while until Q is delivered’. So I find myself rather that working from cause (the circumstances) toward effect (the quip) like in a sim, I’m working from effect (the quip) and only using fancy coding to insert/narrate a linking, plausible cause (following if not in location, deduction if trigger was never set, simple say otherwise). (I realize that’s a verbose and vague complaint, but its the best I could do.)

I don’t know how TADS wants to position itself. If it wants to be the simulation-heavy dev tool, then perhaps a leaner library isn’t appropriate. But it has a lot of programming features such as the dynamic stuff which make possible new kinds of interaction.

Theoretically.

1 Like

TADS is not only the library. The language is geared towards people who want “C++ or Java for IF”. IMO, that’s its strongest point. These languages are well known by the majority of programmers.

On the other hand, it could also be its weakest point; popularity of text adventures is still declining it seems, and people who write them these days aren’t programmers and they’re usually on their own (as opposed to several people working together to create the story, prose, code, graphics, music, etc; which I suppose is the reason today’s games use an extremely plain presentation.)

My guess is that in crafting a more compact library, Mike is hoping to draw in a few people who don’t mind the C-style code but get lost trying to figure out how to handle, oh, Listers and such things. I can’t say whether that’s a good idea or not. I agree, however, that one of the strengths of T3 is its library!

I’m still firmly of the opinion that the best way to get more people interested in writing games in T3 would be to roll out a nice browser-based interpreter. :sunglasses:

–JA

I think I fit into this category. I’m not a programmer, and I prefer to use the standard, out-of-the-box method whenever possible. However, I kind of like a traditional object oriented approach to IF implementation, and there are a few very minor annoyances that I have with Inform 7, even though it is an excellent system in every way. TADS 3 is just way to heavy for me.

The first IF language I learned to a significant extent was Inform 6. Recently, I’ve been studying Hugo after finding that neither I7 nor T3 were quite to my personal tastes. Although I feel very comfortable with Hugo, it is a shame that it’s no longer developed. I think Hugo has some of the same basic strengths as TADS, and a simpler TADS 3 library might be just the thing to fill the gap.

Would this be a fair summary: You want a way to trigger an event so that you can make sure that the player knows it’s happening?

Every bum in the gutter has an opinion. Here are mine:

  1. Mike Roberts is a genius. When I first started to learn TADS 3, I kept saying to myself, “I can’t believe one person created this whole system.”

  2. As RealNC wrote, TADS

Agreed! Please don’t change it! Transference of knowledge from Java to TADS 3 and vice versa is huge.

  1. I think the effort to create a new library that caters to TADS 2 users in an attempt to boost the user base is misguided. (Sorry, Mike!)

Instead, I see these problems with TADS 3…

DOCUMENTATION

  • There are too many different manuals.
  • The same information appears in multiple manuals, yet…
  • I can never find a complete description of any topic (e.g. a class) in one place
  • The TADS3 Library Reference Manual should be the Bible for TADS 3 programming.
    However, too often I find the words “no description available”.

In short, I long for the days of a complete and concise Borland Turbo Pascal or C++ manual.

EXTENSIONS

If you want to attract more users to TADS 3, give us MORE capabilities.

  • Is HTML TADS complete?
  • if-archive/programming/tads3/library/contributions needs MORE modules like

compass.zip (make a banner displaying a compass)
londoncabs.zip (to simulate the cabbie system [yes, the description should be more generic.])
SunTracker.t (to provide tracking of the sun)
xactor.zip (to help write adult-themed games)

It is our responsibility, not Mike’s!

[Additional note: If any of the other contributions have been incorporated into a newer
version of TADS, delete them from if-archive/programming/tads3/library/contributions.]

Have I alienated everyone yet? :smiley: Please say “No” because I still have programming questions to ask.

Jeff

It is a truth universally acknowledged that the TADS 3 manuals are unwieldy. (As a group, that is - the individual manuals are mostly excellent.) Every so often, I think to myself that I should write a tutorial on how to use the TADS 3 manuals. Then I realise how fundamentally absurd the idea of a manual for the manuals is.

I’m not sure what the answer is. There are a few obvious things that would help. Hyperlinking between manuals would be very useful - but it’s hard to link to the Library Reference Manual because it uses frames. The VM documentation should be moved from the Technical Manual into the System Manual (or out of the user manuals altogether) and the Technical Manual should be renamed to something that more clearly reflects its nature as a bunch of useful articles on various subjects. The HTML documentation should be cleaned up and the references to TADS 2 removed.

But that’s mostly surface stuff. I suspect the problems lie a bit deeper. As you said, there are too many manuals. And it’s not at all clear to new users which manual is for what.

One thing I think is good about the TADS 3 manual system is that the reference manuals are mostly separate from the tutorials. Maybe the manuals should be integrated into a few larger, more comprehensive manuals. The Getting Started Guide and Learning TADS 3 would become a single tutorial manual, and the System Manual, Library Reference Manual and the Introduction to HTML TADS would become a single reference manual. I don’t know what you’d do with the Tour Guide and the Technical Manual; they’re both tutorial and reference. (With the Technical Manual, some articles are more tutorial-oriented and some more reference-oriented…)

Of course, if Mike does bring out an alternative library, the Library Reference Manual would have to stay separate from the system reference manuals…

The Library Reference is automatically generated from the comments in the library source code. The code is very well commented, but the automatic generation does cause problems sometimes. Usually when you get “no description available”, it’s because the generator has tripped over some code like this (pseudo-code):

/* comment */ thingy1; thingy2; thingy3;
To a human, it’s obvious that the comment applies to all three thingies, but the generator assumes it belongs to the first thingy. So if you look up the second or third thingy, you’ll get “no description available”. The best thing to do when you stumble across a “no description available” is follow the link to the source code and scroll up a bit, to see if there’s a comment that the generator missed.

I don’t think so. :slight_smile:

I’d love to see not so much a pared down T3 library as a decoupled one, that would make it easier to use some advanced features while easily disabling others. I seem to spend a lot of time trying to get T3 to not do things, or to accept that I want to do things a little differently from the house style. Writing conversations that don’t feature explicit or implicit greetings (at least not in a way that the TADS library would recognise) proves to have a few pitfalls, for example.

Then again, just removing a lot of excess complications would probably amount to the same thing. I mean, I’m sure all that complex Connector code enables all sorts of cool stuff, but I’ve never used it, only ever encountered it when I’ve been trying to do something that I could probably do a lot more simply without it. For me, I’d be happy if TADS could get a straightforward and simple library, while still keeping these advanced features:

  • The conversation system. Perhaps a bit more adaptable, as I mentioned above, but generally the system of topics, alternative topics, conversation nodes and conversation agendas is awesome - especially given that the code pretty much consists of the topic type, plusses, quotation marks and a semicolon to finish it off. I know Inform 7 claims to be big on the ‘writing’ aspect, but so much of that writing is really coding. Writing a complex conversation in T3, almost all of your writing is actually dialogue.
  • The before and after methods in rooms and NPCs for actions and travelling. Being able to have the game world react to the player’s behaviour in this way works really well. TADS 2 didn’t have this, but I think any IF system worth its salt can’t do away with it.
  • Actor states. Designating behaviour and conversation as occuring only within a certain context is really powerful.
  • Not sure if this is adv3 or the standard library, but the logical ranking is great, although I’ve only just found out about it. When you have a pretty good idea what the player’s going to say, and what they’re going to mean, it’s important to be able to bias the parser.

I love the idea of sense simulation, even for light. I’ve messed around with the idea of different light levels allowing you to see different things in a room. And I found that it was way too complicated for me to get to grips with. And then delving into the other senses, I’ve been disappointed to find out that a lot of it seems to be just hard-coded, and not as simulationist as I expected.

This is a popular opinion among people in the old IF community, it seems, but what I see is IF now pretty much accepted in the wider communities of indie/hobbyist/art game makers and players. IF games are appearing pretty regularly in events like Ludum Dare, TIGSource Competitions, Pirate Karts - and places like JayIsGames and Metafilter are holding their own IF making events. No, I don’t think many people are crazy obsessed with IF, but I do think a very substantial number of people now see it as a part of small-scale gaming as much as, say, platform games or roguelikes.

I’d love to write a tutorial or manual at some point. I think the existing manuals are great as either a reference for what TADS can do (the Tour Guide) or an instructional piece on general TADS programming (Learning TADS 3) but I think there’s a need for more of a How-To kind of manual that’s not so interested in what TADS can do, as what authors would want it to do.

There’s plenty of things that are pretty standard things an author might want to do, where you’ll have to dive into the library and try to figure out the correct ‘modify’ statement to use. Modifying the vocab of an existing verb, changing the behaviour of an existing verb and creating new directional systems are all things that I’ve had to do through a combination of searching and trial and error. Similarly, getting started using HTML is pretty hard. It’s not immediately clear where you can find a list of valid tags (for the record, it’s divided between “Getting Started with HTML TADS” and “HTML TADS additions to and deviations from standard HTML”), and the most obvious thing an author (or at least an author that’s me) would want, a command hyperlink, is barely mentioned at all.

Sounds like T3 could use something like a cookbook or idiom site.

I agree with most of the comments. It would be swell if the library were simpler … but: If you’re using a simpler library and you happen suddenly to need one of the more advanced features, you’re sort of up a creek.

Instead of a simpler library, I think what TADS needs is a cookbook. Something that says, “Here are the 20 (or 30, or 50) things you’re most likely to want to do by way of customizing your game, and here’s how to do them, step by step, complete with alternatives and cross-references.”

The LRM is usable, though not great. I agree that “no description available” is annoying. The Tour Guide attempts to fill in the blanks in the LRM, but it isn’t comprehensive by any means. I often search Learning T3 for a particular word. The System and Technical Manuals are very much a grab bag, and it’s hard to remember where to look in them to find what you need.

Maybe after I get done with version 2.0 of my Inform 7 Handbook, I’ll decide to tackle a cookbook project. It would need input from lots of users…

–JA

Everyone has good comments related to the TADS documentation.

Me first! Me first! ( :slight_smile: )

Can I begin with a shriek?

I’m on my knees, begging. Pleeeeeease not another TADS manual. Please.

Overall, the existing manuals have the necessary content. They need…

  • Swallow pride of authorship
  • Grab an axe or a chainsaw
  • Consolidate, back and fill, reorganize…2,3,4
  • Consolidate, back and fill, reorganize…2,3,4
  • Consolidate, back and fill, reorganize…2,3,4

More specific whining from me…

  • The manuals need more bullets, less prose.
    (I want to get in, grab the necessary information, and get out–back to programming, not slog through reams of narrative.)
    Getting Started in TADS 3, TADS 3 System Manual, TADS 3 Technical Manual, and Learning TADS 3 are especially evil culprits.
    .
  • More examples, please. Many, many, many more examples, please.
    (Then, I won’t need to ask [insert your favorite expletive] questions such as “How do I use SuggestedTopic?” See my previous post in this forum.)

Amen, Brother Jim! I have the same problem with these manuals. One more whine…

  • A “table of contents” needs to have clear, meaningful, well-organized contents.
    (“Fundamental Datatypes”, I like. “Reflection”, does nothing for me.)

CONCLUSION

Truly, in the depths of my heart, I believe that the TADS documentation is the single greatest impediment to attracting new users. Fix the documentation. Don’t muck with the library.

I’ll crawl back under my rock now.

Jeff

There is no such concept as too many manuals. I don’t think it’s considered a fault for languages like C++ to have hundreds of different textbooks availale. I do understand that the amount of documentation might feel overwhelming, but you don’t have to read the ones you don’t need (I for example skipped Getting Started in TADS 3 because as I see it there’s nothing there that couldn’t be found in other manuals.) The solution to your complaints is exactly what’s been proposed – a new manual that presents the information differently.

And this is exactly why it’s better to have more manuals than less. Some people actually learn better from narrative than from examples or bullet points. If the existing manuals would be changed to what you would find perfect, many others would complain that they’ve been ruined for them. People have different ways of learning and there is no fit-for-all solution which is why different textbooks with different perspectives are needed.

Of course, if Mike does release a new simplified library (which, I understand, is intended as an alternative to, not a replacement for the existing adv3 library), there’ll have to be some manuals relating to that: at the very least a Mercury LRM to sit alongside the adv3 LRM, and possibly Mercury versions of Learning TADS 3 or the Technical Manual.

Quite so; that’s why, for example, there’s both Learning TADS 3 and Getting Started in TADS 3; the idea is that you use one or the other, not both.

I don’t know how imminent the appearance of the Mercury Library is, but if it’s going to appear in the next year or so it may not be worthwhile anyone doing much work on TADS 3 documentation until the Mercury library is available. At that point, it may be worth someone writing a fresh introduction to TADS 3 based on the Mercury Library, which may be a more manageable way in for people who find the adv3 library a bit overwhelming.

– Eric

Given the inclination towards proliferation of manuals, I’m just curious…

When will Braille versions of each manual become available?

Jeff

I understand where you’re coming from. Without disrespecting Eric in any way – without his weeks and months of hard work, TADS 3 would be entirely impenetrable! – I can recall getting very confused and frustrated when I was first tackling TADS. That was before “Learning T3” was added to the package … but still.

That said, the Inform documentation is not thrilling either. My observations on that point led me to write the Inform 7 Handbook, and I’ve had a lot of positive feedback from users indicating that it filled the gap for them.

Perhaps it’s best to think of learning the TADS docs as a separate exercise to learning the language and the library. Sometimes the information I need (and I need information often!) is in the LRM. From there I may have to click a link to read the library file itself. If I’m still confused, I search Learning T3 for a text string. From time to time I scroll down the page list in the Tour Guide to see if there’s a page on the class that I’m researching. Sometimes I’m still baffled, and have to post questions to the newsgroup, or to this forum.

I’m happy to report that after a while the fog does start to lift. But I’m not entirely sure that the solution, for newcomers, would be to toss the documentation up in the air and redo it all as one coherent manual – even if someone had time to do that, and even if it were possible to do that.

If I had infinite time on my hands, what I would do would be three things. First, I’d build up the Library Reference Manual so that the discussion of each and every class was a lot more thorough. I would also add cross-links from it to the other docs.

Second, I’d integrate the System Manual and Technical Manual (somehow), perhaps adding the coding basics from Getting Started to the mix.

Third, I’d write a strictly task-oriented cookbook.

But in the real world, I’ve started working on a TADS game that I set aside a year ago. It is beyond huge, and it’s going to keep me fully occupied for the foreseeable future.

–JA

I’m probably sounding like an alien or something when saying this, but the best way to understand how to work in T3 is to look at the library files themselves. The code is very well commented; adv3 consists of 85.131 lines (not counting blanks), and 50.000 of those lines are documentation! The code itself is about 35.000 lines. This can give insight at how “stuff works.” The library is not a black box.

Well, yeah. I often sound like an alien too, though perhaps for slightly different reasons.

I think the method you’re recommending would work well for about 5% of aspiring TADS authors – mainly those who already have some serious programming chops. That works out to about 1.25 aspiring authors at any given time. The other 23.75 authors would probably be better advised to read Learning T3.

I do sometimes read the library files themselves. The difficulty, for me, is tracing down all of the calls that various methods in the library are making to other objects. The library is heavily nonlinear. (This is not a complaint, it’s just a statement of fact.) A book that introduces you to the basic concepts in a rational manner, building from simpler code to more complex or special cases, is a better fit for me as a learner.

–JA

More manuals are better for people like myself. When I’m learning something new I prefer to read/skim three or four introductory texts. Even if they cover the same subject matter, the repetition and the variation really help.

However a cookbook wouldn’t really be ‘another manual’, but more like a wiki I think.

An IF cookbook could be cool, something like the Cloak of Darkness site but for many small examples. I think the past RAIF topics article at the IFWiki is like that, just not specialized/categorized enough for the purposes of a cookbook.

Hi Matt. No, it has nothing to do with timers; it’s much broader than that, and goes off into the areas of Holy Grails and Fundamental Re-designs, so it’s probably off-topic. What I was looking for there was a way of attaching pre-conditions and post-conditions to a piece of prose, and the authoring tool would use AI-like intelligence on the sim model to figure out how to deliver that prose while observing those conditions. I.e., the tool would not just check the conditions and complain if they’re not met (which is possible with the tools as-is), but rather, would arrange matters so that they are guaranteed to be met. Or throw a complier error if it’s impossible.

I don’t know if such a thing would be possible in imperative languages such as TADS and Inform, though. So, Holy Grail, I guess. A.I. would be easy enough to do, and already is at run-time thanks to RAP and similar extensions, but I’d nearly require such an intelligence be in the compiler itself!

Perhaps I shouldn’t have bothered the TADS people with the point. But to continue my post:

  1. The ability to parse full sentences, not just imperative sentences. I blogged about the possibilities the words could, would, and should may open in sentential-controlled games such as I-F, and when combined with command history, there’s a lot of artistic possibilities there to explore especially vis-a-vis interactive dialogue. But parsers are difficult to write, and getting all those tenses correct like progressive past-perfect is a chore, but it’s a chore that, since English is fairly immutable, is a prime candidate for enshrinement in a library. (Contrast & compare magic systems, which are necessarily idiosyncratic and possess few traits in common other than the name.)

Can you give an example here? Pre-conditions can be used to perform actions without the player needing to explicitly state them. You can even have the parser solve puzzles on its own this way, and this is the reason the author must put emergency breaks there if the parser tries to get smart in order to avoid such spoilers. But I’m not sure that’s what you mean.