Title: An introduction to ADVSYS

Author: Martin Moene

Date: 17 June 2010 08:56:00 +01:00 or Thu, 17 June 2010 08:56:00 +01:00

Summary: An introduction to this fascinating adventure writing system.

Body: 

ADVSYS is an adventure writing system - a language compiler and interpreter dedicated to writing text adventure game programs. It was written by David M Betz of Manchester, NH, and placed in the public domain for unrestricted non-commercial use.

The system consists of compiler and interpreter programs. The compiler operates on your game source code to produce a data file. This is a packed binary file at which the game user can't usefully peek. Your game consists of the data file, plus the interpreter program with which the user `plays' it.

ADVSYS is written in C. The portability of C is crucial to ADVSYS, which itself takes portability a stage further. Because ADVSYS can work on any computer for which a C compiler is available, a game produced using ADVSYS can be played on any such computer. The game source code simply needs to be run through the ADVSYS compiler on the target machine, and then teamed up with the ADVSYS interpreter for that machine. As well as making it possible to write a program that will run on virtually any computer, ADVSYS relieves the game programmer of all low-level instructions and machine dependencies.

Programmers can put maximum effort into the creative aspects of adventure programming: the objects, locations, and actors, and the way they interact. A further benefit of ADVSYS is that it provides game authors with a standardised framework for them to communicate on aspects of game programming. This could encourage people to try their hand at writing an adventure and may possibly lead to the growth of public domain adventures and co-operative efforts.

Sample ADVSYS code

To give you a quick overview of the ADVSYS language, here's a typical fragment of game source code:

