_{(Written by Richard Bos on May 23, 2014. Download for free here.)}

If you play these games, you'll soon notice two things:

• they're all the same game;
• it's not a very good game.

This is intentional. Cloak of Darkness is not so much an adventure game, as an adventure game sampler, or rather, as an Interactive Fiction Writing System demonstration/comparison sampler. Everything has been reduced to the bare essentials, so that comparisons between systems are feasible; but not to less than the bare essentials, so that it is still a realistic demonstration of both the pitfalls you might encounter in writing an adventure, and the possibilities the chosen system offers.

Thus, we have three rooms, one of which is dark but needs to be lit; one object which needs to be manipulated (and one non-standard verb which can, but does not have to be used on it); two scenery objects; and two endings, one winning and one losing. The only thing which is missing is moving, talking non-player characters.

The whole specification, and implementations in specialised IF languages for other systems, can be found at http://www.firthworks.com/roger/cloak/. This archive contains five implementations for the Sinclair ZX Spectrum, some documentation, and this text. This archive may be freely distributed as long as all files are kept together, and no money or other compensation is asked for it.

BASIC engine #1

We start where every Spectrum adventure programmer probably started: in BASIC. BASIC being a general programming language, there are many ways of writing an adventure in it, most of them bad. It is essential to keep to a system. Of course, there are also several possible systems. In this case, I have chosen - mainly because I have the book - that used in Peter Gerrard's "Exploring Adventures on the Spectrum 48K".

This system isn't perfect. To begin with, the parser is slightly buggy, which means that single-letter directions don't work, and "go" doesn't work (even with a full direction noun) despite being implemented. I have only debugged this until it actually worked - Cloak is meant to inform beginners, and a beginner would not be expected to debug a parser like this completely.

Also, not everything is elegant. The code sometimes jumps all over the place, error messages are not always helpful, and the game re-reads all data for every game. Location descriptions are kept in an array, which on the Spectrum either wastes a lot of space or requires unpleasantly short descriptions. And, of course, being BASIC, it's relatively slow. Still, as stands this Cloak is both solvable and losable. Nevertheless, I wouldn't recommend a beginner to use this system - or any other pure BASIC system.

The tape file for this system is CoD Gerrard.tzx, and CoD Gerrard.text holds the BASIC listing. Also on the TZX is a version that runs on a 16K Spectrum. This had to be hacked about a bit - all code is there but some text has been reduced, sometimes drastically. As the title of Mr. Gerrard's book suggests, for a real adventure this system won't work on a 16K. By the way, only the first three letters of any word (and with the broken parser, only words of at least three letters!) are recognised.

BASIC engine #2

The second system is BASIC assisted by machine code for the critical parts. For this, I've taken inspiration from a series of articles in ZX Computing magazine by Alan Davis (no, not the comedian, that's Alan Davies). First there was Realms of Interaction, which allows for independently-acting characters or monsters (think Gandalf and the warg in The Hobbit), but as it more or less required your game to be based on a grid, like Sorderon's Shadow or Davis' own Runestone, and as there are no other characters in Cloak of Darkness, it's neither suitable nor useful for us.

Davis' second project was Venturespeak, and this is much more like it. It allows for efficient input and parsing of a line of text, which is hard, tedious, space-guzzling and slow in BASIC. That's all it does, but it's a large improvement. A default vocabulary is suggested; I've used the verbs of this, but (because we have no use for them) not the nouns. Here, too, only the first three letters of a word are significant (but words of fewer than three letters work correctly).

His third series was Illuminator, which prints text, automatically formatted without breaking words, and if required with a four-character drop capital. This is not essential but does lend that air of professionalism, and the auto-wrap maked text output so much easier and can save a lot of space - by saving a lot of hand-formatting spaces. (Illuminator, by the way, by default takes up the same space in memory as Realms of Interaction, but as we're not using that anyway that's all right.)

The only great drawback of Illuminator is that while it can print on part of a line - allowing for decorated borders - the text will nevertheless scroll up the whole screen, using the normal Spectrum routine, thus messing up whatever decoration there was. Therefore, I've only used these borders on the introduction screen. Pity.

These machine code bits are called, in a neatly explained way, by a skeleton of BASIC code. This skeleton then calls all the action routines, where speed is not quite as important, and which can use whatever hacks the programmer deems necessary. In Cloak, I've kept the hackery to a minimum, using only the POKEs documented in the system articles, plus one from the Spectrum's own manual (to prevent a "scroll?" prompt).

