                   Adventure Builder

     Tom Frost presents the Adventure Builder System

[   But first a word from our sponsor... sorry, typist.
    This program was published as a two-part series in
  Sinclair User, in June and July 1986. This file contains
  almost all of the text of the articles - I've left out
  only one or two paragraphs talking about "next month".
  Here and there I've altered a few words to make the text
  fit the fact that this file contains both months' text,
  separated only by a line. Throughout the text, any words
  or sentences between square brackets, such as this
  section, are mine, not Mr. Frost's.
    The text in the article was full of bold, italic, and
  capitalised words, with only a hint of regularity. Having
  worked for a publisher, I strongly suspect that this is
  due to the typesetter trying to bring some kind of plain
  text aesthetics to Mr. Frost's technical, Basic-riddled
  article, but I can't be sure. In any case, below I've
  re-regularised this so that Basic keywords and adventure
  verbs and nouns are ALL-CAPS, Basic variables are lower
  case, and proper nouns are Capitalised (the article used
  both Basic and BASIC...). As it was, it could get a bit
  confusing when both the keyword SAVE and the variable
  save were used in the same line.
    There were a few errors in the text, some of which
  were pointed out in a later issue. I have, of course,
  fixed these silently, as well as one or two simple
  typos.
    This text file should be accompanied by a couple of TZX
  files. Critical of these are 'ABS generator.tzx', the
  data generator referred to below as 'listing 1', and
  'ABS core.tzx', the core of the finished adventure, below
  called 'listing 6'. 'ABS demo 1 tape A.tzx', '...B.tzx'
  and 'ABS demo 2.tzx' are the demonstration adventure
  referred to throughout the text, in various stages of
  completion; if you want to follow the article without
  having the listings present, you will very likely need
  these as well.
    Finally, this program is almost the same as the
  similarly-named Adventure Builder System by Tartan
  Software. This in itself is not that strange, because
  Tartan Software's operator was called Tom. D. Frost.
  What does puzzle me rather is that essentially the same
  program, with very little, mainly cosmetic change, was
  both published for free in Sinclair User and sold commer-
  cially, and that within a space of six months. But if
  you like this program, do check out the commercial
  version as well.
                                   Richard Bos, Dec. 2011 ]

 Introduction

Anyone interested in adventures must almost certainly have
come across adventure writing programs like Gilsoft's The
Quill.
  The interest in these programs is that often you feel
you'd like to write an adventure - work out the plot, fill
the caverns with trolls and gold, plan the map and make
fiendish problems to solve.
  Yet where do you start? Unless you're a good programmer
the whole idea is pretty daunting.
  The Adventure Builder System - this month's program
listing - is a complete system for designing and running
your own adventures. It's quite chunky so it's being
printed in two parts, this month and next.


 The Adventure Builder System

The program is in two main sections. Listing 1 is the
adventure builder itself. And listings 2 to 4 (this [part])
and listings 5 and 6 (next [part]) are a demonstration
adventure showing how to use the adventure builder.
Listings 2 to 6, your own versions of which you will
develop when writing your own adventure, give the core
program (listing 1) all the data needed for the adventure:
number of rooms, number of objects, room descriptions and
so on. Before thinking about designing your own adventure
take a careful look at how the demonstration adventure
works. Also essential is to plan your adventure thoroughly
first by mapping it out on paper before even thinking about
using the ABS. Your map should show each location number,
and all the objects identified by type and starting
location.
  When an ABS adventure is running it shows on-screen the
current location descripion (plus graphics if any) together
with a list of objects visible at the location. It prompts
with "What next?" and any input text command (i.e. "GET
TORCH") is printed on-screen and then analysed (usually
into 'Verb' and 'Noun') and acted upon by the ABS. In other
words, it operates just like a conventional adventure
program.
  The main ABS program (Listing 1) also includes the data
for the essentials: movement input (GO NORTH or N etc.) and
also for the common verbs:

