]> 4ch.mooo.com Git - 16.git/blob - 16/v2/VERGEC.TXT
wwww
[16.git] / 16 / v2 / VERGEC.TXT
1                       +----------------------------------+\r
2                       Ý    VergeC 2.0  Reference File    Ý\r
3                       Ý      Language Specification      Ý\r
4                       Ý      VC Built-ins reference      Ý\r
5                       +----------------------------------+\r
6 \r
7 Current as of 5.9.99\r
8 \r
9 =============================================================================\r
10 \r
11 I. Language Specification\r
12 \r
13 A. Comments\r
14 -----------\r
15 Just as in VC1, both C and C++ style comment conventions are supported.\r
16 \r
17     1. Comments: Comments are not required in your VergeC code, but smart\r
18        event coders will use them to help organize and make their event\r
19        scripts readable for future reference. They are ignored by the\r
20        compiler. There are two ways to use comments:\r
21 \r
22       a. If you type a double slash (//) in your code, everything on that\r
23          line after the slashes will be ignored.\r
24 \r
25          Event  // #75: When Dexter joins\r
26          {\r
27           Addcharacter(3);\r
28          }\r
29 \r
30       b. The second method is to use /* and */. When the compiler encounters\r
31          a /*, everything will be ignored until it sees a */. Example:\r
32 \r
33          Event\r
34          {\r
35          /* This is the part where Dexter joins after\r
36             being seen on the path of Jujube mountains.\r
37             The event below is number 75. */\r
38           addcharacter(3);\r
39          }\r
40 \r
41          The // is preferred for simple phrases that you wish commented, while\r
42          the /* */ method is best for large areas of text to be left commented.\r
43 \r
44          NOTE: Try using commenting if you have a problematic area of your\r
45                event script that refuses to compile. Use // before the lines\r
46                that create errors and try recompiling until you can isolate\r
47                the problem.\r
48 \r
49 B. Code control structures\r
50 ---------------------------\r
51 VergeC 2.0 supports most of the code control structures that genuine ANSI C\r
52 does, with some differences that are explained below:\r
53 \r
54     1. IFs: if statements are the most basic form of code execution control.\r
55        They have been much improved since VC1, primarily from the addition\r
56        of OR conditionals as well as the ELSE branching statement.\r
57        The basic format of an IF is:\r
58 \r
59        if (condition <list>)\r
60        {\r
61          (code to be executed if condition is true)\r
62        }\r
63        else\r
64        {\r
65          (code to be executed if condition is false)\r
66        }\r
67 \r
68     2. SWITCHs: switch/case statements basically replace a series of IF\r
69        statements. Cases are yet another method of simplifying and\r
70        empowering your VC code's flexibility. They are most useful in\r
71        situations where you wish to provide multiple results based on the\r
72        condition of some variable. Here's how they're used:\r
73 \r
74        Switch(<variable to be tested>)\r
75        {\r
76          Case <result 1>: <command>;\r
77          Case <result 2>: <command>;\r
78          Case <result 3>: <command>;\r
79        }\r
80 \r
81        When the interpreter encounters this construct, it will test the value\r
82        of what is given in the Switch parentheses, then run the Case statement\r
83        that matches it, if any. Note that unlike C, no break; statements are\r
84        in the below example; break statement in VC are not only unnecessary but\r
85        will cause an error if they are present. Example:\r
86 \r
87        switch (PartyIndex(1))\r
88        {\r
89          case 1: Text(1,"My name's Darin and I'm leading this party!","","");\r
90          case 2: Text(2,"I'm Sara and I'm here to pump you up!","","");\r
91          case 3: Text(3,"Dexter is leading this party.","","");\r
92        }\r
93 \r
94     3. WHILE loops:\r
95        It works much the same as a FOR loop, but can use nearly any condition\r
96        to control how long it executes. The syntax is such:\r
97 \r
98        while (<condition>)\r
99        {\r
100          commands;\r
101        }\r
102 \r
103        The condition inside the parentheses after WHILE can be anything you can\r
104        stuff in an IF statement. When the engine encounters a WHILE loop, it will\r
105        repeatedly execute the commands inside the curly braces until the condition\r
106        inside the parentheses is NOT true. Therefore, your WHILE loop should\r
107        contain some commands that affect that condition, or else your loop will\r
108        run endlessly.\r
109 \r
110     4. FOR loops:\r
111        FOR loops are perhaps more commonly used than WHILE, altho I personally\r
112        dig WHILE loops greatly. Anyhow, FOR loops in VergeC 2.0 are much closer\r
113        to their true C counterparts than they were in VC1. The syntax now is:\r
114 \r
115        for (init; condition; post)\r
116        {\r
117           commands;\r
118        }\r
119 \r
120        To clarify, an example would be:\r
121 \r
122        for (i=0; i<5; i++)\r
123        {\r
124          printstring(i,"This is font "+str(i)+".");\r
125        }\r
126 \r
127 C. system.vc, map-based VC, and the relationship thereof\r
128 --------------------------------------------------------\r
129 There are two distinct types of VC in V2, and that is the system.vc, and\r
130 everything else, which are MAP-based VC files. MAP based VC is very similar\r
131 to how VC was in V1. You cannot declare your own functions or variables in\r
132 a MAP vc. They use the familiar event { } style scripts. When they are\r
133 compiled their pcode is attached directly into the MAPfile itself.\r
134 \r
135 The other type is system.vc, which is compiled into the files system.vcs and\r
136 system.idx, respectively. system.vc allows you to declare your own functions\r
137 and variables - the trick comes in that any of your map VC can access any\r
138 and all of the functions and variables set up in system.vc.\r
139 \r
140 The only real problem arises that, because of the new relationship between\r
141 system.vc and map-based VC, it's conceivable (quite likely, actually) that\r
142 if you modify system.vc you'll break MAPs that you've already compiled. As\r
143 such, VCC now has a 'vcc all' option, that will compile system.vc, and then\r
144 recompile all maps it can find in the given directory. ME2 has a shortcut\r
145 to do this right from inside MapEd - Just hit F6 and it'll rebuild all of\r
146 your VC files. (of course, this means you can't have an ALL.MAP. Oh well,\r
147 live with it. ^_-)\r
148 \r
149 There is nothing like startup.vc or startup.scr in V2. When you execute\r
150 verge.exe, it always starts execution at a MAP file. Which mapfile it starts\r
151 at is determined in user.cfg, by the 'startmap' command. Additionally, you can\r
152 start verge.exe at a specific map by specifying the mapfile on the command\r
153 line, which MapEd makes use of to directly test out the mapfile you're\r
154 currently working on.\r
155 \r
156 D. Syntax for user-declared variables and functions\r
157 ---------------------------------------------------\r
158 \r
159     1. Funtions\r
160        There are two types of user declared functions, ones that return a\r
161        value and those that don't. The simplist declaration for a function\r
162        would be:\r
163 \r
164        void MyFunc()\r
165        { }\r
166 \r
167        You can add passed parameters like so:\r
168 \r
169        void MyFunc(int a, string b)\r
170        { }\r
171 \r
172        These parameters would be accessed inside this function as any other\r
173        variable would be, but it only exists inside the function. You would\r
174        call this function from map or other system.vc code with something\r
175        like this: MyFunc(5, "Hello.");\r
176 \r
177        To make your function return a value, you'd declare it like so:\r
178 \r
179        int MyAdd(int a, int b)\r
180        {\r
181           return a+b;\r
182        }\r
183 \r
184        You cannot currently have a function return a string type. This may\r
185        change in a future version of V2/VC.\r
186 \r
187     2. Variables\r
188        There are only two variable types in VC, int (integer) and string.\r
189        Both are declared the same basic way:\r
190 \r
191        int num;\r
192        string name;\r
193 \r
194        You can define multiple variables of the same type onto a single line:\r
195 \r
196        int x1, y1, x2, y2;\r
197 \r
198        You can also declare arrays of variables:\r
199 \r
200        int flags[8000];\r
201 \r
202        You can declare arrays of both ints and strings. You can only declare\r
203        them in SYSTEM.VC (and any #included sub-files). Variables declared\r
204        outside of any function are global and can be accessed by any system.vc\r
205        OR map-based VC event at all. Variables declared inside a given\r
206        system.vc function are local variables, which only exist during the\r
207        duration of that function's execution, and can't be accessed outside\r
208        of that function.\r
209 \r
210        Limits of passed parameters and local variables: For any given system.vc\r
211        function, the total number of passed parameters and local variables\r
212        cannot exceed 20, and the total number of passed and locally declared\r
213        strings cannot exceed 10. However, if you have 10 strings, you can only\r
214        have 10 ints, otherwise the total limit of 20 variables\r
215        (int and otherwise) would be exceeded.\r
216 \r
217        If there is a global variable and local variable of the same name,\r
218        inside the function the local variable will be used instead. But in\r
219        a function where that local var isn't declared, or a map-vc event,\r
220        the global variable will be used instead.\r
221 \r
222        We may add the ability to declare local variables in map-vc events in\r
223        a later release.\r
224 \r
225 E. Special string operators\r
226 ---------------------------\r
227 \r
228 We strived to make VC2 closer to "real" C in most aspects, but strings is not\r
229 one of them. In real C, string manipulation is fairly clunky, and not very\r
230 easy for beginners to pick up. So, we have created a string system that's\r
231 somewhat like a mix of Pascal and BASIC.\r
232 \r
233 Any string can be combined any number of times, altho the total length of\r
234 any one string cannot exceed 255 characters. For instance, if you had a string\r
235 variable named OurHero, and it contained the main character's name, you\r
236 could do something like:\r
237 \r
238   Text(0,"Greetings, "+OurHero+". We",\r
239          "have been expecting you.", "");\r
240 \r
241 Additionally, there are 4 other commands which can be used during string\r
242 combination: str(), left(), right(), and mid():\r
243 \r
244   str(int) - converts a numerical value into string form.\r
245   left(string, n) - returns the leftmost n characters of string.\r
246   right(string, n) - returns the rightmost n characters of string.\r
247   mid(string, start, run) - returns a section of string, starting at the\r
248                             start character, run characters long.\r
249 \r
250 And lastly, the val(string) attempts to convert a string back to an\r
251 interger value. If the string has too many non-numerical characters in it,\r
252 however, it may not be able to.\r
253 \r
254 F. Preprocessor directives\r
255 --------------------------\r
256 \r
257 As in the original VC, VC2 emulates two primary C preprocessor directives,\r
258 #include and #define. #include has been expanded, while #define has been\r
259 scaled back.\r
260 \r
261 #include is more stable than before, and you can have nested #includes without\r
262 any problems. The primary purpose of #includes in VC2 is to allow you to break\r
263 up your system.vc into sub-files such as menu.vc, battle.vc, or similar\r
264 divisions, and just #include those units into your main system.vc.\r
265 \r
266 Since VC2 now has proper functions, the macro-like behavior of #define in the\r
267 VC1 preprocessor is no longer necessary, and since it was rather highly\r
268 unstable, it was taken out. The primary purpose of #defines in VC2 is to\r
269 allow an unlimited number of simple symbolic constants. An example would be:\r
270 \r
271 #define k_ESC 1\r
272 if (key[k_ESC]) Text(0,"ESC has been pressed.","","");\r
273 \r
274 We may also later add conditional compilaton if there is a request for it.\r
275 \r
276 G. Pointers and direct memory access\r
277 ------------------------------------\r
278 \r
279 If you are not a native C programmer, you are more than welcome to skip over\r
280 this section. I would not dare attempt to teach the principals of pointers\r
281 to those who aren't programmers in their own right, and you don't really need\r
282 to understand VC2's implementation using pointers for direct memory access for\r
283 the vast majority of things you could ever want to do in VergeC.\r
284 \r
285 Since VC deals with all numeric variables as integers (signed, 32-bit values),\r
286 it would not really make sense for us to implement the standard * and &\r
287 operators, since you'd only be able to operate on data of type int.\r
288 \r
289 So, we have 6 builtins which aren't quite functions, and they aren't quite\r
290 variables, but whatever they are, they're there. They are:\r
291 \r
292 (unsigned) byte[ptr]\r
293 (unsigned) word[ptr]\r
294 (unsigned) quad[ptr]\r
295   (signed) sbyte[ptr]\r
296   (signed) sword[ptr]\r
297   (signed) squad[ptr]\r
298 \r
299 Note: signed allows for negative numbers.\r
300 \r
301 Using the convention:\r
302  byte = 8 bits\r
303  word = 16 bits\r
304  quad = 32 bits\r
305 \r
306 The main reason these don't quite qualify as C functions is that you can also\r
307 assign them values. Ie:\r
308 \r
309   byte[myptr]=5;\r
310   if (byte[myptr] != 5)\r
311     Exit("Your computer is smoking crack, my friend.");\r
312 \r
313 H. Misc\r
314 -------\r
315 1. Alternate ways of expressing numbers\r
316    VC has three ways that it recognizes an immediate numerical value.\r
317 \r
318    a. Standard/Decimal\r
319       The first is a standard, base-10 number. Just 65 or something. ex:\r
320 \r
321       myval=65;\r
322       if (myval != 65)\r
323         Exit("Woe to thee, for thine computer smoketh crack, verily.");\r
324 \r
325    b. Hexademical\r
326       VC uses Pascal's convention for handling hexademinal numbers, which\r
327       is to preceed a hexadecimal numerical delcaration with a $ sign. ex:\r
328 \r
329       myval=255;\r
330       if (myval != $FF)\r
331         Exit("For thus sayeth the Lord, that thine processor was created by"+\r
332              "those darwinists who would believe that a CPU can be created"+\r
333              "by putting silicon in a frying pan and shaking it around a lot."+\r
334              "Well, either that, or you're running a Microsoft OS.");\r
335 \r
336    c. ASCII character conversions\r
337       You can use C style single tick marks to denote an ASCII char conversion.\r
338       However, it does not support C's \ codes. Whats in between the tick\r
339       marks is taken directly. ex:\r
340 \r
341       myval=65;\r
342       if (myval != 'A')\r
343         Exit("A stroke from the brush does not guarantee art from the bristles.");\r
344     \r
345 2. Order of Operations\r
346    Does not exist.  Use parentheses gratuitously.  \r
347    Oftentimes you will want to do something like this: putpixel(x+y*320\r
348    This will not work!  V2 will add x and y, then multiply the result by 320.\r
349    As always, any order of operations expression can be rewritten with\r
350    parentheses.  In the example: putpixel(x+(y*320)\r
351 \r
352 =============================================================================\r
353 \r
354 II. Builtin Functions\r
355 \r
356 ---------------------------\r
357 void AllowConsole(int flag)\r
358 ---------------------------\r
359 Controls whether or not the ` key will summon the console or not. 0 will\r
360 disallow the console, 1 will activate it. Disabling the console is a good\r
361 way to prevent cheating, however having it enabled will make developing\r
362 and testing the game easier.\r
363 \r
364 Example:\r
365   AllowConsole(1);\r
366 \r
367 -------------------------------\r
368 int CacheSound(string filename)\r
369 -------------------------------\r
370 Loads a specified sound effect (8-bit, mono, un-compressed WAV file), and\r
371 returns the slot number that you'll access this sound with for PlaySound.\r
372 \r
373 See also: FreeAllSounds(), PlaySound()\r
374 \r
375 Example:\r
376   snd_shriek = CacheSound("SHRIEK.WAV");\r
377 \r
378 -----------------------\r
379 void CD_Play(int track)\r
380 -----------------------\r
381 Begins playing CD audio at the specified track number.\r
382 \r
383 Example:\r
384   CD_Play(6);\r
385 \r
386 --------------\r
387 void CD_Stop()\r
388 --------------\r
389 Stops all CD audio playing.\r
390 \r
391 Example:\r
392   CD_Stop();\r
393 \r
394 ------------------------------------------------\r
395 void Circle(int x, int y, int radius, int color)\r
396 ------------------------------------------------\r
397 Draws a circle (outline only) of the given radius, centered at the given\r
398 coordinates, in the given color.\r
399 \r
400 See also: CircleFill()\r
401 \r
402 Example:\r
403   Circle(screenx/2, screeny/2, 50, 128);\r
404 \r
405 ----------------------------------------------------\r
406 void CircleFill(int x, int y, int radius, int color)\r
407 ----------------------------------------------------\r
408 Draws a filled circle of the given radius, centered at the given\r
409 coordinates, in the given color.\r
410 \r
411 See also: Circle()\r
412 \r
413 Example:\r
414   CircleFill(screenx/2, screeny/2, 50, 128);\r
415 \r
416 ---------------------------------------------------------------\r
417 void CopySprite(int x, int y, int width, int height, int image)\r
418 ---------------------------------------------------------------\r
419 Blits the image pointed to by image with the given dimensions at the\r
420 given location on screen. No transparency, clipping is performed.\r
421 \r
422 See also: TCopySprite\r
423 \r
424 Example:\r
425   im = LoadImage("VECNA.PCX");\r
426   CopySprite(0, 0, image_width, image_height, im);\r
427   free(im);\r
428 \r
429 -------------------\r
430 int cos(int degree)\r
431 -------------------\r
432 Returns the cosine of the given degree of measure (0-360) in 16.16 fixed\r
433 point.\r
434 \r
435 See also: sin(), tan()\r
436 \r
437 Example:\r
438   result = cos(45);\r
439 \r
440 ----------------------------------------------\r
441 void EntityMove(int entity, string movescript)\r
442 ----------------------------------------------\r
443 Sets the given entity to the specified movement script. As in V1,\r
444 you cannot use 'B', the loop command, in an EntityMove given script.. But\r
445 I should be able to work around that so that it will work eventually.\r
446 \r
447 Example:\r
448   ent = EntitySpawn(0, 1, "VECNA.CHR");\r
449   EntityMove(ent, "D2R2");\r
450 \r
451 ---------------------------------------------\r
452 int EntitySpawn(int x, int y, string chrname)\r
453 ---------------------------------------------\r
454 Allocates a new entity at the given coordinates, using the specified CHR file.\r
455 The entity index of the new entity is returned.\r
456 \r
457 See also: SetPlayer()\r
458 \r
459 Example:\r
460   ent = EntitySpawn(0, 1, "VECNA.CHR");\r
461 \r
462 -------------------------\r
463 void Exit(string message)\r
464 -------------------------\r
465 Completely exits out of the engine leaving the user with the specified\r
466 message.\r
467 \r
468 Example:\r
469   Exit("Thank you for playing!");\r
470 \r
471 ---------------------------\r
472 void fclose(int filehandle)\r
473 ---------------------------\r
474 Closes the file given by the specified file handle.\r
475 \r
476 See also: fopen()\r
477 \r
478 Example:\r
479   file = fopen("EXAMPLE.DAT");\r
480   // ** use file here **\r
481   fclose(file);\r
482 \r
483 ----------------------------\r
484 int fgetbyte(int filehandle)\r
485 ----------------------------\r
486 Gets a single byte from the specified file and returns it's value.\r
487 \r
488 Example:\r
489   file = fopen("TEST.DAT");\r
490   Message("First byte in TEST.DAT is: "+str(fgetbyte(file)), 200);\r
491   fclose(file);\r
492 \r
493 ----------------------------\r
494 int fgetword(int filehandle)\r
495 ----------------------------\r
496 Gets a single word (2 bytes) from the specified file and returns it's value.\r
497 \r
498 Example:\r
499   file = fopen("TEST.DAT");\r
500   Message("First word in TEST.DAT is: "+str(fgetword(file)), 200);\r
501   fclose(file);\r
502 \r
503 ----------------------------\r
504 int fgetquad(int filehandle)\r
505 ----------------------------\r
506 Gets a single quad (4 bytes) from the specified file and returns it's value.\r
507 \r
508 Example:\r
509   file = fopen("TEST.DAT");\r
510   Message("First quad in TEST.DAT is: "+str(fgetquad(file)), 200);\r
511   fclose(file);\r
512 \r
513 ----------------------------------------------\r
514 void fgetline(string variable, int filehandle)\r
515 ----------------------------------------------\r
516 Grabs the next line from the specified text file handle and returns it in the\r
517 string variable passed.\r
518 \r
519 Example:\r
520   file = fopen("EXAMPLE.TXT");\r
521   fgetline(my_string, file);\r
522   Message("First line in EXAMPLE.TXT is: "+my_string, 200);\r
523   fclose(file);\r
524 \r
525 Note: String support is a bit sketchy in V2 at the moment, and this command,\r
526       along with fgettoken(), only accept global strings as valid parameters.\r
527       It also will not read correctly into string arrays.\r
528 \r
529 -----------------------------------------------\r
530 void fgettoken(string variable, int filehandle)\r
531 -----------------------------------------------\r
532 Grabs the next token (space delimited) from the specified text file handle\r
533 and returns it in the string variable passed.\r
534 \r
535 Example:\r
536   file = fopen("EXAMPLE.TXT");\r
537   fgettoken(my_string, file);\r
538   Message("First token in EXAMPLE.TXT is: "+my_string, 200);\r
539   fclose(file);\r
540 \r
541 ---------------------------\r
542 int FontHeight(int fontidx)\r
543 ---------------------------\r
544 Returns the height of the font at the given font index.\r
545 \r
546 See also: FontWidth()\r
547 \r
548 Example:\r
549   height = FontHeight(0);\r
550 \r
551 --------------------------\r
552 int FontWidth(int fontidx)\r
553 --------------------------\r
554 Returns the width of the font at the given font index.\r
555 \r
556 See also: FontHeight()\r
557 \r
558 Example:\r
559   width = FontWidth(0);\r
560 \r
561 --------------------------\r
562 int fopen(string filename)\r
563 --------------------------\r
564 Opens the given file and returns a unique file handle integer.\r
565 \r
566 See also: fclose()\r
567 \r
568 Example:\r
569   file = fopen("EXAMPLE.TXT");\r
570   fclose(file);\r
571 \r
572 --------------------------------------------------\r
573 void fread(int buffer, int length, int filehandle)\r
574 --------------------------------------------------\r
575 Reads in a given amount of data from the specified file into the given buffer.\r
576 Thus buffer must be pre-allocated by the user.\r
577 \r
578 Example:\r
579   file = fopen("TEST.DAT");\r
580   buffer = malloc(100);\r
581   fread(buffer, 100, file);\r
582   fclose(file);\r
583 \r
584 ----------------------\r
585 void free(int pointer)\r
586 ----------------------\r
587 Frees the memory space pointed to by the given pointer. (ie, you would pass\r
588 the same value returned by malloc for a memory segment)\r
589 \r
590 Example:\r
591   buffer = malloc(100);\r
592   // ** use buffer here **\r
593   free(buffer);\r
594 \r
595 --------------------\r
596 void FreeAllSounds()\r
597 --------------------\r
598 Frees all sound effect slots.\r
599 \r
600 See also: CacheSound(), PlaySound()\r
601 \r
602 Example:\r
603   FreeAllSounds();\r
604 \r
605 -----------------------------\r
606 void fdelete(string filename)\r
607 -----------------------------\r
608 Deletes the specified file. (uhm.. obviously, be careful with this command.\r
609 This doesn't send it to the recycle bin or anything, the file is GONE after\r
610 this command is executed. Like all the other file I/O vc commands, this\r
611 will ONLY work on files in the main directory VERGE is being run from)\r
612 \r
613 Example:\r
614   fdelete("EXAMPLE.TXT");\r
615 \r
616 ---------------------------------------------\r
617 void frename(string filename, string newname)\r
618 ---------------------------------------------\r
619 Renames the specified file to the new name.\r
620 \r
621 Example:\r
622   frename("EXAMPLE.TXT", "TEST.TXT");\r
623 \r
624 ----------------------------------------\r
625 void fseekline(int line, int filehandle)\r
626 ----------------------------------------\r
627 Moves the file pointer to the given line number in a pre-opened text file.\r
628 \r
629 Example:\r
630   file = fopen("EXAMPLE.TXT");\r
631   fseekline(3, file);\r
632   fgetline(my_string, file);\r
633   Message("Line #3 in EXAMPLE.TXT is: "+my_string, 200);\r
634   fclose(file);\r
635 \r
636 --------------------------------------\r
637 void fseekpos(int pos, int filehandle)\r
638 --------------------------------------\r
639 Moves the file pointer to the given byte position in a pre-opened binary file.\r
640 \r
641 Example:\r
642   file = fopen("TEST.DAT");\r
643   fseekpos(20, file);\r
644   Message("Byte #20 in TEST.DAT is: "+str(fgetbyte(file)), 200);\r
645   fclose(file);\r
646 \r
647 ----------------------------\r
648 void fwclose(int filehandle)\r
649 ----------------------------\r
650 Closes the given file that was open for writing. Be *sure* not to mix\r
651 file handles that were opened for reading and those that were opened\r
652 for writing.\r
653 \r
654 See also: fwopen()\r
655 \r
656 Example:\r
657   file = fwopen("EXAMPLE.TXT");\r
658   // ** use file here **\r
659   fwclose(file);\r
660 \r
661 ------------------------\r
662 int fwopen(string fname)\r
663 ------------------------\r
664 Opens the specified filename for writing.\r
665 \r
666 See also: fwclose(), fwrite(), fwritestring()\r
667 \r
668 Example:\r
669   file = fwopen("EXAMPLE.TXT");\r
670   // ** use file here **\r
671   fwclose(file);\r
672 \r
673 ------------------------------------------------\r
674 void fwrite(int ptr, int length, int filehandle)\r
675 ------------------------------------------------\r
676 Writes the data at the given data pointer to the specified file.\r
677 \r
678 Example:\r
679   file = fwopen("EXAMPLE.TXT");\r
680   buffer = malloc(screenx * screeny);\r
681   GrabRegion(0,0, screenx-1,screeny-1, buffer);\r
682   fwrite(buffer, screenx * screeny, file);\r
683   fwclose(file);\r
684   free(buffer);\r
685 \r
686 ----------------------------------------------\r
687 void fwritestring(string text, int filehandle)\r
688 ----------------------------------------------\r
689 Writes the passed string to the specified file. The string is written in\r
690 text mode format, with a CR/LF pair at the end.\r
691 \r
692 Example:\r
693   file = fwopen("EXAMPLE.TXT");\r
694   my_string = "VERGE 2";\r
695   fwritestring(my_string, file);\r
696   fwclose(file);\r
697 \r
698 --------------------------\r
699 int GetPixel(int x, int y)\r
700 --------------------------\r
701 Returns the color of the specified pixel coordinate.\r
702 \r
703 See also: SetPixel();\r
704 \r
705 Example:\r
706   color = GetPixel(screenx/2, screeny/2);\r
707 \r
708 ------------------------------------\r
709 int GetTile(int x, int y, int layer)\r
710 -----------------------------------\r
711 Returns the value of the given map layer at the given coordinates. For\r
712 layer, 0 through 5 are the first 6 possible map layers, a value of 6\r
713 will always denote the obstruction field, and 7 denotes zone information.\r
714 \r
715 See also: SetTile()\r
716 \r
717 Example:\r
718   tile = GetTile(0, 0, 0);\r
719 \r
720 -------------------------\r
721 void GotoXY(int x, int y)\r
722 -------------------------\r
723 Sets the current text output "cursor" to the given location. This is where\r
724 calls to PrintString will be displayed at.\r
725 \r
726 See also: PrintString()\r
727 \r
728 Example:\r
729   GotoXY(screenx/2, screeny/2);\r
730   PrintString(0, "Hyuck.");\r
731 \r
732 -----------------------------------------------------------\r
733 void GrabRegion(int x1, int y1, int x2, int y2, int buffer)\r
734 -----------------------------------------------------------\r
735 This routine captures a region of the screen and copies it into\r
736 a bitmap buffer. The main trick with using this routine is that you are\r
737 responsible for creating and destroying this buffer with the malloc/free\r
738 commands, and to be sure that you allocate enough memory in your malloc call\r
739 to contain the image. For instance, if you capture the region from (0,0) to\r
740 (49,49), this is a 50x50 square, and you will need to allocate 2500 bytes.\r
741 \r
742 Example:\r
743   save_screen = malloc(screenx * screeny);\r
744   GrabRegion(0, 0, screenx-1, screeny-1, save_screen);\r
745   // ** use save_screen here **\r
746   free(save_screen);\r
747 \r
748 -------------------------------------------\r
749 void HLine(int x, int y, int x2, int color)\r
750 -------------------------------------------\r
751 Draws a horizontal line using the specified coordinates in the given color.\r
752 \r
753 See also: VLine(), Line()\r
754 \r
755 Example:\r
756   HLine(0, screeny/2, screenx-1, 128);\r
757 \r
758 -----------------------------------------\r
759 void HookKey(int scancode, system script)\r
760 -----------------------------------------\r
761 Binds an event to a specified keypress. This allows you to create menus and\r
762 other types of key-based events easily.\r
763 \r
764 ex: HookKey(1, Menu);\r
765 When Escape is pressed (key scancode 1), the function Menu() in system.vc\r
766 will be executed.\r
767 \r
768 See also: HookTimer(), HookRetrace()\r
769 \r
770 Example:\r
771   HookKey(1, menu_script);\r
772 \r
773 -------------------------------\r
774 void HookRetrace(system script)\r
775 -------------------------------\r
776 Given a non-zero event number, it will execute the given VergeC event (from the\r
777 Map VC) each time a frame is rendered. Note that it will be called at the 'R'\r
778 position in the Renderstring, so if there *is* no 'R' position, then it will\r
779 never be executed. As in verge 1, HookRetrace is quite stable, and should be\r
780 used instead of HookTimer whenever possible. You can pass zero to this event\r
781 to turn off the HookRetrace.\r
782 \r
783 See also: HookTimer(), HookKey()\r
784 \r
785 Example:\r
786   HookRetrace(my_script); // hook script\r
787   HookRetrace(1);         // hook event\r
788 \r
789 -----------------------------\r
790 void HookTimer(system script)\r
791 -----------------------------\r
792 Given a non-zero event number, it will execute the given VergeC event (from the\r
793 Map VC) each timer tick (ie, 100 times per second). Note that, like verge 1,\r
794 this is the more volatile of the Hook* family of functions, and HookRetrace\r
795 should be used in place of HookTimer whenever possible. When using HookTimer,\r
796 you should never call any rendering functions, and in general you should do as\r
797 little as possible inside the hooked event as you can. As with HookRetrace,\r
798 passing 0 to this function will turn off the HookTimer.\r
799 \r
800 See also: HookRetrace(), HookKey()\r
801 \r
802 Example:\r
803   HookTimer(my_script); // hook script\r
804   HookTimer(1);         // hook event\r
805 \r
806 ---------------------\r
807 int InitMosaicTable()\r
808 ---------------------\r
809 If you wish to use the Mosaic() routine, you must call this function to\r
810 generate a mosaic palette-matching table (store the value returned by this\r
811 function and pass it to Mosaic each time you call it). We would precompute\r
812 this table, however, it depends on the palette. The table calculations can\r
813 take a while, it takes about 12 seconds on my P200. It is possible, of course,\r
814 to precompute the table in VC and load it at runtime for people that want\r
815 to use this feature and wish to avoid the long table computation time.\r
816 \r
817 See also: Mosaic()\r
818 \r
819 Example:\r
820   table = InitMosaicTable();\r
821 \r
822 --------------------------------------------------\r
823 void Line(int x, int y, int x2, int y2, int color)\r
824 --------------------------------------------------\r
825 Draws an arbitary-angled line from any two sets of coordinates in the\r
826 given color.\r
827 \r
828 See also: HLine(), VLine()\r
829 \r
830 Example:\r
831   Line(0,0, screenx-1,screeny-1, 128);\r
832 \r
833 -----------------------------\r
834 int LoadFont(string filename)\r
835 -----------------------------\r
836 Loads the specified font file and returns the font slot which is used by\r
837 PrintString.\r
838 \r
839 See also: GotoXY(), PrintString()\r
840 \r
841 Example:\r
842   my_font = LoadFont("MYFONT.FNT");\r
843 \r
844 ----------------------------\r
845 int LoadRaw(string filename)\r
846 ----------------------------\r
847 Loads the specied file as raw data into an allocated buffer and returns\r
848 a pointer to that buffer.\r
849 \r
850 Example:\r
851   raw = LoadRaw("SPEECH.SPC");\r
852   // ** use raw here **\r
853   free(raw);\r
854 \r
855 ------------------------------\r
856 int LoadImage(string filename)\r
857 ------------------------------\r
858 Loads the specified image, allocating enough memory for it, and returns\r
859 a pointer to the image. If you no longer need the image, you should\r
860 free() it. The image can be any of the supported V2 image types, which\r
861 are currently PCX, BMP, and GIF.\r
862 \r
863 Example:\r
864   im = LoadImage("CHEESE.GIF");\r
865   // ** use im here **\r
866   free(im);\r
867 \r
868 ---------------------\r
869 void Log(string text)\r
870 ---------------------\r
871 Outputs a message to VERGE.LOG, assuming verge.log is enabled by the user.\r
872 This can be useful for debugging.\r
873 \r
874 Example:\r
875   Log("VERGE 2");\r
876 \r
877 ----------------------\r
878 int malloc(int amount)\r
879 ----------------------\r
880 Allocates the given amount of memory and returns a pointer to the memory\r
881 space allocated.\r
882 \r
883 Example:\r
884   buffer = malloc(100);\r
885   free(buffer);\r
886 \r
887 ------------------------\r
888 void Map(string mapname)\r
889 ------------------------\r
890 Loads the specified MAP file as the current map. Upon encountering this\r
891 command, VC execution is immediately terminated completely and resumed at\r
892 the new map's Autoexec event.\r
893 \r
894 Example:\r
895   Map("TEST.MAP");\r
896 \r
897 ------------------------------------------\r
898 void Message(string message, int duration)\r
899 ------------------------------------------\r
900 Issues the specified system message, lasting the given duration in hundreths\r
901 of a second. This message is displayed in the upper left corner of the screen\r
902 for the given duration, and noted in the verge.log file.\r
903 \r
904 Example:\r
905   Message("VERGE 2", 200);\r
906 \r
907 -------------------------------------------------------------------------\r
908 void Mosaic(int xfocus, int yfocus, int tablepointer, int x1, y1, x2, y2)\r
909 -------------------------------------------------------------------------\r
910 "Mosaics" the screen so far; The best way to describe it is as the mode7\r
911 effect used in FF2 and such to make the screen "blur out" during screen\r
912 transitions. xfocus and yfocus control the "granularity" of this blurring,\r
913 tablepointer must be the value returned by InitMosaicTable or a pointer\r
914 to a precomputed table loaded in memory. The x1,y1,x2,y2 values specify\r
915 the section of the screen to apply the mosaic effect to.\r
916 \r
917 So, to apply the mosaic effect with a 3-to-1 pixel ratio to the whole screen,\r
918 you'd use Mosaic(3, 3, MyMosaicTable, 0, 0, ScreenX, ScreenY);\r
919 \r
920 See also: InitMosaicTable()\r
921 \r
922 Example:\r
923   table = InitMosaicTable();\r
924   Mosaic(4,4, table, 0,0, screenx-1, screeny-1);\r
925 \r
926 -------------------------------------------------------------\r
927 void PaletteMorph(int r, int g, int b, int mix, int lighting)\r
928 -------------------------------------------------------------\r
929 This command alters the entire game palette, which will effect the entire\r
930 screen. It changes the 'tint' of the screen; the RGB values are the color\r
931 you want to tint the screen with, and range from 0 to 63. So, 63,0,0 would\r
932 be red, 0,63,0 is green, and 0,0,63 is blue. 0,0,0 is black and 63,63,63\r
933 is white. The mix value controls how 'thickly' the screen is tinted\r
934 with this color. 0 would mean no mix whatsoever, while 100 would change\r
935 the screen to be the color you specified solidly. The lighting value simply\r
936 controls how light or dark the screen will be as a whole; 63 is normal\r
937 brightness, 0 is black.\r
938 \r
939 Example:\r
940   PaletteMorph(0,0,0,0, 63);\r
941 \r
942 ---------------------------------\r
943 void PartyMove(string movescript)\r
944 ---------------------------------\r
945 This command will have the party follow the specified movement script; player\r
946 control will resume after the script is completed.\r
947 \r
948 Example:\r
949   PartyMove("U1R1D1L1");\r
950 \r
951 -----------------------------\r
952 void PlayFLI(string filename)\r
953 -----------------------------\r
954 Plays the specified FLI or FLC file. Does not loop. The timing in the V2\r
955 playback may be slightly off, but it should be so slight as to be completely\r
956 unnoticable in the vast majority of cases. Also, it would be a good idea to\r
957 set the video mode beforehand to something appropriate to fit the resolution of\r
958 the FLI.\r
959 \r
960 SeeAlso: SetResolution()\r
961 \r
962 Example:\r
963   PlayFLI("INTRO.FLC");\r
964 \r
965 -------------------------------\r
966 void PlayMusic(string filename)\r
967 -------------------------------\r
968 Plays the specified music file. In this version of V2, only MODs, MTMs, S3Ms,\r
969 and XMs are supported.\r
970 \r
971 See also: StopMusic();\r
972 \r
973 Example:\r
974   PlayMusic("AURORA.MOD");\r
975 \r
976 --------------------------------------------------\r
977 void PlaySound(int soundslot, int volume, int pan)\r
978 --------------------------------------------------\r
979 Plays the specified sound effect at the given slot index; volume is a value\r
980 from 0 to 64 indicating the volume the sound file will be played at, and pan\r
981 is a value from 0 to 255; 0 is all the way left, and 255 is all the way right,\r
982 128 is in the center.\r
983 \r
984 See also: CacheSound(), FreeAllSounds()\r
985 \r
986 Example:\r
987   shriek = CacheSound("SHRIEK.WAV");\r
988   PlaySound(shriek, 64, 128);\r
989 \r
990 --------------------------\r
991 int pow(int base, int exp)\r
992 --------------------------\r
993 Raises base to the exp power and returns that value.\r
994 \r
995 Example:\r
996   result = pow(16, 3); // 4096\r
997 \r
998 ----------------------\r
999 void ProcessEntities()\r
1000 ----------------------\r
1001 Processes one tick worth of entity movement. If you call this 100 times a\r
1002 second it will keep the game moving as normal. For example, the following code\r
1003 could be used to draw something on top of the normal map view:\r
1004 \r
1005 Example:\r
1006   while (!done)\r
1007   {\r
1008     while (timer)\r
1009     {\r
1010       timer--;\r
1011       ProcessEntities();\r
1012     }\r
1013     Render();\r
1014     // Put additional things to be drawn per frame here\r
1015     ShowPage();\r
1016   }\r
1017 \r
1018 ---------------------------------------\r
1019 void PrintString(int font, string text)\r
1020 ---------------------------------------\r
1021 Displays the given string in the specified font index, at the location\r
1022 last given by GotoXY.\r
1023 \r
1024 See also: LoadFont(), GotoXY()\r
1025 \r
1026 Example:\r
1027   PrintString(0, "VERGE 2");\r
1028 \r
1029 ---------------------\r
1030 int Random(int range)\r
1031 ---------------------\r
1032 Returns a random number between 0 and the range given.\r
1033 \r
1034 Example:\r
1035   if (Random(100) < 50)\r
1036     PrintString(0, "Heads!");\r
1037   else PrintString(0, "Tails!");\r
1038 \r
1039 ----------------\r
1040 void ReadMouse()\r
1041 ----------------\r
1042 Updates the mouse status variables mx, my, and mb.\r
1043 \r
1044 See also: SetMousePos()\r
1045 \r
1046 Example:\r
1047   ReadMouse();\r
1048 \r
1049 ------------------------------\r
1050 void ReadVars(int filepointer)\r
1051 ------------------------------\r
1052 Reads all the global variables that have been written to a file by WriteVars().\r
1053 You're responsible for opening and closing the file for reading, mainly used\r
1054 for savegames.\r
1055 \r
1056 See also: WriteVars(), fopen(), fclose()\r
1057 \r
1058 Example:\r
1059   file = fopen("SAVE.DAT");\r
1060   ReadVars(file);\r
1061   fclose(file);\r
1062 \r
1063 ----------------------------------------------\r
1064 void Rect(int x, int y, int x2, int y2, int c)\r
1065 ----------------------------------------------\r
1066 Draws an outlined rectangle of the given coordinate set in the specified\r
1067 color.\r
1068 \r
1069 See also: RectFill()\r
1070 \r
1071 Example:\r
1072   Rect(0, 0, screenx-1, screeny-1, 128);\r
1073 \r
1074 --------------------------------------------------\r
1075 void RectFill(int x, int y, int x2, int y2, int c)\r
1076 --------------------------------------------------\r
1077 Draws a filled rectangle of the given coordinate set in the specified\r
1078 color.\r
1079 \r
1080 See also: Rect()\r
1081 \r
1082 Example:\r
1083   RectFill(0, 0, screenx-1, screeny-1, 128);\r
1084 \r
1085 -------------\r
1086 void Render()\r
1087 -------------\r
1088 Performs a render, per the render string, but does not copy the screen\r
1089 buffer to the visible screen, allowing you to draw additional items on top\r
1090 of the game screen.\r
1091 \r
1092 See also: ShowPage()\r
1093 \r
1094 Example:\r
1095   Render();\r
1096 \r
1097 ----------------------------\r
1098 void RestoreRenderSettings()\r
1099 ----------------------------\r
1100 Restores the default clipping window for the given video mode, and restores\r
1101 the render destination to the video buffer.\r
1102 \r
1103 See also: SetClipRect(), SetRenderDest()\r
1104 \r
1105 Example:\r
1106   RestoreRenderSettings();\r
1107 \r
1108 ----------------------------------------------------------------------------\r
1109 void ScaleSprite(int x, int y, int iw, int ih, int dw, int dh, int imageptr)\r
1110 ----------------------------------------------------------------------------\r
1111 Draws a scaled image. A bit more complex than the other blitters to use.\r
1112 The x,y values give the upper-left corner of where the blit will start.\r
1113 iw,ih are the width and height of the *source* image. dw, dh are the width\r
1114 and height that the image should appear on screen. (ie, the end result\r
1115 bounding box of the image would be, x, y, x+dw, y+dh) Imageptr is, as with\r
1116 the other blit routines, a pointer to the image graphic.\r
1117 \r
1118 See also: TScaleSprite()\r
1119 \r
1120 Example:\r
1121   im = LoadImage("VECNA.PCX");\r
1122   ScaleSprite(0,0, image_width,image_height, image_width*2,image_height*2, im);\r
1123   free(im);\r
1124 \r
1125 ----------------------\r
1126 void SetClip(int clip)\r
1127 ----------------------\r
1128 Determines whether clipping versions of general VC graphics routines are\r
1129 used. Defaults to 1; You will never need to turn this off, turn it offers\r
1130 no functional difference, except faster blitting routines, however, great care\r
1131 must be used when turning it off that no part of any blit or graphics call\r
1132 draws off screen boundaries.\r
1133 \r
1134 Example:\r
1135   SetClip(1);\r
1136 \r
1137 ------------------------------------------------\r
1138 void SetClipRect(int x1, int y1, int x2, int y2)\r
1139 ------------------------------------------------\r
1140 Sets the rectangle that image drawing will be clipped to.\r
1141 \r
1142 See also: RestoreRenderSettings()\r
1143 \r
1144 Example:\r
1145   im = LoadImage("PATTERN.PCX");\r
1146   SetClipRect(screenx/4, screeny/4, screenx-(screenx/4), screeny-(screeny/4));\r
1147   WrapBlit(0, 0, image_width, image_height, im);\r
1148   RestoreRenderSettings();\r
1149   free(im):\r
1150 \r
1151 -----------------------------------------------------\r
1152 void SetRenderDest(int width, int height, int buffer)\r
1153 -----------------------------------------------------\r
1154 This sets the video buffer that all VC video functions will draw into.\r
1155 \r
1156 See also: RestoreRenderSettings()\r
1157 \r
1158 Example:\r
1159   buffer = malloc(32 * 32);\r
1160   SetRenderDest(32, 32, buffer);\r
1161   Line(0,0, 15,15, 128);\r
1162   Line(0,15, 15,0, 128);\r
1163   Rect(0,0, 15,15, 128);\r
1164   RestoreRenderSettings();\r
1165   CopySprite(0, 0, 32, 32, buffer);\r
1166   free(buffer);\r
1167 \r
1168 --------------------------\r
1169 void SetLucent(int lucent)\r
1170 --------------------------\r
1171 Determines whether translucent versions of general VC graphics routines are\r
1172 used. Defaults to 0.\r
1173 \r
1174 Example:\r
1175   SetLucent(1);\r
1176 \r
1177 ------------------------------\r
1178 void SetMousePos(int x, int y)\r
1179 ------------------------------\r
1180 Sets the current mouse position to the given x and y coordinates. Does no\r
1181 checking to make sure the coordinates are valid, so check that yourself, they\r
1182 should between 0 and screenx and 0 and screeny, respectively.\r
1183 \r
1184 See also: ReadMouse()\r
1185 \r
1186 Example:\r
1187   SetMousePos(screenx/2, screeny/2);\r
1188 \r
1189 ----------------------------------\r
1190 void SetPixel(int x, int y, int c)\r
1191 ----------------------------------\r
1192 Sets the specified pixel coordinate to the given color.\r
1193 \r
1194 See also: GetPixel();\r
1195 \r
1196 Example:\r
1197   SetPixel(screenx/2, screeny/2, 128);\r
1198 \r
1199 -------------------------------\r
1200 void SetPlayer(int entityindex)\r
1201 -------------------------------\r
1202 Sets the specified entity index as the active player.\r
1203 \r
1204 See also: EntitySpawn()\r
1205 \r
1206 Example:\r
1207   ent = EntitySpawn(0, 1, "VECNA.CHR");\r
1208   SetPlayer(ent);\r
1209 \r
1210 -------------------------------------\r
1211 int SetResolution(int xres, int yres)\r
1212 -------------------------------------\r
1213 Sets the video mode to the specified resolution. Returns 1 if successful, 0\r
1214 if the mode set failed.\r
1215 \r
1216 Common video modes:\r
1217 -------------------\r
1218                      DOS                         Windows\r
1219                      ---                         -------\r
1220                    320x200                       320x200\r
1221                    320x240                       320x240\r
1222                    360x240                       512x384\r
1223                    256x256                       640x480\r
1224                    640x480                       800x600\r
1225                                                  1024x768\r
1226 \r
1227 Example:\r
1228   SetResolution(320, 240);\r
1229 \r
1230 -------------------------------\r
1231 void SetRString(string rstring)\r
1232 -------------------------------\r
1233 Updates the RenderString to the specified string.\r
1234 \r
1235 Example:\r
1236   SetRString("1E2");\r
1237 \r
1238 ------------------------------------------------\r
1239 void SetTile(int x, int y, int layer, int value)\r
1240 ------------------------------------------------\r
1241 Sets a new value to the given map layer at the given coordinates. For\r
1242 layer, 0 through 5 are the first 6 possible map layers, a value of 6\r
1243 will always denote the obstruction field, and 7 denotes zone information.\r
1244 \r
1245 See also: GetTile()\r
1246 \r
1247 Example:\r
1248   SetTile(0, 0, 0, 2);\r
1249 \r
1250 ---------------\r
1251 void ShowPage()\r
1252 ---------------\r
1253 Copys the screen buffer to the visible screen.\r
1254 \r
1255 See also: Render(), CopySprite(), TCopySprite()\r
1256 \r
1257 Example:\r
1258   ShowPage();\r
1259 \r
1260 --------------------------------------------------------------------------\r
1261 void Silhouette(int x, int y, int width, int height, int color, int image)\r
1262 --------------------------------------------------------------------------\r
1263 Renders a silhouette of the specified image.  The silhouette is generated\r
1264 by looking for all non-zero pixels in the image and replacing them with\r
1265 the specified color.\r
1266 \r
1267 Example:\r
1268   im = LoadImage("GOAT.PCX");\r
1269   Silhouette(0, 0, image_width, image_height, 128, im);\r
1270   free(im);\r
1271 \r
1272 -------------------\r
1273 int sin(int degree)\r
1274 -------------------\r
1275 Returns the sine of the given degree of measure (0-360) in 16.16 fixed\r
1276 point.\r
1277 \r
1278 See also: cos(), tan()\r
1279 \r
1280 Example:\r
1281   result = sin(180);\r
1282 \r
1283 ----------------\r
1284 void StopMusic()\r
1285 ----------------\r
1286 Stops currently playing music.\r
1287 \r
1288 See also: PlayMusic()\r
1289 \r
1290 Example:\r
1291   StopMusic();\r
1292 \r
1293 ------------------------------------\r
1294 int strcmp(string str1, string str2)\r
1295 ------------------------------------\r
1296 Compares the two passed strings. Returns 0 if they're identical, or\r
1297 a nonzero number porportional to the difference between the strings.\r
1298 \r
1299 Example:\r
1300   string_a = "alpha";\r
1301   string_b = "zeta";\r
1302   result = strcmp(string_a, string_b);\r
1303   if (!result)\r
1304     PrintString(0, "Strings are equal");\r
1305   else if (result < 0)\r
1306     PrintString(0, string_a+" comes before "+string_b);\r
1307   else\r
1308     PrintString(0, string_b+" comes before "+string_a);\r
1309 \r
1310 ----------------------\r
1311 int strlen(string str)\r
1312 ----------------------\r
1313 Returns the length of the passed string.\r
1314 \r
1315 Example:\r
1316   my_string = "VERGE 2";\r
1317   length = strlen(my_string);\r
1318 \r
1319 -------------------\r
1320 int tan(int degree)\r
1321 -------------------\r
1322 Returns the tangent of the given degree of measure (0-360) in 16.16 fixed\r
1323 point.\r
1324 \r
1325 See also: sin(), cos()\r
1326 \r
1327 Example:\r
1328   result = tan(270);\r
1329 \r
1330 ----------------------------------------------------------------\r
1331 void TCopySprite(int x, int y, int width, int height, int image)\r
1332 ----------------------------------------------------------------\r
1333 Blits the image pointed to by image with the given dimensions at the\r
1334 given location on screen. Transparency and clipping are performed.\r
1335 \r
1336 See also: CopySprite\r
1337 \r
1338 Example:\r
1339   im = LoadImage("SLIME.PCX");\r
1340   TCopySprite(0, 0, image_width, image_height, im);\r
1341   free(im);\r
1342 \r
1343 -----------------------------------------------------------------------------\r
1344 void TScaleSprite(int x, int y, int iw, int ih, int dw, int dh, int imageptr)\r
1345 -----------------------------------------------------------------------------\r
1346 Draws a scaled image. A bit more complex than the other blitters to use.\r
1347 The x,y values give the upper-left corner of where the blit will start.\r
1348 iw,ih are the width and height of the *source* image. dw, dh are the width\r
1349 and height that the image should appear on screen. (ie, the end result\r
1350 bounding box of the image would be, x, y, x+dw, y+dh) Imageptr is, as with\r
1351 the other blit routines, a pointer to the image graphic. This routines draws\r
1352 the image with transparency, unlike ScaleSprite().\r
1353 \r
1354 See also: ScaleSprite()\r
1355 \r
1356 Example:\r
1357   im = LoadImage("SLIME.PCX");\r
1358   TScaleSprite(0,0, image_width,image_height, image_width*2,image_height*2, im);\r
1359   free(im);\r
1360 \r
1361 --------------------------------------------------------------------\r
1362 void TWrapBlit(int xofs, int yofs, int width, int height, int image)\r
1363 --------------------------------------------------------------------\r
1364 Blits an image of any size repeatedly so that it fills the entire screen;\r
1365 This version is color-0 transparent unlike the normal WrapBlit version.\r
1366 \r
1367 See also: WrapBlit();\r
1368 \r
1369 Example:\r
1370   im = LoadImage("PATTERN.PCX");\r
1371   TWrapBlit(0, 0, image_width, image_height, im);\r
1372   free(im);\r
1373 \r
1374 -------------------------\r
1375 void UnPress(int control)\r
1376 -------------------------\r
1377 This will read a control currently being pressed as not pressed until it\r
1378 is released and then pressed again. The values of control are:\r
1379   0: All buttons, not directionals\r
1380   1: b1                              5: up\r
1381   2: b2                              6: down\r
1382   3: b3                              7: left\r
1383   4: b4                              8: right\r
1384 \r
1385 Example:\r
1386   UnPress(0);\r
1387 \r
1388 ---------------------\r
1389 void UpdateControls()\r
1390 ---------------------\r
1391 Updates the control variables up, down, left, right, b1, b2, b3, and b4.\r
1392 \r
1393 Example:\r
1394   UpdateControls();\r
1395 \r
1396 -------------------------------------------\r
1397 void VLine(int x, int y, int y2, int color)\r
1398 -------------------------------------------\r
1399 Draws a vertical line from the specified coordinates in the given color.\r
1400 \r
1401 See also: HLine(), Line()\r
1402 \r
1403 Example:\r
1404   VLine(screenx/2, 0, screeny-1, 128);\r
1405 \r
1406 -------------------------------------------------------------------\r
1407 void WrapBlit(int xofs, int yofs, int width, int height, int image)\r
1408 -------------------------------------------------------------------\r
1409 Blits an image of any size repeatedly so that it fills the entire screen;\r
1410 \r
1411 See also: TWrapBlit();\r
1412 \r
1413 Example:\r
1414   im = LoadImage("PATTERN.PCX");\r
1415   WrapBlit(0, 0, image_width, image_height, im);\r
1416   free(im);\r
1417 \r
1418 -------------------------------\r
1419 void WriteVars(int filepointer)\r
1420 -------------------------------\r
1421 Writes all global variables (ints and strings) to the specified file. You\r
1422 must take care of opening and closing the file for writing. Mostly used\r
1423 for savegames.\r
1424 \r
1425 See also: ReadVars(), fwopen(), fwclose()\r
1426 \r
1427 Example:\r
1428   file = fwopen("SAVE.DAT");\r
1429   WriteVars(file);\r
1430   fwclose(file);\r
1431 \r
1432 =============================================================================\r
1433 \r
1434 III. Builtin Variables\r
1435 \r
1436 b1, b2, b3, b4\r
1437 --------------\r
1438 These represent four primary control buttons. They are updated by the\r
1439 UpdateControls() function. [read-only]\r
1440 \r
1441 Example:\r
1442   UpdateControls();\r
1443   if (b1) Message("Button 1!", 100);\r
1444   if (b2) Message("Button 2!", 100);\r
1445   if (b3) Message("Button 3!", 100);\r
1446   if (b4) Message("Button 4!", 100);\r
1447 \r
1448 cameratracking, tracker\r
1449 -----------------------\r
1450 If cameratracking is 0, the camera is free to be altered by the xwin/ywin\r
1451 variables. If cameratracking is 1, the camera will always follow the player.\r
1452 If cameratracking is 2, the camera will always follow the entity specified in\r
1453 tracker. [read/write]\r
1454 \r
1455 Example:\r
1456   ent = EntitySpawn(0, 1, "VECNA.CHR");\r
1457   cameratracking = 2;\r
1458   tracker = ent;\r
1459   EntityMove("R2D2L2U2");\r
1460 \r
1461 entity.x, entity.y\r
1462 ------------------\r
1463 x/y coordinates of the specified entity in world-coordinates (pixel-accurate).\r
1464 [read/write]\r
1465 \r
1466 Example:\r
1467   Log("Player X="+str(entity.x[player])+", Y="+str(entity.y[player]));\r
1468 \r
1469 entity.tx, entity.ty\r
1470 --------------------\r
1471 x/y coordinates of the specified entity in tile coordinate. [read/write]\r
1472 \r
1473 Example:\r
1474   Log("Player TX="+str(entity.tx[player])+", TY="+str(entity.ty[player]));\r
1475 \r
1476 entity.facing, entity.moving, entity.specframe, entity.speed, entity.movecode\r
1477 -----------------------------------------------------------------------------\r
1478 Various variables effecting the specified stats of the given entity.\r
1479 [read/write]\r
1480 \r
1481 Example:\r
1482   Log("Player info");\r
1483   Log("   Facing: "+str(entity.facing[player]));\r
1484   Log("   Moving: "+str(entity.moving[player]));\r
1485   Log("SpecFrame: "+str(entity.specframe[player]));\r
1486   Log("    Speed: "+str(entity.speed[player]));\r
1487   Log(" MoveCode: "+str(entity.movecode[player]));\r
1488 \r
1489 entsonscreen\r
1490 ------------\r
1491 Array of entity indexes which are currently onscreen.\r
1492 \r
1493 Example:\r
1494   // log all tile coordinates of entities onscreen\r
1495   for (i=0; i<numentsonscreen; i++)\r
1496     Log("X="+str(entity.tx[entsonscreen[i]])+", Y="+str(entity.ty[entsonscreen[i]]));\r
1497 \r
1498 key\r
1499 ---\r
1500 Returns or set the on/off flag of the specified key scancode.\r
1501 \r
1502 Example:\r
1503   if (key[1])\r
1504     Message("ESC is pressed", 200);\r
1505   else Message("ESC is not pressed", 200);\r
1506 \r
1507 lastent\r
1508 -------\r
1509 The last entity that called a VC event, either via movement script or\r
1510 activation.\r
1511 \r
1512 Example:\r
1513   Message("Last entity: "+str(lastent), 200);\r
1514   \r
1515 Note: Untested currently.\r
1516 \r
1517 mx, my, mb\r
1518 ----------\r
1519 mx and my are the x and y coordinates of the mouse pointer. mb returns the\r
1520 mouse button status.\r
1521 \r
1522 Example:\r
1523   Message("Mouse info: X="+str(mx)+", Y="+str(my)+", B="+str(mb), 200);\r
1524 \r
1525 numentsonscreen\r
1526 ---------------\r
1527 Number of entities currently on screen, number of values in entsonscreen array\r
1528 that are valid.\r
1529 \r
1530 Example:\r
1531   Message("Number of entities onscreen: "+str(numentsonscreen), 200);\r
1532 \r
1533 pal\r
1534 ---\r
1535 Active palette array (256 RGB entries; 768 bytes). Changes made will only\r
1536 be enforced when PaletteMorph() is next called.\r
1537 \r
1538 Example:\r
1539   // greyscale the active palette\r
1540   for (i=0; i<256; i++)\r
1541   {\r
1542     r=pal[i*3+0];\r
1543     g=pal[i*3+1];\r
1544     b=pal[i*3+2];\r
1545     average=(r+g+b)/3;\r
1546     pal[i*3+0]=average;\r
1547     pal[i*3+1]=average;\r
1548     pal[i*3+2]=average;\r
1549   }\r
1550   PaletteMorph(0,0,0,0, 63);\r
1551 \r
1552 player\r
1553 ------\r
1554 Returns which entity index number is currently the active player. [read-only]\r
1555 \r
1556 Example:\r
1557   ent = EntitySpawn(0, 1, "VECNA.CHR");\r
1558   SetPlayer(ent);\r
1559   Message("Active entity index is #"+str(player));\r
1560 \r
1561 screen\r
1562 ------\r
1563 Single-dimensional array access to the video virtual buffer. [read/write]\r
1564 \r
1565 Example:\r
1566   SetResolution(320, 240);\r
1567   screen[(120*320)+160]=128;\r
1568 \r
1569 screenx, screeny\r
1570 ----------------\r
1571 Return the x and y dimensions of the current video mode. [read-only]\r
1572 \r
1573 Example:\r
1574   Message("Current resolution is "+str(screenx)+"x"+str(screeny));\r
1575 \r
1576 timer\r
1577 -----\r
1578 This variable is incremented 100 times per second. It can be used to for\r
1579 timing purposes. [read/write]\r
1580 \r
1581 Example:\r
1582   while (timer)\r
1583   {\r
1584     timer--;\r
1585     ProcessEntities();\r
1586   }\r
1587 \r
1588 up, down, left, right\r
1589 ---------------------\r
1590 These represent the four directional controls. Also updated by\r
1591 UpdateControls(). [read-only]\r
1592 \r
1593 Example:\r
1594   UpdateControls();\r
1595   if (up)    Message("UP!", 100);\r
1596   if (down)  Message("DOWN!", 100);\r
1597   if (left)  Message("LEFT!", 100);\r
1598   if (right) Message("RIGHT!", 100);\r
1599 \r
1600 vctrace\r
1601 -------\r
1602 This is a 0/1, off/on variable that defaults to 0; when it is turned on,\r
1603 VERGE.LOG will contain dumps tracing the code flow of system.vc function\r
1604 calls. However, this log can get very big very quickly, so it's recommended\r
1605 that you turn it on to track and debug a particular section of code and then\r
1606 turn it off afterwards.\r
1607 \r
1608 Example:\r
1609   vctrace = 1;\r
1610 \r
1611 vsp\r
1612 ---\r
1613 Array of tile image data. Sequential ordering of 256 byte (16*16) blocks.\r
1614 \r
1615 Example:\r
1616   TCopySprite(screenx/2,screeny/2, 16,16, vsp+(slot*256));\r
1617 \r
1618 xwin, ywin\r
1619 ----------\r
1620 These control the camera, if cameratracking is 0. Otherwise, the camera will\r
1621 follow the player. [read/write]\r
1622 \r
1623 Example:\r
1624   xwin = 100;\r
1625   ywin = 200;\r