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 initialisation logic?



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

  

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



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 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 and rooms by name, but you MUST

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



	R_BEDROOM	a room

	O_LAMP		an object

	V_GET		a verb

	M_SORRY		a message

	

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



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.



  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 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 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.



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



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!



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