The skeleton as written by Davis was truly minimal, and didn't even include location description, or any other kind of BASIC routine; it only demonstrated how to use the system itself. I've kept that (removing some details dealing with speech, which doesn't occur in Cloak), and added BASIC to do everything else.

This BASIC shows some other choices than the Gerrard system. For starters, it uses what I believe is a much superior way to describe locations, also used in some other BASIC systems: instead of a piece of data, a location description is a piece of code. This is both more space-efficient and more flexible; doors and such can easily be added to the relevant routine.

Less critically, it also uses a state for every object, allowing each to be, e.g., "worn", or "lit", instead of using a separate object for each state. This does have the advantage of not needing noun adjustment (see line 5300 in CoD Gerrard.text), but it's less flexible - you can't swap "a dark lamp" for "a lit lamp", it has to be "a lamp" and "a lamp (lit)". More a matter of taste, this choice.

As the Davis system doesn't include a Save Game routine, I haven't provided one, but one could certainly be written with not too much effort. I did write an Inventory command, and a few others, all of which are essential for Cloak, and none of which are particularly tricky. To keep to the brief (no advanced hacks), I haven't included any dirty POKEs to, e.g., change the Venturespeak prompt and colour; those are certainly possible, but not officially documented.

While I wouldn't actually recommend using this system to write an adventure, it is certainly a great improvement on plain BASIC. With a few modifications to the machine code, to make Venturespeak work within rather than along Illuminator, and to make Illuminator scroll only within its designated window, it could be even better. And of course it's flexible; you can change it about as you like, and make your program differ from any others, avoiding that "obviously written in the Quill/GAC/PAW" look.

The TZX is CoD Davis.tzx, and it contains the game, all necessary machine code and POKEd data as generated by Venturespeak and Illuminator and loaded by the program, and following that, the unPOKEd data to load into the Venturespeak editor, should anyone feel so inclined. (The new character set and capitals can be loaded into Illuminator as they are. By the way, you might find the character set oddly familiar yet not entirely so... it's a modification of my own making of the Spectrum ROM character set, with serifs added for legibility in text. Feel free to use it elsewhere.)

CoD Davis.text is the listing of the BASIC part, and CoD Davis vocab.text is the vocabulary as printed by the Venturespeak editor. Both Venturespeak and Illuminator themselves are available at World of Spectrum.

Adventure Builder System

There was going to be a version in Tom Frost's Adventure Builder System, but I couldn't get it to play nice with an object starting in your inventory and being worn, which is required for Cloak of Darkness. So ABS is out. In any case, it's (over)complicated to use, so I wouldn't recommend it to anyone starting out in interactive fiction programming in the first place.

There's also something called The Dungeon Builder, but that's a rather odd program more suitable, it seems, for building roleplaying dungeons than real interactive fiction; for starters, I can't even tell whether it handles darkness, which is of course a requirement for Cloak of, erm, Darkness...

The Quill

We now come to the professional, all-machine-code, full-editor systems. And of these, we begin with the earliest and most famous: Gilsoft's Quill. Famous for allowing anyone, for the first time, to write an adventure game which was actually publishable - and infamous for allowing anyone to publish a whole load of mostly-similar, not very good but still barely publishable, games. But despite all the slush, it is a proper system and some really good games were written in it, as well.

It also got some additions, later, for adding full-screen graphics (The Illustrator), then for making split-screen graphics and adding machine-code gimmicks like siren sounds (The Patch) and compressing text so more will fit (The Press). I've written a Cloak with only The Quill, because that fits in 16K (and you can, just barely, write a real, working, if excessively short, adventure in 16K with The Quill), and then I've gone on to add pictures with The Illustrator.

By the way, if you think the graphics for any of these games are rotten, don't blame the tools. I'm just a bad artist. The tools work, as demonstrated by many professionally-written games; it's just that creating decent adventure illustrations on the Spectrum is something some people can do, and some people can't. I can't. I do prefer The Illustrator's tools to GAC's, and PAW's graphics editor to both of those, but a real artist may reasonably disagree and stand a good chance of being right; in any case, all three do work for a beginner, which, as far as graphics are concerned, I am as much as anyone.

I've chosen not to use the Patch, because in use it is decidedly hacky and not suitable for beginners (thus, not within the Cloak of Darkness purview); whereas The Illustrator merely requires a cycle of Write Adventure; Load Adventure Data in Illustrator; Draw Pictures; Load Adventure Data again to Save Running Adventure With Pictures. The Patch, by contrast, requires all that and the addition of hacky, non-pausing PAUSE statements in the original code, plus a slightly trickier loading procedure. Doable, but not nice for the beginning IF writer. (As for The Press, it's not needed and the documentation seems to have gone missing.)

The Quill handles Cloak of Darkness reasonably well. Darkness is built into the system; the only thing that had to be special-cased for most verbs is scuffling the message in darkness. Removing and wearing clothes is also built-in, but putting the cloak on the hook is not, so that had to become a second object. Words are now recognised up to four letters. One drawback: word wrap is not automatic. You can insert tab characters rather than multiple spaces, but still.

CoD Quill.tzx contains first the program with pictures (which cannot be turned off, but only display on the first non-dark entry or LOOK); then the program without pictures, which will run on a 16K Spectrum; then the data file, as saved from and loadable into The Quill (C edition, by the way), and then the graphics file for use with The Illustrator.

There are two text files for this, not from the programs themselves but extracted by UnQuill and UnPaws); you may prefer one or the other's layout, but AFAICT only UnPaws extracts the graphics data. Oh, and yes, I'd recommend The Quill for beginners wanting to write a Spectrum adventure, but with the proviso that PAW is available, closely related, and better.

