4.1cBSD/usr/src/games/ddl/doc/doc.ms

Compare this file to the similar file:
Show the results in this format: 

.RS
.ds CF "\(co 1981 UCLA Computer Club
.TL
A Brief Description of UCLA
Dungeon Definition Language (DDL)
.AU
Bruce Adler
Chris Kostanick
Michael Stein
Michael Urban
.AI
University of California
Los Angeles, CA 90024
.AB
This document describes Dungeon Definition Language, a meta-adventure
specification language.  It is designed primarily for the programmer
who wishes to create a 
\s-2DDL\s+2 
"world", and secondarily for the programmer
attempting to implement 
\s-2DDL\s+2 
on a new host machine.  
.AE
.bp 1
.ds CF "\(co 1981 UCLA Computer Club
.NH 
Introduction.
.PP
\s-2DDL\s+2
is a system of notation for the specification of "worlds".  Using
\s-2DDL\s+2,
a programmer may create Objects, Verbs to act upon those objects,
and Routines to describe the behavior of Objects and Verbs.  The user
of a 
\s-2DDL\s+2
program, known as the Player, types these verbs and the names of
objects to manipulate those objects at a high level.  Thus, a Player's
dialogue with a 
\s-2DDL\s+2
program will appear something like:
.IP
.DS
.SM

  You are standing outside the north entrance of a large
  brick building.  Inscribed above the doorway, appear the
  text: 'AARDVARK'S MUSEUM -- GATEWAY TO ADVENTURELAND'.
  There is a coil of rope here.
  There is a shovel here.
  There is a carbide-flame lamp here.
  There is a copy of a newspaper here.
 >take rope
  OK
 >south
  You are in a large rotunda of an old museum.  Doors lead
  to the north, south, east, and west, and a narrow stairway
  in the north-east corner of the room leads down.
  There is a ball-point pen here.
  There is a slip of paper here.
 >take paper
  OK
 >take pen
  OK
 >e
  You are in a dimly lit room containing an empty display case.
  A portion of a vandalized sign above the case reads:
  'ARTIFACTS OF ANCIENT INDIA -- Several of these items,
  including the sacred rhinoceros horn, the deadly ...'.
  The rest of the sign is unreadable.
  To the west, you can look through a large door into the rotunda
  of the museum. On the east wall of the hall there is an outline
  of an arch.
 >sign paper
  In a blinding flash of light, a stone archway appears in the east wall!