GET (or TAKE)
DROP
LOOK (or L or R)
EXAMINE
QUIT (or STOP)
INVENTORY (or I or LIST)
SAVE
LOAD.


 Loading and saving the listings

The procedure for loading the listings and saving them to
tape is quite complex but, if you follow the instructions
correctly at the end of this first part the program will
stand on its own - despite the fact that only a part of the
demonstration adventure has been typed in - and you will be
able to explore a monster-less adventure. (Monsters next
[part]!) [No, there won't... Puzzles, yes, monsters, no.]
  First the code generator (listing 1) has to be typed in.
Once that is in save a master copy by GOTO 9990. [This is
in file 'ABS generator.tzx'.] Now add the data lines for
the demonstration adventure (Listing 2) and save by GOTO
9990 to a blank tape (Tape A). [This is file 'ABS demo 1
tape A.tzx'.]
  Now enter listing 3 and save it on a second blank tape by
GOTO 120, verify it and do not rewind it (Tape B). [This
is the program called "Intro" on, surprisingly enough,
'ABS demo 1 tape B.tzx'.]
  Type in listing 4, which is part of the demonstration
adventure and save it on Tape B by GOTO 9990, verify and
do not rewind the tape. [This is the program called
"Adventure".]
  Load Tape A and enter the following numbers to the
on-screen prompts:
17,5,9,5,22,2,13,3,15,0,7
then save the data on Tape B (there are two sections to
save). Rewind and load Tape B. Stop tape when prompted,
delete line 9949, enter GOTO 9950 and restart the tape.
You should now be able to explore all the locations and
perform no action other than OPEN. After checking that
the Basic program has been correctly entered, delete Line
9955 and alter Line 9991 to read: 9991 SAVE "System" CODE
save, len and re-save, after the loader, by GOTO 9990.
[Strictly speaking this should have been written over the
top of the previous two programs; I have, instead, appended
another copy of the loader plus this new version of the
data to 'ABS demo 1 tape B.tzx', which therefore contains
two copies of the demo, one for checking and one for
playing.]
  The remainder of the listing for the demonstration
adventure will be given [in the next part].


 Your adventure

Once you've got the demonstration adventure working, the
next thing is to start your own adventure.
  When you have planned it out on paper you are ready to
begin entering the data into the core ABS program,
  The easiest way to understand what to do is to follow how
the demonstration adventure was set up. The core program
provides a number of on-screen prompts which must be
satisfied and all the necessary data must be added.
  So here goes. For each section - each on-screen prompt
from the builder program - follow the format shown and look
at how that particular section is set up by the demo
program example. After each section prompt the number in
brackets is the response appropriate for the demo program.

a) How many verbs? (17)
The data for these is entered in Lines 1003 to 1999 (see
listing 2 [i.e., '...Tape A.tzx']) of the demo program in
the format
DATA "OPEN",9,"UNLOCK",10
i.e. the verb (in full) [and in ALL-CAPS, because the input
routine, as usual in adventure authoring systems, allows
only upper-case input - if your entries are in lower case,
they won't match], followed by its assigned number.
As the verb numbers (vb) 0 to 8 are already assigned the
first additional verb takes the value 9.
  Synonymous verbs (e.g. SHUT and CLOSE) are allocated
the same number but count as separate entries when 
responding to 'How many verbs'.

b) Verb length check (5)
The ABS offers a choice (between 3 and 7) for the number
of leading letters which will be used to determine a match
between player input and the adventure database. The 
selection of 4 or 5 is usual. If 3 is selected confusion
could arise between inputs such as FEED and FEEL, both of
which would be considered as FEE.

c) How many objects? (9)
This refers to the objects which could be included in the
Inventory of the adventurer.
  For DATA entry details, see Section (e).

f) Noun length check (5)
[ This section came later in the article, but since the
  rest of the list follows the order of the prompts in the
  program, I've moved it here. ]
This is similar to 'Verb length check'... and is variable
between 3 and 7. The value can be different from that
chosen for verbs.

d) Maximum length of object description (22)
Enter here the number of characters in the longest object
description.

