the Golden Skull

Learning multimedia TADS

 

The Golden Skull started out life as a few lines of sample code that Mike Roberts wrote for the TADS Author’s Manual. I thought it could be useful as a starting point for a small multimedia TADS demo game. So here’s some information about it.

Note that the first multimedia TADS interpreter was HTML TADS for Windows, so elsewhere you may still see the term “HTML TADS” referring to the whole multimedia TADS environment.

What does the Golden Skull do?

As noted, it’s just a miniature game designed to demonstrate some of the new capabilities of multimedia TADS and, as such, it’s not a particularly engrossing or challenging work. Sorry about that. Nor is it a game meant to teach absolute novices how to program in TADS. You’re expected to know a little bit about TADS basics before checking this out. Finally, it has some really annoying featurettes that you probably won’t want to implement in a real game. At least, not if you have any taste... but they’re here to show you the kind of interesting stuff that can be done with the tools.

Here are the basic multimedia features that this game illustrates:

Getting the files.

First of all, you obviously need the latest copy of the TADS software for your computer. You’ll need both a copy of the compiler and a copy of a multimedia TADS-compatible interpreter. (this latter means that multimedia TADS development is currently only possible on Windows 32 and Macintosh operating systems, since nobody has yet ported the multimedia TADS interpreter to UNIX or any other OS.) For more information on this, have a look at the authoring section of the TADS Page.

Next you’ll probably want a copy of the multimedia TADS documentation. These files are included with the Windows distributions of HTML TADS, but since there’s no specific multimedia-compatible compiler for Macintosh you won’t have these files if you’re a Mac user. So I’ve mirrored the documentation on my Web site:

http://www.tela.bc.ca/tads/authoring/multimedia-tads-docs/

Finally, you’ll need a copy of the Golden Skull source code and associated multimedia files. You can download all this stuff as a single file from the IF Archive:

http://ifarchive.org/if-archive/programming/tads2/examples/goldsrc.zip

This zipped archive (you’ll need an unzipping program for your computer) contains the following files:

b-skull.jpg - a picture of the Golden Skull on a black background
bird.wav - a digitized bird chip sound
cave.jpg - a picture of the cave interior
cave.wav - the sound of a dripping cave
click.wav - a brief clicking sound
clock - a folder containing the images that make up a digital clock
compass - a folder containing the images that make up the electronic compass
death.wav - the sound of someone croaking amidst a flurry of darts
dots.png - a black and white pattern
drip.wav - the sound of a water drop
entrance.jpg - a picture of the mysterious cave entrance
gold.gam - the precompiled TADS game file for the Golden Skull
gold.t - the TADS source file for the game
outside.wav - the sound of a tropical jungle
readme.1st - a brief readme file
red-bg.jpg - a red background text for the About box
redtitle.jpg - the game title for the About box - on a red background
scrape.wav - the sound of a rock scraping as it’s being moved
title.jpg - the game title image, only on a white background
w-skull.jpg - a picture of the Golden Skull on a white background

Now, if I were to redo the organization of the game files today I’d probably segregate the picture and sound files into separate “image” and “audio” folders rather than throwing them all in at the top, but this is how I structured the thing originally.

Note as well that the audio files are all in WAV format. This isn’t a very efficient format compared to MP3, and so the files are quite gigantic despite being low-quality and very short. However, at the time I wrote The Golden Skull multimedia TADS only supported WAV. MP3 support was to appear in the future.

How the game works.

Fire up your favourite text editing program and take a look at gold.t, the source code which makes up the game itself. It’s quite liberally commented and should be fairly easy to understand, assuming you know how TADS works.

In fact, as mentioned above, this document assumes that you already have a basic understanding of how to write a TADS game. The non-textual aspects to multimedia TADS are built upon the basic TADS foundation. If you want to learn more about TADS itself have a look at the list of beginner TADS resources available to you.

Compile using the latest versions of adv.t and std.t.

