The Interactive Fiction Authoring System Developer's Guide (version 0.99, 2005-11-27), which is for programmers who want to create an authoring system for Interactive Fiction. Copyright © 2004, 2005 Peer Schaefer (peer@wolldingwacht.de).
The most recent version of this document is—without guarantee—available at http://www.wolldingwacht.de/if/if-auth-dev-guide.html. In the same place this document should available in alternative file-formats (PDF, Postscript PS, Info, HTML, plain ASCII-text, DVI, and Texinfo-source). If you have problems getting these files please contact me via peer@wolldingwacht.de or—if that fails—via peerschaefer@gmx.net or peer.schaefer@hamburg.de.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License”. (a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”
This document is not for authors of Interactive Fiction who want to use an authoring system to create Interactive Fiction; this document is for programmers who want to create an authoring system for Interactive Fiction—that is a system which allows authors of Interactive Fiction (a.k.a. “Text Adventures”) to write Interactive Fiction. In other words: this document is about writing a system like Inform1 or TADS2 (so, we're on a pretty abstract meta-level here). I will try to lay down the most important aspects that the developer of an authoring-system should consider, and the most important pitfalls she should avoid.
So, what qualifies the author of this document to write something substantial about the matter? Well, maybe not very much. Long time ago I wrote a very simple C compiler for the Amiga 500 and a cross-platform assembler for the i386 PC (generating code for the C-64, C-Plus/4 and Atari VCS 2600), and in the course of these projects I learned a little bit about compiler building. Or at least I think so. And I am playing Interactive Fiction for some years now. Some time in the past—before I learned that Inform and TADS are out there—I tried to write my own authoring system for Interactive Fiction. It took me about three or four months to realise that I had completely failed—and one month more to find enough courage to finally give up. In fact, I only just finished the user-interface and had no clue how to build a parser. In the end I learned much about the difficulties you step into if you persue such bold goal. Later I made myself familiar with Inform and TADS and learned a little bit by studying their inner functionality, with a focus on Inform. Currently I'm writing silly tiny adventures in Inform, but my small sparetime and my bad english prevent me from finishing anything worth publishing.
This document provides an advice and some extensive guidelines. The advice tries to prevent you from wasting your time. And the guidelines try to help you doing the job right. The target group of this document is propably very small, but maybe someone finds this document useful or instrumental in saving him much time.
Thanks to Roger Firth, Andrew Plotkin, Samwyse and Dan Shiovitz for their kind feedback and suggestions. I have taken freely from their replies. All errors and opinions remain—of course—my own. Thanks to Graham Nelson for Inform and Michael J. Roberts for TADS. And of course thanks to Will Crowther, Don Woods, Dave Lebling, Tim Anderson, Mark Blank and all the friendly girls and boys at rec.arts.int-fiction3.
I am always happy about feedback, both cheers and criticism (including corrections of my bad english) or just saying hello, so please feel free to contact me via peer@wolldingwacht.de or—if that fails—via peerschaefer@gmx.net or peer.schaefer@hamburg.de.
So, you want to write an Interactive Fiction authoring system? Ok, here's my advice: don't do it. At least, think twice about it. What's wrong with Inform or TADS? In what respect would your system be better? And is your point important enough to justify the effort? And after you've thought twice, think twice again. Inform and TADS are around and should suit your needs. Both may have some minor or major flaws in design and implementation. They are not perfect. But they are pretty good and almost bug-free. They have been intensively tested. They are well documented. They are very flexible. They have been ported to many different platforms. They are widely spread, well discussed and well known, so there is a good chance that some guy at rec.arts.int-fiction4 can help you with your programming problem. Many add-ons or contributions are available for both. Even if your brand new system would be twice as good as Inform or TADS, both Inform and TADS would still be ten times better documented, a hundred times better discussed and a thousand times better tested. So it's not only a matter of quality. Your system should provide some really new and cool features, or it would be totally pointless.
And if you have thought twice and then twice again, and you are still willing to create your own Interactive Fiction authoring system, I have another advice for you: Make sure that you have a huge amount of sparetime. You can not underestimate the time this project will take. If you have a job and a girlfriend5, cancel both (no, not really—that was a joke).
And one more advice: don't think that anybody will pay for your product. No exact numbers are known, but there are probably only a few tenthousand people worldwide who play Interactive Fiction, and there are only a hundred people or so worldwide who write Interactive Fiction. Since Inform and TADS are free and nobody gets money for writing Interactive Fiction,6 nobody will pay for an authoring tool.
I would also encourage reading the article “So you want to write a text adventuring authoring system...” by Alan Conroy in the XYZZY magazine issue #147. It is perhaps not strikingly brilliant but it is—as far as I know—the only report about developing an IF authoring tool that was written by someone who really did it (and wasn't just talking about it, like myself).
Think about what you want. What's wrong with Inform or TADS? What's missing or what's unsatisfying? Are the flaws important enough to write a complete new system? Maybe you could contribute to an existing system, either by providing a library add-on or by providing a patch to the compiler. Be careful and watch your motives. If you think that Inform or TADS are simply not elegant enough, and if that's the only point, than you are both right and wrong: right regarding the lack of perfect elegance in these systems, but wrong in thinking that this is a good reason to create a new system. It's not.
Instead make a list of all the reasons you have to write your own system. Put the list away for two weeks, then pull it out and read it carefully. Are you still convinced by your own reasons?
Make yourself familiar with
Read the manuals of Inform and TADS and learn each language. Write at least one small game in each language, e.g. a simple three-rooms-game with a small puzzle. Take a look at the many different implementations of the sample game Cloak Of Darkness10. Read the documentation for Inform and TADS, especially the technical parts and the chapters about the library and the world-model. Take a look at the sourcecode of the compiler and of the library-files.Design a language for writing Interactive Fiction. There are—at least—two very different paths you can take:
If you take option (b), you are very much on your own. Such radically new approaches have the advantage that your system doesn't have to compete directly with Inform or TADS, because it's totally different and has other design-goals and a different target group resp. audience. But it also has at least two drawbacks: first, there are no or at least very few prototypes or examples you can orient yourself; and secound, there is—from my point of view—nothing as flexible as a “traditional” programming language; every other approach will almost sure be more rigid and more restricted, resulting in somehow “limited” games. On the other hand, a symbolic approach or a graphical interface would be less intimidating to non-programmers; that could open up a complete new “market” and would make the authoring of Interactive Fiction possible for a completely new group of people.
If you take option (a), your language should provide some very nice and cool “gimmicks” that are real improvements compared to Inform and TADS. It seems that Inform and TADS have probably saturated the market for C/C++-like languages for Interactive Fiction; it's hard to imagine another one in the same image having much to offer, so your “gimmicks” better have to be really cool. Possible “gimmicks” would be e.g.:
In the process of language-design itself you should choose an existing language as a prototype. Start from that point and “modify” the language whenever and wherever required, so that it in the end suits your needs. As hinted above, I would recommend C/C++ as a starting point, because it's a generic all-purpose language, powerful, widely used and almost a standard for programming. Other fair choices would be Java, Pascal or a standardized object-oriented variant of BASIC. I would discourage scripting languages (e.g. Perl, Python) because they were designed for different purposes and wouldn't fit very well. I would also discourage “ancient”, seldom used or special purpose languages like Lisp, Fortran, Forth, Logo, etc. unless you have a very good reason, because they lack some of the more powerful constructs and concepts, or they are difficult to learn because they are so different from what people nowadays are used to and comfortable with. Almost anybody with some programming experience knows C/C++, so learning a C/C++-like language will be very easy for most people; using Lisp, Fortran or Logo will force 90% of your audience to learn a completely new language from scratch, which wouldn't promote the success of your system. On the other hand, a complete new approach—e.g. the use of Lisp or Logo—could result in complete new solutions to old problems. Maybe that justifies the trouble and effort necessary for learning a new language (or re-learning an “ancient” one), but the surplus has better to be large—or your approach will fail. Or maybe your “strange” choice drives off 90% of your adience, but the remaining 10% could be people that were not attracted by all the other C/C++-like languages (e.g. newbies oder professionals with different preferences or just another attitude).
If you have chosen a language, customize and modify it with your goal —a language for implementing Interactive Fiction—in mind. Here are some suggestions:
objectloop
).
boolean
) a native data/variable-type.
TRUE
to the parser”. That's a damn clever feature.
;-)
.
STDIO.H
. That's ok for an all-purpose-language like
C/C++, but not ok for a specialized language like yours. Make life simple
for you and for all programmers that will later use your language.
Develop a compiler for the language that you have designed according to Design a language.
Write the compiler in a widely used and standardized language that is available for many plaforms, at least for Windows, MacOS-X, and Linux/Unix. Write portable, good structured, well documented code. I suggest plain standard C (make sure that it can be compiled with gcc14). Using C would also allow you to use the Bison15 tool, which can ease the pains of compiler-building by automatically writing a code-parser in plain portable C for you that parses your self-designed source language. Other fair choices are C++, Java or Perl. I would discourage the use of any language that is not available for free (like Delphi) or not standardized (like BASIC).
The compiler should generate platform-independent code. Glulx runtime-code would be a good choice, because it's specifically designed for Interactive Fiction, well documented, and free (and interpreters are available for several platforms). Another fair choice would be runtime-code for the Java-VM16 or for the T3 Virtual Machine17. Other possible choices would include Java sourcecode, or Z-CODE18 (V5, V6 or V8). C/C++-sourcecode as output might be acceptable, but keep in mind that many players of text adventures haven't used a compiler in their lives (at least make sure that the code compiles with gcc), and distributing compiled binaries would make the game platform-dependend. Poor choices would be assembler/machine code, BASIC, Fortran, Forth, and other languages that are not portable, not standardized, seldom used, less powerful, out of date or not available for free. And there is really no point in designing a new runtime-format, unless you have a very good reason.
Write some library files in your language (see Design a language)
for use with your compiler (see Develop a compiler) that can
simply by included in the author's sourcecode via #include
or a
similar command. Write clean, nicely formatted, well commented code. The
library should provide two things:
The parser fetches the textual input from the player and translates it
into a computer-readable form. For example, the parser should translate
a player's command like "OPEN THE WOODEN DOOR WITH THE GOLDEN KEY"
into a data-structure that contains the following elements: the internal
ID for the OPEN
-action, the internal ID of the WOODEN DOOR
object and the internal ID of the GOLDEN KEY
object.
The parser should also handle placeholders like "ALL" or "IT" or "EVERYTHING", so that commands like "TAKE IT" or "TAKE EVERYTHING FROM THE TABLE EXCEPT THE BRASS LANTERN" are solved and the parser passes the right IDs of the right objects to the game. Maybe the parser has to colaborate with the world model (see Develop a world model below) to handle this, or the entire task has to be left to the world model; but these are intricate questions you have to make up by yourself.
See p. 1 and chapter IV of the Inform Designer's Manual, 4th edition19.
The world-model should provide some basic rules, for example that
you can only see something when there is light, that some things
(e.g. a bag) can contain other things, that you can't see or touch
things that are inside other things (except when the container
is transparent
or open
) etc.
The world-model should provide some default-behavior for all standard actions. For example, commands like TAKE or DROP should by default work as you might expect and should handle concepts like containment (inclusion inside of other things) and the “scope” (what you can see, touch and reach).
See p. 1 and chapter III of the Inform Designer's Manual, 4th edition.
Keep in mind that the biggest problem that an author of Interactive Fiction is confronted with is customizing the game, which means overriding, changing, and redesigning library behavior. I'm not just talking about “hacking the library” here. As Andrew Plotkin once said on rec.arts.int-fiction, every line of code in a piece of Interactive Fiction exists to customize the library—even the simplest object description is a customization of the default “You see nothing special”-response. So your library should provide many entry points on many levels to allow the author to customize the behavior of the library from within in the code of his game, without having to modify the library files themselves. Freedom is good, and options are good. The author should have the power to override pretty much everything, as and when he feels like it. Of course, not overwhelming the author with a forest of infinite detail is also good. Thus, the library should provide factory-equipped default values for (almost) everything, so that the author only has to mess around with that what is special about the particular player input, line of grammar, verb, action, room, object or NPC.
A typical entry point should be a variable that is defined in and
provided by the library (parser or world-model), which contains a pointer
to a function/routine. The
default value of the variable should be 0
(NULL
), signaling the library that the
default-behavior should
apply. But if the author provides his own function/routine and lets the
entry-point-variable point at it, the library calls that routine. If the
routine returns 0 as a return value, the
default-behavior still applies,
but if the routine returns some other value the library knows that the
routine has handled the matter, and the
default-behavior is suppressed.
The library should provide entry points at as many stages and levels as possible (parsing level, grammar level, scope determination, action-resolving, action-verification, object reaction, post-action, etc.). Examples for good entry points can be found in the Inform Designer's Manual at pages 412ff. and 431ff., and in the appropriate sections of the TADS Manuals20. But—of course—there is always room for more...
Write a piece of Interactive Fiction in your language, using your compiler and your library files.
Maybe it's a good idea to start with a small and simple game (two or three rooms with two simple puzzles, some furniture and at least one nice gimmick, e.g. a machine that does something). During the process of writing the game you will discover bugs in your compiler and in the library files. Correct them. But you will also notice some things about your language that are inconvinient or missing. Improve your language (and—in consequence—your compiler and/or library files).
Then write a large game (or let somebody write a large game and keep in touch with him closely). Some game that requires several hours to play through. For example, Inform was published together with the superb Curses21, and that was crucial for the success of Inform because Curses proved that Inform can really produce a really large game of some quality. Writing your large game you will propably run into difficulties. Improve your language, your compiler, your library files. Maybe you will run into serious difficulties. Well, take a deep breath, go ahead and redesign your system—parser, world-model, common library, language syntax—, and try again.
Write detailed and accurate specifications (reference manuals) for your language (see Design a language), your compiler (see Develop a compiler) and your library-files (see Develop a library).
Write an easy-to-read tutorial that introduces a new programmer with some basic programming knowledge to your language, the compiler and the library files.
Provide the reference manuals and the tutorial at least in PDF, Postscript (PS) and HTML-format. Maybe it's a good idea to use the Texinfo22-standard that can easily produce nicely formated PDF, PS and HTML output from one document-source. Using DocBook23 is also an option.
Don't publish your work now. Beta test it first. Inform two or three competent girls or boys from rec.arts.int-fiction about your project and ask them for a first beta-test. If they are interested, give them a FTP or HTML download location where your work is available for download. Let them test your compiler, your library-files and your manuals. Listen to them. Take them serious. Take their advices. It's much, much work, it's boring and it's a nuisance. But it's neccesary.
Upload your system to the IF-archive24 and announce it at rec.arts.int-fiction. Don't fall into any illusions; half of the work is still ahead you.
Prepare for a flame-war. The use of computer languages or development systems is a religious question, and there are many priests out there. Don't care about unpolite, unfriendly or unspecific criticism (“Your system sucks!”). But do care about criticism that points at specific aspects or makes specific suggestions (these should be the majority, since rec.arts.int-fiction is usually a friendly place with intelligent and helpful people).
Wait a few months. Monitor rec.arts.int-fiction. Monitor your mailbox. Does your authoring system have any audience? Is there a circle of at least a few users that use your system? If yes, keep on working on your system.
If nobody uses your system, if you are the only one who writes postings to rec.arts.int-fiction about your system, you should stop working now. You have wasted your time. Sorry, bad luck. Maybe your system is not good enough. Maybe your system has some fundamental flaws. Maybe your system is pretty good but doesn't provide any substantial improvements in comparison to Inform or TADS. Well, never mind. Hell, there is more to life than programming an Interactive Fiction authoring system. Keep your mood up and think about all the programming experience that you have made. Go fishing. Get a girlfriend25. And, of course—don't loose your interest in Interactive Fiction.
Send me an e-mail and tell me about your experiences and what you think about these guidelines. Correct my bad english. Thank you.
I think we can close with some conclusions:
Thanks to Roger Firth, Andrew Plotkin, Samwyse and Dan Shiovitz for their kind feedback and suggestions. I have taken freely from their replies. All errors and opinions remain—of course—my own. Thanks to Graham Nelson for Inform and Michael J. Roberts for TADS. And of course thanks to Will Crowther, Don Woods, Dave Lebling, Tim Anderson, Mark Blank and all the friendly girls and boys at rec.arts.int-fiction.
The most recent version of this document is—without guarantee—available at http://www.wolldingwacht.de/if/if-auth-dev-guide.html. In the same place this document should available in alternative file-formats (PDF, Postscript PS, Info, HTML, plain ASCII-text, DVI, and Texinfo-source). If you have problems getting these files please contact me via peer@wolldingwacht.de or—if that fails—via peerschaefer@gmx.net or peer.schaefer@hamburg.de.
Copyright © 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
This is some kind of general index, so don't wonder if you find persons, concepts, keywords and names all mixed up here.
The index is aimed to be complete regarding topics, not complete regarding references. Therefore, not every occurence of e.g. “TADS” in the text is referenced here, only those occurences that put TADS in the context of developing an authoring system (and e.g. not the mentioning of TADS in the preface).
STDIO.H
: Design a languageCreated using GNU Make 3.80
, Copyright (C) 2002 Free Software Foundation, Inc.; pdfTeX
(Web2C 7.4.5) 3.14159-1.10b, kpathsea version 3.4.5, Copyright (C) 1997-2003 Han The Thanh; Kpathsea is copyright (C) 1997-2003 Free Software Foundation, Inc.; TeX
(Web2C 7.4.5) 3.14159, kpathsea version 3.4.5, Copyright (C) 1997-2003 D.E. Knuth; Kpathsea is copyright (C) 1997-2003 Free Software Foundation, Inc.; dvips(k)
5.92b, kpathsea version 3.4.5, Copyright (C) 2001 Radical Eye Software.; makeinfo (GNU texinfo) 4.7
, Copyright (C) 2004 Free Software Foundation, Inc.
Created Sun Nov 27 21:13:41 CET 2005 using a Mobile Intel(R) Pentium(R) 4
running Ubuntu GNU/Linux(R) 5.10
(kernel 2.6.12-10-686).
[1] Inform: The Inform fiction
compiler by
Graham Nelson:
http://www.inform-fiction.org/
http://www.ifarchive.org/indexes/if-archiveXinfocomXcompilersXinform6.html
ftp://ftp.ifarchive.org/if-archive/infocom/compilers/inform6/
[2] TADS: The Text Adventure Development System by
Michael J. Roberts:
http://www.tads.org/
http://www.ifarchive.org/indexes/if-archiveXprogrammingXtads2.html
http://www.ifarchive.org/indexes/if-archiveXprogrammingXtads3.html
ftp://ftp.ifarchive.org/if-archive/programming/tads2/
ftp://ftp.ifarchive.org/if-archive/programming/tads3/
[3] The newsgroup about writing (authoring)
Interactive Fiction:
rec.arts.int-fiction
http://groups.google.de/groups?hl=en&lr=&ie=UTF-8&group=rec.arts.int-fiction
[4] The
newsgroup about writing (authoring) Interactive Fiction:
rec.arts.int-fiction
http://groups.google.de/groups?hl=en&lr=&ie=UTF-8&group=rec.arts.int-fiction
[5] Or a boyfriend.
[6] Peter Nepstad may be the great exception nowadays, since his “1893 - A Worlds Fair Mystery” scored some economic success. For details take a look at http://www.illuminatedlantern.com/1893. By the way: Peter Nepstad used the TADS authoring tool by Michael J. Roberts for creating “1893”.
[7] “So you want to write a text adventuring authoring
system...”, by Alan Conroy, in XYZZY magazine issue #14:
http://www.xyzzynews.com/xyzzy.14i.html
http://www.ifarchive.org/if-archive/magazines/XYZZYnews/XYZZY14.PDF
[8]
Glulx: The
Glulx virtual machine (standard) by Andrew
Plotkin:
http://www.eblong.com/zarf/glulx/
http://www.ifarchive.org/indexes/if-archiveXprogrammingXglulx.html
ftp://ftp.ifarchive.org/if-archive/programming/glulx/
[9]
Glk: Andrew Plotkin's
Glk API, which provides a
portable interface for text adventure systems:
http://www.eblong.com/zarf/glk/
http://www.ifarchive.org/indexes/if-archiveXprogrammingXglk.html
ftp://ftp.ifarchive.org/if-archive/programming/glk/
[10] The Cloak Of Darkness sample
adventure, written in many different languages:
http://www.firthworks.com/roger/cloak/
[11] XML, the Extensible Markup Language:
http://www.w3.org/XML/
[12] “Ladder-logic”:
http://en.wikipedia.org/wiki/Ladder_logic
http://www.google.com/search?hl=en&q=ladder+logic&btnG=Google+Search
[13]
Glk: Andrew Plotkin's
Glk API, which provides a
portable interface for text adventure systems:
http://www.eblong.com/zarf/glk/
http://www.ifarchive.org/indexes/if-archiveXprogrammingXglk.html
ftp://ftp.ifarchive.org/if-archive/programming/glk/
[14] gcc: The GNU
C/C++ compiler:
http://www.gnu.org/software/gcc/
http://www.delorie.com/djgpp/
[15] The GNU Bison parser generator:
http://www.gnu.org/software/bison/
[16] The Java(TM) Virtual Machine Specification:
http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html
[17] The Specification of the T3 Virtual Machine:
http://www.tads.org/t3spec/intro.htm
[18] Z-CODE:
http://www.ifarchive.org/indexes/if-archiveXinfocomXinterpretersXspecification.html
ftp://ftp.ifarchive.org/if-archive/infocom/interpreters/specification
[19] The
Inform Designer's Manual, 4th edition, by
Graham Nelson:
ftp://ftp.ifarchive.org/if-archive/infocom/compilers/inform6/manuals/designers_manual_4.pdf
http://www.ifarchive.org/if-archive/infocom/compilers/inform6/manuals/designers_manual_4.pdf
[20] The
TADS Manuals, by
Michael J. Roberts and
Eric Eve:
http://www.ifarchive.org/indexes/if-archiveXprogrammingXtads2Xmanuals.html
http://www.ifarchive.org/indexes/if-archiveXprogrammingXtads3Xmanuals.html
[21] Curses, by
Graham Nelson.
http://www.ifarchive.org/indexes/if-archiveXgamesXzcodeXcurses.z5
ftp://ftp.ifarchive.org/if-archive/games/zcode/curses.z5
[22] Texinfo: The GNU Texinfo system
for creating documentations:
http://texinfo.org/
http://www.gnu.org/software/texinfo/
[23] DocBook: an
XML/SGML vocabulary particularly well suited to books and papers about
computer hardware and software:
http://www.oasis-open.org/docbook/
[24] IF-archive: The central repository
for software related to Interactive Fiction:
ftp://ftp.if-archive.org/
http://www.ifarchive.org/
[25] Or a boyfriend (I'm repeating).