This folder contains details on how CAT source can be interfaced to your own

custom C code. I would not recommend you use the techniques discussed in this

folder until you have at least a basic understanding of CAT and C.



These features will allow the advanced user to provide functionality not

normally provided by the standard CAT package - maybe graphics or music,

or simply turning the mouse pointer off in first logic, and back on again

in last logic?



  or maybe you could use these techniques to perform repetitive functions?

  

******************************************************************************



You can have one custom C source file in your Csource folder. This file should

be named 'x.c' and should have the following lines included at the top:



#include "xdef.h"	/* Definitions of all Items in adventure */

#include "xlang.h"	/* CAT -> C interface macros */

#include "xfuncs.h"	/* Return values of CAT internal functions */

#include "xglobals.h"	/* Global variables */



(Note - xlang.h #includes <stdio.h> so you will not need to #include stdio.)



******************************************************************************



You can write your own custom C functions in your csource\x.c file, and you can 

call these functions, or even standard C library routines from within CAT

logic. Your custom functions can include both standard C code, and CAT logic,

but CAT logic should be specified in UPPER case, and WITHOUT the preceding '@'.

You cannot use low priority CAT logic in your custom C code.



Unlike normal CAT logic, when calling external C functions, you should use 

braces even if the function has no parameters. i.e. _testfn()



*******************************************************************************



You can reference objects, verbs, messages, rooms and strings by name, but you

MUST use upper case and prefix the names with their identifier, i.e. 



	R_BEDROOM	a room number

	O_LAMP		an object number

	V_GET		a verb number

	M_SORRY		a message number

        S_S1            a string number

   strp[S_S1]           a string

	

*******************************************************************************



The names chosen for your C functions are important - CAT looks at the name of

the function to determine which type of item is being passed. Additionally,

each external function should begin with an underbar '_', so that CAT knows

it is an external function. This underbar will be stripped before placing

the call to the external function - it is just there to let CAT know that this

is an external function.



  The type of the first parameter passed to a function is always determined

  by the name of that function. All further parameters will be objects. You

  can bypass these rules if you use @MSGNO, @OBJNO, @ROOMNO, @STRNO when

  passing the parameters. 

  

  If the name contains 'room', then the first parm is a room.

  

  If the name contains 'msg', then the first parm is a message.



  If the name contains 'verb', then the first parm is a verb.



  If the name contains 'str' but doesn't contain 'strength' or 'tostr', then 

  the first parm will be a string.



  If the name matches none of the above, then first parm is an object.



*******************************************************************************



Your custom C functions can return values to CAT logic.



*******************************************************************************



You can have a look at interfce.d and csource\x.c for examples.



Globals.txt details the globals variables that are available to you.



*******************************************************************************



If you are writing machine specific C code in your x.c file, you can condition

it by target machine, with the identifiers ST and PC. e.g.



#ifdef ST

   /* ST specific code */

#endif



#ifdef PC

   /* PC specific code */

#endif



*******************************************************************************



One final note, these techniques leave CAT WIDE OPEN - it is possible to use 

them to add features that would not have been possible otherwise, but it is 

also possible to completely hash up your adventure!! Be warned!



*******************************************************************************