As you know, the TADS compiler ships with adv.t and std.t, which provide standard library definitions for a basic TADS game. Be sure that you’re using the latest versions when compiling gold.t. If you happen to have a really old version lying around you’ll almost certainly have problems with the HTML coding. The newer versions include correct HTML-compatible banner code to handle the status line.

If you use an older version you may find strange things happening. A common problem is status line code which screws up and puts the room description down by the command prompt each time.

Custom functions.

You’ll note that the code starts off with a number of custom functions designed to simplify the task of displaying graphics. Since the graphics displayed can change depending on internal game states it makes sense to write a bunch of frequently reused custom functions that assist in image display. Otherwise you’ll need a bunch of IF statements every time you want to show a picture or whatever.

Regular HTML.

Next you’ll notice that multimedia TADS simply uses pretty standard HTML to accomplish its tricks. On some systems you might need to call a special function that’s unique to the gaming environment in question to display an image. But in multimedia TADS you simply display a bit of text like this:

<IMG SRC="picture.jpg">

This is an HTML tag that specifies an image. The source of the image is the file named “picture.jpg”. So, it goes without saying that to make use of multimedia TADS’ enhanced features you’re going to have to learn HTML.

Luckily, HTML is both pretty simple to use and thoroughly documented. I’m not going to get into it here, simply because there are a lot of other resources you can learn HTML that are far better than anything I could assemble quickly here. But you might want to look into introductory HTML books or Web pages if you’re new to the field. Here are some starting points:

Webmonkey.com HTML introduction.

Webmonkey.com HTML cheat sheet.

Builder.com HTML introduction.

Escaped quotation marks.

HTML tags frequently use quotation marks to delineate tag attributes, as in the example above. The problem is that quotation marks are interpreted by the TADS compiler in a specific way. There are two ways around this.

First, you can safely substitute apostrophes for quotation marks in most places. eg:

<IMG SRC='picture.jpg'>

or second you can escape each quotation mark by using a backslash \ character:

<IMG SRC=\"picture.jpg\">

Which is better is a matter of preference.

Custom HTML.

For the most part, multimedia TADS follows the official HTML 3.2 standard very closely. But there are a couple of points here.

First, multimedia TADS supports a few HTML 3 tags. However, HTML 3 was not supported in the Web browser world for political reasons. It was intended as a superset of HTML 2, but the big browser players (Microsoft and Navigator) didn’t like it, so they did their own thing. In an attempt to maintain their credibility the World Wide Web Consortium hastily retrofitted their work to accommodate Internet Explorer and Navigator, ending up with the HTML 3.2 standard. In fact, the W3C site doesn’t even list HTML 3, as though the ill-fated standard was an unseemly aberration to be purged from the records in a data pogrom.

Anyway. I mention this little historical anecdote primarily because there are several very useful HTML 3 tags (eg: <BANNER> and <TAB>) supported by multimedia TADS, but you won’t find a lot of references to HTML 3 in textbooks and the like.

Second, there were a number of areas in which Mike Roberts had to come up with ways of extending HTML to enable features that are appropriate for text adventure games but which aren’t needed for Web browsers. For instance, multimedia TADS has its own sound tag. Here’s an example:

<SOUND SRC=\"outside.wav\" LAYER=BGAMBIENT REPEAT=LOOP>

These deviations from the official HTML 3.2 standard are documented in the files that ship with Windows HTML TADS. Look for the file "deviate.htm", where they’re all listed. I also have a full list of supported tags with the TADS manual.

Engage HTML.

There’s a small magic incantation in multimedia TADS that’s required to enable HTML parsing. And that is the text string “\H+”. Until this string is encountered by the TADS interpreter no attempts to parse (read) HTML will be made, and the game will operate just like a standard text-only TADS game of years gone by. However, when it sees “\H+” then it switches over to the HTML mode required by multimedia TADS.

This gives you a fair bit of control over things. For example, if you’re trying to debug some HTML problem or other you can just not print \H+ anywhere. When you do this actual HTML tags will appear on the screen, and you can follow through them yourself to see what’s going wrong.

International entities.

