@rem This file introduces the new features of version 2. @rem I have not provided a tutorial for these new features, but documentation and old tutorials have been updated where appropriate. It is presumed that by the time you have completed the five tutorials, then you will have a firm enough understanding of CAT to use this document as it stands. @rem If you have created an adventure with CAT V1, you can just regenerate it using CAT V2, and then re-compile it. This will give your adventure all the new features of V2. The only thing that you should be aware of is that V1 game save files will no longer load - and may crash your adventure if you attempt to load them. @rem ************************************************************************* @rem GEN now supports a further 4 switches as follows: -R Tells GEN to perform a report only run. The only file that will be written is GENOUT.TXT. This switch is useful if you want to check the syntax of your definition files, without wasting all the time involved in creating C source. -C This switch tells GEN to compress the text in your adventure. WARNING: compressing adventures with small amounts of text may result in LARGER programs being generated. Compression will be most successful in games with a lot of text. -Apath This switch tells GEN to automatically copy GENSRC files from \CAT\GENSRC to the destination folder. A path can be optionally specified, telling GEN where the GENSRC files live on your system. -Dpath This switch tells GEN where to place the source it generates. For example, you could write all source to a ram drive with this option - thereby considerably reducing generation time. @rem ************************************************************************* @rem GEN switches can now be specified in your GENLIST file. Any switches included in the GENLIST file will override conflicting switches from the command line. For example, the following GENLIST will automatically copy GENSRC from \CAT\GENSRC, and output will be encrypted. -e -a \cattutr5\first.d \cattutr1\tutor1.d \cattutr2\tutor2.d \cattutr3\tutor3.d \cattutr4\tutor4.d \cattutr5\tutor5.d \cat\std\zzstd.d \cat\std\zzrqd.d \cattutr5\last.d @rem ************************************************************************* @rem GEN will now report on any text that is over 254 characters, and is therefore likely to be unportable between compilers. The default action of a C compiler is to lop off the extra characters and say nothing - so it is important that GEN provides this check. @rem ************************************************************************* @rem The " character can now be used in any text, as can the \ character. @rem ************************************************************************* @rem @FIRST and @LAST logic modes are now supported. FIRST logic is executed as soon as the program loads.... before the title screen is displayed AND before any decryption takes place. LAST logic is executed just before the program ends. A typical use of @FIRST and @LAST logic processing would be to turn the mouse off in FIRST processing, and back on again in LAST processing. Note: you will still need to use external functions to actually perform the task of turning the mouse on and off. @rem ************************************************************************* @rem @ROOMSEEN can now be used to determine whether or not a room has been visited. CAT already had this information, but it was not accessible through CAT logic. @rem ************************************************************************* @rem Remarks can now be included in logic groups, for example. @rem this is a comment @if @iscarried(hammer) @do @rem This is another remark - covering two lines @pmsg(carrying_hammer) @rem another comment @pmsg(testing) @endif @rem That's all folks! @rem ************************************************************************* @rem Full string support is now available. Ten strings are automatically provided, with sizes as follows: S1 - 200 characters S2 - 200 characters S3 - 100 characters S4 - 100 characters S5 - 100 characters S6 - 100 characters S7 - 50 characters S8 - 50 characters S9 - 50 characters S10 - 50 characters It is also possible to create up to 90 of your own strings. Only the ten automatic strings will be saved as part of saved games, therefore - you should only use the automatic strings to store information that is relevant to the current game position. You can use your own strings to contain temporary data, or to hold any text that will never change - i.e. comparison strings etc. Strings can be defined with initial text, and this text will be restored whenever the adventure is restarted. The following tokens can be used to define strings: =================================================== @STR name - give the string a name @STRSIZE - define size of string (up to 254 characters). The default size of a string is 254 characters. @STRTXT - Initial value of string. @ENDSTR - End of string definition. The following tokens can be used to query strings: ================================================== @STRNO(str) - return number of str. @STRLEN(str) - return length of str. @STRASC(str) - return ascii code of 1st character in str. @STRNUM(str) - returns the numeric value contained in str. @PSTR(str) - prints str. @STRFCHR(str,c) - return position of character c in str, or -1 if no match. @STRFSTR(str1,str2) - return position of str2 in str1, or -1 if no match. @STRCMP(str1,str2) - returns 0 if str1 and str2 are the same. <0 if str1 is less than str2. >0 if str2 is greater than str2. The following tokens can be used to affect strings: =================================================== @MSGTOSTR(msg,str) - copy msg into str. @NUMTOSTR(val,str) - Convert val to a string, and save in str. @OLTOSTR(obj,str) - Copy object long text to str. @OSTOSTR(obj,str) - Copy object short text to str. @RLTOSTR(room,str) - Copy room long text to str. @RSTOSTR(room,str) - Copy room short text to str. @GETSTR(str,size,sep) - get input from the player and place in str. size is the maximum number of characters. If sep is 1, separators will be allowed. If sep is 0, separators will NOT be allowed. @STRCLR(str) - clear str. @STRUPP(str) - convert str to upper case. @STRLOW(str) - convert str to lower case. @STRCAP(str) - convert first character of str to upper case. @STRADDC(str,c) - adds character c onto end of str. @STRCPY(str1,str2) - copies str2 onto str1. @STRCAT(str1,str2) - concatenate str2 onto str1. @STRPCPY(str1,str2,s,l) copies part of str2 into str1. s= start position l= number of characters to copy. *** WARNINGS *** When referring to a CAT string, you are actually referring to a number, it is therefore very important that you do not use standard C functions to access them - always use the CAT logic tokens. The first character of a string is in position 0, and NOT 1. With any string functions where a string name appears anywhere other than as the first parameter, you must use @STRNO to convert the parameter to a string - otherwise CAT will presume the parameter is the number of an object. I.e. @rem Copy characters 10-14 from MY_STRING into S1. @STRPCPY(s1,@strno(my_string),10,5) It is your responsibility to ensure that you do not write past the end of any given string - i.e. if a string is defined with @STRSIZE 50, then make sure it never contains more that 50 characters. IF THIS HAPPENS, UNPREDICTABLE RESULTS MAY OCCUR! @rem ************************************************************************* @rem Macros can now be included in any piece of text - these will be expanded whenever the text is displayed as follows: $1, $2, $3, $4 etc. - replaced with value in 1st, 2nd, 3rd, 4th string etc. #1, #2, #3, #4 etc. - replaced with value of 1st, 2nd, 3rd, 4th counter etc $A - replaced with the actor, from command line. $V - replaced with verb, from command line. $VC - replaced with compound verb, from command line. $N - replaced with noun, from command line. $NC - replaced with compound noun, from command line. @rem For example, the following would print: BOB: "I have no time to PUT KEY IN BED" ... (If the user issued the command 'bob, put the key in the bed') @str tmp_str @Rem String number 11 (1-10 already defined) @strtxt I have no @endstr @msg tmp_msg @msgtxt $A: "$11 time to $V $N $VC $NC" @endmsg @low @if @playeris(bob) @do @pmsg(tmp_msg) @endif @rem ************************************************************************* @rem Verb checking will now tell you which object is in error. For example if the user typed 'Put the key in the box', and the box was not available, then the adventure would have just reported: You don't see that here. Now, you will get: BOX: You don't see that here. @rem ************************************************************************* @rem A command line interface has been provided for user input in adventures. The following keys map as follows: 7 8 9 \ | / The numeric keypad can be used for directional movement. (i.e. 8-North, 3-Southeast etc) 4- 5 -6 / | \ additionally 5-Up and 0-Down. 1 2 3 [ Repeat last command line ] Delete entire command line * Delete one word from command line Ctrl(A) Repeat last verb B Repeat last noun C Repeat last compound verb D Repeat last compound noun E Examine F Drop G Get I Inventory J Jump K Kill L Look N No O Open P Close Q Quit R Restore S Save T Lock U Unlock V Vocabulary W Whoami X Exits Y Yes Z Copyright line @rem The standard advertisement has been changed to include details of these command line editing keys. @rem ************************************************************************* @rem A new program (CATHELP) has been provided to allow quick access to the Cross reference manual CATMAN.TXT. When you supply keywords to CATHELP, it will scan the manual for headings that contain your keywords, and display each of the matching sections. You can supply as many keywords as you like. For example, the following command would find all topics relating to strings, and messages: CATHELP str msg Or this would find details of all definition tokens: CATHELP defin Or this would find all details to do with logic: CATHELP logic CATHELP will look in the current folder, the root folder, the \CAT folder and the \CATSRC folder for a CATMAN.TXT file. If it doesn't find the file in any of these folders, it will give up. If you are running CATHELP from the GEM desktop, then you will have the opportunity to type your keywords on the parameters screen. @rem ************************************************************************* @rem The player can now use 'EXCEPT' in commands. For example: GET ALL EXCEPT THE HAT. PUT EVERYTHING EXCEPT THE KEY INTO THE CHEST. @rem ************************************************************************* @rem RAMSAVE and RAMLOAD are now supported to allow the game position to be saved to memory. @rem ************************************************************************* Runnable adventures for CATTUTR4 have been removed due to disk space crisis! @rem ************************************************************************* @rem And finally, for CATEXPRT users.... @rem External functions are now called WITHOUT the preceding underbar (_). You still need to use the underbar in CAT source, but this will be stripped before the call is placed in the generated C source. This change will allow the advanced user to call C library functions, as well as their own custom C functions - DIRECTLY from CAT source. @rem For portability reasons, all machine specific code from the GENSRC files has been moved to a separate file - PORTAB.I. This should greatly smooth the efforts required to port CAT adventures to another machine. @rem ************************************************************************* *** VERSION 1.0 PROBLEMS CORRECTED AS FOLLOWS: *** @rem ************************************************************************* @rem The @RANDOM function was returning negative numbers on some C compilers. This should now be fixed. @rem ************************************************************************* @rem In version 1, expressions like @PVAL(1*2+tony/apple) were not being processed properly. With version 2, the above expression will be correctly parsed to: PVAL(1*2+O_TONY/O_APPLE) @rem ************************************************************************* @rem @FIRSTOB and @LASTOB will now include objects that are worn. @rem ************************************************************************* @rem Counters are now reset to zero at the start of every game. @rem ************************************************************************* @rem Not all messages were encrypted/decrypted properly. This has been corrected. @rem ************************************************************************* @rem @ENDGAME can now be used in initialisation logic. @rem *************************************************************************