home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / games / gkit.zip / GKIT.DOC < prev    next >
Text File  |  1988-05-05  |  13KB  |  265 lines
  1.              **********************************************
  2.              *  PLEASE READ THE FILE  GRULES.DOC  FIRST!  *
  3.              **********************************************
  4. /*=====================================================================*/
  5.              GATEWAYS DEVELOPMENT KIT DOCUMENTATION
  6.  
  7.  
  8. 05/05/88.. The first official release.  Look for New features highlights
  9.            in this spot of the next version.
  10. /*=====================================================================*/
  11.  
  12.                 FILES you should have:
  13.  
  14. GATEWAYS.H  A header file that you must include in all your modules
  15. G0KIT.C     The test functions and main() driver function
  16. D0MAIN.C    A simple example gateways game
  17. D0MAIN.H    An example header file for the example game
  18. D0QUEST     File of quiz questions used by D0MAIN
  19. D0MAIN.PRJ  Project file to use with Turbo C
  20. D0MAIN      Makefile to use with Microsoft C 5.0
  21. MAKEFILE    Makefile to use with IBM Aztec C
  22. /*=====================================================================*/
  23.  
  24.                 GATEWAYS.H features:
  25.  
  26. GATEWAYS.H contains overgame define macros and compiler specific stuff.
  27. It is not the place for you to add macros and declarations specific to
  28. your game (Create a file like D0MAIN.H and include it in all your files).
  29.  
  30. Be sure to #include "GATEWAYS.H" at the top of all your game modules.
  31.  
  32. You will need to edit GATEWAYS.H and indicate which compiler you are using
  33. and what features it supports. The compilers currently supported are
  34. IBM Turbo C, IBM Microsoft (or Quick C), IBM Aztec C, CP/M Aztec C, Amiga
  35. Manx (Aztec) C.
  36.  
  37. If your compiler is not supported, you will need to add a #define for it
  38. and implement statements in GATEWAYS.H and G0KIT.C to support it. Feel free
  39. to ask me for help and BE SURE TO SEND ME A COPY OF THE CHANGES RIGHT AWAY.
  40. Be sure to place any include statements for include files that come with your 
  41. compiler in GATEWAYS.H if needed by your game, or in G0KIT.C if only needed 
  42. by the kit functions. Do not include any H files of your own creation in 
  43. GATEWAYS.H.
  44.  
  45. Later you will indicate the name of you entry function to your game
  46. (see GAME in GATEWAYS.H)
  47.  
  48. You can turn on/off kit validation with VALIDATE.
  49.  
  50. You can customize carrier loss simulation with SIM_CARRIER and C_LOSS_P.
  51. Before submitting your game, Please reduce C_LOSS_P and thoroughly test
  52. the effects of carrier loss on your game.
  53.  
  54. You may be able to have the pseudo random numbers start at the same number
  55. to reproduce results by changing RANDOM_START to 0.
  56.  
  57. Use MAX_PLAYERS as the maximum number of players in the game for setting
  58. aside storage.
  59.  
  60. Set NUMGATES for the number of gates (exit/entry points) you want in your
  61. game.. Do not use this macro..use the value passed to your entry function
  62. only.
  63.  
  64. There are some global variables for your use in GATEWAYS.H:
  65.  
  66. char gss[gss_SIZE]; A character array suitable for temporary string use
  67. void *gp0,*gp1,*gp2,*gp3,*gp4,*gp5,*gp6,*gp7,*gp8,*gp9;
  68.         Pointers to use to keep track of og_malloc()'ed memory
  69.                                  see og_malloc() and og_onexit()
  70. int gfd0,gfd1,gfd2;              use for file handles
  71. int gflag0,gflag1,gflag2,gflag3; use for global bitmaps
  72.  
  73. /*=====================================================================*/
  74.  
  75.                       LIBRARY FUNCTIONS
  76.  
  77. Here is a list of functions that your compiler may have that I think are
  78. currently ok to use. This list is subject to change.  Please do not use any
  79. functions not listed without asking first.
  80.  
  81. memcpy(void *dest,const void *source,int count);
  82. memset(void *dest,int c,int count);
  83. double atof(const char *string);
  84. int atoi(const char *string);
  85. long atol(const char *string);
  86. long lseek(int handle,long offset,int origin);
  87. int sprintf(char *buffer,const char *format[[,argument]]...);
  88. double acos(double x),asin(double x),atan(double x),atan2(double x, double y);
  89. double ceil(double x),cos(double x),cosh(double x),fabs(double x);
  90. double fabs(double x),floor(double x),log(double x),log10(double x);
  91. double sin(double x),sinh(double x),sqrt(double x),tan(double x);
  92. double tanh(double x);
  93. strcat(char *dest,char *source);
  94. int strcmp(const char *string1,const char *string2);
  95. strcpy(char *dest,char *source);
  96. int strlen(char *string);
  97. int strncmp(const char *string1,const char *string2,int n);
  98. strncpy(char *dest,char *source,int n);
  99.  
  100. /*=====================================================================*/
  101.  
  102.                 G0KIT.C FUNCTIONS
  103.  
  104. If you have ideas for changing any of these functions or adding more, please
  105. contact me.
  106.  
  107. Your entry function will be passed the player#, current# of players,
  108. the gate number the player came in by, and max # of gates that your
  109. game supports. The gate number may be used by the overgame in linking
  110. the games together.
  111.  
  112. example:   int d0main(plnum,numplayers,gatenum,numgates)
  113.  
  114. If you think of some overgame functions that you need, let me know.
  115.  
  116. Be sure to use the GATEWAYS echo to communicate your needs and ideas.
  117.  
  118. /*=====================================================================*/
  119. main() /* driver function for your game */
  120. /*=====================================================================*/
  121. void error_check() /* internal use */
  122. /*====================================================================*/
  123. int og_open(filename,mode)  /* open files for read or write */
  124. char *filename;
  125. int mode; /* can be 1 for read/write or 0 for read only */
  126. /*
  127. This function returns a file handle or -1 if the file didn't exist
  128. or -3 if there is an error condition.
  129. Be sure to use the global file handle variables like gfd0 so that
  130. the function you specify to og_onexit() can close any open files
  131. */
  132. /*=====================================================================*/
  133. int og_create(filename) char *filename; /* create a file with this */
  134. /*
  135. This function returns -3 for an error condition.
  136. Be sure to use the global file handle variables like gfd0 so that
  137. the function you specify to og_onexit() can close any open files
  138. */
  139. /*=====================================================================*/
  140. int og_close(fd) int fd; /* MAKE SURE YOU CLOSE ALL FILES WITH THIS */
  141. /*=====================================================================*/
  142. int readline(fd,buffer,size,stopat)
  143.    /* read a line in from a ascii file until <CR> found */
  144. int fd; file  /* handle */
  145. char *buffer; /* where to read into */
  146. int size;    /*  max size of buffer (includes room for null byte) */
  147. char stopat /* character to stop at before the <CR> if encountered */
  148. /*
  149. - If a line is greater in length than size-1, the remainder of the
  150.   line will be ignored and the file positioned at the start of the next line.
  151. - The file is always positioned to the beginning of the next line.
  152. - readline() returns the string length of the line read or it returns -1
  153.   if at the end of file or CTRL-Z encountered.
  154. - A null byte (0) is added to the end of the buffer string.
  155. - stopat should be 0 if not used
  156. - an example use for stopat would be to parse phrases separated by comma.
  157. - You can mix calls to uread and readline.
  158. */
  159. /*=====================================================================*/
  160. int writeline(fd,buffer) /* write a line to a file + <CR><LF> */
  161. int fd; /* file handle */
  162. char *buffer; /* a null terminated string (no <CR><LF> needed) */
  163. /*
  164. returns the length of the string written
  165. */
  166. /*=====================================================================*/
  167. int writestr(fd,buffer) /* write a ascii str to a file */
  168. int fd; /* file handle */
  169. char *buffer; /* a null terminated string */
  170. /*
  171. returns the length of the string written
  172. */
  173. /*=====================================================================*/
  174. int uread(fd,buffer,size) /* raw binary mode read */
  175. /*=====================================================================*/
  176. int uwrite(fd,buffer,size) /* raw binary mode write */
  177. /*=====================================================================*/
  178. void og_onexit(fn) void (*fn)();
  179. /*
  180. fn is function in your game to execute if carrier is lost such as to
  181. close files or free up og_malloc()'ed memory.
  182. See example of usage in D0MAIN.C
  183. */
  184. /*=====================================================================*/
  185. void og_carrier() /* internal usage to simulate random carrier loss */
  186. /*=====================================================================*/
  187. int keyin() /* returns character pressed by player */
  188. /*=====================================================================*/
  189. int keyout(c) char c; /* output a char c to player */
  190. /*=====================================================================*/
  191. int keystat()
  192. /* returns -2 if no char waiting, 1 if char waiting from player */
  193. /* if your compiler doesn't support checking for keyboard status */
  194. /* this will return -2 or 1 on a random basis to simulate */
  195. /*=====================================================================*/
  196. void outstr(ss) char *ss; /* output a string to player */
  197. /*=====================================================================*/
  198. int inpstr(ss,len) /* input a string ss from player */
  199. /* returns 0 */
  200. char *ss; /* buffer location to put string typed in by player */
  201. int len; /* max length of string, NOTE: DOES NOT INCLUDE ROOM FOR NULL BYTE */
  202. /*
  203. len should be no more than the sizeof the buffer - 1
  204. */
  205. /*=====================================================================*/
  206. int isin(s0,c) /* check to see if char c is in char array s0 */
  207.                /* returns 0 if the char c is not in string s0 */
  208.                /* else returns the position + 1 where c is found in string s0 */
  209. char *s0; /* the string to be searched */
  210. char c; /* the character you are searching for */
  211. /*=====================================================================*/
  212. void trim(ss) char *ss; /* remove beginning or trailing spaces from string */
  213. /*=====================================================================*/
  214. char upchar(c) char c; /* convert a character to uppercase */
  215. /*=====================================================================*/
  216. void upcfy(ss) char *ss; /* convert a string to upper case */
  217. /*=====================================================================*/
  218. int og_mode(i) int i; /* reserved usage: set modes of overgame */
  219. /*=====================================================================*/
  220. int og_gateways(gnum) int gnum;
  221. /* allow player to exit your game (or not) at your gate# gnum
  222. /*  returns -3 must exit -2 continue */
  223. /*=====================================================================*/
  224. char *og_plname(num) int num; /* returns pointer to player #num's name */
  225. /*
  226. Do not assume that this name will always be in memory. In other words,
  227. do not use a pointer to remember where the name is and then call
  228. og_plname() again to get the name of another player and expect the
  229. first player's name to still be there. It may be and it may not.
  230. */
  231. /*=====================================================================*/
  232. int *og_plscore(num) int num; /* return pointer player #num's score */
  233. /*
  234. Do not assume the score will always be in memory (see og_plname())
  235. */
  236. /*=====================================================================*/
  237. double drandom() /* return a random double d>=0.0 && d<1.0 */
  238. /*=====================================================================*/
  239. int irandom(max) int max; /* return a random integer i>=0 && i<=max-1 */
  240. /*=====================================================================*/
  241. void *og_malloc(size)
  242. int size; /* keep this value between 30 and 32000 */
  243. /*
  244. - request an area of memory of size bytes and return a pointer to it
  245.   or return (void *)0 if failed.
  246. - request no more than 32000 bytes to ensure portability
  247. - avoid requesting small amounts of memory because of the memory overhead of
  248.   using og_malloc()
  249. - You MUST keep track of all areas you og_malloc and call og_free() to
  250.   free the memory up for each area.
  251. - Remember to notify David Larson of your use of this function and use
  252.   of global or static variables.
  253. - Be sure to use the global pointer values (gp0,gp1..) provided to remember
  254.   the pointers to the blocks so you can use them to free up the areas in
  255.   the function you specify to og_onexit() in order to free them up when
  256.   carrier is loss (or some other condition occurs).
  257. */
  258. /*=====================================================================*/
  259. void og_free(ptr)
  260. void *ptr; /* pointer to the block of memory */
  261. /* Free a block of memory that was requested by og_malloc()
  262. /*=====================================================================*/
  263. /* Designed and written by David M. Larson, BBS: 916-753-8788  opus 203/955 */
  264. /* Dynasoft, P.O. Box 915, Davis, CA 95617 */
  265.