.NL
.DE
.PP
This sort of behavior will be familiar to users of the celebrated programs,
.I "Adventure" 
and 
.I "Dungeon" 
(AKA 
.I "Zork"
), of Crowther, Woods, Anderson
and Blank.
While not as sophisticated in many ways as some of these programs,
the primary function of 
\s-2DDL\s+2 
is to allow a number of interesting
puzzles and games to be exchanged among users of disparate machines
with a minimum of portability problem.
.NH
General Flow of Execution.
.PP
When the 
\s-2DDL\s+2
program begins execution, a special routine which has been
coded by the 
\s-2DDL\s+2
programmer is executed.  This routine must be given the
name START.  START will normally initialize demons and set certain initial
values.  Execution then proceeds in the cyclic fashion described below.
.PP
When a 
\s-2DDL\s+2
scenario is running,
execution proceeds in a series of cycles known as "turns".  On
each turn, a number of actions takes place.
.IP "(1) Demons: " 10
Each of the Demon routines currently active is run in order
of activation.
Demon routines are specified and activated by the 
\s-2DDL\s+2
program by executing
the $sdem function.
.B Note: 
The normal action of Looking (executing description routines) which
one expects to occur on each turn must be coded by the 
\s-2DDL\s+2
programmer
as a Demon.
.IP "(2) Fuses: " 10
All active Fuse routines are checked to see if they
are to be executed on this turn.  Those Fuses which have thus "burned down"
are then executed (in reverse order of activation) and removed.
.IP "(3) Parse: " 10
The player types a line of input,
and an attempt is made to resolve that input into a Verb, an Indirect Object,
and a Direct Object, by means of attendant Prepositions, Articles,
and Adjectives.  Unambiguous abbreviations for words are recognized
by the parser.
If an input Noun is ambiguous (because of two objects distinguished by only
adjectives), 
\s-2DDL\s+2
routines called DWIMD and DWIMI are used to disambiguate
direct and indirect objects respectively.  DWIMD and DWIMI each return
nonzero if the direct or indirect object is "possibly the one he means"
(e.g. if it is in the room, etc)); only if exactly one such object
exists with the given Noun name can the parse complete successfuly.
any of the input components are found to be missing, the value zero is
assumed for that object (and no associated routines are executed).
.PP
If a syntax error or unknown word is detected, a hopefully informative
error message is printed.  In addition, unknown words encountered
in the input
may be saved in a file for perusal by the DDL programmer.
.PP
The direct object may be enclosed in double-quotes by the Player.
Such a direct object is returned as a String to the program.  Strings
may be detected by the program as having "numeric values" less than
zero.  Strings may be operated on with the $eqst, $subs, and $leng
functions, and the $say procedure.
.IP "(4) Pre-action: " 10
The PREACT routine (if any)
that the 
\s-2DDL\s+2
programmer has associated
with the input Verb is executed.  These routines typically will check
for the availability of the object in question, and so on.
.IP "(5) Indirect Object: " 10
The ACTION routine associated with the Indirect Object
that the Player typed (if any) is executed.
.IP "(6) Direct Object: " 10
The ACTION routine associated with the Direct Object
that the Player typed (if any) is executed.
For most specialized actions (like "rub lamp") the particular code
is frequently attached to the object.
If the Direct Object is a String, the ACTION routine (if any)
associated with the object STRING (if such is defined by the
programmer) is executed.
.IP "(7) Room Action: " 10
The ACTION routine associated with the room the Player is
in (actually, the LOC of .ME) is executed.  Normally, this will be
a "transition" routine which will check if the verb is "north", and so on.
.B Note:
This is the ONLY aspect of "built-in" action which depends in ANY
WAY upon the actual state of variables within the "dungeon" itself.
.IP "(8)  Verb: " 10
The ACTION routine associated with the input Verb (if any)
is executed.  ACTION routines for most Verbs will often be
default routines.  For example the Action routine for the Verb "rub"
might print "Rubbing that object is not useful."
.LP
If any of these routines terminates with an ($exit 1), the remainder of
the current turn is skipped.  Furthermore, the 
\s-2DDL\s+2
programmer is responsible
for incrementing the Turn Counter (normally in a Demon routine) if Fuses
are to be used.
.NH
Data types.
.NH 2
Objects.
.PP
Player machinations are in terms of Objects.  All Objects are nodes in
a tree, the root node of which is labelled ".ALL".  A second special
object, ".ME" is considered to represent the Player.  Objects will
normally be treated either as rooms or portable-type objects, but 
\s-2DDL\s+2
itself
does not distinguish these functions; all objects are stored and treated
uniformly.  It is therefore possible, in principal, to write a 
\s-2DDL\s+2
scenario in which the Player may pick up a room, carry it, and
later enter it.  Each object possesses the following attributes.  If
any of these is not specified, it is given the default value of zero.
.IP "LOC: " 6
The object ID of the parent (location) of the object.
.IP "CONT: " 6
The object ID of the first child (contents) of the object.
.IP "LINK: " 6
The object ID of the next sibling (others in the same place) of the
object
.IP "ADJ: " 6
The Adjective ID which uniquely distinguishes this object from others
of the same name (if any).
.IP "OTHERS: " 6
The Object ID of another object with the same name as this object,
though with a different adjective.
.IP "NAME: " 6
The unqualified Noun by which the Player names the object.
.IP "PROPS: " 6
Up to
25
numeric values can be arbitrarily associated with an object by the 
\s-2DDL\s+2
programmer.  Properties
1-16
may only possess the values 0 or 1.  The others may range in value from
-32768 to +32767.
The last three of these properties have special usages.  Their indices
are predefined by the compiler.
.IP "LDESC (23)" 6
The Routine ID of a "Long Description" routine
.IP "SDESC (24)" 6
The Routine ID of a "Short Description" routine
.IP "ACTION (25)" 6
The Routine ID of a "Action" routine, to be called if the Player
either attempts to do something with that object (specifies it as a
Direct or Indirect Object), or while inside that object.
.NH 2
Verbs.
.PP
The "commands" typed by the Player must name Verbs which have been
defined by the 
\s-2DDL\s+2
programmer.  Each Verb is associated with two Routine
ID's:
.IP "PREACT: " 6
The Routine ID of a routine to execute when the verb has been
recognized and the remaining input identified, but before any "Action"
routines associated with the Objects in that input have been executed.
For example, the PREACT routine of "take" might check to see if
the direct object is in the room.
.IP "ACTION: " 6
The Routine ID of a routine to execute after all input object action
routines have been called.
Our experience has been that such routines end up being "default" routines
that typically only say things like "Rubbing that object does nothing."
.NH 2
Strings.
.PP
Simple strings may be defined by the 
\s-2DDL\s+2
programmer to be printed.  Strings
may be up to 255 bytes in length, delimited by double-quote marks.
Carriage returns may be embedded in strings freely, or the sequence \\n
may be used to represent a carriage return at any point.
.NH 2
Numbers.
.PP
\s-2DDL\s+2
programers may only specify nonnegative integers up to 32767.
However, a routine may compute any integer value from -32768 to +32767.
.NH 2
Adjectives.
.PP
Adjectives possess no data, but are uniquely numbered by the 
\s-2DDL\s+2
compiler
so as to have unique internal IDs (which begin at the value 1).
Adjectives are normally only used to distinguish various objects which
have the same Noun name (eg the "red book" and the "blue book").
.NH 2
Routines
.PP
Routines represent the actual logical behavior of the Dungeon.  A routine
consists of one or more calls to builtin or user-defined functions.
Internally, a routine may be stored as an interpretive program for a
very simple stack machine.  The internal representation is up to the
implementer.
Routines may call one another, and a single
routine may call itself recursively.
.NH 2
Globals
.PP
50
globals (numbered
0-49)
are available to the 
\s-2DDL\s+2
programmer and may contain any integer value.  They are named by
numeric constants.  Such constants are conveniently assigned
symbolic names by means of the VAR declaration described below.
The last three globals are set each turn to contain the Indirect
Object, Direct Object, and Verb typed by the player.  The constants
Iobj, Dobj, and Verb are predefined by the compiler to refer to those
globals.
.NH
\s-2DDL\s+2
Programs
.PP
.B Note:
In the syntactic descriptions below, metavariables such as
.I varname
refer to user-defined identifiers.  These identifiers consist
of a string of alphameric characters of arbitrary length.
A 
\s-2DDL\s+2
specification consists of one or more 
\s-2DDL\s+2 
statements, each terminated
by a semicolon.  The following statements exist:
.sp
.IP "VAR \fIvarname, varname\fR,..." 8
.PP
Declares each 
.I varname
as a new symbol.  The symbol
is defined as a constant with a value different from each
previously declared <varname>.  <varname> must not
be previously declared.
.PP
.B "Example:  "
VAR strength, intell, wisdom;
.sp
.IP "VERB \fIverbname, verbname\fR,..." 8
.PP
Declares each 
.I verbname 
as a new verb.  
.I verbname
must
not be previously assigned.
.PP
.B "Example:  "
VERB north,south,east,west;
.sp
.IP "ADJEC \fIadjectivename, adjectivename\fR,..." 8
.PP
Creates a new adjective with name 
.I adjectivename,
which must not be previously assigned.
.PP
.B Example: 
ADJEC red,green,blue;
.sp
.IP "NOUN \fInoun\fR[(\fIcontainer\fR)]" 8
.PP
Creates a new object named 
.I noun
whose
initial location is 
.I 
container.  noun 
.R
may not
be previously assigned; 
.I container
must be of
type NOUN.  If the (\fIcontainer\fR) clause is omitted,
the new object is placed in object .ALL .
the 
.I noun
may actually be a adjective-noun pair.
.PP
.B Examples: 
.DS
NOUN red book, blue book;
NOUN worm(red book);
.DE
.sp
.IP "ROUTINE \fIroutinename, routinename, ...\fR" 8
Declares that the \fIroutinename\fRs listed will be used
for Routines later in the program.  This is to allow \s-2DDL\s+2,
which is intended to be easily implementable, to deal with
recursive routines (which have not yet been declared at the
time of their definitions).  Only routines which are used
before being defined need to be declared with this statement.
.sp
.IP "ARTICLE \fIarticle, article,\fR..." 8
.PP
Creates each \fIarticle\fR as an article.  Articles are recognized
by the run-time parser, but are basically "noise" words.
.PP
.B Example: 
ARTICLE the;
.IP "PREP \fIprep, prep\fR,..." 8
.PP
Creates each 
.I prep
as a preposition.  Prepositions are basically
noise words, but are used by the parser to recognize the presence of
indirect objects in the Player's input.
.PP
.B Example: 
PREP into,on,using,to,at;
.sp
.IP "\fInoun\fR (\fInumexp\fR) = \fIexp2\fR" 8
.PP
Property \fInumexp\fR of \fInoun\fR is set to the
value of \fIexp2\fR.
.I exp2
may be a number, a string, a routine name, or a new routine;
the numeric value or ID of
.I exp2
is always placed into the specified property.
.PP
.B Examples: 
.DS
gem(11)=0;  		{ 11 == Luminous }
gem(LDESC) = ($say "There is a bright gem here!");
gem(SDESC) = ($say "a bright gem");
gem(ACTION) = GmAct;
.DE
.sp
.IP "\fIverb\fR (PREACT | ACTION) = \fIroutine\fR" 8
.PP
Assigns \fIroutine\fR as the pre-object action or default action of
the given \fIverb\fR.  The routine may be a predefined routine name or
an actual routine.
.PP
.B Example: 
.DS
rub(ACTION) =	($say "Rubbing ")
		($sdisc ($dobj))
		($say " seems silly.\\n");