(location storage-room
(property
    description "You are in a small storage room
                 with many empty shelves. The only
                 exit is a door to the west."
    short-description "You are in the storage room."
    west hallway)

(method (leave obj dir)
    (if (send obj carrying? rusty-key)
       (send-super leave obj dir)
       (print "You seem to be missing
               something!\n"))))

This code defines an object of class location, called storage-room. (Assume that we have already defined what a location is.) Its properties include long and short descriptions and the direction of the adjacent location.

It also has a method, a routine to be executed whenever the system sends that location a particular message. In this case the message is leave.

Elsewhere in the program we will have defined under what circumstances the message leave will be sent to a location. Here we have to define what happens when this location receives that message. We want to prevent the actor leaving the location without carrying a particular object, the rusty key.

The message brings with it two parameters: the identity of the object that is leaving (this will be an object of class actor), and the direction of travel. Because this location has no directional properties other than west, ADVSYS will prevent the player from leaving in any direction other than west.

The line

(if (send obj carrying? rusty-key)

sends to obj (the actor) a message called carrying? and the parameter rusty-key. We will have defined the method carrying? for the actor object as returning a TRUE when the actor is connected to the object named in the parameter. Thus, this IFstatement will be TRUE if the actor is carrying the rusty key. You can see that ADVSYS, like C, allows well-written programs to be terse yet self-documenting.

The next two lines

(send-super leave obj dir)
(print "You seem to be missing
        something!\n"))))

are the actions to be taken on the IF statement returning TRUE and FALSE respectively.

The send-super statement sends a message up the class hierarchy to the parent class of the current object. In this case the current object is the storage-room and its super-class is the location class of objects. In the definition of location we will have defined a generalised method for leave, which will disconnect the actor from its current location and connect it with the adjacent one.

Thus the effect of this code is that when the player types W, provided he has taken the rusty key, the game responds `You are in the hallway.' Nine lines of code needing eight paragraphs of explanation is, I think, typical of both ADVSYS and C. It's clear that although ADVSYS offloads the `grunt work' from adventure programming, this doesn't mean you will be able to write the adventure of your dreams in five minutes. Even the fundamental object classes actor and location aren't built-in, but must be defined by the programmer.

You define each class of object, then go on to define particular instances of that class. The instances may have their own properties and methods, in addition to those inherited from the parent class. C programmers, familiar with hierarchical structure definitions, will have no problems with this.

ADVCOM features

Adventure definition files (MYPROG.ADV) are ASCII text files, written using the editor of your choice. They are compiled to data files (MYPROG.DAT), which contain an internal name and version number used by the game's Save and Restore features.

The familiar-looking @include statement instructs the compiler to include another file. The ADVSYS language is highly simplified. The statements available are minimal and the syntax makes no concessions to English. It is LISP-like, with `lots of irritating single parentheses'. Many C programmers will be familiar with editors that have special features to deal with parentheses. For example, the Megamax C editor can find the corresponding opposite of a selected brace or bracket. This feature is extremely useful for ADVSYS.

Operations include integer arithmetic and comparison, Boolean and bitwise logical functions, and random numbers. User-defined functions are supported with arguments, return values, and local variables.

Control constructs include conditional execution, if-then-else, and conditional iteration. Block structures can be defined.

In strings, end-of-line is treated as a space, and multiple spaces are collapsed into one. The special character-pairs \n, \t, and \\ have the meanings expected by the C programmer. For I/O, there is a print statement which provides the plain-vanilla terminal needed by a text adventure. (The line width of the terminal is a compiler option so that it can be set to suit the target machine.) All user input is via the parser, which sets the game variables with the objects to be manipulated and the actions to be performed. The programmer's only other access to what the user actually typed is the yes-or-no expression, which returns TRUE if the player typed a line beginning with Y or y.

Save and Restore are built-in functions. They prompt the user for a filename, and save or load the game's data area. Restore checks that the file selected by the user corresponds to the adventure name and version being played.

ADVINT features

From the game player's viewpoint, the most obvious features of ADVINT are (of course) those programmed by the game author. ADVINT itself stays in the background. You primarily need to write five handler definitions: INIT, UPDATE, BEFORE, AFTER, and ERROR. The handlers control game activity and form the game's personality. UPDATE, BEFORE, and AFTER are called in sequence with the parser to form the main loop of the game.

The UPDATE handler prepares for the player's next turn, and should describe the player's location if it has changed since the last turn.

The parser is then called. It prompts (:) the player for a command in any of the following formats:

[actor,] verb
[actor,] verb dobjects
[actor,] verb dobjects preposition iobject
[actor,] verb iobject dobjects

It parses the command and sets the variables $ACTOR, $DOBJECT (the first direct object), $NDOBJECTS (the number of direct objects), $IOBJECT (indirect object) and $ACTION. These variables are used by the handlers. The BEFORE handler is called before the action requested by the command, to inspect the parser variables before proceeding to the action itself.

After the BEFORE handler completes, the action itself is called (or whatever action is stored in the built-in variable $ACTION when the BEFORE handler completes). When the action completes, the AFTER handler is called to handle events that happen only at the end of a successful turn. The ERROR handler is called when the parser detects an error.

Availability

The C source code for the compiler and interpreter, together with the system documentation and a small sample adventure, are available from public domain sources such as CIX (and Chronosoft BBS, see back page for details. ED). Executable programs for various computers are starting to appear too.

The compiler source code amounts to 53K, the interpreter 40K.

However, the total to download is only about 50K (including the sample adventure) because the files are ARCed. In executable form on my machine (an Atari ST) the compiler is 27K and the interpreter 22K. The system documentation is a separate file of 30K.

The C code of ADVSYS appears to have been written for an IBM-PC, with compiler options (#ifdef MAC) for a Macintosh. I was intrigued as to whether I could compile the programs on my Atari ST using Megamax C.

In fact, ADVCOM compiled and linked successfully with no modifications at all. For ADVINT it was necessary to change a number of bdos(x) calls in ADVTRM.C which perform character I/O. I substituted various Atari BIOS calls until the terminal behaved properly. However, I discovered from info posted on CIX that it's possible to directly substitute Atari gemdos(x) for IBM bdos(x) calls.

From CIX I also obtained info on several bug fixes, and much other useful stuff that originated on BIX in the US.

With six or seven source files to compile and link I found the Megamax Make function most useful and time-saving. I was extremely pleased to find that I could compile and play the sample adventure on my ST.

There is a conference on CIX dedicated to ADVSYS, for users to swap experience, hints and tips. The download area contains the ADVSYS source code and several executable programs. No doubt in the near future some additional public-domain game source code will appear here.

The possibility exists for more than one programmer to work simultaneously on different parts of a large adventure, and there is word of a possible UK-vs-US challenge to produce the best ADVSYS-based adventure! If there is sufficient interest I shall be pleased to contribute further ADVSYS reports to "C Vu".

Details of how to contact Martyn can be found on the back page, with your questions, suggestions, etc. We look forward to hearing more about ADVSYS in future issues -- ED.

Notes: 

More fields may be available via dynamicdata ..