GAC

The next system is The Quill's only rival, as three years after its first arrival (two years after The Illustrator, and one year after The Patch) Incentive Software published the Graphic Adventure Creator, commonly and henceforth called GAC. It allowed split-screen graphics from the start (indeed, it doesn't allow any other sort), it allows for words to be recognised to whatever number of letters are necessary to distinguish them from other words, and in general it integrated everything that Quill, Illustrator and Patch did. (But not The Press; Essential Myth later wrote GACPAC.)

Personally, I find GAC less congenial than the Gilsoft programs, but this is probably a matter of taste. In any case, it is somewhat, but not much, more powerful of expression, and has no problem handling the Cloak scenario; the muddling-in-the-dark code is rather less ad-hoc here than in The Quill.

One thing which is not a matter of taste is that GAC has an unfortunate habit of mucking up spaces. In one place there will occur a space at the start of a line which shouldn't be there (you'll come across this in the Bar), and if you rid yourself of your coat, then look again in the Cloakroom, you'll see a missing space between a full stop and the next sentence. This is not my problem, and it is not even me being intentionally beginnerish; as many if not all published GAC games demonstrate, this is a real problem with GAC itself. To me, these missing and extra spaces stand out like a sore thumb; others may differ, but the problem, in any case, is there. Apart from that, word wrap is automatic.

The worst part about GAC, for me, is its manual. It is not, by a long way, up to the level of those for The Quill, let alone PAW. In fact, I'll go out on a limb and state outright that it's not good enough. A beginning programmer, in particular, is left to swim. There is also a GAC Adventure Writers Handbook which does remedy this slightly, but no more; and documents one real bug in GAC's IF statement, so make sure you do get that.

CoD GAC.tzx has the runnable game, followed by the code as loadable in GAC. There are text dumps from two programs for this, as well, Grackle and UnGAC; again, only UnGAC dumps the graphics code, but I prefer Grackle's format for the rest of the data.

PAW

And so we come to the final system: Gilsoft's answer to GAC, the Professional Adventure Writer a.k.a. PAW. It has everything The Quill plus all of its add-ons has, and more; and almost everything the GAC has, and better. The GAC allows for more locations - irrealistically in a 48K computer - and any length of word, whereas PAW only recognises five letters. (This did trip up people used to the Quill's four.)

As mentioned above, to me the PAW way of coding actions is more legible than the GAC way, but this may be taste. It is in any case very similar to, but an improvement on and extension of, the Quill way. And it handles Cloak of Darkness without even flinching. Even the blundering-about-in-darkness code is simple, because PAW, unlike Quill, allows for catchall code before, as well as after, the normal command handlers.

PAW also has adjectives (never used well, in any system), talking to NPCs (not used in Cloak), split-screen graphics of any size, not just GAC's fixed size, full-screen graphics if you must, and built-in support for alternative character sets, several if needed - very useful, what with the Spectrum's own unimpressive one. (The set used in Cloak is one that was supplied with PAW, by the way.)

Text is handled well, too. Like in GAC, word-wrap is automatic, although unlike in GAC and like in The Quill, you can insert tab (and now newline) characters if you want to. This saves a lot of fiddling. Punctuation is handled correctly, unlike in GAC. And crucially, PAW comes with a lot more standard verbs.

The advantage of PAW over any of the systems in this document is its manual. Or manuals, rather - a Technical Manual detailing what every built-in flag is for and how every bit of code works, and crucially, an Introduction which takes you through the process of creating your own starter adventure, complete with a dark location, two NPCs, and a picture. This is a great boon for a beginner - indeed, for anyone.

CoD PAW.tzx holds the game, and then the PAW code. The accompanying text file was made using UnPaws, as mentioned under The Quill; UnPaws can read and dump Quill programs, but UnQuill can't handle PAW games.

Of these systems, if for whatever reason someone wanted to start out writing interactive fiction for the ZX Spectrum, I would unhesitatingly recommend PAW. Not only is it certainly better than The Quill, it's also better than GAC, and of course beats writing your own from scratch, but the manual will give you a head start.