.DE
.sp
.IP "\fIname\fR = \fInumber\fR" 8
.PP
Assigns \fIname\fR as equivalent to \fInumber\fR.  \fIname\fR
must not be previously assigned.
.PP
.B Example: 
OPEN=11; TRUE=1;
.IP "\fIname1\fR = \fIname2\fR" 8
.PP
Assigns 
.I name1
as a synonym for 
.I name2.
.PP
.B Example: 
n=north;s=south;se=southeast;
.IP "(\fInumexp\fR) = \fInumexp2\fR" 8
.PP
Assigns the global (or VAR) named by \fInumexp\fR to the value
given by \fInumexp2\fR.
.PP
.B Example: 
(Maxpt)=450;
.IP "\fIname\fR = "
"\fIstring\fR"
.PP
Assigns 
.I name
as equivalent to "\fIstring\fR".
.B Note:
This seems to be rarely, if ever, used.  Usually it's just
as easy to assign a routine to Say the given string.
However, there are other string functions, such as $eqst
and $substr, for which it may be useful to predefine strings.
.PP
.B Example: 
err="Nothing happens.\\n";
MagicWord = "ShaZam";
.IP "\fIname\fR = \fIroutine\fR" 8
.PP
Assigns 
.I name
as equivalent to 
.I routine
.PP
.B Example: 
sayer=($say "Nothing happens.\\n");
.IP "INCLUDE ""\fIfilename\fR""" 8
.PP
.B
(\s-2UNIX\s+2 implementation only)
.R
Causes input to be read from the named file.
.RE
.NH 
Routines
.PP
A routine is a list of one or more "forms".  Forms are of three types:
.RS
.IP "(\fIform1\fB : \fIform, form\fR ... [: \fIelseform, elseform\fR ...])" 8
.PP
Conditional expression.  If 
.I form1
evaluates to
nonzero, the subsequent \fIform\fRs are executed in
sequence.  Otherwise, the list of \fIelseform\fRs is executed in sequence.
.B Note:
The second colon, and the subsequent \fIelseform\fRs, are optional.
.PP
.B Example: 
.PP
.DS
(TRUE : ($say "Always do me") : ($say "Never do me"))
.DE
.IP "(WHILE \fIform1\fR : \fIform, form ... \fR)" 8
.PP
Simple looping construct.  If \fIform1\fR evaluates
to nonzero, the subsequent \fIform\fRs are evaluated
in sequence.  This process is repeated until such
a time as \fIform1\fR is found to evaluate to zero.
.PP
.B Example:
.PP
.DS
(WHILE ($eq ($loc .ME) JewlRoom) : (TRYmv .ME Prison))
.DE
.IP "(\fIfunction arg1 arg2\fR ...)" 8
.PP
Function call (note that all builtin functions
begin with the character $).  The \fIfunction\fR is applied
to the \fIarg\fRs.  An argument may be a number,
string, declared name, or another form.  However, the function must
be a simple identifier, or a form which evaluates to a function
identifier (
.I 
e.g.
.R
($ldisc xxx)).
In addition, three special argument types are recognized:
.PP
An argument such as "@\fInumber\fR" is interpreted as 
"contents of global \fInumber\fR".
.PP
An argument such as "%\fInumber\R" is interpreted as "the value of the \fInumber\R
argument to this function".
.PP
An argument such as "[\fIadj noun\fR]" must be used if the programmer wishes to
refer to an object with an associated adjective.
.RE
.PP
.B Examples:
.DS
.SM
VERB north,south,east,west,ne,nw,se,sw,up,down;
n=north; s=south; e=east; w=west; u=up; d=down;

NOUN rm001,rm002,rm003,rm004,rm005,rm006;
NOUN .ME(rm001);

ADJECTIVE red,blue;
NOUN red ball(rm002),blue ball(rm003);

red ball(LDESC) = ($say "There is a red ball here.");
red ball(SDESC) = ($say "Red ball.");

VAR score;
(score) = 0;

TAKBT = 16;
TRUE = 1; FALSE=0;
red ball(TAKBT) = TRUE;

ROUTINE takeR;			{ Declared later }

VERB take;
take(ACTION) = 	( ($and ($prop ($dobj) TAKBT)
	 	  	($eq ($loc .ME)($loc ($dobj)))):
				(takeR ($dobj))
		);
takeR = 	($move %1 .ME)
		(($eq %1 [red ball]):
			($say "The ball is glowing!")
			($setg score ($plus 10 @score)));
.NL
.DE