e) How many objects can have an altered description? (2)
This refers to items such as "A small TORCH" and "A lit
TORCH". The data for these objects is entered in Lines
2000 to 2018 (see Listing 2 of the demo program) in the
following format:
DATA "COAT",1,"A tartan COAT","A tartan COAT (worn)"
DATA "TORCH",2,"A small TORCH","A lit TORCH"
i.e. the word which would be typed, the assigned number,
the original description, the changed description. [As
above, the typed words have to be in ALL-CAPS. Note that,
although Mr. Frost has also put these nouns in all-caps
inside the descriptions, this is not required. A descrip-
tion of "A tartan coat" would have worked just fine.]
  The description of objects is held in the string array
o$(x,y), where x is the total number of objects and y is
the character length of the longest description.
  Those objects which can alter during the course of the
adventure must be allocated the first and last numbers of
the string array. See list of data for demonstration where
"A tartan COAT" and "A small TORCH" are objects 1 and 2
while their corresponding changed versions are objects
8 and 9.
  The data for the remaining objects is entered in Lines
2020 to 2188 in the format:
DATA "BOX",3,"A wooden BOX","SPADE",4,"A short SPADE", etc.

g) Other words (13)
The first assigned number for these words (DOOR, STAIRS
etc.) is calculated as follows:
Total number of objects + 7
e.g., in the demonstration program this produced the number
16 for DOOR. (Total number of objects (9) + 7 = 16). The
data is entered in lines 2190 to 2988 in the format:
DATA "DOOR",16,"CUPBOARD",17 etc.

h) Maximum inventory (3)
Enter here the maximum number of items which the adventurer
is allowed to carry at any one time.

i) Number of locations (15)
Enter here the total number of locations in the adventure.

j) Scroll routine (0)
ABS contains a split-screen technique which can be used
in two ways:
1) If it is required that the top X number of lines remain
on screen, then an entry here of X will scroll the text
"behind" these lines when the screen is full; and
2) If the number of lines required to stay on screen is
variable (eg after "Here you can see" section) then this
can be achieved by entering 0 as this response and by
adding POKE 64453, PEEK 23689-1 at the appropriate
place in the Basic listing.

k) Starting location (7)
Enter here the number of the location at which the
adventure commences.

l) Movement data
The data to control movement is entered in Lines 3000 to
3998 as 7 numbers for each location as follows:
DATA 7,3,13,8,6,0,0
The first number is the location number, followed by the
number of the six locations which would be reached by
entering N,S,E,W,U and D, respectively. An entry of 0
indicates no exit in that direction.
  The data entered here should take no account of the need
to remove obstacles or unlock doors etc as such restric-
tions can be accomodated by the Basic program, in lines
1005 to 1089.
  See the example in the demonstration program at lines
1005 and 1010 (see Listing 4 [that is, "Adventure" on 
'...Tape B.tzx']).

m) Object status table
Each object will at any time have one of the following
numbers allocated to it:
a) 0 - the object is 'invisible'
b) 99 - the object is included in inventory
c) Location number - the object currently resides at this
location and will appear on screen after "Here you can see"
when that location is entered.
  The data for start-up positions is entered in lines 4000
onwards (see Listing 2 of demo program ['Tape A'].
DATA 4,10,0,1, etc.
This indicates that object 1 is at location 4, object 2 is
at location 10 and so on. An entry must be made for each
object.

n) Save and load routines
These routines can be used on a temporary basis either
effecting a save into and load from RAM or as a perma-
nent measure to tape.


-----------------------------------------------------------


 Finishing the demo

To complete the demonstration adventure from [the first
part,] load Tape B and add [...] Listing 5. Save the
completed demo adventure[. The resulting game, with
intro, is in 'ABS demo 2.tzx'.]


 Text analyser routine

