I can second the IF Archive version. It is currently the most up to date.
Oh, I have a half bugfix, half suggestion if it’s not too late. Because adv3Lite gets rid of roomFirstDesc, the only way to print a different message on first room examination is using embedded expressions, which is… not ideal. But every room has an “examined” property inherited from Thing which the documentation (Room’s libref) claims is set for a room once examined via entering a room or using LOOK AROUND. However, some basic testing shows this does NOT happen in adv3lite.
My suggestion is to properly set “examined” to true like it should, but after the description is printed. This way someone could easily implement a first room description as follows:
desc()
{
if (examined)
// Will never print in lite 1.5
"This is the usual room description!";
else
"This is the first room description!";
}
1 Like
Thanks for your input.
In adv3Lite Room has a visited property that’s set to a true for a room when its description is displayed, so this should enable you to do what you want with the room description. If the documentation says that it’s the Room’s examined property that’s set in this way, that’s an error in the documentation, but I’m unable to find where the docs say this. Can you point me to it so I can correct it? (I suppose it’s possible the reason I can’t find it is that it’s an error I’ve already corrected, but I can’t recall doing so).
That said, it seems logical that a Room’s examined property should also work as you suggest, so I’ve now made that change for version 1.6.
2 Likes
Sure thing! It’s
Adv3Lite 1.5 System Reference Manual → Room class → Summary of Properties → examined
Screenshot:
2 Likes
Fully concur with Hiram: one of the reasons I have kept one of my major work in adv3 and not ported into a3lite is the absence of roomFirstDesc (said work rotate on ever-changing understanding of the environment, and roomDesc are already the realm of adaptive prose & embedded expressions, but also the first impression on rooms &c. depends on the level of understanding…
for Eric, I list the other reasons for my choice: I needed both scenes and guiding Npc TravelTo (the latter for a very unique, and still on the drawing board, mechanism: for a situation in which the player should be steered along a path, I’m designing an invisible and untangible “dungeon master npc” (lacking better term…) and from the docs, I noted that the ancestor of the adv3lite, scenes.t, has just what I needed, so I kept this work as adv3 + scenes.t
oh, this led to a suggestion whose perhaps is for an a3lite 2.0: why not give more flexibility to adv3liter, allowing more variety to a3liter ? I understand that reducing the dependences of the optional parts isn’t easy, and easily led to duplication and inefficiencies in general, but is only a suggestion…
Thank for your effort, and
Best regards from Italy,
dott. Piergiorgio.
1 Like
Thanks for this. In version 1.6 what the docs say here will be true; examined will be set to true provided the room is lit (whereas entering a dark room won’t set examined to true, since the full room description presumably won’t have been displayed). Note that this means that examined and visited will nearly do the same thing, except that a dark room for which isRecognizableInDark is true will be considered as visited but not examined.
3 Likes
I’ve now added roomFirstDesc for version 1.6. It’ll only be displayed if it’s not left as nil.
4 Likes
Can you expand on what you have in mind here? If you start from the adv3Library you can include any additional files from the adv3Lite library you wish, which I’d have thought offers a fair amount of flexibility, but perhaps you had something else in mind.
1 Like
This may be on me since I’m not intimately familiar with the TADS3 library system, but it looks like attachables.t was once an optional module but now part of adv3lite 1.5’s main library. (At least, it appears that way, as it is referenced in the main adv3Lite.tl library but the documentation says it is an optional module). A problem I noticed just now is that thing.t defines the same dObjFor as the attachables file (PlugIn, Unplug, PlugInto, UnplugFrom, etc).
Essentially, cleanup needs to be done where the object interactions should be moved directly from attachables.t to thing.t, because thing.t still contains half-baked dummy implementations assuming that the attachables system is an optional module.
The current design standard for adv3lite is to have classes act as wrappers for properties within Thing (for example, the Wearable class just sets isWearable = true, and this applies to edibles, fixtures, decorations…). However, currently, if a user defines isPlugable = true but neglects to inherit from PlugAttachable, they’ll get the dummy implementations from thing.t.
That got a little long, but the bottom line is that since attachables are part of the standard adv3lite library now, attachable logic either needs to be moved to thing.t, or the dummy implementations in thing.t completely removed.
1 Like
Eric, for sure there’s a major misunderstanding…
what I mean is, looking at the relevant doc of a3Lite manual, some optional modules depends (for valid reasons) from other optional modules (e.g. thought.t depends from TopicEntry.t for obvious, I hope, valid reasons), but what about a story having thoughts but not consultables ? in this case, the compiled but unused code for consultables became an deadweight, I think.
This can be implemented either with more module granularity, e.g. separate module for topicEntry (used in think.t) and Consultables, or duplicating the needed code with appropriate ##ifdef’s (a sure-fire nest of bugs leading to duplicated and/or “deadweight” code in the binary…), hence my “suggestion for a far remote release” proviso.
What I can’t understand is your
whose confused me: AFAIK (and noted in the attempt, a year or so ago, to port that (relatively small back then) major WIP from adv3 to a3lite), the two core libraries are incompatible, mainly at the very root (thing.t) where a3Lite joins vocabWords and name into the (well-designed) vocab, and also a similiar treatment is done for travel.t for rooms, hence I seriously doubt that single a3lite modules can be compiled under adv3 (I admit that I never tried nor tested this hybrid compilation…)
Hope to have clarified my thought (without .t 
) and I hope that you clarifies my confusion on your passage I have quoted above, and
Best regards from Italy,
dott. Piergiorgio.
1 Like
Ah - that will be because what I wrote contained a typo that renders it meaningless. What I meant to say was:
If you start from the adv3Liter library, you can include any additional files from the adv3Lite library you wish.
Sorry for the confusion!
I see what you’re getting at, but I’m not sure it would be worth the effort. I suspect the impact (e.g., on compiled file sizes) of the deadweight code is likely to be negligible (especially on any reasonably modern computer), while breaking the library down into a larger number of smaller files to avoid incorporating code any given game may not need puts an increased burden on game authors to keep track of which library modules depend on which other library modules and which library files they need to include in their game. In practice, I suspect most game authors will find it easier simply to use the entire adv3Lite library so its entire functionality is available to them without them having to worry about what to include; adv3Liter was an interesting experiment, but I wonder if it actually has much practical use. But maybe I’m wrong about that.
2 Likes
Greetings to Erik and other TADS3 fans,
thank you very much for the information and I’m glad that the Adv3Lite library is still evolving. I have a few questions:
- I create two text games in Czech language, for the Adv3 library Tomáš Bláha prepared a very good translation some time ago (he is not working with the TADS3 system anymore):
I was looking for more information about the Adv3 library translation and found this signpost:
http://www.tads.org/xlat3/xlat.htm
However, I could not find more precise information on the Adv3Lite library translation. In the case of Adv3, it is sufficient to copy the resulting translation to the cs_cz directory next to the existing en_us directory in the case of Czech, Adv3Lite contains the english directory and I have some information in the english.t file.
I have little programming experience, so I am not sure if I would be able to implement the translation. Would there be more detailed information available, or an example of translating Adv3Lite into another language?
-
Documentation - The TADS 3 Library Reference Manual is created from comments from the source code, similar to the way that e.g. Java documentation is created using Javadoc. I would like to generate such documentation for my games, but I haven’t found any command to do so (I use Arch linux and Frobtads 2.0 and develop in VSCode with the vscode-tads3tools extension by Thomas Oberg)
-
Translation of the manuals - Eric has produced excellent manuals (Getting started in TADS3, Learning T3, Learning TADS 3 with adv3Lite). During my studies of TADS 3 I would translate at least one of them into Czech (e.g. in Learning TADS 3 with adv3Lite there is information on page 8 that the author welcomes translations). Is there any update planned (e.g. after the release of adv3Lite 1.6)? I’d prefer to work with the modern Adv3Lite library (Adv3 is no longer being developed as far as I know), but looking at them, there are no big differences except for the different number of classes, so if I can’t translate Adv3Lite into Czech, I’ll stick with Adv3 for now and translate e.g. Learning T3.
Have a nice weekend
Ludek Stastny
1 Like
That would be the place to start. You’d need to supply Czech equivalents for everything in the english directory. You’re Czech language files would also need to supply a CustomMessages object containing Czech equivalents of all the adv3Lite library messages and a modification of the libMessages object to supply translations of the handful of messages defined there. I’d suggest looking at the Messages chapter of the adv3Lite Library Manual for further details.
If you mean, do I have any plans to immediately start work on adv3Lite 1.7, then the answer is no, but given that bug reports and feature requests are unlikely to come to a complete halt with the release of adv3Lite 1.6, it’s fairly likely there’d be further updates in time.
I’d say the differences between adv3 and adv3Lite are a bit more substantial than that, for all the similarities between them.
1 Like
The adv3Lite library manual is generated by a program called docgen, which was originally written for the adv3 library by Edward Stauffer quite a while back and then maintained by Mike Roberts. At my request, Mike sent me the C# source code and I modified it further for adv3Lite, and it’s that modified version I’m using, compiled to a Windows executable, which might not work for you. If you want to try compiling it for Linux you could grab the source code from here:
1 Like
Which I’ve now reminded myself you can also find at EricEve/docgen: TADS 3 docgen tool customized for adv3Lite (github.com)
1 Like
Good morning, Eric,
thank you so much for your quick response:
-
translation of Adv3Lite into Czech language - excellent, I will carefully examine the Messages chapter in the Adv3Lite Library Manual, I see there information about CustomMessages and libMessages objects. Then I will try to translate all files in the English directory, if I don’t know anything, I will ask.
-
there are plans to release some update - I was probably unclear here, I didn’t mean updating Adv3Lite to version 1.7, but updating the manual Learning TADS 3 with adv3Lite.pdf. As I can see, beta version of Adv3Lite 1.6 was released yesterday, the manual is still the same as version 1.5. After the translation of the library into Czech language I would like to translate this manual as well, I believe it will attract other Czech authors to learn about TADS3. By the way, your manuals are excellently written and I am glad that they cover both the technical corners of the language and the creation of games with lots of interesting examples.
-
the differences between Adv3 and Adv3Lite - I’ve researched the differences between these libraries and I agree, they are indeed a blessing in disguise. Adv3Lite really isn’t as Lite as it seems to be at first glance (it’s Adv3Liter) and I really like the modularity. The only thing I’ll miss in part is the Different lighting levels (I like working with lighting and day and night time in my games), but I’m sure it won’t be a problem to convert and modify the necessary classes with Adv3 and place it to the extensions folder.
-
generating documentation from source - I downloaded docgen and tried to compile it from source (using Mono library, necessary SDK libraries and VSCode extension). The translation failed (the source code is from 2013 after all), I can run the docgen.exe file in Wine emulator or under virtualized Windows (setup.exe from app.publish directory cannot be run and throws errors). I have explored the quick help using the wine Docgen.exe -h command, I have tried e.g. “wine DocGen.exe -i action.t -o /home/wanbli/output” or “wine DocGen.exe -i /homw/wanbli/heidi/ -o /home/wanbli/output”, but I still see the error message “no inputs specified”. Can I ask for a working example?
Congratulations on the release of beta 1.6, Adv3Lite definitely has a future and I look forward to us all using it in TADS3. I won’t get to my computer until Wednesday (we’re going on a short family vacation) and then I’ll start translating the library, I’m looking forward to it.
1 Like
I’ve no plans to update Learning TADS 3 with adv3Lite in the foreseeable future. The documents that are routinely updated with each new release are the Library Manual and the Library Reference Manual. I also corrected a number of errors and typos in the Quick Start Guide and adv3Lite tutorial, since someone very kindly sent me a list of errata. But I doubt that Learning TADS 3 with adv3Lite will get updated unless someone spots some errors I need to correct, or some future release of adv3Lite necessitates making changes (but since I’m trying to preserve backwards compatibility, I don’t think this is likely to happen).
To simplify my use of docgen, I keep the full command in a batch file. Here’s the contents of the batch file I used to regenerate the Library Reference Manual for version 1.6:
docgen adv3Lite*.h adv3Lite*.t adv3Lite\english*.t adv3lite\extensions*.t “c:\program files (x86)\tads 3\include*.h” “c:\program files (x86)\tads 3\lib*.t” -i intro.html -v %1 -o adv3LiteLibRef
I’d use it by typing:
docgene 1.6
So that the %1 parameter in the batch file is replaced with the version number that’s inserted into the introductory page of the LRM.
So, the docgen command is followed by the list of source (.t and .h) files you want the program to scan to build the output. The -i specifier is followed by the name of an HTML file to use as the LRM’s introductory page. The -o specifies the output directory and the -v the version number (which is inserted along with the date into the HTML file specified by the -i parameter).
You should have found a copy of the intro.htm file in the docgen repo. For your purposes you could either use it as is (since it’s mainly explaining how to use the LRM) or else tweak (or translate) it for your own needs.
1 Like
Well done, I’m glad that the Learning TADS 3 with adv3Lite manual will remain in the same state, it’s true that if you’re trying to keep backwards compatibility (especially for text games, definitely the right decision) there’s no reason to change it. So I’ll translate it as it is now, hopefully to help aspiring text game writers to take a closer look at TADS3.
Thank you very much for the description of the Docgen parameters, I tested it while generating documentation for both the whole adv3lite library and the classic Heidi game, but I still see the unknown include file: adv3.h error:
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
preprocessing Heidi.t
Unhandled Exception:
System.Exception: unknown include file: adv3.h
at DocGen.Preprocessor.Preprocess (DocGen.SourceFile file) [0x0011e] in <50b464c7b8c94651a27135b219baf859>:0
at DocGen.Preprocessor.Preprocess () [0x0001c] in <50b464c7b8c94651a27135b219baf859>:0
at DocGen.DocGenApp.Main (System.String[] args) [0x000a7] in <50b464c7b8c94651a27135b219baf859>:0
[ERROR] FATAL UNHANDLED EXCEPTION: System.Exception: unknown include file: adv3.h
at DocGen.Preprocessor.Preprocess (DocGen.SourceFile file) [0x0011e] in <50b464c7b8c94651a27135b219baf859>:0
at DocGen.Preprocessor.Preprocess () [0x0001c] in <50b464c7b8c94651a27135b219baf859>:0
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
The problem seems to be that the Wine emulator doesn’t see the path to the adv3.h file, I’ll try some other settings.
In the next few days I will try to translate the adv3lite library into Czech, hopefully I will succeed.
2 Likes
I hope that goes well!
I hope that works out too. I suppose you could try putting a copy of the adv3.h file in a directory WINE can find.
As a small suggestion, you could include an <.unreveal tagtext> tag. I use this mechanism in my game for handy off/on flags that don’t need to be defined under an object, and don’t require a method block with a statement to flip them. It’s small overhead and users don’t really have to learn anything new other than to know it’s there as an option…
If it’s an idea to entertain I can send you the code so you don’t have to put one more chore on your plate…
1 Like