*** C Adventure Toolkit (CAT) - Introduction This file introduces the concepts behind the C Adventure Toolkit (CAT), tells you how to install it, and explains how it should be used. ****************************************************************************** The CAT system is shipped on a 720K MS-DOS formatted disk, with both PC and ST versions included. The ST can use MS-DOS format disks with no problems, so the system is available to users of both families of machines. The principle behind CAT is simple: You provide details of your adventure to CAT in a very high level language, which will be 'compiled' into C source code. Your generated C code can then be compiled, along with standard CAT C code, to produce your finished adventure! The code generated by CAT is portable - I have tested in on Sozobon C; MWC; and LaserC on the ST, as well as TurboC on the PC. The CAT system comprises of a generator program, standard definition files, and standard C code to be compiled with your generated code. The generator program (GEN.TTP or GEN.EXE) lives in the \CAT folder. The standard definition files live in the \CAT\STD folder. The standard C code files live in the \CAT\GENSRC folder. ****************************************************************************** To use CAT, you will need the following: PC == At least 512K memory. At least 720K floppy. A C compiler. A text editor that will write pure ASCII files. A vivid imagination A basic understanding of C is recommended. ST == At least 512K memory. At least 720K floppy. A C compiler. A text editor that will write pure ASCII files. A vivid imagination A basic understanding of C is recommended. Note: Whilst CAT will run happily with 512K on an ST, you may find that some memory intensive C compilers run out of memory when compiling the generated C code. Sozobon C is memory intensive - source generated by CAT will probably be too big to be compiled by Sozobon C with just 512K. MWC is disk intensive - this means it can compile far bigger programs, as all of its' work is done on disk, not in memory! ****************************************************************************** Installation: ============= 1) Make a back up copy of the production disk! 2) Copy the CAT folder, and all sub-folders to the root folder on your working drive. It is recommended that CAT is run from a Hard disk, but a floppy will be okay, as long as it is formatted to at least 720K. 2) If you are running CAT on a PC, modify your AUTOEXEC.BAT file to include \CAT in the PATH. Add this line to the end of the file... PATH %PATH%;\CAT 3) If you are running CAT on a PC, make sure that at least 30 FILES are available. You should have a line like this in your CONFIG.SYS file... FILES=30 4) If you are running CAT on an ST, and you are using a shell program (i.e. Gulam; MSH etc), then set your PATH environment variable to include \CAT - the command will be something like this for MSH... setenv PATH=$PATH,\CAT or this for GULAM... setenv PATH $PATH,\CAT rehash 5) If you are running CAT from a PC, you can delete any .PRG and .TTP files - these are for the ST version and you won't be needing them! 6) If you are running CAT from an ST, you can delete all .EXE and .BAT files - these are for the PC version and you won't be needing them! 7) You are now ready to use CAT! ****************************************************************************** The main program (GEN.TTP on an ST, or GEN.EXE on a PC), processes your adventure definition, and generates C code for your adventure program. When GEN starts up, it looks in the current folder for a file called 'GENLIST'. The GENLIST file should contain the names of each definition file that is to be used to generate the adventure source. These definition files can have any names, but it would be advisable to use the standard extendor '.d' e.g. - file1.d, file2.d file3.d. You can use any number of definition files to create your adventure. Each line in the GENLIST file can contain a simple file name, or a file with a pathname, and optionally a drive - so a typical GENLIST file may be: OBJECTS.D ROOMS.D MESSAGES.D LOGIC.D A:\MYSTDS.D \CAT\STD\ZZRQD.D \CAT\STD\ZZSTD.D The next thing GEN will do is look for a sub-folder from the current folder, called CSOURCE. This is the destination folder for the generated C code. If all is okay, GEN will begin it's work. As it works, GEN will display any potential errors it encounters on the screen, and these will also be written to the file 'GENOUT.TXT'. ****************************************************************************** You will notice the two standard defintion files ZZRQD.D and ZZSTD.D are included in the sample GENLIST file detailed above. These definition files are supplied with CAT, and provide the vast majority of the processing you need. You should use these files, or a version of them to create your adventure. ZZRQD.D - contains all the required definitions. CAT refers to anything that is defined in this file internally. You can change this file, but make sure all the names remain the same. ZZSTD.D - contains standard logic for your adventures. The definitions in this file are not referred to internally by CAT, so you can change anything contained in it. ****************************************************************************** The GEN program has the following command line options: -Spath - use this to specify the source folder. This option is useful if you are using GEN via the GEM desktop on the ST. The option forces GEN to change directory to the selected folder - i.e. the folder where your GENLIST lives. The -S option does not allow a drive to be specified. -L - This tells GEN to list the definition source as it processes it. -V - This tells GEN to give a verbose list of all possible errors it discovers. By default, GEN only reports the more rare and possibly hazardous errors. -E - This tells GEN to encrypt the code it produces, safe from prying eyes. You should always use this option when producing a finished copy of your adventure. -C - This 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. -I - This tells GEN to print the names of all the items that are defined. By default, GEN only reports those items that are defined but are not directly referred to. -F - This tells GEN to do full logic checks. i.e. it makes sure that low priority logic is only used in low priority logic, that logic tests are not used in commands, that logic tokens are recognised tokens, etc. This switch is additional to -V. -R - Perform a report only run. Do not write any files. This is FAST, and allows you to easily check the syntax of your source. -Dpath - Specify the destination path (override default of CSOURCE). This can include a drivespec. The path should be direct i.e. -DF:\output or relative to the folder to where the GENLIST file lives i.e. -Dtest\output. This option is useful if you want to direct the output to a ramdrive - much faster! -Apath - Autocopy GENSRC files to destination folder. By default, the GENSRC files will be copied from \CAT\GENSRC, but you can optionally specify the folder where GEN can find GENSRC files. The folder can include a drivespec. GEN -E -I -F would look for a GENLIST in the current folder, encrypt all output, and produce a list of all the items that were defined. Full logic checking will be performed. GEN -S\ADVENT -V -L would look for a GENLIST in the folder \ADVENT. It would list the definition files as it processed them, and give a verbose list of ALL errors. It would not encrypt the generated C source. Only those items that are defined but not directly referred to will be listed. Full logic checking will not be performed. GEN -R would look for a GENLIST in the current folder, and perform a report run. GEN -A -E would look for a GENLIST in the current folder, encrypt all output and automatically copy the GENSRC files from \CAT\GENSRC. GEN -AA:\CAT\GENSRC -S\AWE -Df:\ would look for a GENLIST in \AWE. Output would be created in F:\ - GENSRC files would be automatically copied to F:\ from A:\CAT\GENSRC. ****************************************************************************** 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 ****************************************************************************** Once your C source has been generated, if you didn't use the -Autocopy option, then you will need to copy all the files from the \CAT\GENSRC folder into your destination folder (CSOURCE by default). After this, you can compile your adventure with your favourite C compiler. If you are compiling on a PC, you must define PC, and use the large model i.e. TCC *.c -DPC -ml FAILING TO DEFINE PC WHEN COMPILING A PC ADVENTURE WILL RESULT IN FAILURE! ****************************************************************************** Two batch files have been supplied, with PC and ST versions of each: The first batch file (GEN1) generates encrypted C code in CSOURCE, and copies all the standard C files from \CAT\GENSRC into CSOURCE. The second batch file (GEN2) compiles the C source in CSOURCE, and produces the runnable adventure program 'ADVENT' in the current folder. ****************************************************************************** ST version of GEN1 - suitable for MSH (and possibly Gulam?) GEN1 ---- gen -e -a ****************************************************************************** ST version of GEN2 - suitable for MSH (and possibly Gulam?) GEN2 ---- cd csource cc *.c -o advent.prg mv advent.prg .. cd .. ****************************************************************************** PC version of GEN1 - suitable for Turboc GEN1.BAT -------- gen -e -a ****************************************************************************** PC version of GEN2 - suitable for Turboc (In my case the TurboC libraries live in D:\PC\TURBOC TurboC header files live in D:\PC\TURBOC\INCLUDE) GEN2.BAT -------- @cd csource tcc -Ld:\pc\turboc -Id:\pc\turboc\include -ml -DPC -eADVENT.EXE *.c @copy advent.exe .. @cd .. ******************************************************************************