Category : A Collection of Games for DOS and Windows
Archive   : GAGS.ZIP
Filename : PART2.DOC

2-1


The Generic Adventure Game System
Copyright 1985 by Mark J. Welch


__________________________________
| |
| How to write an adventure game: |
|__________________________________|



-------------------------------------------------------
Introduction: Why Should I Write My Own Adventure Game?
-------------------------------------------------------

If you're asking that question, it's quite possible that you
shouldn't. But let me suggest a scenario:

- Imagine your office as an adventure game. Imagine the
wonderful descriptions you could provide for your co-workers'
offices, the analogies you could make for the delivery people,
and the thinly-veiled insults of your boss you could include. If
such an adventure game scenario were written in reasonable taste,
it could serve as a well-deserved diversion on a Friday
afternoon. Of course, if it's written in poor taste, and your
insults aren't veiled enough, it could be your last Friday.
- Maybe you are trying to teach someone something. Perhaps you
want them to learn about computers. Maybe you want to guide them
through many screens of tutorials. If you could write the text as
an adventure game, and make learning a game -- even fun -- the
game players might learn more faster.
- Or maybe you're well-equipped with a great imagination and
you want to develop a game that will rival the ones you've
bought in stores or played with friends. Perhaps this is your
chance to prove your fiction-writing abilities. Who knows what
adventure lurks in the heart of the computer user?



2-2

---------------------------------------------------------
How the Adventure Game Works -- A Superficial Explanation
---------------------------------------------------------

(This section explains how GAGS does what it does. You might want
to look at a copy of a .DAT file, such as UNDERGND.DAT, as you
read this.)


