Quest Four files are included in Quest. Three provide independent libraries of useful utilities which are the framework of any Quest scenario. The fourth is a simple sample scenario. The sample scenario doesn't do anything, but does illustrate the use of the rest of the system, and provides a working demo of most of the facilities. qcrt.d - CRT routines. These routines handle a 24 line by 80 column screen. Even though the sizes are parameterized as constants (NLINES and NCOLUMNS), it is not likely that the code would work properly with a different size screen. All routines whose names begin with 'CRT_' are in my CRT library. The routines used are: CRT_Initialize(*char title; ushort nLines, nCols) - open a window of given size and set its title CRT_Terminate() - closes the window CRT_ClearScreen() - clear the screen & leave cursor at (0, 0) CRT_ClearLine(ushort line) - clear line & leave cursor at (line, 0) CRT_Abort() - close window and return to system cleanly CRT_Move(ushort line, column) - move the cursor to the indicated (0-origin) line and column on the screen CRT_EnterHighLight() - output after this will be highlighted, e.g. in a different color CRT_ExitHighLight() - output after this will be normal CRT_ClearTail() - the current line from the cursor to the last column is cleared - the cursor is not moved CRT_ClearToEnd(ushort line) - the cursor is moved to the beginning of the given line and the screen is cleared from there on down CRT_PutChars(*char string) - the given string is output to the screen at the current cursor position CRT_PutChar(char ch) - the character is output to the screen CRT_ReadChar()char - wait for and read a character from the terminal CRT_GetLine(*char buffer; ushort length) - this routine reads an input line of the given maximum length into the buffer. Input line editing (backspace, line delete) is enabled. The upper left-hand corner of the screen, 11 lines by 38 columns, is used to display an 11 line by 19 column region of a "scenery map" which is a sort of bird's eye view of the region around the player character (PC) or group. Each 'cell' in the map is represented by two characters, side by side. The CRT routines maintain this view by calling a user- supplied scenery generator, which, given the line and column co-ordinate, returns the pair of characters to display for that position. Also maintained is a list of 'movable objects' which are not considered part of the scenery. Each has a pair of characters to display. They are displayed 'over top of' the scenery, and the last such specified at a given position is the one displayed. Each has an identifier by which the user programmer can refer to it. The one with identifier = 0 is assumed to be the PC or group, and if it is moved to or off of the edge of the viewing area, then the entire map view is windowed (which will entail a number of calls to the user-supplied scenery generator). The upper right-hand corner of the screen, 11 lines by 40 columns, is used to display various status indicators needed by the scenario. There are three kinds of status indicators: numeric, string and string- list. These are set up by calling the appropriate routine with a numeric identifier for the item, it's header string, it's position in the status area (line, column of the first character of the header), and the item's size. These routines are also passed the address of the actual variable which records the current value, so that a simple call to 'scUpdate' can update the status display directly. String-list items are used for things such as the list of things the PC is carrying - the update routine handles correct formatting for multi-line display with separating commas. Instead of being given the address of the list header, the 'scMult' routine is passed a procedure which it is to call to get successive strings to display. The bottom 12 lines of the screen are used for text input/output as occurs in most Adventure style games. When the bottom of the screen is reached, the area is cleared and I/O continues on the first line of the region. If the bottom is reached during output, then the output pauses until the end-user types a key to continue (my version displays 'MORE', highlighted, down the right-hand edge of the region). The output routine handles one character at a time. This allows me to use it as a Draco text output channel through which I can 'write' or 'writeln' whatever I need to output. Output in this way will automatically do word breaks at the correct place. (This means that, unless special output formats are needed, text can be output in one big continuous stream, and will be automagically broken on word boundaries.) All CRT routines have names beginning with 'sc'. They are: Miscellaneous routines: scInit() - this must be called once before any other calls. scTerm() - called to free up resources used by CRT routines. This also calls CRT_Terminate to terminate the entire program. Map area routines: scNewMap(proc(long line, column)[2]char scenery; *byte oldObj)*byte - this fancy header indicates that 'scNewMap' has 2 parameters and returns a result. The first parameter is a procedure which takes two long integer parameters and returns an array of 2 characters - this is the scenery generator mentioned above. The second parameter is the list of "movable objects" associated with the map. This is usually just 0, but is used when a scenario involves more than one map (it preserves the "movable objects" between uses of the map). The value returned is the "movable objects" list that used to be active. This routine must be called before the map area is used for anything. scObjFree(*byte ol) - free any object list left behind from other map areas by calls to scNewMap. The list currently active is freed by scTerm. scWindow(long line, column) - forces the map area to be redrawn, centered on the given co-ordinates. scNew(Id_t id; long line, column; [2]char chars) - this routine is used to create a new "movable object". The id is used to refer to the entry when moving or deleting it. The line and column are where the object is now, and the two characters are what to display for it. scAt(long line column)[2]char - return the pair of characters which is currently displayed at the given position. scMove(Id_t id; long line, column) - the specified "movable object" is moved to the given location and redisplayed (if within the window). scDelete(Id_t id) - the specified "movable object" is removed and can no longer be referenced. Status area routines: scNumber(Id_t id; *char name; ushort line, column, length; *long ptr) - this routine is used to create a numeric status display. 'name' is the string to use for a header, 'line' and 'column' specify where in the status area to display the item, 'length' is the number of spaces to use for the numeric display (format is 'HEADER: xxxx'), and ptr is the address of the variable which is being displayed. ( This address is saved away so that calls to 'scUpdate' can cause a re-display without having to pass in the new value.) scString(*d_t id; *char name; ushort line, column, length; **char ptr) - this routine is used to create a string status display. 'length' is the length of the string to be used (it will be padded on the right or truncated as needed). 'ptr' points to the string variable. scMult(Id_t id; *char name; ushort line, column, lines; proc(bool first)*char gen) - this routine is used to create a string-list status display. 'lines' is the number of lines reserved for this item (successive lines start in the 3rd column of the status display area). 'gen' is a procedure to call to get the items to be displayed in the list. It has a parameter telling it to start over since, if the items won't fit in the available space, the display process will prematurely stop calling it. If the items won't fit in the available lines, the last one is followed by '..' to indicate that there were more items. scUpdate(Id_t id) - the specified status item is re-displayed. Once the display items are set up, this is the only display item routine that will be needed. Text I/O routines: scPut(char ch) - this routine is called to output a character in the text area. Word break and pagination is handled as discussed above. The character '\n' (linefeed) are used to signal the need for a forced newline. scPrompt(*char prompt) - this routine is called to specify the prompt to use on input. scRead(*char buffer) - an input line is read into the passed buffer. If any text was left to be output (it is buffered up to allow for the word-break processing) it is output first and a new line started. Any prompt is output before the read is done. qparse.d - the parser. The parser is fairly simple but will handle a variety of input styles, ranging from the simple 'get book' to the more complex 'Put the magic sword into the glass trophy case.' No provisions are currently present for having multiple commands on one line unless the grammar specifies it directly (quite cumbersome). Prefixes, consisting of words before an initial ':' can be picked off, but this facility will probably not be used (see later). These routines handle the dictionary, which contains words, along with their id (should be unique) and type (the parser places no interpretation on types, but they are needed). The words are stored directly as given (any characters can be used), but when the parsing occurs, case will be ignored. Also, when parsing, spaces are used as word separators, so having 'words' with spaces in them will not work. The grammar parsed consists of a number of sentence forms, each of which is simply a list of elements. An element can be a specific word which is required, a specific word-type which is required, an optional specific word, an optional word-type or a sequence of words of a given type. For example, the grammar sentence give [ARTICLE] ADJECTIVE* NOUN to [ARTICLE] ADJECTIVE* NOUN [PUNCTUATION] could be used to handle the verb 'give'. Input sentences like Give the big red rose to the ugly dwarf. give sword to troll would be accepted (provided the words were in the dictionary and had been flagged with the appropriate types). The various sentence forms are tried one at a time to match the input commands, thus the ones given first will take precedence over later ones in case of ambiguity. All parser routine names start with 'ps'. They are: psInit(bool prefixEnabled) - must be called once before any other parser routines are used. If 'prefixEnabled' is true, then prefixes ending with ':' will be picked off of input sentences, otherwise they are handled as part of the input sentence. Even when such prefixes are used (e.g. to talk to NPC's), it is probably better to have separate grammar rules for the things that can be said to NPC's, instead of having these things mixed in with the rules for direct commands. The whole area needs more thought. psTerm() - called at the end of the run to free up space used by the stored dictionary and grammar, and any working storage used by the parser. psWord(Id_t id; *char txt; Id_t typ) - the given word is added to the dictionary with the given id and word-type. More than one entry with the same id can be added - they are synonyms. Punctuation 'words' are added in the same way. psDel(Id_t id) - called to delete the specified word from the dictionary. psgBegin(Id_t id) - called to start the specification of a grammar rule with the given id. psgWord(PSForm_t form; Id_t data) - called to add an element to a grammar rule. PSForm_t is an enumeration type with values f_reqId, f_reqType, f_optId, f_optType, and f_multiple which is included in q.g. The five element types were discussed above (required word of given id, required word of given type, optional word of given id, optional word of given type, multiple words of given type). The 'data' parameter is either the id or word-type, as needed. psgEnd() - called to signal the end of a grammar rule. Grammar rules can be added at any time, as can dictionary entries; thus the language can grow as the game progresses. psgDel(Id_t id) - delete the specified grammar rule from the grammar. psFind(*char txt)Id_t - looks a word up in the dictionary. Returns the id of the word, or 0 if the word isn't found (thus id = 0 should not be used for any word). psType(Id_t id)Id_t - returns the word-type of the identified word psGet(Id_t id)*char - returns the text of the identified word psParse(*char sentence)Id_t - this routine parses the given input string according to the currently existing dictionary and grammar rules. It returns: PS_ERROR if some word in the input is unknown (call pspBad to get the text of the word); PS_BAD if all words were known but the input didn't match any of the grammar rules; else the grammar rule number of the matched rule For a successful match, 'pspWord' and 'pspPref' can be used to find more details. pspBad()*char - called after pspParse has returned PS_ERROR to get the text of the word which wasn't in the dictionary. (The parser stops as soon as it finds one, so there will only be the one.) pspWord(uint pos)Id_t - returns the id of the word(s) that matched the 'pos'th position in the successful grammar rule. For optional elements, 0 is returned if no word was there. For multiple elements, successive calls to 'pspWord' with the same 'pos' will return the various words that matched. No more (or none at all) is signalled by 'pspWord' returning 0. pspPref()Id_t - After psParse when prefixes are enabled, successive calls to this routine will return the id's of the words that were part of the prefix (the stuff before the first ':'). To handle prefixes like 'Dan, Joe:', comma should be made a word and will be dutifully returned by pspPref. (The ':' is thrown away.) pspPref returns 0 when there are no more prefix words (if there were any at all). qlist.d - list handling routines. These routines are used for handling semantic information. They care nothing about meanings - they are just general tools. One set of routines (names start with 'l') simply handles lists of integers ( adding, appending, deleting, etc.) Another set handles properties ( essentially arbitrary boolean (true/false) flags) associated with identifiers. A third set handles attribute-value pairs associated with identifiers (things like (size 2), (weight 20), (color red), etc.). lInit() - this routine must be called before any others in this set. lFree(*List_t il) - called to free a list for the user program. lTerm() - called to free up all list structures at end of run. getId()Id_t - called to get a unique integer id. The values returned on consecutive calls are just 1, 2, 3, etc. Note that this routine was never used in the sample scenario program, since all id's were needed to be known in several places. Simple list handling routines. Type List_t given in q.g defines the elements of the lists. A list variable is of type *List_t. lAdd(**List_t pil; Id_t n) - the value 'n' is added to the front of the list. No check is made to see if it is already in the list. lAppend(**List_t pil; Id_t n) - the value 'n' is appended to the end of the list. No check is made to see if it is already in the list. lDelete(**List_t pil; Id_t n) - the first occurrence (if any) of the value 'n' is deleted from the list. lGet(*List_t il; ulong n)Id_t - the value of the n'th element of the list is returned (if any, else 0). lIn(*List_t il; Id_t n)bool - returns 'true' if the value 'n' is in the list, else returns 'false'. Property handling routines. putProp(Id_t id, prop) - associates property 'prop' with item 'id'. getProp(Id_t id, prop)bool - returns 'true' if property 'prop' is associated with item 'id', else returns 'false'. delProp(Id_t id, prop) - ensures that property 'prop' is not associated with item 'id'. Attribute-value handling routines. putAttr(Id_t id, attr, val) - associates attribute 'attr' with value 'val' with item 'id'. Any previous association is replaced. getAttr(Id_t id, attr)Id_t - returns the value for attribute 'attr' associated with item 'id', else 0 if none. delAttr(Id_t id, attr) - dissassociates attribute 'attr' from item 'id'. qmain.d - sample scenario. If you are going to study any of the Quest source files, it should be this one. Writing a scenario does not require studying of the others, but this one is a must. I won't describe here what it does, but instead refer you to the comments in the file itself. You may have to refer back to the above descriptions, so you'll probably want to load the two files into an editor and read them that way.