hadeishi@husc4.harvard.edu (mitsuharu hadeishi) (10/14/86)
Keywords:
This Quick Reference Guide can be loaded into AmigaBasic
as well. If you need help on a particular section of code in AmigaBasic,
you can type "list label-" and some text describing that section of
code will come up in the LIST window. (The Reference Guide is organized
in the same fashion as the actual program.) Following that is
a section describing the object-handling primitives and data list
subprograms, and finally a list of the main variables used in AmigaVenture.
Invaluable guide for deciphering the example adventure and example
verbs given in the source code.
Some of the variables listed are for internal use and should only
be used in conjunction with the higher-level access. All features of
AmigaVenture are documented in the source code, but details of
implementation of these features require an intrepid programmer.
If you have questions about a particular section of code, feel free
to email me, though I can't guarantee an immediate response.
(The most cryptic is the implementation of a rather sophisticated
system of conditional descriptions. This allows you to have a
description of a room which varies depending on the state of various
program flags. You can even have separate descriptions for nighttime
and daytime, for example. How to do this is fully documented, but
the implementation of this is a rather complicated set of array
indirection and conditional evaluation. If you wish to move the
descriptions onto a random-access disk file, please email me and
I'll try to describe how the system works. Essentially you only
have to copy the portion of Initialize: dealing with descriptions
in a setup program, write the final values of the arrays to
a sequential file to be loaded later by the program, and write the
strings to a random access file for perusal by Look:. In the actual
program you need to change Initialize to read the sequential file,
(move all of the location data statements to the setup program, of
course), and change Look: to look into disk files instead of string
arrays.)
This is NOT a shell archive. Just cut and LIST.
--------[ cut here ]---------[ cut here ]---------[ cut here ]----------
'
' AmigaVenture 1.17 Quick Reference Guide
'
' by Mitsu Hadeishi 8/21/86
' 3 Sacramento Street
' Cambridge MA 02138
'
' Written for the Winner's Circle Amiga User's Group
' Winner's Circle Systems, 2618 Telegraph Avenue,
' Berkeley, CA 94704
'
'---------------------------------------------------------------------------
' Permission is given to freely distribute this text in full or in part
' provided this notice is copied IN FULL:
'
' AmigaVenture Kernal Copyright (c) 1986 by Mitsu Hadeishi
' This code may not be used in part or in full in any commercial
' product, nor may this code in part or in full be sold intentionally
' to make a profit, without an explicit written agreement with the author.
'---------------------------------------------------------------------------
'
'Useful program labels (use with the list command):
'
'Introductory labels...
'
' Initializes version string and load/save data format version at beginning
' NOTE: This is different from version 1.16 and earlier.
'
Messages:
' System-wide messages, frequently printed error messages, e.g.,
' "You can't verb the noun!", "You don't have the noun!" etc.
'
Calc:
' Calculation subprograms, including Visible(), Avail(), CheckLight(),
' and NameNoun().
'
Calc2:
' More calculation subprograms, including ListSib(), Inside(),
' EvalCond(), ListBottles().
'
Lists:
' These subprograms are used to manipulate the linked lists of objects.
' Includes Contents(), Remove(), Insert(), Setloc(), RemList(), Concat(),
'
WaterLists:
' These subprograms are used to fill and empty bottles of water.
' Includes Fill(), Empty().
'
' Tumble() is located here as well, for some odd reason.
'
Interpreter:
'
' The interpreter subprograms are located here. GetVerb(),
'ExNoun(), SkipNoun(), GetNoun(), GetPrep(), ChooseVisible(), GetThatClause(),
'SkipThatClause(), and ResolveThat().
'
Initialize:
'
' This is the first thing done in the program. The game version is
'stored here, along with the initialization of system constants, strings,
'arrays, and the reading of the interpreter and description DATA statements.
' These routines can be selectively or wholly replaced by reads from
'a disk file or opening of random access files on disk. I would suggest
'developing the adventure first with DATA statements, then later storing
'the DATA in disk files for random access to save memory. You could keep
'an AmigaBasic file with just these initialization routines and the
'DATA statements which reads the statements, then puts the data onto a
'disk file for sequential or random access. The game program would then
'be set up to read the disk files instead of DATA statements.
'
' Description of routines---
' Initialize z$, FNcap$, etc.
' Read abstract noun descriptions
' Read folded state descriptions
' Read verbs
' Read verb attributes
' Read nouns
' Read prepositions
' Read preposition descriptions
imap:
' Read map/descriptions
' Read flags
iobj:
' Read objects and object attributes
Arrays:
' Allocate and initialize arrays
Initvals:
' Initialize system constants and the starting location
Player:
' Initialize player constants (size, carry capacity, etc.)
'
'Command control labels---
'
NewCommand:
' Immediately cancel the command in progress and all pending commands
' and return to the command prompt.
'
ContCommand:
' Return to the player prompt, but keep the command in progress and
' pending commands in mind. Jump here if you need to ask the player a
' question to resolve some ambiguity without canceling the old command.
' (as in "Take what?" "> bag" "Taken.")
'
GetCommand:
' Get the next pending command if there is one, otherwise return to
' the command prompt.
'
' InCommand:
' Issue command prompt.
'
'Command parser---
Parse:
' Jump here if you want to parse or re-parse a cmd$ string.
' Take care of grammatical quirks, excess spaces, etc.
'
Interpret:
' Process a cmd$ string and return verb, direct object, preposition,
' and indirect object codes.
'
' Description of routines---
' Get a verb
InNoun:
' Get (another) noun
' If there's a "that" (as in "get the purse that's in the bag"),
' resolve ambiguity with the "that's in the bag" clause
InPrep:
' Get (another) preposition or conjunction
' Loop back to get another noun if necessary
'
PreProcess:
' Check for error conditions, set up multiple noun loops
'
Filter:
' Make obvious grammatical replacements, check for more error
' conditions, make sure the command makes sense, check for the
' visibility, availability, and appropriateness of the direct and
' indirect objects for the verb in question, do some preliminary
' commands if necessary (if the player needs to have an object
' in his/her hands, then Take it if the player doesn't have it.)
' See Commands:
'
DoCommand:
' Jump to the proper routine for the verb code.
'
PostProcess:
' The command goes here after it's done, and then returns to
' GetCommand (usually; unless the ask flag is set.)
'
'Command stack routines (manipulate the command stack)---
' These routines are used with Alias() to do another command before
' the command in question is completed. I.e., taking the book before
' reading it, etc. The stack is used to keep track of which commands
' are being executed at the moment, and which were executed, etc.
'
RecordCommand:
' Record last command on the command stack (push command stack)
'
ClearCommand:
' Clear current command (clear top of stack)
'
ClearList:
' Clear and record multiple noun lists
'
RestoreCommand:
' Restore recorded command (pop command stack)
'
' The subprogram Alias() is here.
'
Commands:
' The list of the actual commands, along with DATA statements specifying
' the kind of grammar allowed with that verb.
'
'Current commands implemented are---
Look: 'look around
Take: 'get stuff
Drop: 'drop stuff
Inventory: 'examine self
Examine: 'examine stuff
Go: 'go places
Place: 'put things in their place
OpenIt: 'open up things
CloseIt: 'close up stuff
Lock: '(stub implementation)
Unlock: '(stub implementation)
TurnOn: '(only works with the lamp)
TurnOff: '(ditto)
Wordy: 'always use long descriptions
Brief: 'normal descriptions (use long first, then short)
Superbrief: 'always use short descriptions
SaveGame: 'save a game to disk (should require minimal changes for
' each new adventure)
LoadGame: 'load a game from disk (ditto, but be sure to change this if
' you change the above)
PutOn: 'wear something (backpack, earring, etc. NOTE: if you wear
' a large container like a backpack, your load capacity increases,
' since if you put stuff in the pack, you don't tie up your hands)
TakeOff: 'take off something being worn
Wrap: 'wrap, tie, or roll up stuff
UnWrap: 'undo the above
Restart: 're-run the program from the beginning
Again: 're-parse the last cmd$ string (stored in ocmd$)
Empty: 'empty out a container or bottle
Fill: 'fill a bottle
Eat: 'eat edible stuff
Drink: 'drink water
Sit: 'sit on it
Stand: 'stand up
Lie: 'lie down (no, this has nothing to do with mendacity)
QuitGame: 'quit playing (WHAT!!???)
'
Map:
' These DATA statements hold the map connections, the conditional
' directions, and the conditional descriptions. A long explanation of
' the meaning of the statements is given here.
'
MapList:
' DATA statements start here for the map and descriptions.
'
Flags:
' DATA statements for the initial values of the flags. This code is
' also directly executed by Initialize:. (i.e., there is a GOSUB
' Flags in Initialize:). Put flag-related initialization code here
' as well as DATA statements. (i.e., there is a random flag that
' requires a RANDOMIZE TIMER, and so forth.)
'
Objects:
' All the attributes for the objects. A LONG explanation of
' what everything means is given here.
'
Objlist:
' Look here for the actual DATA statements.
'
Nouns:
' All nouns for the parser are listed here, including directions
' (north, south, etc.), abstract nouns (everything, you, it, etc.),
' and object specifiers and adjectives.
'
Abstract:
' Words to use when talking about the abstract nouns (the negative
' numbered nouns.) Since they do not refer to objects, descriptions
' must be given here.
'
Fold:
' Words to use to describe various states of being folded up.
'
Verbs:
' All the verbs recognized by the parser, listed with the three-
' word verb first.
'
Prepositions:
' All the prepositions and conjunctions recognized by the parser.
'
Prepnames:
' Words to be used when referring to prepositions.
'
'---------------------------------------------------------------------------
Dataformats:
'
'Quick Reference Guide to Data Formats:
'
' For more information, see the actual explanation under the label
'Objects: in the AmigaVenture program.
'
'
Objectformat:
' number,prefix,word,adjectives,long description
' location,parent,relation-mode
' size,weight
' inopening,wrapopening,onopening,underopening
' incapacity,wrapcapacity,oncapacity,undercapacity
' inopaque,wrapopaque,onopaque,underopaque
' open?,openable?,folded?,foldable?,locked?,holdwater?
' worn?,wearable?,soft?,food?,immobile?
'
' relation-mode: 0-in, 1-wrapped by, 2-on, 3-underneath
' folded?: 1-rolled, 2-folded, 3-tied up
' worn?: 1-hand, 2-head, 4-torso, 8-waist, 16-legs
' soft?: 1-chair, 2-bed
'
Locationformat:
Descriptionformat:
'
' number,N,NE,E,SE,S,SW,W,NW,U,D, light, on?
' light: 0-cave, 1-natural (depends on the value of flag(day)),
' 2-electric (depends on the values of on?)
' on?: 0-off (depends on lamp or natural light), 1-on (light is on)
' [flag,comparision,value,trueloc,falseloc,"falsemessage"]
' [..repeat as many times as there are map conditionals..]
' short description (one line)
' long description (lines terminated with a "" null string)
' [flag,comparison,value,verbosity condition
' conditional description (if above is satisfied, print this)
' terminated with a "" null string]
' [repeat above as often as necessary]
' -1,0,0,0 (this indicates the end of a location definition)
'
Commandformat:
' Note: there should be exactly as many commands as there are
' verbs definitions in the parser. The highest numbered verb is
' assumed to be the number of command definitions available.
' Each command requires the following data:
'
' require_direct_object?, require_indirect_object?
' 0-not required
' 1-visible
' 2-accessible
'
' default_preposition?
' 0-no default prep
' 1..nprep-default preposition
'
' direct_object_location, indirect_object_location
' 0-no checking
' 1-carried by the player only
' 2-not carried by the player, but in the room
'
' direct_obj_default_location, indirect_obj_default_location
' 0-anywhere
' 1-carried by the player
' 2-not carried by the player, but in the room
'
' number_direct_objects, number_indirect_objects
' 0-NONE
' 1-EXACTLY ONE
' 2-no checking
'
'If a command sets the *ask* varaible, control will go to the following
'places:
' ask = 0 : GetCommand (default)
' 1 : ContCommand (ask question)
' 2 : NewCommand (cancel current command, fatal error)
' 3 : Parse (start again)
'
'---------------------------------------------------------------------------
'
Subprograms:
'
'Quick Reference Guide to Subroutines and Subprograms:
'
' Subprograms are called with CALL. Subroutines are called with
'GOSUB, and are marked by a colon (":") following the name.
' Numbers in the array parentheses refer to the number of dimensions of
'the array. For further description of the routines, please see the
'actual program code.
'
'Message subroutines/subprograms:
'
' Cannot:
' CantSee(nn$)
' DontHave(nn$)
' CantGetAt(nn$)
' Absurd: - "Don't be absurd." or "Don't talk nonsense."
' Mystery: - "I can't see what you're referring to."
' AskAmbig(choice(2),num) - choice(2) is choice(listsize,1), where
' choice(,0) holds the list, and choice(,1)
' is used as temporary calculation space by
' the subprogram. num is the number of items found
'
'Calculation subprograms:
'
' Visible(noun,vis,type) - type: 0-anywhere, 1-on player, 2-not on player
' Avail(noun,ava,type) - type: 0-anywhere, 1-on player, 2-not on player
' CheckLight(light) - light: 0-dark, 1-lamp light, 2-moonlight,
' 3-twilight, 4-daylight
' NameNoun(n,n$,nn$) - returns n$, nn$
' ListSib(obj,array(2),count(1),nn) - nn: 0-direct object, 1-indirect obj
' - array(2) is array(listsize,1), where
' array(,0) holds a list for direct object,
' and array(,1) holds a list for indirect.
' The list that is used depends on nn.
' count(nn) returns # of items found
' EvalCond(a,b,c,ret) - Evaluates a flag conditional a,b,c and
' returns ret (see program code)
' RollDice - Puts a random value from 0 to 99 in
' flag(random)
' ListBottles(array(1),count) - bottles carried by player returned in
' array(). Number found in count
'
'List subprograms:
' Contents(obj,indent,sing) - sing: 0-all siblings, 1-just obj
' Remove(obj) - removes object from list, puts in limbo
' Insert(from-obj,to-code,mode) - code: positive-object, negative-location
' Setloc(obj,l,sing) - sing: 0-all siblings, 1-just obj
' RemList(code,mode,head) - removes child list from code/mode, returns
' first in list in "head"
' code: positive-object, negative-location
' Concat(head,code,mode) - concatenates list starting with "head"
' to end of the child list related to
' code/mode
' code: positive-object, negative-location
' Fill(obj,water) - obj must be a water container
' Empty(obj) - obj must be a water container
'
'Special subprograms:
' Tumble(obj) - knock everything on top off of it
'
'Command stack subroutines/subprograms:
' RecordCommand: - record current command on stack (push)
' RestoreCommand: - make last command recorded current (pop)
' ClearCommand: - clear current command (clear top of stack)
' Alias(v$,v,n,p,o) - push current command on stack and replace top
' of stack with a new command, with v$ set to the verb string,
' v the verb code, n the direct object, p the preposition,
' and o the indirect object. VERY useful for doing preparatory
' actions consistent with the design of AmigaVenture
'
'Interpreter subprograms:
' For all of the following, choice(2) is choice(listsize,1), where
' choice(,0) holds the list, and choice(,1)
' is used as temporary calculation space by
' the subprogram. num is the number of items found
' GetVerb(cmd$,v,v$) - returns v,v$
' ExNoun(cmd$,choice(2),nchoice,that) - returns extracted noun choices
' in choice(). "that" set true if "that" found.
' SkipNoun(cmd$) - skips all nouns found
' GetNoun(cmd$,choice(2),nchoice,n,vtype1,vtype2,that)
' - returns all sorts of information given
' all sorts of information (see program code)
' GetPrep(cmd$,p) - get preposition number, return in p
' ChooseVisible(choice(2),nchoice,vtype)
' - from choices given in choice(,0), select those visible
' - vtype: 0-anywhere, 1-on player, 2-not on player
' GetThatClause(cmd$,tp,tn) - extract a preposition and a noun
' from cmd$, return tp,tn
' SkipThatClause(cmd$) - skip next preposition-noun combination
' ResolveThat(choice(2),nchoice,n,tr,tn)
' - select those in choice(,0) that are related
' to object tn in relation-mode tr (i.e.,
' only those items "IN the FOUNTAIN", etc.)
'
'---------------------------------------------------------------------------
'
Variables:
'
' AmigaVenture Variables Quick Reference Guide
'
' A somewhat incomplete list of important variables in AmigaVenture.
'
Objectvars:
'
' Lfirst(l),Llast(l) -first,last in list of objects in location l
' pre$(n),word$(n),adj$(n),long$(n) -descriptions of object n
' lo(n),par(n),rel(n) - location, parent, relation-mode of n to parent
' rel(n) is zero in n is lying free in lo(n)
' first(rel,n),last(rel,n),left(n),right(n)
' - first,last in lists of objects related to n in relation
' rel, object to left,right in sibling list, (0 if
' first, last) see Objects: for explanation
' size(n),opening(rel,n),cap(rel,n),opaque(rel,n)
' - size, opening, capacity, opacity
' closed(n),openable(n),folded(n),foldable(n),locked(n),holdwater(n),
' worn(n),wearable(n),soft(n),immobile(n)
' totw(n),totb(n),bulk(rel,n) - total weight, bulk of object, bulk of
' everything related to n in relation rel
'
Constants:
'
'Some important constants:
'
' game$ - game title and version
' z$ - chr$(8)
' mdepth - maximum parser stack depth
' nverb - number of verbs (and thus number of commands)
' nloc - number of locations
' nflag - number of flags
' nobj - number of objects
' nbot - number of bottles (list of bottle kept in bottles())
' mlist - a goodly sized constant (around 30-50 or so)
'
'Some important arrays:
' lnoun(1,mlist) - holds lists of multiple objects
' nlnoun(1) - number of items in each list above
' ncount(1) - current item being processed
' olnoun(mlist) - old list of items (saved by RecordCommand)
'
'Command stack:
' rlev - current command stack level
' vo(rlev) - old verb (indexed by stack level)
' po(rlev),no(rlev,1) - old preposition, direct and indirect object
' vo$(rlev),po$(rlev),no$(rlev),nno$(rlev) - strings for same
'
'Parser variables:
' n$(1), nn$(1), n(1) - hold the direct and indirect object code and strings
'
'Miscellaneous variables and constants:
' l,ol - location, old location
' t = flag(tim) - time (in turns)
'
'Player's own parameters:
' maxcap, maxweight - player's carrying capacity and maximum weight
' maxgrab, maxlift - maximum size, weight, player can lift at once
' fat - size of player when sitting (fat*3 is size when lying down)
'
'BE SURE TO CHECK FLAGS: FOR ADDITIONAL CONSTANT DEFINITIONS.
'
'Locations:
'
' Don't even try to understand the following. Provided only as a
' cryptic guide to the intrepid. To actually use these, please
' consult the documentation in the program under the Map: label.
'
' mloc,avdes,mmcond,mfcond,avfcond - description list parameters
' map(,dir),dindex(),des$(dindex()),Llight(),Lon() - map,
' description index array, description string array, light, and on
' mcond(member,mindex),mmdex$(mindex) -map conditionals
' -member: 0-flag,1-comparison,2-value,3-loctrue,
' 4-locfalse
' findex(),fcond(member,findex()),fdes$(fdindex) -conditional descriptions
' -member: 0-flag, 1-comparison, 2-value, 3-verbosity
' condition, 4-fdindex
' (NOTE: dindex() and findex() index off of location number and use
' the next value in dindex and findex to determine the number of items
' or lines, by subtracting the next value from the current value.)
'