A Sequential Account
--------------------
As an author, I knew that anyone who developed an adventure game
using GAGS would want instant credit, so the first thing GAGS
does is look on the disk for a title file, which should contain
the name of the game, the author's name, and perhaps a copyright
statement. Each line in the file is displayed centered on the
screen.
Being protective, I also make sure the program posts my
copyright notice just below the game writer's. If, for some
reason, there is no file TITLE.DAT, the GAGS copyright
information is displayed by itself. The title screen, with the
author's information and mine, stays on the screen while the
program initializes all its data arrays and records and reads the
data file.
The program next reads the datafile (filename.DAT). It
searches each of its 17 keywords (words like "ROOM," "NOUN," or
"CREATURE"). When it finds one of these words as the first word
on a line (ignoring spaces and punctuation), it looks for a
number so it knows where to store the information that follows.
It then carefully analyzes each line that follows, updating its
internal arrays to match the specifications in the text file,
until it finds a keyword beginning with "END_" (i.e.
END_CREATURE, END_NOUN, END_ROOM). Note: the game will NOT
detect a mismatched END_keyword; all it really checks is that the
the first four letters are "END_".
Since the file contains both descriptions and data record
information, it takes a while to scan the whole file: for a 30K
file with about 65 rooms, it takes fifty seconds. Among other
things, this gives the player a good chance to read the title
screen, thus satisfying the game author's conceit and mine.
If the file contains some text preceded by the keyword INTRO
and ended with the keyword END_INTRO, that text is displayed as
it is encountered. It cannot be re-read during the game.
Once all the data has been read in, the program puts the
player into room 2 of the game (there is no room 1: a location of
1 indicates the player's pockets). GAGS then prints the long text
description for room 2, (defined by ROOM_DESCR 2...END_ROOM_DESCR)
and the player is asked what to do.

(continued)

2-3

(how GAGS works, continued)


Each time the player types in a command and , the
program sends the input line to the "parse" module. The parser
take the input line, breaks it into separate words, and tries to
locate a verb, a noun, a preposition, and another noun as the
object of the preposition. It does this by eliminating extra
words like "the" and "please"; and by checking and then
eliminating adjectives. It returns four words: verb, noun,
preposition, and an object of the preposition. (If any element is
missing, the "empty string" ('') is returned.)
If an invalid word is found by the parser, it informs the
user by suggesting what part of speech it sought and what word it
didn't recognize. Otherwise, the program then calls the execute
module; this section selects a procedure to call based on the
verb (throw, take, eat, move). Depending on the procedure's own
checking, the noun, preposition and object might be rejected as
invalid or, in some cases, ignored partly or completely.

If motion is called for, the program checks to see if the
direction is valid (i.e. if moving EAST was supposed to get the
player to a new room). If it's valid, the player is moved to the
new room; if not, the player is informed. Other actions are
checked in the same way: if a noun is expected, does the player
have it or is it in the room? If the thing is here, does this
time, place, and action constitute a special event of some sort?
If it does, the player is sent off to a "special" procedure;
otherwise the action is executed and the thing is changed as
specified, or is described or taken.

There are two ways a player can be moved to a new room. One
is by specifically trying to do so. Moving east is generally
accomplished by typing "EAST."
The other way to move is by meeting a set of special
requirements that the current game's author has defined as a
"special." The special might be defined, in plain language, as "if
the player is in the sauna, and he turns the faucet, then move him
to another room X." That other room might be anything. One
possibility is that it may be a room with a similar or identical
description, but with a new exit or without an old one. It might
even be the same room, but by executing the "special," the program
displays several lines of text.
In this case, the special text might be "You turn on the
faucet, and scalding hot water pours onto your feet. You scream in
agony and kick the faucet, which is turned off." If the author was
cruel, the "special" here might move the player to a new room
called "hell" and be told "As you turn the faucet, scalding hot
water pours out onto your legs. You scream in agony, but the faucet
won't shut off. In minutes, you are scalded to death. You awaken in
hell, where Satan tells you that your punishment for killing the
lizard [something the player did earlier to get here] will be
boiling in oil for eternity." The new room description would
describe a vat of boiling oil, provide no exits, and include the
keyword GAME_END to end the game.

(continued)

2-4

(how GAGS works, continued)


"Specials" are the way you do almost anything unusual. Of
course, a special can be used to move a player to a new room
(i.e. "touch mirror" might cause the player to fall through the
looking-glass and into a new room). But specials also allow a
room to be "changed" in the player's view -- this is accomplished
by actually moving the player to a new, but similar room. If you
want an airlock to close one door and open another, you use a
"special" which moves the player to a 'new' airlock with a
different exit. If you want a player to 'teleport,' you use a
special. If you want to player to be surprised by some action but
not moved (i.e. 'play stereo' could lead to "Beethoven's Fifth
plays loudly, awakening the neighbors. Someone pounds loudly on
the ceiling"), use a special.
There is one problem with using a special to "change" a
room. If you decide, for example, to have a player move from an
intact room to a damaged room when s/he decides to "push button,"
you may have some problems. Suppose the intact room was 13, the
damaged room was 14, and room 7 was adjacent. The player moves
east from 7 to 13. S/he pushes the button and is "specialed" to
room 14. S/he exits west to room 7, since you've provided that
exit from either room 13 or 14. When s/he moves east from 7,
however, s/he moves back to room 13, since room 7's pointers
remain unchanged by the "special." My fix to this is to simply
not provide reverse pointers: once you've blown up a room, make
sure the player can't ever trace his/her steps back to the
undamaged room.

Internally, specials are stored as a direction, and each
room that has a special has a "key" -- a matching noun. This is
probably the most complex part of creating an adventure game: you
need to have some fairly complex linkage in your data file, all
done manually.


2-5

How GAGS Works: Another Approach
--------------------------------

GAGS keeps track of three large record arrays internally: the
rooms, the nouns, and the creatures.

-----
Rooms
-----

Each room is a record, with the following fields:
name (string)
n,s,e,w,ne,se,sw,nw,u,d,enter,exit,special
(all integers: what room do they lead to?)
key (integer - what noun activates the 'special' direction?)
has_seen (true/false: has the player seen this room yet?)
locked_door (true/false - is there a locked door here?)
points (how many points for just getting to this room?)

The room specification in the data file is quite simple:

ROOM


.
.
.

< optional: SPECIAL and KEY >
< optional: POINTS >
< optional: LIGHT >
< optional: GAME_END >
END_ROOM

A room description must also be provided:

ROOM_DESCR
Some text, any number of lines, about the room.
END_ROOM_DESCR


(Similar formats are used for descriptions of nouns and creatures.)

It is recommended that at a minimum, one exit be provided;
otherwise the player will be stuck in the room until he quits. Of
course, that direction might be a special.


2-6

--------
Specials
--------
To 'activate' the special, the player must 'do something' to
the noun specified as the room's KEY. This can include turning
it, pushing it, pulling it, or playing it (depending on what can
be done to the noun as defined). If the proper action is taken on
the noun while in the room, the player will be relocated to the
room specified in the SPECIAL line and the SPECIAL nn text will
be displayed. (If the Special points to the current room, the
only effect apparent to the reader will be the display of the
SPECIAL text.)

An example:

--------

ROOM 13
.
.
SPECIAL 13
KEY 218
END_ROOM

NOUN 218
Stereo
.
.
TURNABLE
PLAYABLE
END_NOUN

SPECIAL 13
As you turn on the stereo, you hear a song by "Duran Duran." The
stereo turns itself off when the song is finished.
END_SPECIAL

-----------

Defaults: The default for almost all integer values is zero:
thus, any direction not specified will be set to zero (no room),
including 'special' and the key noun pointer, unless the data
file specifies differently.


2-7

-----
Nouns
-----

Nouns are necessarily more complex. They are specified in the
following format, listed with the possible values (and defaults)

NOUN
- must appear on second line, must be one word (underscores
permitted)
- must appear on 3rd line - a one-word adjective (or 'NO_ADJ')
- must appear on 4th line - one line of text describing the noun
(the remaining words and phrases may appear in any order or may be
omitted to obtain the default values)
WEIGHT - 1 to 100+ (default=1)
SIZE - 1 to 100+ (default=1)
LOCATION - initial location (room number, another noun, or the
player) (1=player) (default = 0)
READABLE - default is 'not readable'
CLOSABLE - default is 'not closable'
CLOSED - default is 'open'
ON - default is 'off'
PUSHABLE - default is 'not pushable' - activates special!
TURNABLE - default is 'not turnble' - activates special!
PLAYABLE - default is 'not playable' - activates special!
LOCKABLE - default is 'not lockable'
LOCKED - default is 'unlocked'
KEY - default is 0 (what noun is used to unlock this noun?)
POISONOUS - default is 'nonpoisonous'
EDIBLE - default is 'inedible'
DRINKABLE - default is 'undrinkable'
UNMOVABLE - default is 'movable' (can be TAKEn)
POINTS - default is 0 -- how many points if carried?
IS_LIGHT - default is 'false'
END_NOUN - this word must appear alone on a line!

Note: To 'spice' up the game, you might want to put things inside
other things initially, so the player has to open everything to
be sure s/he doesn't miss anything important. Be logical, though:
a refrigerator seems likely to be open-able, but a crabapple
probably ought to be 'closed' and 'unclosable' and thus unable to
contain something else (unless you're into razor blades...).


2-8

----
TEXT
----
Things that can be "read" are perhaps best described as
"special specials." Rather than using the "SPECIAL" function,
readable objects use "TEXT." Thus, the following would be a
valid set of definitions:

--------

NOUN 232
Book
Red
There is a small red book here.
WEIGHT 1
SIZE 3
LOCATION 32
READABLE
END_NOUN

NOUN_DESCR 232
The red book is quite thin, and has a hard cover. There is
writing on the book.
END_NOUN_DESCR

TEXT 232
The title of the book is "The Wisdom of Ronald Reagan."
The pages are all blank.
END_TEXT



----------
PUSH_DESCR
PULL_DESCR
TURN_DESCR
PLAY_DESCR
----------
If a noun is described as being pushable, playable, turnable, or
pullable, you can define a response to the player taking those
actions. This description will be displayed only if the player
takes the specified action AND that action does not activate a
SPECIAL for the current room. If there is no description
provided, a standard ("nothing happens") message is provided.


2-9

---------
Creatures
---------

Creatures, like rooms, are relatively simple. Any living thing is
identified as a 'creature', and can be either 'friendly' or
'hostile'.

CREATURE



LOCATION - default := 0
WEAPON - what noun kills it? (default := 0)
HOSTILE - (default is FRIENDLY)
END_CREATURE - must be the only thing on the line!

Friendly creatures are quite passive; hostile creatures are not
quite as friendly. It is recommended that provisions be made for
a weapon to kill any hostile creatures. For fairness, that weapon
should be accessible by the player BEFORE s/he meets the hostile
creature.
Players should be discouraged from wild and unwarranted
killing: i.e. they ought not kill friendly creatures. If no
weapon will kill the creature (i.e. if you leave or specify
WEAPON as the default value 0), the player cannot kill it. For
friendly creatures, you should not lead the player on by making
the weapon something unexpected: if the player kindly offers a
jelly bean to the friendly creature, it ought not be fatal. On the
other had, using a poisoned jelly bean to kill the Reagan_Beast
might be both appropriate and challenging. Only one weapon can
kill any given creature, but the same weapon might be used to kill
many creatures.

---------



2-10

Some last-minute notes:


Order of definitions:
Note: GAGS doesn't require that the definitions be in a
specific order. Definitions can be freely mixed throughout your
data files. You'll probably want to group items together that
logically belong together; that's how I wrote the sample game.
The order of definitions in the file has NO effect on game
performance, as long as each definition is properly structured.
If you write 'INTRO' text for the game, it's best to put that
text at the end of the data file; that way the initialization
will be done when the player finishes reading the introduction.
(If the INTRO text is at the top of the file, GAGS must read the
rest of the data file after the player has read the
introduction, causing a more noticable and worrisome delay.)


Word Processors:
Note: I used PC-Write to create the sample adventure file. You
MUST use a word processor which creates plain ASCII/DOS text
files with a true carriage return at the end of each line. Lines
longer than 80 characters, and WordStar document files, will
cause GAGS to gag! (For information on obtaining PC-Write, see
appendix D -- "Other Shareware.")

Value Ranges for Game Definitions:
Note: The following are the valid ranges of numbers for nouns,
rooms, and creatures. DO NOT assign improper numbers to any
category, or you will experience unpredictable (but consistently
erroneous) results.
Player: 1
ROOMS: 2 to 199
NOUNS: 201 to 299
CREATURES: 301 to 399

Note: The GameWriter Diagnostics Mode

GAGS has a "diagnostics" mode which should be somewhat
helpful as you develop games. By adding /d to the DOS command
line that invokes GAGS, you'll be able to see exactly what the
game is doing during initialization. If you compare a paper copy
of your .DAT file to the diagnostics screen output, you'll be
able to see exactly when and if the system encounters any
problems with your file. The diagnostics mode is specifically
designed to let you graphically see if any "END_" statements are
missing. It is not a very powerful debugging tool, but it takes
much of the guesswork out of the system.

(continued)

2-11

(Last-minute notes, continued)


Light and Darkness:
If a room has a LIGHT value other than 0 (the default), the
room will appear pitch black if the player wanders in empty-
handed. There are two "types" of lights and two types of
darkness. A noun may be defined as being a light by specifying
the word IS_LIGHT in its definition; in this case, it will light
any dark room defined as LIGHT 1. The light value of 1 in a room
definition means that any light will make the room visible. Of
course, these "general-purpose" lights must be turned on to light
the room, and thus all LIGHTs can be TURNed ON and OFF (or
LIGHTed and EXTINGUISHed.). (EXT is an acceptable abbreviation
for EXTINGUISH; EX is the abbreviation for EXAMINE.)
If the LIGHT value is more than 1 (i.e. LIGHT 218), only the
noun with the matching number will make the room's contents
visible. This is useful if the darkness comes from something
other than an absence of light: for example, a fan might be the
only object that makes a smoky room clear enough to see in.
A special-purpose light need not be defined as a light (i.e. it
doesn't have to be defined IS_LIGHT), nor does it have to be on,
to work as a light in a room with that noun as a LIGHT. A
noun can function as a special-purpose light for more than one
room, but each room can only be lit by one special-purpose light.
(A room with a LIGHT value of 1 will be lit by ANY noun defined
as IS_LIGHT.)


-----------

Note: Command abbreviations

Some command abbreviations have been implemented:

. = examine (i.e. ". bar")
! = attack (i.e. "! wolf")
ex = examine
ext = extinguish (turn off)



2-12

Creating a typical room:
------------------------

Let's suppose that my game contains a bedroom, connected to a
closet, a bathroom, and a hallway. In the bedroom are a lamp, a
bed, a dresser, a mirror, and a werewolf.

First, I want to define the room itself:


===============================================
ROOM 34
Master Bedroom
WEST 33 (33 is the hallway)
EAST 35 (35 is the bathroom)
NORTHEAST 36 (36 is the closet)
END_ROOM
===============================================

A description of the room is appropriate here:

===============================================
ROOM_DESCR 34
This is the master bedroom, where Mommy and Daddy usually sleep.
Plainly visible in the room are a bed, a dresser, a lamp, and a
large wall mirror. The room smells horrible, as if a large,
unclean animal had been here recently.
END_ROOM_DESCR
===============================================

Note that this description mentions the nouns that are
initially in the room. This is OK, since all of the nouns are
UNMOVABLE, but if they could be taken by the player, they should
not be described in the room description since they won't be
there if the player should return.

That werewolf is begging to be described, too:


===============================================
CREATURE 315
Werewolf
Black
There is a menacing black werewolf here.
LOCATION 34
WEAPON 217 <-- Noun 217 will kill it
HOSTILE <-- ever met a friendly werewolf?
END_CREATURE
===============================================

===============================================
CREATURE_DESCR 315
The werewolf is about the size of a small horse. Its matted fur
stinks, and a sickening smell emerges from its open mouth,
through which you can see sharp, large teeth.
END_CREATURE_DESCR
===============================================

2-13

Finally, each noun within the room ought to be defined and
described:

===============================================
NOUN 220
Bed
Large
There is a large (king-size) bed here.
LOCATION 34
UNMOVABLE
END_NOUN
===============================================
NOUN_DESCR 220
The bed is quite ordinary.
END_NOUN_DESCR
===============================================
NOUN 221
Dresser
Wooden
There is a large wooden dresser here.
LOCATION 34
CLOSABLE
CLOSED
UNMOVABLE
END_NOUN
===============================================
NOUN_DESCR 221
The wooden dresser looks pretty much like most wooden dressers.
END_NOUN_DESCR
===============================================
NOUN 222
Lamp
Small
There is a lamp on the dresser.
LOCATION 34
UNMOVABLE
END_NOUN
===============================================
NOUN_DESCR 222
The small table lamp is pink and has a green shade.
END_NOUN_DESCR
===============================================
NOUN 223
Mirror
Strange
There is a wall-size mirror here.
LOCATION 34
UNMOVABLE
END_NOUN
===============================================
NOUN_DESCR 223
As you gaze into the mirror, you sense something unusual about
it. It seems to shimmer, and your reflection seems somehow
unreal, as if the mirror weren't really there at all.
END_NOUN_DESCR
===============================================

2-14

Hmm. That mirror seems rather interesting. Maybe we could make
a "special" out of it. For example: when the player touches it,
s/he is sent to room 50, the mystic cavern of the Wizardess.
To do so, we need to add a "special" to room 34 and specify the
mirror as its key, and we need to make the mirror touchable.
(Note: "touch" and "push" are synonyms -- you should use the
word "push," not the word "touch," in your definitions.)

===============================================
ROOM 34
Master Bedroom
WEST 33 (33 is the hallway)
EAST 35 (35 is the bathroom)
NORTHEAST 36 (36 is the closet)
SPECIAL 50 <--
KEY 223 <--
END_ROOM
===============================================

===============================================
NOUN 223
Mirror
Strange
There is a wall-size mirror here.
LOCATION 34
UNMOVABLE
PUSHABLE <-- Here's how we'll activate the special
END_NOUN
===============================================


The player will see room 50's description when s/he gets
there, but the SPECIAL text for room 50 will be displayed first:


===============================================
SPECIAL 50
You reach out to touch the mirror, and are shocked to find that
your fingers vanish through the surface. Before you can react,
you feel yourself drawn forward through the mirror, and into a
black nothingness. You look back to try to see the mirror, but
everything is black.
You are falling, but not very quickly -- it's almost as if you
are floating. As you fall, your eyes begin to adjust to the
darkness. Then, suddenly, you land on a soft cushion of some
sort. As you rest on the cushion, your eyes adjust to the very
dim light of this new room.
END_SPECIAL
===============================================

(Note that usually, you'd want to have a PUSH_DESCR prepared
for when the player touches a noun when it doesn't activate a
special, but the mirror can't be moved so it will always
activate a special when touched.)


2-15

How to include Comments:
------------------------

Within your data file, you'll probably want to include
comments which won't be processed by the game itself, so you'll
be able to understand why you did certain things.

In general, GAGS treats anything it doesn't understand as a
comment. Thus, if you have a paragraph of text in between
definitions, GAGS will usually ignore it.
BEWARE: If one of the lines in the paragraph begins with a
keyword like "noun" or "text," GAGS will probably decide that
it's the beginning of a definition and get confused.
To avoid this, you can use a nonsense word to start each line
of a comment: words like "REM" (for remark) are useful since they
also clearly state what the line is.
Gags ignores most punctuation completely, so using "comment"
indicators like "(*" and "*)" or { and } won't help anything.
GAGS usually only sees alphabetic characters ('a'..'z' and
'A'..'Z').
You can put comments on lines which contain a keyword or a
keyword and a number; don't include comments on lines which
contain a full-line description.

Example of properly-commented definitions:

===============================================
ROOM 34
Master Bedroom
WEST 33 (33 is the hallway)
EAST 35 (35 is the bathroom)
NORTHEAST 36 (36 is the closet)
SPECIAL 50 <-- Special goes to room 50 (cavern)
KEY 223 <-- Spec.activated by touching mirror
END_ROOM
===============================================

===============================================
NOUN 223
Mirror
Strange (isn't there a better adjective?)
There is a wall-size mirror here.
LOCATION 34 (in the Master Bedroom)
rem: the player finds this mirror in the master bedroom,
rem: and gets to the Cavern by touching it. The player
rem: can only return if s/he has the magic amulet, and
rem: will need the soap from the bathroom to kill the
rem: demon on the bridge.
UNMOVABLE (not very useful if the player can take it!)
PUSHABLE <-- Here's how we'll activate the special
END_NOUN
===============================================

2-16


Example of a badly-commented definition:

===============================================
ROOM 34
Master Bedroom
WEST 33 (33 is the hallway)
(If the player decides to enter the bathroom to the
west, s/he will find the 32 gold pieces.)
EAST 35 (35 is the bathroom)
NORTHEAST 36 (36 is the closet)
SPECIAL 50 <-- Special goes to room 50 (cavern)
KEY 223 <-- Spec.activated by touching mirror
(The player gets to the mystic cavern by means of a
key special, activated by noun 233)
END_ROOM
===============================================

In the above example, the second full comment line begins with
the keyword "WEST" and contains the number 32, so GAGS might
decide that WEST should lead to room 32, changing the game! The
last line before the END_ROOM could confuse GAGS and redefine the
key number (probably to zero).



-30-








REFERENCE MANUAL

for the

GENERIC ADVENTURE GAME SYSTEM



by

Mark J. Welch


September 1, 1985



Copyright 1985 by Mark J. Welch

All Rights Reserved


_____________________________________________________________
| |
| The Generic Adventure Game System, in all source code and |
| object code formats, and all related documents, are copy- |
| right 1985 by Mark J. Welch. The Generic Adventure Game |
| System is distributed as Shareware, with restrictions as |
| specified in the documentation. Commericial use without |
| prior written permission is prohibited. |
| GAGS is distributed as Shareware: if you like the |
| program, please become a registered user by sending $15 |
| to the author: Mark J. Welch |
| P.O. Box 2049 |
| San Francisco, CA 94126-2409 |
| 415-982-4591 (voice) |
| 415-391-9148 (modem) |
|_____________________________________________________________|


R-1


Introduction to the GAGS Reference Manual
-----------------------------------------

This document describes the precise syntax and rules for the data
files relating to the Generic Adventure Game System (GAGS). Two
data files are associated with each game: filename.DAT and
filename.TTL.


filename.TTL: The Opening Screen(s)
--------------------------------

The file filename.TTL is not "inspected" by GAGS in any way. The
game program merely reads the file line by line and echoes it to
the screen, pausing if the screen fills. (You might need to
experiment with spacing if the "More" prompt obscures sections of
text or graphics.)

While any ASCII or IBM characters can be used -- including
some control characters -- use of non-ASCII characters is not
recommended if you believe the game might be used by people who
do not have IBM-compatible systems. Note that Control-Z (a value
of 26) is the end-of file character, so don't embed this
character in your text.

If you want your game to be covered by standard copyright
protection, include the statement "Copyright by " in
the opening screen, and provide a mailing address. The GAGS
copyright notice, for the game "engine," will also be displayed
after your opening screen.


filename.DAT: The Main Data File
------------------------------

Needless to say, filename.DAT is the file that takes all the work,
and this reference manual is devoted to the syntax of that file.


Classes: NOUNs, ROOMs, and CREATUREs
------------------------------------
There are three classes of "things" in the game: NOUNs, VERBs,
and CREATUREs. Each object defined must have a separate
definition and description. Other specifications may pertain to a
room or noun, as described in the precise syntax.



R-2

Structure of the .DAT file
--------------------------------
(A more formal syntax)

The .DAT file consists of a set of definitions.

Each definition is one of the following types; each type is also
the introductory keyword of the definition:

NOUN ROOM CREATURE INTRO
NOUN_DESCR ROOM_DESCR CREATURE_DESCR
TEXT SPECIAL PULL_DESCR
PLAY_DESCR PUSH_DESCR TURN_DESCR

Each definition is ended by a word beginning with the the string
'END_' (i.e. 'END_NOUN'). NOTE: While it is advisable to use
matching keywords, GAGS only checks for the initial characters
'END_' and not for the complete appropriate end-of-block keyword.

Comments: Any text which occurs outside a definition is
considered a comment and is ignored. In addition, unknown words
*within* a defintion are *usually* ignored as well. However, to
avoid unpleasant surprises, it is recommended that a known
nonsense word ('rem' or 'comment') be used at the start of all
comment lines.


DESCRiption types:
------------------

Each description type consists merely of lines of ASCII text
which are echoed to the screen when the user expects a
description of something defined in the game.

If the file contains the following lines:

NOUN 2
Globe
Red
.
.
.
END_NOUN

NOUN_DESCR 2
The small red globe is a perfect sphere. It glows
slightly.
END_OF_NOUN

NOUN_DESCR 3
The towel is about eighteen inches wide by twenty-four
inches long, and is quite soft.
END_NOUN

The result of a player typing 'examine globe' would be:

The small red globe is a perfect sphere. It glows
slightly.


R-3


NOUNs
-----

NOUN nnn <-- nn is a number from 201 to 299
Name <-- one-word name of the noun
Adjective <-- one-word adjective
Short description of the noun
REM ^-- a one-line description of the noun
{other characteristics go here}-
END_NOUN

Other characteristics (optional):

SIZE nn <-- nn is a number from 1 to 99+
WEIGHT nn <-- nn is a number from 1 to 99+
UNMOVABLE <-- default is movable (carryable)
LOCATION nn <-- nn is a room number (1-199)
READABLE <-- default is "not readable"
{if READABLE then
must also be defined}
CLOSABLE <-- default is "not closable"
CLOSED <-- default is "open"
{if open then it can hold
something}
LOCKABLE <-- default is not lockable
LOCKED <-- default is unlocked
KEY nn <-- default is 0
{noun nn unlocks this noun
if it's lockable}
EDIBLE <-- default is inedible
DRINKABLE <-- default is undrinkable/solid
POISONOUS <-- default is nonpoisonous
{predictable effect if poisonous
edible/drinkable noun is eaten}
ON <-- default is 'off'
PUSHABLE <-- default is not pushable
{PUSH_DESCR nn recommended but
not required if it is pushable}
PULLABLE <-- (ditto, PULL_DESCR nn)
PLAYABLE <-- (ditto, PLAY_DESCR nn)
TURNABLE <-- (ditto, TURN_DESCR nn)
IS_LIGHT <-- default is NOT is_light
(IS_LIGHT -> illuminates any room
defined as LIGHT 1 or LIGHT nnn
where nnn is the noun number)
POINTS <-- default is 0 (points awarded to player
if object is held at game_end)
CAN_SHOOT <-- default is can't shoot (can the
weapon be used to shoot a
creature? if not, it must be
thrown)
NUM_SHOTS <-- default is 0 (how many bullets/
charges are there initially?
decremented each time the noun is
fired.)


R-4


ROOMs
-----
The syntax of a room definition:


Required:

|<-----significant----->|<------ignored------------------------>|
|

ROOM nnn <-- nnn is a number from 1 to 199
Room Name <-- room name (no comments!)
{other characteristics}
END_ROOM


Optional characteristics: <-- optional but at least one is
strongly recommended

|<-----significant----->|<------ignored------------------------>|
|

{direction} nnn <-- nnn is a number from 1 to 199
(default is 0)
{any one of 12 directions can be
specified, from the list:
NORTH NORTHEAST UP
SOUTH SOUTHEAST DOWN
EAST NORTHWEST ENTER
WEST SOUTHWEST EXIT}
SPECIAL nnn <-- optional, nnn is a room number.{If
present, the current definition
must include KEY xxx and there must
be a SPECIAL nnn definition}
KEY xxx <-- xxx is a noun number (201-299)
{activates special nnn}
LIGHT xxx <-- xxx is a noun number (201-299)
OR the value 1 ("any light")
{default is 0}
POINTS xxx <-- xxx is number of points player is
awarded just for getting here.
Default is 0.
GAME_END <-- if this line is in the def, the
game ends as soon as the player
enters the room (the room_descr
is displayed, then the score).


R-5

CREATUREs
---------

Required:

CREATURE nnn <-- nnn is a number from 301 to 399
Name <-- one word name
Adjective <-- one word adjective
Short description of creature.
^-- a one-liner
{optional characteristics}
END_CREATURE


Optional:

LOCATION nn <-- nn is a room number from 1 to 199.
{default is 0}
WEAPON nn <-- nn is a noun number from 201 to 299
{default is 0}
{noun nnn kills this creature}
HOSTILE <-- default is friendly
THRESHHOLD n <-- {n is number of times monster can be
unsuccessfully attacked before it
kills the player - default 3}



NOTE: A player cannot exit a room containing a hostile monster.
When killed, creatures are relocated to LOCATION 0. Currently,
friendly/non-hostile creatures have no effect on the game's outcome.





SPECIALs
--------

If a player properly accesses the KEY to a SPECIAL, by acting on
it in the proper ROOM in a defined manner (PLAY, PUSH, PULL,
TURN), the player is relocated to the room specified in SPECIAL
nn within the room definition, and the text defined in the SPECIAL nn
definition is displayed. In reality, if the entry SPECIAL nn
within the original room definition points to the same (current)
room, the player will not actually be moved anywhere, and the
only effect will be to display the SPECIAL text, which is
arranged like the '_DESCR' texts. (If the SPECIAL is activated, the
TURN_DESCR, etc. text is NOT displayed.)

R-6

TEXT:
-----

TEXT is like the '_DESCR' texts, except that it is displayed only
when a noun is 'READ' by the player.



Page Pauses
-----------
Normally, the game pauses after every 22 lines of text (so that the
player can read it), and the player then hits to read more. As you
play-test your game, you might try to adjust your paragraph or line
spacing so that the page breaks don't come at awkward spots and confuse
the player. This is probably most important in the title screen and the
INTRO text; it is less controllable in the individual room descriptions.


PLAY, PUSH, PULL, TURN:
-----------------------
If a noun is defined as playable, pushable, pullable or turnable
and the player attempts to do so, the relevant '_DESCR' text is
displayed. If the action is valid but there is no accompanying
text, the player is informed that nothing interesting happens.
EXCEPTION: if the specified action fulfills the current room's
requirement for a SPECIAL, the push/pull/turn/play text is NOT
displayed, and the SPECIAL nn text is displayed instead for the
room the player is "moved" to.

Note: While "touch" is a synonym for "push" within a game, TOUCH
is NOT a keyword in a .DAT file. Use PUSHABLE and
PUSH_DESCR, not TOUCHABLE or TOUCH_DESCR.


INTRO
-----
The introductory text is displayed during the game's initialization
and cannot be re-read later. It also cannot be skipped over. It is
recommended that the INTRO text be put at the end of the data file since
it is displayed as it is encountered during initialization (locating it
at the top of the file would result in a long delay AFTER the
introduction and long after the initialization delay message has
vanished).



LIGHTs and darkness
-------------------
If a room has been defined with a LIGHT value other than 0, it will
appear dark if the player enters the room empty-handed. If the LIGHT
value is 1, any noun serving as a light will make the room visible
(provided that the noun has been turned on). If the LIGHT value is a
number from 201 to 299, the room will only be visible if the player is
carrying that noun (it need not be turned on).


R-7

EATing, DRINKing, and dying
---------------------------
Any object defined as EDIBLE can be eaten. Any object defined as
DRINKable can be drunk. And any object defined as POISONOUS will kill the
player if s/he eats or drinks it. POISONOUS has no effect if the noun is
neither edible nor drinkable. In most situations, it is considered poor
sport to make completely non-threatening and logically edible things
poisonous; it is likewise questionable to make packages of rat poison
edible but non-poisonous.


WEIGHT and SIZE
---------------
Those values are there for a reason. No player can lift an object
heavier than 100, even if it's defined as MOVABLE. Likewise, objects
larger than 100 are too awkward to be carried. The total weight the
player can carry is 100, so the player cannot carry two 60-weight objects
at once. Total size limit is also 100. It is considered poor sport to
assign large weight values to feathers and low values to large slabs of
steel, but cruel gamewriters are able to do so. Likewise, a game will be
less baffling if small objects (pens, tin cans) have small size values
and large ones (desks, cars) are larger.
(Remember, of course, that if your scenario puts the player in the
role of King Kong or Godzilla, you'd want to scale everything down so
s/he might be able to easily carry six cars and a bus but have difficulty
with more than one fully-loaded semi or house.)



SCORE (POINTS)
--------------
The player's progress in the game is reported in two ways: the number
of rooms visited, and the number of points currently held. The player
receives the defined number of points for visiting each room (default
point value is 0), and for carrying each noun when scoring is done
(default is 0). Players get no points for having eaten something, since
objects which are eaten or drunk are removed from the game. There is no
facility to reward the player for eating or punish the player for not
eating.
For best results, it is best to assign a point value to each room
which the player arrives at after solving some puzzle. It's also wise to
award a few points for out-of-the-way rooms. Objects should only have
point values if they can reasonably be expected to be carried at the end
of game -- if an object is too heavy to be lifted, it's not logical to
assign it a point value. Also, make sure that the total weight and size
of the point-valued objects doesn't exceed 99, since the player can't
carry that weight.