The text analysis system allows a maximum input of 30
characters as upper case letters or numbers.
  The analyser routine examines the input and returns to
Basic with an allocated number for 'verb' (vb) and 'noun'
(no) which the Basic program can understand. Any unrecog-
nised word returns a value of 200 for 'verb' and 201 for
'noun'. This information can be used in various ways by the
Basic program but in the demonstration adventure, either
situation produces the response of "You can't do that".
  Possible single-word inputs require some explanation. The
text analysis routine - the parser - looks at the input by
considering the first word as the verb and the last word as
the noun so that 'DROP THE SPADE' or 'DROP THE SHORT SPADE'
produces the same response as 'DROP SPADE'.
  However, a one-word input, for example 'LOOK', gives both
a verb and noun of 'LOOK' with values of vb=4 and no=210.
This would produce a response of "You can't do that" due
to no=201, but such an outcome is prevented by including
LOOK in the list of nouns and assigning it a default value
of 99.
  Any additional verbs which could be used as single-word
inputs should be included in both lists in a similar way.
Alternatively, the noun number could be a true assigned
value for use by the Basic program. In the demonstration
program such an approach has been used for DIG where it
has been assigned the same noun number as HOLE as an
input of 'DIG' implies 'DIG A HOLE'.


 Control of the adventure

The adventure is controlled in the Basic program by the
following:
  Variable vb (the verb number)
  Variable no (the noun number)
  The object status table
  The flag status table
All other controls are operated by the generated code.

a) Object status table
Fifty entries are available in this table and each object
has at all times an entry here in the position identified
by the number of the object.
  For example, the status of object number x is found by
PEEK (o+x) and a change in status is effected by
POKE (o+x),y where y indicates the new status.

b) Flag status table
A hundred entries are available in this table with a few
being reserved for specific uses:
Flag (f+99) is used to control size of inventory; and
Flag (f+0) contains number of current location.
  The first x entries are reserved for use by x objects
which change description during the course of the
adventure. All other flags are available for use by the
Basic program.
  A flag staus is determined by PEEK (f+x) and a change in
status is effected by POKE (f+x),z where z indicates the
new status and x indicates the flag number.
  As the adventure progresses, the Basic program will
update the values in the object and flag status tables.
  When any edventure begins all flags (except f) have the
value of 0. So, in the demonstration adventure, the flags
(f+1) and (f+2) are altered to the value 1 when the coat is
worn and the torch is lit, respectively. Also, (f+3) is
altered to 1 when the cupboard is open.


  Completion of the basic program

1) Location descriptions
These are entered as simple PRINT statements in a maximum
of 10 lines starting at line 7000+(location number*10),
with each group ending with RETURN.

2) Verb sub-routines
A hundred lines are available for each sub-routine
commencing at line 1000+(vb*100).

3) Printing of responses
As it is most likely that you will want a split-screen
presentation, it is necessary to check for the need to
scroll before each response is printed on screen. To
remove the need to include such a check before each PRINT
statement the responses are identified as r$(1), r$(2),
r$(3) and r$(4) which are then printed by the main print
routine (at line 50).

4) Inventory and 'Here you can see'
The machine-code system performs the checking necessary to
identify which objects are to be printed and the routines
in the Basic program effect the printing without further
need for a slow FOR ... NEXT loop.

5) Variables used by the Basic program
Variables assigned in the core Basic program are: vb, no,
f, o, max, mob, pbs, save, len, dmov, o$(x,y) and r$(4,32).


 Generating your own adventure

1) Type in listing 6 and save a master copy by GOTO 9990.
[This is in the file 'ABS core.tzx'.]
2) Load listing 1 (code generator[, 'ABS generator.tzx']),
add your adventure data then save on a blank tape by
GOTO 9990 (Tape A).
3) Make a copy of listing 6, verify and do not rewind tape
(Tape B).
4) Load Tape A and supply the information required by the
on-screen prompts then save the two sections of data on
Tape B. Make a note of the CLEAR number.
5) Enter as a direct command:
     CLEAR number: LOAD ""