No, not global celebrities, but textual symbols (glyphs) required by non-English languages. Most computers are based around the 7-bit ASCII (American Standard Code for Information Interchange) code, which supports up to 127 different characters. Unfortunately it was designed many decades ago, when presumably it was assumed that the only people using computers in the world spoke English. ASCII has been extended, in a platform-specific way, to support 8-bit character sets, but international support has always been dodgy.

TADS supports HTML-style character entities for full support of most European languages. This won’t help you if you’re wanting to write a game in Arabic or Hebrew or Japanese or whatever, but then such languages don’t work well with TADS anyway, which assumes a certain model for its language parsing. However, if you want to include accented (diacritical) characters in your game you now can.

Entities are enclosed by the & and ; symbol, and have an abbreviated English-language code. Thus &eacute; is a lower-case E with an acute accent on it - é - for instance.

Here is a list of ISO Latin 1 (Western European) entities and here is a list of ISO Latin 2 (Eastern European) entities. Most of these are supported by TADS.

Some Opinionated Editorializing on illustrated text adventure game design:

I thought I’d also offer a few suggestions, comments and editorial remarks concerning what I’ve learnt in assembling this simple demo, the first real TADS game to incorporate HTML, graphics and sound. Take this advice as you will. Some people will undoubtedly find these suggestions rather patronizing, but, well... there you go.

Graphics.

First, graphics. Graphics are a hell of a lot of work to do! Putting this game together really hammered home that point for me, since I wanted something that looked professional, not some cheesy MacPaint or Windows Paintbrush doodlings.

There’s a reason why text adventures are still being written by the proverbial guy or gal in a garage, and why modern graphical epics are assembled by large teams of underpaid slaves to a faceless corporation. Graphics are time-consuming to create (it took several days of intermittent work to get the five main images in Golden Skull done - mostly photographing things, laboriously removing handrails and other unwanted things from the photos, replicating leaves and so on to cover up patchy bits... pictures which take nanoseconds for the player to view!) and expensive to do well. On top of which, you need to have some modicum of talent to create decent artwork.

I dodged this last issue to some extent simply by taking photographs and reworking them... an approach many of us should probably consider. Because most of us can’t draw worth crap. If you have any doubts about the professionalism of your images, it might be better for your reputation and the overall success of your game if you exercise the null option and simply leave them out. A well-written text adventure with no graphics is going to come across a hell of a lot better than the same game with awful, amateur graphics. Be honest with yourself. If your drawings look like something that belong on a proud parent’s fridge, do yourself a favour and leave ’em out of your game. (unless, of course, children’s drawings are the point of the whole game, as in Stephen Granade’s Arrival)

Of course, if you actually are a person with artistic abilities or are in the position to get someone who is to do graphics for you, just think of the possibilities... Most games tend to go for retouched photographs or fuzzy full- motion video or the glossy, unreal look of computer imaging. But textual IF is different - it often has pretensions to a more literary form. So I think an illustrated book could be a very intriguing metaphor for a multimedia TADS game.

The illustrations could be watercolours, charcoal sketches, cross-hatched pen and ink. Like John Tenniel’s drawings for Alice in Wonderland, or E. H. Shepard’s sketches (later coloured with watercolours) for Winnie the Pooh. Or, for something more contemporary, the stylized look of a comic book with exaggerated perspective and flat colour. Hell - why not a game about Elvis and UFOs, illustrated uniquely with black velvet paintings?

Going for an illustration-based approach also neatly side-steps one of the bigger problems with including graphics in a game - state changes. If you go for a more literal approach to game illustration you’ll want to have different images to represent different states of the objects in question. So you’ll need a picture of the cave, a picture of the cave with the gold skull in it, etc. Or two pictures of a car - one with the door open and one with the door shut. That rapidly becomes very space and time consuming. It took an entire evening of mucking around to get the compass graphics done, with all of its different pieces and colour variants.

It can be particularly onerous if you want to include portable objects, because multimedia TADS has no mechanism for overlaying images onto scenes. There’s a reason why Myst and Riven, both games built around elaborate pre-rendered images, don’t let you pick too much stuff up and carry it around.

