![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to doc.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 42BSD / games / ddl / doc|
Return to doc.ms CVS log | Up to [CSRG BSD Unix] / 42BSD / games / ddl / doc |
1.1 root 1: .RS
2: .ds CF "\(co 1981 UCLA Computer Club
3: .TL
4: A Brief Description of UCLA
5: Dungeon Definition Language (DDL)
6: .AU
7: Bruce Adler
8: Chris Kostanick
9: Michael Stein
10: Michael Urban
11: .AI
12: University of California
13: Los Angeles, CA 90024
14: .AB
15: This document describes Dungeon Definition Language, a meta-adventure
16: specification language. It is designed primarily for the programmer
17: who wishes to create a
18: \s-2DDL\s+2
19: "world", and secondarily for the programmer
20: attempting to implement
21: \s-2DDL\s+2
22: on a new host machine.
23: .AE
24: .bp 1
25: .ds CF "\(co 1981 UCLA Computer Club
26: .NH
27: Introduction.
28: .PP
29: \s-2DDL\s+2
30: is a system of notation for the specification of "worlds". Using
31: \s-2DDL\s+2,
32: a programmer may create Objects, Verbs to act upon those objects,
33: and Routines to describe the behavior of Objects and Verbs. The user
34: of a
35: \s-2DDL\s+2
36: program, known as the Player, types these verbs and the names of
37: objects to manipulate those objects at a high level. Thus, a Player's
38: dialogue with a
39: \s-2DDL\s+2
40: program will appear something like:
41: .IP
42: .DS
43: .SM
44:
45: You are standing outside the north entrance of a large
46: brick building. Inscribed above the doorway, appear the
47: text: 'AARDVARK'S MUSEUM -- GATEWAY TO ADVENTURELAND'.
48: There is a coil of rope here.
49: There is a shovel here.
50: There is a carbide-flame lamp here.
51: There is a copy of a newspaper here.
52: >take rope
53: OK
54: >south
55: You are in a large rotunda of an old museum. Doors lead
56: to the north, south, east, and west, and a narrow stairway
57: in the north-east corner of the room leads down.
58: There is a ball-point pen here.
59: There is a slip of paper here.
60: >take paper
61: OK
62: >take pen
63: OK
64: >e
65: You are in a dimly lit room containing an empty display case.
66: A portion of a vandalized sign above the case reads:
67: 'ARTIFACTS OF ANCIENT INDIA -- Several of these items,
68: including the sacred rhinoceros horn, the deadly ...'.
69: The rest of the sign is unreadable.
70: To the west, you can look through a large door into the rotunda
71: of the museum. On the east wall of the hall there is an outline
72: of an arch.
73: >sign paper
74: In a blinding flash of light, a stone archway appears in the east wall!
75: .NL
76: .DE
77: .PP
78: This sort of behavior will be familiar to users of the celebrated programs,
79: .I "Adventure"
80: and
81: .I "Dungeon"
82: (AKA
83: .I "Zork"
84: ), of Crowther, Woods, Anderson
85: and Blank.
86: While not as sophisticated in many ways as some of these programs,
87: the primary function of
88: \s-2DDL\s+2
89: is to allow a number of interesting
90: puzzles and games to be exchanged among users of disparate machines
91: with a minimum of portability problem.
92: .NH
93: General Flow of Execution.
94: .PP
95: When the
96: \s-2DDL\s+2
97: program begins execution, a special routine which has been
98: coded by the
99: \s-2DDL\s+2
100: programmer is executed. This routine must be given the
101: name START. START will normally initialize demons and set certain initial
102: values. Execution then proceeds in the cyclic fashion described below.
103: .PP
104: When a
105: \s-2DDL\s+2
106: scenario is running,
107: execution proceeds in a series of cycles known as "turns". On
108: each turn, a number of actions takes place.
109: .IP "(1) Demons: " 10
110: Each of the Demon routines currently active is run in order
111: of activation.
112: Demon routines are specified and activated by the
113: \s-2DDL\s+2
114: program by executing
115: the $sdem function.
116: .B Note:
117: The normal action of Looking (executing description routines) which
118: one expects to occur on each turn must be coded by the
119: \s-2DDL\s+2
120: programmer
121: as a Demon.
122: .IP "(2) Fuses: " 10
123: All active Fuse routines are checked to see if they
124: are to be executed on this turn. Those Fuses which have thus "burned down"
125: are then executed (in reverse order of activation) and removed.
126: .IP "(3) Parse: " 10
127: The player types a line of input,
128: and an attempt is made to resolve that input into a Verb, an Indirect Object,
129: and a Direct Object, by means of attendant Prepositions, Articles,
130: and Adjectives. Unambiguous abbreviations for words are recognized
131: by the parser.
132: If an input Noun is ambiguous (because of two objects distinguished by only
133: adjectives),
134: \s-2DDL\s+2
135: routines called DWIMD and DWIMI are used to disambiguate
136: direct and indirect objects respectively. DWIMD and DWIMI each return
137: nonzero if the direct or indirect object is "possibly the one he means"
138: (e.g. if it is in the room, etc)); only if exactly one such object
139: exists with the given Noun name can the parse complete successfuly.
140: any of the input components are found to be missing, the value zero is
141: assumed for that object (and no associated routines are executed).
142: .PP
143: If a syntax error or unknown word is detected, a hopefully informative
144: error message is printed. In addition, unknown words encountered
145: in the input
146: may be saved in a file for perusal by the DDL programmer.
147: .PP
148: The direct object may be enclosed in double-quotes by the Player.
149: Such a direct object is returned as a String to the program. Strings
150: may be detected by the program as having "numeric values" less than
151: zero. Strings may be operated on with the $eqst, $subs, and $leng
152: functions, and the $say procedure.
153: .IP "(4) Pre-action: " 10
154: The PREACT routine (if any)
155: that the
156: \s-2DDL\s+2
157: programmer has associated
158: with the input Verb is executed. These routines typically will check
159: for the availability of the object in question, and so on.
160: .IP "(5) Indirect Object: " 10
161: The ACTION routine associated with the Indirect Object
162: that the Player typed (if any) is executed.
163: .IP "(6) Direct Object: " 10
164: The ACTION routine associated with the Direct Object
165: that the Player typed (if any) is executed.
166: For most specialized actions (like "rub lamp") the particular code
167: is frequently attached to the object.
168: If the Direct Object is a String, the ACTION routine (if any)
169: associated with the object STRING (if such is defined by the
170: programmer) is executed.
171: .IP "(7) Room Action: " 10
172: The ACTION routine associated with the room the Player is
173: in (actually, the LOC of .ME) is executed. Normally, this will be
174: a "transition" routine which will check if the verb is "north", and so on.
175: .B Note:
176: This is the ONLY aspect of "built-in" action which depends in ANY
177: WAY upon the actual state of variables within the "dungeon" itself.
178: .IP "(8) Verb: " 10
179: The ACTION routine associated with the input Verb (if any)
180: is executed. ACTION routines for most Verbs will often be
181: default routines. For example the Action routine for the Verb "rub"
182: might print "Rubbing that object is not useful."
183: .LP
184: If any of these routines terminates with an ($exit 1), the remainder of
185: the current turn is skipped. Furthermore, the
186: \s-2DDL\s+2
187: programmer is responsible
188: for incrementing the Turn Counter (normally in a Demon routine) if Fuses
189: are to be used.
190: .NH
191: Data types.
192: .NH 2
193: Objects.
194: .PP
195: Player machinations are in terms of Objects. All Objects are nodes in
196: a tree, the root node of which is labelled ".ALL". A second special
197: object, ".ME" is considered to represent the Player. Objects will
198: normally be treated either as rooms or portable-type objects, but
199: \s-2DDL\s+2
200: itself
201: does not distinguish these functions; all objects are stored and treated
202: uniformly. It is therefore possible, in principal, to write a
203: \s-2DDL\s+2
204: scenario in which the Player may pick up a room, carry it, and
205: later enter it. Each object possesses the following attributes. If
206: any of these is not specified, it is given the default value of zero.
207: .IP "LOC: " 6
208: The object ID of the parent (location) of the object.
209: .IP "CONT: " 6
210: The object ID of the first child (contents) of the object.
211: .IP "LINK: " 6
212: The object ID of the next sibling (others in the same place) of the
213: object
214: .IP "ADJ: " 6
215: The Adjective ID which uniquely distinguishes this object from others
216: of the same name (if any).
217: .IP "OTHERS: " 6
218: The Object ID of another object with the same name as this object,
219: though with a different adjective.
220: .IP "NAME: " 6
221: The unqualified Noun by which the Player names the object.
222: .IP "PROPS: " 6
223: Up to
224: 25
225: numeric values can be arbitrarily associated with an object by the
226: \s-2DDL\s+2
227: programmer. Properties
228: 1-16
229: may only possess the values 0 or 1. The others may range in value from
230: -32768 to +32767.
231: The last three of these properties have special usages. Their indices
232: are predefined by the compiler.
233: .IP "LDESC (23)" 6
234: The Routine ID of a "Long Description" routine
235: .IP "SDESC (24)" 6
236: The Routine ID of a "Short Description" routine
237: .IP "ACTION (25)" 6
238: The Routine ID of a "Action" routine, to be called if the Player
239: either attempts to do something with that object (specifies it as a
240: Direct or Indirect Object), or while inside that object.
241: .NH 2
242: Verbs.
243: .PP
244: The "commands" typed by the Player must name Verbs which have been
245: defined by the
246: \s-2DDL\s+2
247: programmer. Each Verb is associated with two Routine
248: ID's:
249: .IP "PREACT: " 6
250: The Routine ID of a routine to execute when the verb has been
251: recognized and the remaining input identified, but before any "Action"
252: routines associated with the Objects in that input have been executed.
253: For example, the PREACT routine of "take" might check to see if
254: the direct object is in the room.
255: .IP "ACTION: " 6
256: The Routine ID of a routine to execute after all input object action
257: routines have been called.
258: Our experience has been that such routines end up being "default" routines
259: that typically only say things like "Rubbing that object does nothing."
260: .NH 2
261: Strings.
262: .PP
263: Simple strings may be defined by the
264: \s-2DDL\s+2
265: programmer to be printed. Strings
266: may be up to 255 bytes in length, delimited by double-quote marks.
267: Carriage returns may be embedded in strings freely, or the sequence \\n
268: may be used to represent a carriage return at any point.
269: .NH 2
270: Numbers.
271: .PP
272: \s-2DDL\s+2
273: programers may only specify nonnegative integers up to 32767.
274: However, a routine may compute any integer value from -32768 to +32767.
275: .NH 2
276: Adjectives.
277: .PP
278: Adjectives possess no data, but are uniquely numbered by the
279: \s-2DDL\s+2
280: compiler
281: so as to have unique internal IDs (which begin at the value 1).
282: Adjectives are normally only used to distinguish various objects which
283: have the same Noun name (eg the "red book" and the "blue book").
284: .NH 2
285: Routines
286: .PP
287: Routines represent the actual logical behavior of the Dungeon. A routine
288: consists of one or more calls to builtin or user-defined functions.
289: Internally, a routine may be stored as an interpretive program for a
290: very simple stack machine. The internal representation is up to the
291: implementer.
292: Routines may call one another, and a single
293: routine may call itself recursively.
294: .NH 2
295: Globals
296: .PP
297: 50
298: globals (numbered
299: 0-49)
300: are available to the
301: \s-2DDL\s+2
302: programmer and may contain any integer value. They are named by
303: numeric constants. Such constants are conveniently assigned
304: symbolic names by means of the VAR declaration described below.
305: The last three globals are set each turn to contain the Indirect
306: Object, Direct Object, and Verb typed by the player. The constants
307: Iobj, Dobj, and Verb are predefined by the compiler to refer to those
308: globals.
309: .NH
310: \s-2DDL\s+2
311: Programs
312: .PP
313: .B Note:
314: In the syntactic descriptions below, metavariables such as
315: .I varname
316: refer to user-defined identifiers. These identifiers consist
317: of a string of alphameric characters of arbitrary length.
318: A
319: \s-2DDL\s+2
320: specification consists of one or more
321: \s-2DDL\s+2
322: statements, each terminated
323: by a semicolon. The following statements exist:
324: .sp
325: .IP "VAR \fIvarname, varname\fR,..." 8
326: .PP
327: Declares each
328: .I varname
329: as a new symbol. The symbol
330: is defined as a constant with a value different from each
331: previously declared <varname>. <varname> must not
332: be previously declared.
333: .PP
334: .B "Example: "
335: VAR strength, intell, wisdom;
336: .sp
337: .IP "VERB \fIverbname, verbname\fR,..." 8
338: .PP
339: Declares each
340: .I verbname
341: as a new verb.
342: .I verbname
343: must
344: not be previously assigned.
345: .PP
346: .B "Example: "
347: VERB north,south,east,west;
348: .sp
349: .IP "ADJEC \fIadjectivename, adjectivename\fR,..." 8
350: .PP
351: Creates a new adjective with name
352: .I adjectivename,
353: which must not be previously assigned.
354: .PP
355: .B Example:
356: ADJEC red,green,blue;
357: .sp
358: .IP "NOUN \fInoun\fR[(\fIcontainer\fR)]" 8
359: .PP
360: Creates a new object named
361: .I noun
362: whose
363: initial location is
364: .I
365: container. noun
366: .R
367: may not
368: be previously assigned;
369: .I container
370: must be of
371: type NOUN. If the (\fIcontainer\fR) clause is omitted,
372: the new object is placed in object .ALL .
373: the
374: .I noun
375: may actually be a adjective-noun pair.
376: .PP
377: .B Examples:
378: .DS
379: NOUN red book, blue book;
380: NOUN worm(red book);
381: .DE
382: .sp
383: .IP "ROUTINE \fIroutinename, routinename, ...\fR" 8
384: Declares that the \fIroutinename\fRs listed will be used
385: for Routines later in the program. This is to allow \s-2DDL\s+2,
386: which is intended to be easily implementable, to deal with
387: recursive routines (which have not yet been declared at the
388: time of their definitions). Only routines which are used
389: before being defined need to be declared with this statement.
390: .sp
391: .IP "ARTICLE \fIarticle, article,\fR..." 8
392: .PP
393: Creates each \fIarticle\fR as an article. Articles are recognized
394: by the run-time parser, but are basically "noise" words.
395: .PP
396: .B Example:
397: ARTICLE the;
398: .IP "PREP \fIprep, prep\fR,..." 8
399: .PP
400: Creates each
401: .I prep
402: as a preposition. Prepositions are basically
403: noise words, but are used by the parser to recognize the presence of
404: indirect objects in the Player's input.
405: .PP
406: .B Example:
407: PREP into,on,using,to,at;
408: .sp
409: .IP "\fInoun\fR (\fInumexp\fR) = \fIexp2\fR" 8
410: .PP
411: Property \fInumexp\fR of \fInoun\fR is set to the
412: value of \fIexp2\fR.
413: .I exp2
414: may be a number, a string, a routine name, or a new routine;
415: the numeric value or ID of
416: .I exp2
417: is always placed into the specified property.
418: .PP
419: .B Examples:
420: .DS
421: gem(11)=0; { 11 == Luminous }
422: gem(LDESC) = ($say "There is a bright gem here!");
423: gem(SDESC) = ($say "a bright gem");
424: gem(ACTION) = GmAct;
425: .DE
426: .sp
427: .IP "\fIverb\fR (PREACT | ACTION) = \fIroutine\fR" 8
428: .PP
429: Assigns \fIroutine\fR as the pre-object action or default action of
430: the given \fIverb\fR. The routine may be a predefined routine name or
431: an actual routine.
432: .PP
433: .B Example:
434: .DS
435: rub(ACTION) = ($say "Rubbing ")
436: ($sdisc ($dobj))
437: ($say " seems silly.\\n");
438: .DE
439: .sp
440: .IP "\fIname\fR = \fInumber\fR" 8
441: .PP
442: Assigns \fIname\fR as equivalent to \fInumber\fR. \fIname\fR
443: must not be previously assigned.
444: .PP
445: .B Example:
446: OPEN=11; TRUE=1;
447: .IP "\fIname1\fR = \fIname2\fR" 8
448: .PP
449: Assigns
450: .I name1
451: as a synonym for
452: .I name2.
453: .PP
454: .B Example:
455: n=north;s=south;se=southeast;
456: .IP "(\fInumexp\fR) = \fInumexp2\fR" 8
457: .PP
458: Assigns the global (or VAR) named by \fInumexp\fR to the value
459: given by \fInumexp2\fR.
460: .PP
461: .B Example:
462: (Maxpt)=450;
463: .IP "\fIname\fR = "
464: "\fIstring\fR"
465: .PP
466: Assigns
467: .I name
468: as equivalent to "\fIstring\fR".
469: .B Note:
470: This seems to be rarely, if ever, used. Usually it's just
471: as easy to assign a routine to Say the given string.
472: However, there are other string functions, such as $eqst
473: and $substr, for which it may be useful to predefine strings.
474: .PP
475: .B Example:
476: err="Nothing happens.\\n";
477: MagicWord = "ShaZam";
478: .IP "\fIname\fR = \fIroutine\fR" 8
479: .PP
480: Assigns
481: .I name
482: as equivalent to
483: .I routine
484: .PP
485: .B Example:
486: sayer=($say "Nothing happens.\\n");
487: .IP "INCLUDE ""\fIfilename\fR""" 8
488: .PP
489: .B
490: (\s-2UNIX\s+2 implementation only)
491: .R
492: Causes input to be read from the named file.
493: .RE
494: .NH
495: Routines
496: .PP
497: A routine is a list of one or more "forms". Forms are of three types:
498: .RS
499: .IP "(\fIform1\fB : \fIform, form\fR ... [: \fIelseform, elseform\fR ...])" 8
500: .PP
501: Conditional expression. If
502: .I form1
503: evaluates to
504: nonzero, the subsequent \fIform\fRs are executed in
505: sequence. Otherwise, the list of \fIelseform\fRs is executed in sequence.
506: .B Note:
507: The second colon, and the subsequent \fIelseform\fRs, are optional.
508: .PP
509: .B Example:
510: .PP
511: .DS
512: (TRUE : ($say "Always do me") : ($say "Never do me"))
513: .DE
514: .IP "(WHILE \fIform1\fR : \fIform, form ... \fR)" 8
515: .PP
516: Simple looping construct. If \fIform1\fR evaluates
517: to nonzero, the subsequent \fIform\fRs are evaluated
518: in sequence. This process is repeated until such
519: a time as \fIform1\fR is found to evaluate to zero.
520: .PP
521: .B Example:
522: .PP
523: .DS
524: (WHILE ($eq ($loc .ME) JewlRoom) : (TRYmv .ME Prison))
525: .DE
526: .IP "(\fIfunction arg1 arg2\fR ...)" 8
527: .PP
528: Function call (note that all builtin functions
529: begin with the character $). The \fIfunction\fR is applied
530: to the \fIarg\fRs. An argument may be a number,
531: string, declared name, or another form. However, the function must
532: be a simple identifier, or a form which evaluates to a function
533: identifier (
534: .I
535: e.g.
536: .R
537: ($ldisc xxx)).
538: In addition, three special argument types are recognized:
539: .PP
540: An argument such as "@\fInumber\fR" is interpreted as
541: "contents of global \fInumber\fR".
542: .PP
543: An argument such as "%\fInumber\R" is interpreted as "the value of the \fInumber\R
544: argument to this function".
545: .PP
546: An argument such as "[\fIadj noun\fR]" must be used if the programmer wishes to
547: refer to an object with an associated adjective.
548: .RE
549: .PP
550: .B Examples:
551: .DS
552: .SM
553: VERB north,south,east,west,ne,nw,se,sw,up,down;
554: n=north; s=south; e=east; w=west; u=up; d=down;
555:
556: NOUN rm001,rm002,rm003,rm004,rm005,rm006;
557: NOUN .ME(rm001);
558:
559: ADJECTIVE red,blue;
560: NOUN red ball(rm002),blue ball(rm003);
561:
562: red ball(LDESC) = ($say "There is a red ball here.");
563: red ball(SDESC) = ($say "Red ball.");
564:
565: VAR score;
566: (score) = 0;
567:
568: TAKBT = 16;
569: TRUE = 1; FALSE=0;
570: red ball(TAKBT) = TRUE;
571:
572: ROUTINE takeR; { Declared later }
573:
574: VERB take;
575: take(ACTION) = ( ($and ($prop ($dobj) TAKBT)
576: ($eq ($loc .ME)($loc ($dobj)))):
577: (takeR ($dobj))
578: );
579: takeR = ($move %1 .ME)
580: (($eq %1 [red ball]):
581: ($say "The ball is glowing!")
582: ($setg score ($plus 10 @score)));
583: .NL
584: .DE
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.