and load Tape B. Stop the tape when prompted, delete Line
9949 then enter GOTO 9950 and restart tape.
6) Delete Lines 9955 and 7010, alter Line 9991 to:
9991 SAVE "system" CODE save, len
7) Add the remainder of the Basic program (location des-
criptions, verb sub-routines, screen display data etc).
8) Save, by GOTO 30, the following loader at the start of
a blank tape:
  10 CLEAR number
  20 LOAD ""
  30 SAVE "loader" LINE 10
9) Save the adventure, after the loader, by GOTO 9990
  When writing your own adventure, the verbs and nouns in
Table I are included automatically.
  The following verb sub-routines are included in the core
Basic adventure listing.
    LOOK:       at line 1400
    INVENTORY:  at line 1500
    QUIT:       at line 1600
    SAVE:       at line 1700
    LOAD:       at line 1800
  The movement sub-routine is partially completed only,
starting at line 1000. It remains to insert any lines to
account for temporary blocks such as closed doors or
removal of guarding monsters.
  As an example of the data for an adventure look at the
demonstration program. Fig. 1 shows a map of the demo
adventure, together with the organisation for the object
and verb data (Tables II and III), and flag status table
(Table IV). [All these tables, and the map, can be found
at the end of this document.]


 Response time and memory

1) Variables
When memory becomes a problem the first consideration is
usually to replace frequently used numbers with a variable.
For example 0 and 1 abound in many Basic adventure listings
and the use of:
    LET n=0 and LET j=1
followed by the replacement in the listing of each of these
numbers by n or j can effect a considerable saving of
memory. Such an approach can, when applies to extremes,
have an adverse effect on the response time.

2) Sub-routine structure
a) the EXAMINE sub-routine
This is likely to be one of the longest in terms of number
of lines but acceptable response times can be achieved by
dividing the sub-routine into several sections. A line such
as line 1300 in the demonstration program effectively
produces two shorter EXAMINE sub-routines, each of which
could be further sub-divided if necessary.
b) the movement sub-routine
This routine requires almost instant response but can be
slowed down if there are many considerations of locked
doors etc. to be evaluated by the Basic program. This does
not apply to the demonstration program as there are only
two such lines. Removal of such lines can be achieved with
the following modifications.
  On return from RANDOMIZE USR 65005 the maximum value of
PEEK 64115 will be the number of locations in the adventure
(in this case, 15). Also, if the door is closed then that
response is required for an east movement from location 8
and a west movement from location 9. Currently, in the
movement data, east from location 8 has a value of 9 and
west from location 9 has a value of 7. Change both of these
values to 16 in the DATA lines of the code generator
program, or as a shortcut these changes can be effected by
the direct commands:
    POKE ((dmov-7)+59),16
    POKE ((dmov-7)+67),16
  Now make the following alterations to the Basic listing:
1) Remove lines 1005, 1606, 1816, 7080, 7081.
2) Add the following lines:
1820 IF PEEK (f+4)=1 THEN POKE ((dmov-7)+59),9: POKE
     ((dmov-7)+67),7
1825 GOTO 100
1606 IF a$="Y" THEN GOTO 1620
1620 POKE ((dmov-7)+59),16: POKE ((dmov-7)+67),16
1629 RANDOMIZE USR 65058
1630 GOTO 100
Renumber 1090 as 1050 then delete 1090
Renumber 1092 as 1052 then delete 1092
1055 IF PEEK 64115<16 THEN GOTO 1060
1058 LET r$(1)=n$(PEEK 64115-15): GOTO 50
9972 DIM n$(2,9)
9973 LET n$(1)="The DOOR is closed!"
9974 LET n$(2)="The GATE is closed!"
3) Alter the following lines:
1900 after POKE (f+4),1: add POKE ((dmov-7)+59),9: POKE
     ((dmov-7)+67),7