But if you opt for a more figurative than literal approach to illustration you can simply ignore the state change problem altogether - the graphics are there to provide a mood or illustrate a feeling, not to be a realistic and literal portrayal of the current state of a virtual environment.

Elaborate text formatting.

Second, fancy formatting. This game uses some horrible formatting simply to demonstrate what multimedia TADS can do. But just because something can do something doesn’t mean you have to use it. Go lightly on the formatting. Simple bold and italic now and again make a big difference to the appearance of a game. As does something typographically appropriate like using a sans serif font for certain headers and a serif font for body text. Curved typographical quotation marks ( “ and ” ) instead of ugly neutral ones ( " ) make an amazing difference.

But please, don’t go crazy. Especially with formatting options like colour. I’d strongly suspect that most of your players will find wacky formatting far more annoying than cool, once the initial novelty has worn off. Think of novels. Most novels contain plain text with simple elegant formatting. It’s only things like short-lived periodicals that rely on hard to read and flashy text styling.

Fonts.

Third, be careful with fonts. You can specify fonts in multimedia TADS, but don’t forget that font choices are totally dependent on what fonts the player happens to have installed on his or her computer. If you specify a font that the player doesn’t have then text will be displayed in the interpreter’s default font, whatever that happens to be.

Luckily, to work around this problem, multimedia TADS has a number of “parameterized” fonts built in. This means you can simply specify a generic type form - serif or sans serif or script - and the copy of multimedia TADS for the OS that you’re using will automatically map this to the appropriate available font.

I recommend using these TADS named font types instead of platform-specific fonts. After all, you may happen to have a copy of a font named “Bilbo’s Strawberry Dream” on your computer, and your game may look fabulous displayed in it, but that doesn’t mean anyone else will necessarily have the font. And using an OS-specific font, like Geneva or Arial, is no guarantee that someone else using another OS will have it. Note that the Golden Skull code doesn’t use parameterized fonts for the simple reason that the feature did not exist when I wrote it - Mike added the feature later.

Another option is to specify a list of fonts, and multimedia TADS will pick the first font that is available on the current system. This affords you a certain degree of flexibility. For example, most Windows systems have Times New Roman installed and most Macintoshes have Times installed. So you can put in the tag:

<FONT NAME="Times,Times New Roman,TADS-Serif">

and you should get Times on either platform. Failing which you’ll get a serif font of some kind anyway.

And of course don’t forget that using dingbat fonts (fonts that consist of little pictures rather than letters) is very unwise. Zapf Dingbats may be available on most Macs and Wingdings on most PCs, but they have very different characters. And other platforms may not have a standard dingbats font of any kind. To avoid messiness you’re best off avoiding dingbats and using graphics files instead.

Sound.

Fifth, sound. My previous comments regarding misuses of graphic and text formatting apply to the audio feature.

Tasteful, professional and appropriate sound can do wonders for a game. Plug a pair of speakers into your machine and play Cyan’s sequel to Myst, Riven - you’ll see what I mean. But if you load your game down with constant cheesy sound effects you’ll simply annoy your audience, who’ll probably just exercise their right to turn sound off altogether. So why even bother?

But I admit there are borderline examples. For instance, you might think it’s cool to add the soft grunting noises of an ancient 5.25" floppy drive at certain points in the game, as if the game were loading off disk the way old Infocom games would. This will thrill a lot of people, who’ll delight at the sheer retro nostalgia value of aving a brand new computer emulating an old clunker from 1981. But other people, particularly those who don’t remember the old machines, might find it simply irritating. I might be inclined to include such an effect, but allow the player to disable the option. Or, of course, just rely on the “Sound effects” menu option in multimedia TADS.

Of course, keen-eared people will undoubtedly point to the general hypocrisy of me telling you not to include cheesy sound effects - as this game includes some very annoying and cheesy sound effects. Well, yes, but again this isn’t meant to be a real game that real people will play. That’s my feeble excuse. Also, please note that the sound effects in this current version of the game are sort of placeholders so that I could get it out the door in time for Mike’s preview of the new authoring environment. The cave, for example, has more of a rain sound effect than anything else. Ah well.

This all may read like I’m trying to say “Use multimedia TADS but don’t use any of the cool new multimedia TADS features.” Well. Not quite. My point is that these new functions can be startlingly effective when used lightly and appropriately. Mike has implemented some extremely cool new features. But if you pile them all on it’s going to be counter-productive, in my opinion.

Colour.

Finally, colour. I do play around a little bit with coloured text and backgrounds in this game, basically to show off the capabilities of the system. But in a real game I advise restraint. For one thing, an older computer with a very limited colour palette will have difficulty displaying a multimedia TADS game with a lot of colours. In fact, it’s possible to have a screen that’s virtually illegible on older computers if you set the wrong colours. You also don’t want a page that’s hard for the player to read. (such as, ahem, white text on a black ground like in this demonstration)

Now, it’s true that players can override colours with the interpreter program, but I don’t think they should need to do this.

Conclusion.

Remember when word processors first introduced style features and people started printing posters in Helvetica 72 Bold Outline Shadow Italic? Same thing here.

Advanced tips.

Here are some more advanced coding ideas which go beyond The Golden Skull itself.

Converting an existing TADS game to multimedia TADS.

There are a number of things you have to do to turn a regular game into a multimedia-compatible game - at the very least, reformatting some of the on-screen text to be HTML compatible. I’ve written up a separate tutorial on the basics of this:

http://www.tela.bc.ca/tads-manual/html-convert.html

Multimedia TADS games with text-only interpreters.

As mentioned above, the text-only versions of TADS also support named character entities. They also are capable of interpreting a few HTML tags which make sense in a text-only environment, such as <B> and <HR>.

You can, therefore, easily write a text adventure that’s fully compatible with both text-only and multimedia versions of TADS. Naturally there may be some instances in which you may want the text-only versions to provide a little extra textual information to avoid ambiguity, but at least the technical framework is there.

However, older versions of TADS do not support HTML or named entities. So you might want to add some code that checks for the browser version and refuses to load the game if the interpreter is too ancient. Here’s some code that you could put into the commonInit() function that can do that.

if ( systemInfo( __SYSINFO_SYSINFO ) = true )
{
  // if the systemInfo function is present then this
  // is TADS version 2.2.4 or higher
  "\H+"; // engage HTML mode
  (do whatever else you need to do)
}
// TADS version is less than 2.2.4.
// No good; we don't even bother going any further
else
{
  "I'm really sorry, but the version of TADS you are running is
   extremely old and so is incompatible with my super-spiffy new
   game. Please download a newer copy of TADS from ifarchive.org.
   Thanks! ";
  quit();
}

You might also want to check for higher version numbers. There are some compatibility issues with the oldest versions of multimedia TADS, so you might want to require at least TADS 2.3 or so. Here’s one way to check for version 2.3 or higher:

if ( cvtnum( substr( systemInfo( __SYSINFO_VERSION ), 3, 1 ) ) < 3 )
{
  "Sorry. You need at least version 2.3 of TADS to play this game. ";
  quit();
}

This sort of version checking may inconvenience a few players, but shouldn’t shut anyone out entirely. There are versions of the TADS interpreter that can run on ancient IBM PC AT and Mac Plus machines.

The same basic principles can be used to check for a variety of cases. You can use systemInfo() calls to check and see what level of multimedia support the player’s interpreter can handle. (MP3 playback, PNG graphics, etc) Then you can tailor the game’s multimedia output to their system’s abilities.

The About box and chapters.

Multimedia TADS supports a “chapter” feature whereby a clearscreen() function call creates a new page of text. You can then flip back and forth between these chapters by using a menu item. However, this works by resetting the entire text window, and that includes the HTML code which makes up the About box. So if you set an About box and then issue a clearscreen() you’ll find that the About box is empty for the second chapter.

The easiest way to fix this problem is to pull all the HTML that makes up the About box itself and put it into its own method or function somewhere. Then you can call it every time you perform a clearscreen().

This page copyright © 2001 NK Guy. Please email me at tela @ tela.bc.ca if you have any comments or suggestions.