2600 after POKE (f+4),1: add POKE ((dmov-7)+59),16: POKE
     ((dmov-7)+67),16
[ I have not made a TZX containing these changes; they are
  left as an exercise for the reader. ]


Fig. 1 The demonstration adventure
            1 Barn
               | spade
               |
 2 Loft     3 Farmyard          4 Living        5 Dining
   u||d        |                  Room            Room
    ||         |                    |               |
6 Stable----7 Field----8 Door---9 Front Hall----10 Kitchen
   u||d        |                                    | torch
11 Cellar      |                                    |
     (box)     |                                    |
12 Dead----13 E/W Road-------------14 Gate------15 Garden
   End                                              (key)

   Table I. Standard verbs and nouns
 -------------------------------------
   Verb  vb number   Noun  no number
 -------------------------------------
    GO       0        N        1
    N        0      NORTH      1
    S        0        S        2
    E        0      SOUTH      2
    W        0        E        3
    U        0       EAST      3
    D        0        W        4
   GET       1       WEST      4
   TAKE      1        U        5
   DROP      2        UP       5
  EXAMINE    3        D        6
   LOOK      4       DOWN      6
    L        4       LOOK     99
    R        4        L       99
 INVENTORY   5        R       99
    I        5     INVENTORY  99
   LIST      5        I       99
   QUIT      6       LIST     99
   STOP      6       QUIT     99
   SAVE      7       STOP     99
   LOAD      8       SAVE     99
                     LOAD     99

                 Table II. Object data
 ------------------------------------------------------
  Number   Object (o$)         Data  Starting location
 ------------------------------------------------------
    1     A tartan COAT        COAT          4
    2     A small TORCH       TORCH         10
    3     A wooden BOX         BOX           0
    4     A short SPADE       SPADE          1
    5     A bronze KEY         KEY           0
    6   Splinters of WOOD      WOOD          0
    7    A large DIAMOND     DIAMOND         0
    8  A tartan COAT (worn)    COAT          0
    9      A lit TORCH        TORCH          0
 ------------------------------------------------------
  Number   Other nouns        Number   Other nouns      
 ------------------------------------------------------
    16         DOOR             23        GARDEN
    17       CUPBOARD           24        FIELD
    18         LAWN             25         SAFE
    19        STAIRS            26        PATCH
    20        LADDER            27         JUMP
    21         GATE             22         DIG
    22         HOLE

      Table III. Verb data in demo program
 ------------------------------------------------
                                 Movement data
 vb number  Verb      Location  N  S  W  E  U  D
 ------------------------------------------------
      9     OPEN          1     0  3  0  0  0  0
     10    UNLOCK         2     0  0  0  0  0  6
     11     DIG           3     1  7  0  0  0  0
     12    LIGHT          4     0  9  5  0  0  0
     13  EXTINGUISH       5     0 10  0  4  0  0
     14    CLIMB          6     0  0  7  0  2 11
     15   DESCEND         7     3 13  8  6  0  0
     16    CLOSE          8     0  0  9  7  0  0
     17     TOSS          9     4  0 10  7  0  0
     18     FILL         10     5 15  0  0  0  0
     19     LOCK         11     0  0  0  0  6  0
     20     WEAR         12     0  0 13  0  0  0
     21    REMOVE        13     7  0 14 12  0  0
     14    ASCEND        14     0  0 15 13  0  0
     16     SHUT         15    10  0  0 14  0  0
     22     JUMP
     23     USE

  Table IV. Flag Status Table: Assigned Values
 ----------------------------------------------
  Flag Number   Action for Value=1
 ----------------------------------------------
        1       COAT worn (fixed allocation)
        2       TORCH lit (fixed allocation)
        3       CUPBOARD open
        4       DOOR open
        5       HOLE in field
        6       HOLE in gargen
        7       GATE open
        8       SAFE unlocked
        9       Found BOX
       10       Found KEY
       11       First OPEN CUPBOARD
       99       INVENTORY (fixed allocation)
