VERGE-RPG DOCS, The VERGE 3 Manual
The reference manual for the VERGE 3 game creation engine.



***********************
******* N O T E  ******
***********************

This file is a snapshot of the online VERGE Manual from 2004.10.14
The up-to-date version is always accessible at:

http://www.verge-rpg.com/docs/view.php?libid=1

***********************
******* N O T E  ******
***********************


This manual might be lacking in parts.


**** Table of Contents ****
I. Dedication
II. Introduction
III. Variables
    a. Integers
    b. Fixed-point
    c. Strings
    d. Arrays
    e. Structs
IV. Language Specification
    a. basic syntax
    b. Operators
    c. Comments
    d. preprocessor directives
    e. control structures
    f. functions
    g. system and map code
    h. DMA
V. Engine
    a. verge.cfg options
    b. changelog
    c. planned features
    d. known issues
VI. Function Reference
    a. General Utility Functions
    b. String Functions
    c. Map Functions
    d. Entity Functions
    e. Graphics Functions
    f. Sprite Functions
    g. Sound/Music Functions
    h. Font Functions
    i. Math Functions
    j. File Functions
    k. Window Managment Functions
    l. Movie Playback Functions
    m. Netcode Functions
VII. Global Variables
    a. General System Variables
    b. Mouse Variables
    c. Joystick Variables
    d. Entity Variables
    e. Sprite Variables
    f. Camera Variables
    g. Map Variables
    h. Layer Variables
    i. Event Variables
    j. Date/Time Variables
VIII. Built-in Defines
    a. Version
    b. Scan Codes
    c. Color Filters
IX. Appendix
    a. history of verge
    b. archived related sites
X. Credits
XI. Colophon


================================================================================
--------------------------------------------------------------------------------
a. Dedication
--------------------------------------------------------------------------------
================================================================================




For Sully

VERGE is dedicated to erudite marine life everywhere.





================================================================================
--------------------------------------------------------------------------------
b. Introduction
--------------------------------------------------------------------------------
================================================================================

"Not documenting important features is a major aspect of the VERGE dev
philosophy 
 though! Because it places the knowledge in the hands of an elite priesthood
upon 
 whom the lower classes are dependent"
				-Gayo, in the sooper-secret VERGE dev chatroom 


Welcome to VERGE!!!
Okay, well, after too many weeks of coding this system, and 3 hours of data
entry, I'm making this library public and calling it a night.
Hopefully vecna will decide to add more infos here and there.
All of the function refernce at the least has a nodeshell that matches up with
the most recent v3vergec.txt.
The documentation widget doesn't seem to be working 100% as planned, but I'm
sure I can crush the quirks that didn't manifest until I gave it the rigorous
testing of the for-real v3 docs tonight.
If anyone wants to start making their own documentation, go right ahead.  You
may need to log-in and log out after doing so.  It may also not work.  I've been
too busy adding stuff here.
I'll appoint contributors/editors/moderators after I wake up at the boss's
discretion.
Sincerely,McGrue
PS: If you couldn't figure it out, this is a highly temporary introduction.


================================================================================
--------------------------------------------------------------------------------
c. Variables
--------------------------------------------------------------------------------
================================================================================
What is a variable?
When running any program, certain information need to be kept track of by the
computer. For instance, most rpgs will want to know a health value that changes
when the player is damaged. To do this, you can 'declare' a variable called
"playerhealth", which would then store a number that relates to their health,
and then use the name of the variable to refer to it.


Types of variables

Like all programming languages, verge has a several different means of storing
data, for different purposes. Each has a subsection, with more information:



	Integer: (or int) Used for storing numbers, does not support decimals (numbers
with fractional parts)
	Fixed-point: Not actually another type of variable, but a way of using integers
so you can store fractions.
	String: Used for storing text, whether a single character or a whole line.
	Array: A certain number of either strings or integers, listed under one name.
	Struct: A collection that can have arrays, strings, and integers, arranged and
named however you want.



Declaration

Declaring a variable is creating it.  You cannot use a variable without creating
it first. In verge the syntax is:


(type of variable) (name of variable);


So, in our example, we would write the following line of code:

int playerhealth;

This says we want to use a number, which we are going to refer to as
"playerhealth" from now on. Arrays and structs are handled rather differently,
see their specific sections for more information, but strings are similar:

string playername;

What we must do is make sure we declare the variable BEFORE using it anywhere
else. This generally means you just need to make sure the line you declare the
variable is above any lines in which you use it. This is good:

int playerhealth;
playerhealth = 100;

This is BAD, verge will not like it:

playerhealth = 100;
int playerhealth;

Note we could also assign a value when we first declare it, this sometimes saves
space and confusion:
int playerhealth = 100;
Unlike other programming languages, verge automatically sets numbers to 0 and
strings to blank (or "" as it may be referred to), even if you don't assign a
value when you first declare it. However, it is considered good practice to make
sure you variables always contain something before you use them.

Naming variables
You can call your variable pretty much anything you like, but it's best to name
them something obvious that will remind you what  information it stores. Verge
allows variable names to consist of upper and lower case letters, numbers, and
underscores (like _ that). ( Well, to be honest it allows all symbols that
aren't reserved as something else, but don't use them. ) However, make sure the
name always begins with a letter.
Bad variable names:

hit%    //No special symbols like % allowed
3DModel //Putting a number at the start will make verge try to do maths on your
variable)
player$ //(Ok, so the $ is technically allowed, but will cause confusion)
estbx   //(This is allowable, BUT WHAT DOES IT MEAN? Use names that make
sense)


Good alternatives:

HitPercent
Model3D
playerMoney
enemy_status_box


Another important thing to note here, is that you need to make sure all things
that have names, and might exist at the same time (see scope below) must be
called different things. In particular, don't name variables and functions the
same, and (for a different reason) don't name ANYTHING the same as defines. A
final point here is that unlike in some programming languages, upper and lower
case letters are not treated is differently, so make sure to have completely
independent names.

Having some kind standard system is useful to keep track of what each name is,
however exactly what sort of standard system is the sort of thing programmers
can argue over for hours. If you are brave, do  a search and pick a method you
like. However, I'll give a few guidelines at the bottom of the page that might
be useful. Remember, these are not RULES, just SUGGESTIONS.

Scope

In verge, a variable can be either local or global. This is related to whether a
variable is declared inside or outside a function. A local variable will only
exist for the duration of the function it is in, and will be created every
function call. A global variable will exist for the duration of the program
itself. Remember, each variable needs a certain amount of computer memory to
store it, so even though that's not so much of a problem with modern machines,
do try to keep global variables to a minimum. However, at the moment ALL arrays
and structs MUST be global, they cannot be declared locally.

Also, scope effects how variable can be named as well. So, you can have to
entirely different "x" variables in two different functions, but you cannot have
a global "x" and have another "x" variable anywhere else at all.


Pointers
If you do not know what pointers are, skip the next section: you're done with
this one. ;)
Verge, for all intents and purposes, has no pointers. As such. However, to
understand how it handles images, sounds, entities and suchlike, it's useful to
know what it is doing. When you use a Load...() function verge assigns what ever
you just loaded some space in memory, and records where it is located. It then
assigns a number to that location, and gives it back to you. That number can be
later used to tell verge which image you want it to use in a function. It's just
like saying 1st, 2nd, 3rd, 4th image and so on - verge removes all of the memory
management worries from your shoulders.
However, if you simply must have direct memory access, you can, via a very
arcane system, directly access memory.  To read more on v3's DMA, go [here].




================================================================================
a. Integers
================================================================================
ints hold non-fractional numerical values.  an int can have a value from
-2,147,483,648 to 2,147,483,647.  


int an_int; //this creates an int named 'an_int'
int another_int; //this creates another int.

an_int = 5; //this sets it to the value 5.
another_int = 3; //another_int is now equal to 3.

another_int = an_int; //another_int is now equal to 5.

an_int = 7; //an_int is now 7, but another_int is still 5.


The verge integer is 32 bit, here's a detailed run down of what that means:

In a 32 bit integer, there are 32 bits than can be either on or off

This is 2^32 combinations, or 4294967296

Binary numbers: 0   1   0   1   1.....0

Equivalent to:	2^0+2^1+2^2+2^3+2^4...-2^31

Which is: 1 + 2 + 4 + 8 + 16....-2147483648

Why is the last number (bit) negative?

So we can store all the negative numbers easily as well.

Then it is still just case of adding to bits to get the number.

Note that as 0 has to be stored as well, there is one less positive than
negative

So in a 32 bit int, the number can be between -2^31 and 2^31-1

Alternatively in decimal from -2147483648 to 2147483647

Eg. The number 13 is stored as 8+4+1 or 1011000...0

The number -13 is stored as -2147483648 plus everything BUT 8+4 so 11001111...1

Note that the +1 is still on, as negative numbers stretch one lower than
positives

Because the top bit is negative, in an overflow case (trying to store to large a
number) you will 'wrap around' and get a negative number.

================================================================================
b. Fixed-point
================================================================================
An overview of fixed-point notation
by aen, grade 6
Fixed-point is a way of treating whole numbers as both whole and fractional
parts. It's called fixed point because you decide how much precision you need.
Do you need to be able to represent halves? Tenths? Hundredths? Thousandths?
You can sort of think of fixed-point as a "secret code" for numbering. I'm sure
you've heard of such numbering systems as binary, hexadecimal, and octal. Binary
uses only 1s and 0s. Octal uses the numbers 0 through 7. Hexadecimal uses the
numbers 0 through 9 and also the letters A through F.
Fixed-point also has a special sytstem for representing numbers. One example
could be the number 100. You could decide, for example, that you want your
fixed-point system to be able to track precision into the tenths. In that case,
you could say that every ten numbers represent 1 whole number. The number 100,
then, would end up being representative of the number 10.
How is that pulled off? The numbers 0 through 9 would equate to 0, 10 through 19
would equal 1, 20 through 29 would equal 2, etc. You can basically "decode" a
system like this by dividing a number by 10. This division yields the integer
part of your number. The fractional part is the number modulus 10. If you are
unfamiliar with modulus, it's just the remainder of a division. For example,
13/10 equals 1 with a remainder of 3, so 3 is your fractional part.
When dealing with tenths, you're always going to have a fractional part of 0
through 9. In this case, these values correspond directly to .0, .1, .2, etc.
However, if you decide to go with different precisions, this will not always be
the case. If you were dealing in fourths for example (division and modulus by
4), you would have to take that into account when interpreting the fractional
part. Fractionl parts are basically percentages of a whole number, so with
fourths the fractional part is going to be one of 0, 1, 2, or 3. 0 would be 0%
or .0, 1 would be 1/4th or .25, 2 would be 2/4ths or .5, and 3 would be 3/4ths
or .75.
You may see a lot of >>8 or >>16 going on in fixed-point examples in C all over
the web. This is basically the same as dividing by 256 or 65,536. Usually you'll
see >>8 when dealing with 16-bit numbers, since 8 is half that many bits, or
>>16 when dealing with 32-bit numbers for the same reason. These systems are
capable of precision up to 256ths or 65,536ths, basically. Sometimes people
aren't too picky about how much precision is needed, which is why they'll just
split things down the middle like that. Bit shifting can also be faster, which
is another reason you'll see it all over the place. As long as you understand
the concept, you can do it any which-way you want!

================================================================================
c. Strings
================================================================================
strings hold phrases of text in them.  


string your_name; //this creates a string named 'your_name'

your_name = "mud"; //this sets your_name to the value 'mud'

Is a string a fixed number of characters?

vec: No. There's limits in some situations.. log and exit() probably have limits
of 4k. But general string ops are virtually unlimited. 

Gayo: Nyahaha. I set up a loop to double the size of a string with every
iteration and got to several hundred megs of memory usage before giving up. 

Because the memory is dynamically allocated to the string at runtime, you have
very few bounds worries.

================================================================================
d. Arrays
================================================================================
 strings and ints may also be put into arrays.  Arrays can only be declared with
constant values.


int numbers[15]; //makes a list of 15 integers

string names[7]; //this one is a list of 7 strings

numbers[0] = 42; //this sets the first member of 'numbers' to 42.
numbers[14] = 3; //this sets the last member of 'numbers' to 3.

// the following line will do very very bad things
// because it is setting data outside of the array's bounds.
numbers[15] = 3; 

//The following is also illegal:
int foo = 17;
int illegal[foo]; //verge does not allow this.


 Arrays are defined with the number of elements that they contain, but when
accessing the elements you start counting with 0.  So if you have 15 elements,
they are numbered 0 through 14.
 Arrays can also be created in multiple dimensions.  


//this creates a 2-dimensional array of ints
int mock_screen[320][240];

//this sets element 0,0 of the array to 12
mock_screen[0][0] = 12; 

//this sets element 123,79 of the array to 43
mock_screen[123][79] = 43;


//this creates a 3-dimensional array of ints.
string goats[100][100][100];

//this sets element 0,41,12 of this array to "Toothgnip".
goats[0][41][12] = "Toothgnip";

//this makes a 10-dimensional array of ints.
//making a multi-dim array this big is stupid, 
//but possible.
int tacos[5][4][17][22][79][34][11][19][7000][2];


 You cannot set an array instance equal to another array instance.  You may only
set array elements.  To wit, the following is completely bad and wrong:


int list_a[100];
int list_b[100];

list_a = list_b; //NO!


================================================================================
e. Structs
================================================================================
 The struct is a custom-made type of variable that you can put multiple ints and
strings inside of.



//
// The below defines a struct named 'user'

struct user 
{
  int id;
  string name;
  int coolness;
  string pet_names[15];
  int bank_account_numbers[4];
}

//
// Now that 'user' is defined, we can make specific
// instances of it

user mcgrue;
user vecna;

//
// And now we can alter these instances just like you 
// could alter an int or string... except with special syntax!

mcgrue.name = "Ben";
vecna.name = "Also Ben";
vecna.coolness = 7;
mcgrue.pet_names[0] = "Oliver";

//Note: While you can set the member variables of a struct, 
// you cannot copy an entire struct's contents to another instance
// of that struct.  To wit, the following is completely illegal:

mcgrue = vecna; //THIS WILL NOT COMPILE.


 and finally, you can make arrays and multidimensional arrays of structs.  This
is generally the best way to use structs since you cannot copy them via
reference like in the previous example, so to move them around it's best to keep
them all in the same array.



struct point
{
  int x, y, z;
  int color;
}

//makes an array of 1000 points
point buncha_points[1000];

//this set's element 3's x-variable to 20.
buncha_points[3].x = 20;

================================================================================
--------------------------------------------------------------------------------
d. Language Specification
--------------------------------------------------------------------------------
================================================================================
VergeC, or vc, is a C-like scripting language created specifically for use in
creating VERGE games.

You create vc files in any text editor you want, and when you run verge.exe
(with releasemode 0 set in your verge.cfg), the engine will attempt to compile
your code starting with a mandatory system.vc file in the same base directory as
the engine file, and then any other vc files you #include therein.





================================================================================
a. basic syntax
================================================================================
As a C-like scripting language, vc has certain syntax rules that need to be
adhered to.  For veteran coders, much of this will be old-hat.

First off, the semicolon is analguous to a period in english.  It denotes the
end of a statement.  Whenever you declare a variable, set a variable, or call a
statement, you need to end the line with a semicolon, like so:


int a_variable;

a_variable = 42;

some_function();


 Curly braces are also prevalent, acting as bookends between a block of code. 
Whenever using conditionals or defining a function, you will be using curly
braces to delimit the boundaries of the conditional or function, like so:



void some_function() 
{
	if( a_variable == 42 ) 
	{
		exit( "Ah, yes... but what was the question?" );
	}
}



Notice how everytime I opened a curly brace I tabbed everything in a level, and
when the curly brace was closed I deleted that level of tab.  This is not
strictly neccesary, but a very good habit to get into to make your code more
readable to others... which is an exceptionally good thing if you want help
debugging your program from others. ;)

The rest of the syntax will be covered in their specific sections.  A whole
plethora of odd symbols awaits the novice programmer.  You can find syntax
highlighting files for text editors in the [files section].  We strongly suggest
you get one and use the appropriate text editor (everyone on the verge
development team uses [textpad]).  We would be lost in a sea of bland symbols
ourselves without syntax highlighting, you surely shouldn't go it without.



================================================================================
b. Operators
================================================================================
For those of you familiar with C, I'll give you a quick rundown (everyone else
skip this paragraph): VERGE has pretty much all the C operators you'll need
except pointer stuff. It has no order of operations. There's no *=, /=, or %=,
but there is a += and -=. The assignment operators do not return values and as
such cannot be used inside an arithmetic or logical expression. Logical
operators can't be used in arithmetic expressions. There's no bitwise NOT. You
can't use assignment operators in logical or arithmetic expressions. Since all
integers are signed, bitshifting is automatically signed as well. You can't use
parentheses to change the evaluation order of a logical expression.

Verge contains five kinds of "operators" used to build statements. An operator
is a symbol which, when combined with one or more "operands" (constants,
variables, or expressions), changes the value of the operands or produces a new
value based on them. For example, the + arithmetic operator takes two integer
operands and produces a new integer which is the sum of those two.
Operators are either unary or binary; that is, they take either one or two
operands. Unary operators either precede or follow their operands, whereas
binary operators have are placed in between their two operands. The + operator
mentioned above is binary, so its operators are placed on either side; to
produce the sum of 5 and 6, we type "5 + 6". Except where otherwise stated, all
the operators described below are binary.

ARITHMETIC OPERATORS:
The arithmetic operators represent fundamental mathematical operations such as
addition and subtraction.
Addition (+): The addition operator generates a new number that is the sum of
its operands.
Subtraction (-): The subtractio operator generates a new number that is the
difference of its operands. Order is important; the operand after the minus sign
is subtracted from the one before it.
Multiplication (*): The multiplication operator generates a new number that is
the product of its operands.
Division (/): The division operator generates a new number that is the quotient
of its operands. As with subtraction, order is important; the first operand is
the numerator, the second the denominator. This is integer division, which means
that the final value is always an integer, rounded down if necessary. 
Modulus (%): The modulus operator returns the remainder of the division of the
first operand by the second.
Arithmetic operators can be combined into complex arithmetic expressions. They
are evaluated from left to right; that is to say, there is no order of
operations. To enforce a specific evaluation order, you may use parentheses. 


// Arithmetic Operator examples
int n = 0;      // n starts out as 0

n = 2 + 3;      // Addition: n is now 5
n = 12 - n;     // Subtraction: n is now 7
n = 2 * 4;      // Multiplication: n is now 8
n = n / 2;      // Division: n is now 4
n = 10 % 3;     // Modulus: n is now 1 (the remainder of 10 / 3)

// Examples of complex expressions

n = 1 + 3 * 5;                    // n is now 20 (since there's no order of
operations)
n = 100 % (9 * 3);                // n is now 19 (the remainder of 100 / 27)
n = 2 * (5 - (7 * 3));            // n is now -32



BITWISE OPERATORS:

Bitwise operators are so called because they operate individually on every bit
of a (32-bit signed) integer. Because they manipulate numbers on a binary level,
they are somewhat tricky for beginners. If you feel comfortable with them,
however, you can use bitwise operators freely in arithmetic expressions.

Bitwise OR (|): The Bitwise OR generates a new value by ORing each bit of the
two operands. What this means is that the new value will have a 1 in each bit
location where either or both of the operands had a 1, and a 0 in every other
bit location.
Bitwise AND (&): The Bitwise AND generates a new value by ANDing each bit of the
two operands. What this means is that the new value will have a 0 in each bit
location where either or both of the operands had a 0, and a 1 in every other
bit location.
Bitwise XOR (^): The Bitwise XOR generates a new value by exclusive-ORing each
bit of the two operands. What this means is that the new value will have a 1 in
each bit location where either one or the other but not both of the operands had
a 1, and a 0 in every other bit location.
Left Bitshift (Right Bitshift (>>): The Right Bitshift operator generates a new
number which its its first operand with all the bits shifted right a number of
spaces equal to the value of the second operand. In the expression m>>n, the
value returned is equal to m divided by 2 to the nth power (using integer
division, naturally).

LOGICAL OPERATORS:
The logical operators can be used only in the conditions of if and while
statements. They return either true (a nonzero number) or false (zero). Like
arithmetic operators, logical operators take integer variables, constants, or
expressions (arithmetic or logical) as their operands, and are evaluated from
left to right. However, as of this writing, you cannot change the evaluation
order of a logical expression using parentheses.
Equality (==): The Equality operator returns true if the two operands are equal;
otherwise, it returns false. It is represented as a double equals sign to
differentiate it from the Assignment operator (which see). Note that neither
strings nor structs can be used as logical operands, so this operator cannot be
used to test their equality.
Inequality (!=): The Inequality operator returns true if the two operands are
inequal; otherwise, it returns false.
Greater Than (>): Greater Than returns true if the first operand is greater than
the second; otherwise, it returns false.
Lesser Than (Greater Than or Equal To (>=): Greater Than or Equal To returns
true if the first operand is greater than or equal to the second; otherwise, it
returns false.
Lesser Than or Equal To (Logical OR (||): The logical OR returns true if either
or both of its operands are true; otherwise, it returns false.
Logical AND (&&): The logical OR returns true only if both of its operands are
true; otherwise, it returns false..
Logical NOT (!): The logical NOT is a unary operator that precedes its operand.
It returns true if its operand is true; otherwise it returns false.

Note that there is no logical XOR in VERGE.

ASSIGNMENT OPERATORS:

Assignment operators are special in that they actually change the value of one
of their operands. The operand to be changed must be a variable, since only
variables can have their values altered. Assignment operators are also unique
because they do not return values; for this reason, they cannot be used inside
expressions.

Assignment (=): The ordinary assignment operator changes the the value of the
first operand to the value of the second.
Increment (++): Increment is a unary operator that follows its operand. It
increases the value of its single operand by 1.
Decrement (--): Decrement is a unary operator that follows its operand. It
decreases the value of its single operand by 1.
Increase (+=): The Increase operator increases the value of the first operand by
the value of the second.
Decrease (-=): The Decrease operator decreases the value of the first operand by
the value of the second.

The ordinary assignment operator (=) can be used within a declaration statement
to initialize a newly declared variable to a specific value.


// Assignment operator examples
int n = 2;        // n is declared and assigned the value of 2
n = 7;            // n is assigned the value of 7
n++;              // n is now 8
n--;              // n is now 7 again
n += 12 + n;      // n is now 26
n -= n;           // n is now 0



STRING OPERATORS:

There are only two string operators in VERGE. They accept only string variables,
string literals, and functions that return strings as their operands.

String Concatenation (+): The string concatenation operator is the plus sign,
just like the addition operator. Since the operator is preceded by its first
operand, the compiler figures out whether it's doing addition or concatenation
by looking at the type (int or string) of that operand. Concatenation produces a
new string composed of the second operand appended to the first.
String Assignment (=): The String Assignment operator is identical to the
ordinary assignment operator, except it functions on strings rather than
integers.


// String concatenation examples
string s = "";                     // s is declared and set to an empty string
string s = "hell" + "o";           // s is now "hello"
string s = "why " + s + " there";  // s is now "why hello there"


Note: You can't do these togther with the += operator.

string s = "Fish";
s += " and Chips"; // NOT valid
s = s + " and Chips"; // Use this instead

================================================================================
c. Comments
================================================================================
Just as in VC1 and VC2, both C and C++ style comment conventions are
supported.

Comments: Comments are not required in your VergeC code, but smart coders will
use them to help organize and make their scripts readable for future reference.
They are ignored by the compiler. There are two ways to use comments:


 If you type a double slash (//) in your code, everything on that line after the
slashes will be ignored.
        

void dex_join  // #75: When Dexter joins
{
	AddPlayer(3);
}


The second method is to use /* and */. When the compiler encounters a /*,
everything will be ignored until it sees a */. Example:


void dex_join
{
	/* This is the part where Dexter joins after
	being seen on the path of Jujube mountains.
	The event below is number 75. */
	
	addcharacter(3);
}



The // is preferred for simple phrases that you wish commented, while the /* */
method is best for large areas of text to be left commented.

NOTE: Try using commenting if you have a problematic area of your event script
that refuses to compile. Use // before the lines that create errors and try
recompiling until you can isolate the problem.

================================================================================
d. preprocessor directives
================================================================================
Preprocessor directives are special statements that begin with a pound # sign,
and are the only ones that don't need the semi-colon ; at the end. 






Preprocessor directives must be in a linear order, and BEFORE the code to keep
certain errors from coming up. 






There are two important directives: 






1) #include "[filename]" 



Includes a file to be compiled in addition to SYSTEM.VC. This is recommended to
have a neat categorizing of your codes. The filename is quotes and must also
have the extension at the end of the filename with it. 






Example: 



#include "draw.vc" 






2) #define A B 



#define is basically a seek-replace statement. Where A will transform into B
after being compiled. You can use a define like you would a string or int but
you can never change their value after its initially set. It can be used for
thign such as file paths, debugging, or keeping track of numbers and their
interpretation with different functions such as the scan codes and color
filters






Example: 



#define MAX_PARTY_MEMBERS 5 



int partyIndex[MAX_PARTY_MEMBERS]; 




================================================================================
e. control structures
================================================================================
VergeC 3 supports most of the code control structures that genuine ANSI C
does, with some differences that are explained below:


IFs: if statements are the most basic form of code execution control. They have
been much improved since VC1, primarily from the addition of OR conditionals as
well as the ELSE branching statement. The basic format of an IF is:

if (condition )
{
	(code to be executed if condition is true)
}
else
{
	(code to be executed if condition is false)
}

SWITCHs: switch/case statements basically replace a series of IF statements.
Cases are yet another method of simplifying and empowering your VC code's
flexibility. They are most useful in situations where you wish to provide
multiple results based on the condition of some variable. Here's how they're
used:

Switch()
{
	Case : ;
	Case : ;
	Case : ;
}

 When the interpreter encounters this construct, it will test the value of what
is given in the Switch parentheses, then run the Case statement that matches it,
if any. Note that unlike C, no break; statements are in the below example; break
statement in VC are not only unnecessary but will cause an error if they are
present. Example:


switch ( Party[0] ) //checking the first person in the party...
{
	case 1: Text(DARIN,"My name's Darin and I'm leading this party!","","");
	case 2: Text(SARA,"I'm Sara and I'm here to pump you up!","","");
	case 3: Text(DEXTER,"Dexter is leading this party.","","");
}


FOR loops:FOR loops are perhaps more commonly used than WHILE, altho I
personally dig WHILE loops greatly. Anyhow, FOR loops in VergeC 2.0 are much
closer to their true C counterparts than they were in VC1. The syntax now is:


for (init; condition; post)
{
	commands;
}

To clarify, an example would be:

for (i=0; i
       
WHILE loops: These work much the same as FOR loops do, but can use nearly any
condition to control how long it executes. The syntax is such:

while ()
{
	commands;
}


The condition inside the parentheses after WHILE can be anything you can stuff
in an IF statement. When the engine encounters a WHILE loop, it will repeatedly
execute the commands inside the curly braces until the condition inside the
parentheses is NOT true. Therefore, your WHILE loop should contain some commands
that affect that condition, or else your loop will run endlessly.


V3 logical expressions are not short-circuited: every part of the condition is
evaluated, even if unnecessary. 

================================================================================
f. functions
================================================================================
Verge does not support prototypes.  Do not use them.  Indeed, prototypes are not
necessary at all in verge.  All function names are known to all other functions.
--chillaxen

eg:  (no need for this)

int func( arg1, arg2);

void autoexec()
{
   /* code */
}

int func( arg1, arg2)
{
   /* code */
}



================================================================================
g. system and map code
================================================================================
Since V2, VERGE has had this concept of separate system codespace and map
codespace.  While in V1, everything happened in the map VC, in V2 and V3, the
majority of the important code is now in the realm of the system code, while
only events and code relevant to that map is in the map codespace.



In V3, the only 3 files you need to make a barebones VERGE game are verge.exe,
fmod.dll, and system.vc. 



Inside system.vc, the function autoexec() is called once verge has finished
initializing.  That is your entry point.  You can #include any number of
additional .VC files into your system.vc in order to provide a logical breakdown
of your code components into different source files, for instance, menu.vc,
effects.vc, etc.  These are all considered to be part of the system codespace.



Any functions, variables, or structs you declare in any system file are
considered globally accessable.  You can access system code and variables from a
map VC.  In general, most of the descriptions of code you will see in tutorials
and discussions on the forum are implicitly describing system VC code.  Aside
from some enhancements, the general concept and structure of system VC code has
not changed since V2.



Map code, however, has changed a good bit since V2.  In V2, your map code
consisted of numbered events rather than the named functions you see in system
VC code.  



In V3, its more accurate to think of a map's VC code as an extension of
system.vc, but that only 'exists' while that particular map is loaded.  In
reality, the functions that are declared in your map VC are simply added onto
V3's list of system functions when the map is loaded, and unloaded when the map
is changed.  You can declare as many named functions as you like, functions that
return values, helper functions, functions with local variables.



Its important to understand however that these functions only exist when that
map is laoded. This has the following consequences:

If you declare a foo() in system.vc, you cannot declare a foo() in map1.vc. 
However, if you have chest() function in map1.vc, you can also have a chest()
function in map2.vc - provided you don't already have one in system.vc. 
Lets say you have function Camel() in system.vc, and you have funtions Llama()
and Hamster() in your map1.vc. From your map code, you can call Camel()
directly.  However, because Llama() only exists when this particular map is
loaded, and other maps may have their own functions named Llama(), it is
impossible to know at compile time, which Llama() to call from a system.vc
function.  So you cannot directly call Llama() from a system function.  What you
can do is use CallFunction("Llama"), which will call the function if it exists
at that time, or simply return and do nothing if that function does not exist at
runtime. 



While you cannot call a map vc function directly from a system vc function, you
can call another map function directly from another function in that same map
file.  In the above example, you could call Llama() from Hamster() directly
without needing to use CallFunction, because it is known at compile time exactly
which function you're talking about.
Because of this concept that the functions declared in a map VC only exist while
that map was loaded - in addition to certain technical considerations - it was
decided that you cannot declare global variables in a map VC file.  You can
declare local variables in your map VC functions, and you can use global
variables declared in system.vc.  But you cannot declare global variables in a
map VC file, because they would cease to exist when the map was unloaded.  While
we intuitively think of a local variable as being non-persistent between
function calls, we DO think of global variables as being persistent, so having
your global variables pop out of existence would be confusing and prone to
bugs.

One other note.  While event zero was always the 'autoexec' event of a map in
V2, in V3, each map has (in the Map Properties dialog) a simple string arguement
called startup script. This is simply the name of the function - if any - you
would like called when the map is loaded.  Since I said before that MAP VC is
simply an extension of system VC that only exists for that map, you can use
either a system VC function name or a map VC function name as your startup
script - or for any other script arguement, such as an entities activation
script, or a zone's script.



This also means that you can do things like: Set your HookRender function to a
MAP vc name and leave it. If the function does not exist, the HookRender will
simply do nothing. When you enter a map that defines that function name, it will
be used for the HookRender, and when you enter a different map that uses the
same function name, that map's appropriate function will be used instead.

================================================================================
h. DMA
================================================================================
Access a DMA buffer via the following arrays:

dma.byte[]

dma.word[]

dma.quad[]

dma.sbyte[]

dma.sword[]

dma.squad[]


The latter three use a signed representation of the data for reading purposes.


int buf = malloc(10);
int ofs = 4;
dma.byte[buf+ofs] = -1;
messagebox(dma.byte[buf+ofs]); //will display 255
messagebox(dma.sbyte[buf+ofs]); //will display -1


--------------------------------------------------------------------------------
int Malloc (int size)
--------------------------------------------------------------------------------
Allocates a chunk of memory and returns a pointer handle to it.

Documentation:
Returns a pointer to a newly allocated memory space of the specified size. NOTE:
This function is NOT intended for general use. It is only for advanced users.
There is rarely a need to use it. Memory blocks allocated with Malloc should be
freed with MemFree, which is not interchangeable with FreeImage, FreeSound,
FreeFont, or anything else.


Example Usage:
int myptr = Malloc(256); //myptr now points to a 256-byte block of memory.


--------------------------------------------------------------------------------
void MemCopy (int source, int dest, int size)
--------------------------------------------------------------------------------
Copies a block of memory from one location to another.

Documentation:
Does a direct memory copy between two pointers. This is an advanced function and
should, generally speaking, not be used. ^_^


Example Usage:
int ptr1 = Malloc(256);
int ptr2 = Malloc(256);

MemCopy(ptr1, ptr2, 256);


--------------------------------------------------------------------------------
void MemFree (int pointer)
--------------------------------------------------------------------------------
Frees a malloc()-allocated block of memory.  INCOMPATIBLE WITH NON-DMA MEMORY.

Documentation:
Frees a memory block allocated with Malloc. NOT interchangeable with any other
Free function, such as FreeImage. Other V3 constructs such as images, fonts, and
sounds are virtual objects which return handles and not direct pointers.


Example Usage:
int myptr = Malloc(256);

MemFree(myptr);

================================================================================
--------------------------------------------------------------------------------
e. Engine
--------------------------------------------------------------------------------
================================================================================
Download the Current Engine. This has no pack-in demo, but includes everything
you need to start making games in Verge3.

Here is a list of the contents of the engine download, and what each file is.

chrmak5.exe - The sprite maker for Verge3. It's called "Character Maker 5". See
the documentation.
corona.dll - This is Corona, an image loading library. Used by maped3.exe, I
think. Detailed information here.
darin.mak - A sample sprite creation file. ChrMak5 uses these to create V3
sprites.
darin.pcx - The actual graphic data for a sprite. PCX is a graphic format
similar to BMP.
fmod.dll - A music playback library. It is one of the few files Verge.exe
requires. Detailed information here.
maped3.exe - Maped3.exe is the Verge3 Map Editor. It loads, edit, and creates 2D
tile maps for use in Verge. See the documentation.
MapedPreferences.xml - This file stores settings for Maped3.exe. You don’t need
to mess with it.
MRU.dll - ?????????????? It may be used with Maped3.
packed.exe  - A program that edits and creates Verge3 .pak files, which are
collections of graphics, sound, and code contained in a single file. Packfiles
are kind of like a zip file, but only Verge3 uses them. DOCUMENTATION IN
PROGRESS.
pr2-common-cpp.dll ?????????????????
README.TXT - This is a readme from Verge’s creators, which tells about the
engine.
RegisterFileType.dll - This is used by maped to register the .map extension,
which means any V3 Map file can be opened by double-clicking on it.
Render.dll - ??????????????I imagine this is used by maped3 to render the map on
the screen.
system.vc - This is a sample System VergeC code file.
v3changes.txt - The changelog that's updated from build to build.
v3vergec.txt - This is code reference with all types of information on functions
and variables for VergeC. When you learn to program in VergeC, this will come in
handy.
verge.exe - Verge.exe is the actual Verge3 engine. When you download a game, you
run Verge.exe to run the game.
zlib.net.dll - Zlib is used to compress images. Maped3 uses it for tile image
data, I imagine. Detailed information here.





--------------------------------------------------------------------------------
int Malloc (int size)
--------------------------------------------------------------------------------
Allocates a chunk of memory and returns a pointer handle to it.

Documentation:
Returns a pointer to a newly allocated memory space of the specified size. NOTE:
This function is NOT intended for general use. It is only for advanced users.
There is rarely a need to use it. Memory blocks allocated with Malloc should be
freed with MemFree, which is not interchangeable with FreeImage, FreeSound,
FreeFont, or anything else.


Example Usage:
int myptr = Malloc(256); //myptr now points to a 256-byte block of memory.


--------------------------------------------------------------------------------
void MemCopy (int source, int dest, int size)
--------------------------------------------------------------------------------
Copies a block of memory from one location to another.

Documentation:
Does a direct memory copy between two pointers. This is an advanced function and
should, generally speaking, not be used. ^_^


Example Usage:
int ptr1 = Malloc(256);
int ptr2 = Malloc(256);

MemCopy(ptr1, ptr2, 256);


--------------------------------------------------------------------------------
void MemFree (int pointer)
--------------------------------------------------------------------------------
Frees a malloc()-allocated block of memory.  INCOMPATIBLE WITH NON-DMA MEMORY.

Documentation:
Frees a memory block allocated with Malloc. NOT interchangeable with any other
Free function, such as FreeImage. Other V3 constructs such as images, fonts, and
sounds are virtual objects which return handles and not direct pointers.


Example Usage:
int myptr = Malloc(256);

MemFree(myptr);


================================================================================
a. verge.cfg options
================================================================================
xres [res] -width of screeen in pixels 

yres [res] -height of screeen in pixels (note this is different than vid_mode or
whatever). 

nosound [0/1] - turn sound on or off 

windowmode [0/1] - fullscreen mode or windowed mode 

automax [0/1] - maximizes window automatically 

releasemode [0/1] - to compile or not to compile 

startmap [mapname] - initial map

vcverbose [0/1] - controls whether or not verge generates vccverbose.txt during
compilation (default 0)



(from v3changelog.txt)

 - Added 'gamerate' verge.cfg option, will set the timer think rate. Note that
using the default of 100 is highly recommended unless you know what you're doing
- changing this value will effect the timing of EVERYTHING.

================================================================================
b. changelog
================================================================================
========================================
09/28/04
 - Fixed bug in 32-bit, 50% lucent vertical line render
 - Fixed bug in idle frame handling of follower entities
 - Added code that validates animations when a VSP is loaded.
   Previously if a tileset had an animation which referenced
   tiles greater than the number of tiles in the tileset (because
   some were deleted), the engine would simply crash at random
   times and give no indication of the cause. 
 - Fixed a bug relating to a #define being the last line
   of an #include causing valid VC code to not compile
 - Fixed a crash bug when an integer type is passed
   as a string argument
 - Fixed a crash bug with non-arrayed strings in
   a non-arrayed struct
 - Added CF_CUSTOM color filter mode, along with
   SetCustomColorFilter(int color1, int color2)
 - Added netcode.

========================================
08/01/04
 - Added RenderMap() to allow rendering chunks of map direct to
   an image you specify.
 - Added SetButtonKey() and SetButtonJB() to allow remapping of
   b1-b4; up/down/left/right cannot be remapped because in both
   keyboard and joystick handling, special processing is done
   for these.
 - Bug fixed in FileReadString()
 - Fixed bug causing SetEntitiesPaused() to totally stop responding
   to the message queue in the main game loop
 - FontHeight() no longer returns... the font width.
 - Fixed a bug in PrintRight()
 - automax 0 works again.
 - Added FunctionExists()
 - Added atan2()
 - Added windows clipboard functions CopyImageToClipboard() and 
   GetImageFromClipboard() and the variable clipboard.text
 - Corrected a bug in the vc error system that performs reverse-
   lookups on code offsets for stack traces. This should help fix
   some situations where VERGE crashes due to a (runtime) VC error 
   rather than return an error message.
 - Added GetInt(), SetInt(), GetString(), SetString(),
         GetIntArray(), SetIntArray(), GetStringArray(), and SetStringArray()
 - EntityStop() will now abort any delay commands
 - Added FlipBlit()
 - SetRandSeed() will now give deterministic results.
 - Improved line number error reporting drastically.  
 - Added 'vcverbose [0/1]' verge.cfg command to control if the vc compiler
outputs
   vccverbose.txt (defaults 0)
 - cameratracking = 2 functionality added, cameratracker variable added
 - Added several new variables:

	entity.visible
	entity.obstruct
	entity.obstrucable
	entity.script

	curmap.w
	curmap.h
	curmap.startx
	curmap.starty
	curmap.name
	curmap.rstring
	curmap.music
	curmap.tileset

	layer.lucent

========================================
04/21/04
 - Bug in renderstring parser fixed.
 - HookTimer() crash bug fixed. (between this and the above fix,
   it seems most win98-related crashes are gone now too)
 - SCAN_GPLUS is now correctly defined.
 - Upon ChangeCHR(), the entity animation/specframe/etc state will
   be reset to prevent out of bounds frame errors.
 - Maximum image capacity has been increased.
 - Added 'P' and 'T' commands to entity movestrings. P will enable
   pixel-accurate arguements to U/D/L/R (X/Y will still work in tile
   increments). T will set it back to tile increments. 
 - Added 'gamerate' verge.cfg option, will set the timer think rate.
   Note that using the default of 100 is highly recommended unless you
   know what you're doing - changing this value will effect the timing
   of EVERYTHING.
 - You'll no longer get a message looking for a map file if autoexec
   returns without a Map() or Exit() call.
 - Added SetEntitiesPaused() to pause/unpause automatic entity processing.
 - Added SetRandSeed() to allow setting the random number generator seed.
   Note that passing a value of 0 will set a random seed (since generating
   a random seed can be tricky if you already set the random generator's
   seed to something deterministic).
 - Bug causing the maximum volume of SetSongVol() to be 666 (!) instead
   of 100 fixed. I swear, if you saw the math going on, ... 666... wtf.
 - Added HookKey() and HookButton()
 - Tweaked font spacing for fixed-width fonts.
 - Introducing the V3 Sprites system! This is a preliminary version, 
   additional improvements are planned for the next build, including
   horiz/vert flipping, layer specification, and a sprite-thinking 
   callback system that will assist people that have a hard time writing 
   timer-based code :D

========================================
04/09/04
 - GetObsPixel is fixed.
 - entity.frame[] will now account for idle frames.
 - Idle frames will now be the idle frames specified in the
   CHR, not the first frame of the walking animation for that
   direction.
 - cameratracking is fixed.
 - Samples will no longer loop when played regardless of the
   default looping setting of the sample.

========================================
04/04/04
 - Map/Entity/CHR system.
 - Map VC system implemented.
 - Issue with Random seeding has been corrected.
 - Tools and stuff released. 

========================================
02/22/04 
 - Mikmod out. FMOD in. Music API restructured.
   There is now a "simple music" API and an advanced
   music API, which is needed to do things like
   crossfading, pausing, and manipulation of music position.
   Both APIs fully support modules, MIDIs and mp3/oggs.
   Sound effects can also be either wav or mp3/ogg.
   (however they are handled differently. sound effects are
   fully loaded into memory; mp3s played as music are streamed)
 - A bug in for() loops was fixed.
 - The "system" font now renders to any image correctly.
 - A few new window management routines were added.
 - Some new string-handling functions. TokenCount() and
   GetToken() will aid with breaking a string apart for 
   purposes of word wrapping for instance. Also added 
   ToUpper() and ToLower().
 - LoadFont no longer takes w/h arguments. The cell size 
   is automatically detected. Its not foolproof however, in 
   cases where the autodetection fails, you can still use the
   original loader that takes width/height, now named 
   LoadFontEx.
 - Joystick variables are now activated.
 - Miscellaneous new VC commands: FontHeight(), MixColor(),
   and chr().
 - Fixed a bug involving string arrays causing problems with
   all strings declared after it by not updating the offsets
   correctly.
 - Fixed a bizarre bug with launching v3 from Textpad :o
 - Using %s or other %codes in VC strings wont screw stuff
   up anymore.
 - Added lastkey; returns the last key pressed as an ASCII
   character
 - Eagle/2xSAI has been removed until such time as we get around
   to fixing it and putting it back in or giving a care about it
   in general
 - Preliminary AVI playback is in. There are still some bugs
   and quirks that we are working out. We HIGHLY RECOMMEND 
   that you use only simple codecs like intels Indeo and not
   DIVX/XVID due to codec compatibility issues. Unless you 
   plan to make an installer and include the codecs your 
   game uses. ^_^



================================================================================
c. planned features
================================================================================
Next Build:
Well, all the stuff that was on this list is now done. But we can look forward
to binary trees (faster compile, better error reporting and faster
CallFunction(). Also, hopefuly a little more stuff with entities. :D

================================================================================
d. known issues
================================================================================
Crash on returning from switch () statements. Use an intermediary varaible or if
() instead.
int ReturnSomething(int pass) // This will crash
{
	switch (pass)
	{
		case 23: return 1;
		case 24: return 0;
	}
}

int ReturnSomething(int pass) // So use this instead
{
	int thingy;
	switch (pass)
	{
		case 23: thingy = 1;
		case 24: thingy = 0;
	}
	return thingy;
}

int ReturnSomething(int pass) // Or this
{
	if (pass == 23) return 1;
	if (pass == 24) return 0;
}
No unary operator. There are workarounds.
x = -1; // verge does not like this
x = 0-1; // So use this instead
if (!x) // This is fine - there's a custom handler for this case
#defines tend to behave a little oddly. Use global variables instead if you run
into problems. (probably all fixed now)

Hex can be fussy. Use plain numbers instead if you run into trouble
if (w & $FF00 == $FF00)
{
    // BROKEN
}
if (w & 65280 == 65280)
{
    // Using decimals works fine
}
Various win98 issues, such as window size problems.



MOAR TO BE ADDED
================================================================================
--------------------------------------------------------------------------------
f. Function Reference
--------------------------------------------------------------------------------
================================================================================

================================================================================
a. General Utility Functions
================================================================================
For the General System Variables, go [here].

--------------------------------------------------------------------------------
void CallFunction (string funcname)
--------------------------------------------------------------------------------
Executes a function by the name it's given.

Documentation:
Calls a function by name. This can be useful for creating "function tables" of a
sort, which might be useful for item effects or magic visual effects or things
like that.

The function to be called MUST take no parameters. It may or may not return
void, but it is impossible to catch the return value when called this way.

If you wish to simulate arguments and return values, it is neccesary to use
global variables for both roles.  Be careful in doing this, as it leaves a lot
of room for user error.  I would suggest heavy error checking within the
functions, unless the CallFunc is something that's being called frequently.

If the specified function name does not exist, or is a v3 builtin function,
CallFunction() will just do nothing (no error messages).  If you care that a
function exists, please refer to FunctionExists(). 

Example Usage:
//
// A simple example.
//

void MyFunc()  
{ 
	exit( "Hello world!" );
}

void Autoexec()
{
	CallFunction("MyFunc");
}



//
// A more complicated example illuminating the possibilities of this function
//

void FuncA()  
{ 
	log( "Function A was called!  Eeeeh!" );
}

void FuncB()  
{ 
	log( "Function B was called! Bzzzz..." );
}

void Autoexec()
{
	int i, j; //for the for-loop lower down...
	
	// let's make a lookup table
	string MyLookupTable[2]; 
	
	// and now we initialize it...
	MyLookupTable[0] = "FuncA";
	MyLookupTable[1] = "FuncB";
	
	//and now let's set up a silly way to make it look things up
	for( i=0; i


--------------------------------------------------------------------------------
void Exit (string message)
--------------------------------------------------------------------------------
Quits the VERGE Engine with the supplied message.

Documentation:
Exit terminates the verge engine application.

If the message string is empty, it will exit immediately with no message box. 

If the message string is not empty, the a message box will pop up with the exit
message displayed, when the message box is closed the application will end.



Example Usage:

//this exits the program without an alert window.
Exit(""); 


//this exits the program with a little self-centered promotion! :D
Exit("http://vecna.verge-rpg.com");


--------------------------------------------------------------------------------
int FunctionExists (string funcname)
--------------------------------------------------------------------------------
Determines the existance of a given function based on it's name.

Documentation:
Returns 1 if the function named in the argument exists, 0 if it doesn't exist. 
However, it does so with the following caveats:


v3 builtin functions will return 0.
All user-defined system functions will return 1.
All map-specific functions will only return 1 if the map with that function is
loaded.

 ie: if island.map has a Sully() in it's vc file, and castle.map does not have
Sully() in it's vcfile, FunctionExists("Sully") will return 1 if island.map is
loaded, and 0 if castle.map (or any other map that doesn't have a Sully()) is
loaded.

All compares are case insenitive.


This function is extremely useful for errorchecking purposes when you're using
CallFunction() in conjunction with datafile-defined strings, or any other time
you're using CallFunction() and explicitly demand that a function exist.

Example Usage:
//copy this all into a blank system.vc and run verge 
//if you don't understand what's going on.

void Sully() 
{
	exit( "I am a clam.  I have no beard.  Isn't that weird?" );
}

void Autoexec() 
{
	if( FunctionExists("Sully") )
	{
		CallFunction( "Sully" );
	}
	else
	{
		exit( "Sully() does not Exist!" );
	}
}


--------------------------------------------------------------------------------
int GetInt (string intname)
--------------------------------------------------------------------------------
Returns the value of an integer.

Documentation:
Returns the value of an integer variable. Does not work on integers inside
structs currently.

Example Usage:
int num;
string my_var="num"; //'my_var' now points to 'num'.
GetInt(my_var); //Gets the value of 'num'.


--------------------------------------------------------------------------------
int GetIntArray (string intname, int index)
--------------------------------------------------------------------------------
Returns the value of an index of an int array

Documentation:
Returns the value of an index inside an integer array variable. Does not work on
integer arrays inside structs currently.



Example Usage:
int num[12];
string my_var="num"; //'my_var' now points to 'num'.
int my_index=7; //'my_index' is set to 7.
GetIntArray(my_var,my_index); //Gets the value of 'num[7]'.


--------------------------------------------------------------------------------
string GetString (string strname)
--------------------------------------------------------------------------------
Returns the value of a string.

Documentation:
Returns the value of an string variable. Does not work on strings inside structs
currently.

Example Usage:
string name;
string my_var="name"; //'my_var' now points to 'name'.
GetString(my_var); //Gets the value of 'name'.


--------------------------------------------------------------------------------
string GetStringArray (string strname, int index)
--------------------------------------------------------------------------------
Returns the value of an index of a string array

Documentation:
Returns the value of an index inside an string array variable. Does not work on
string arrays inside structs currently. 


Example Usage:
string name[98];
string my_var="name"; //'my_var' now points to 'name'.
int my_index=21; //'my_index' is set to 21.
GetStringArray(my_var); //Gets the value of 'name[21]'.


--------------------------------------------------------------------------------
void HookButton (int button, string function)
--------------------------------------------------------------------------------
Calls the specified function on every discrete press of the specified button

Documentation:
Each time the key, set by the standard button numbers, is pressed the function
is called. Note this is once and only per button press, it is not called
repeatedly if the button is held. It needs to be released then pressed again to
trigger another function call. As with all hook functions, it requires the
string of a function name that requires no passed values, and any return value
is ignored. To remove the hook, call pass "" as the function name. The button
numbers to pass are:

1 - Enter or b1

2 - Alt or b2

3 - Esc or b3

4 - Space or b4

5 - Up *CURRENTLY NOT WORKING*

6 - Down *CURRENTLY NOT WORKING*

7 - Left *CURRENTLY NOT WORKING*

8 - Right *CURRENTLY NOT WORKING*


Example Usage:
// Put this in system.vc and it will actually compile and run...
void autoexec()
{
	// Hooks the up key to the function
	HookButton(1, "ButtonDown_Enter");
	while (!b3) { UpdateControls(); }
	exit("And you said you would change...");
}

void ButtonDown_Enter() // If up arrow is pressed
{
	// Display a little message box
	MessageBox("One enter button pressed");
}


--------------------------------------------------------------------------------
void HookKey (int key, string function)
--------------------------------------------------------------------------------
Calls the specified function on every discrete press of the specified key

Documentation:
Each time the key, set by a scan code is pressed the function is called. Note
this is once and only per key press, it is not called repeatedly if the key is
held. It needs to be released then pressed again to trigger another function
call. As with all hook functions, it requires the string of a function name that
requires no passed values, and any return value is ignored. To remove the hook,
call pass "" as the function name. Where you can, use HookButton() instead, as
this also supports gamepad input.

Example Usage:
// Put this in system.vc and it will actually compile and run...
void autoexec()
{
	// Hooks the up key to the function
	HookKey(SCAN_UP, "KeyDown_Up");
	// Stay in the program loop until escape is pressed
	while (!b3) { UpdateControls(); }
	exit("Well, if you will take another lover...");
}

void KeyDown_Up() // If up arrow is pressed
{
	// Display a little message box
	MessageBox("One up key pressed");
}


--------------------------------------------------------------------------------
void HookRetrace (string func)
--------------------------------------------------------------------------------
Calls the specified function everytime an R is hit in the renderstring.

Documentation:
Calls the specified function everytime an R is hit in the renderstring.  For
example, if your renderstring is "1E2R", every time the 'R' is rendered, the
function you specified in this hook will be called.
HookRetrace's frequency of calling varies from system to system and game to
game.  If person a is getting 40 frames per second, the hooked function will be
called 40 times a second for them.  If another person gets 80 frames per second,
that person's hooked function will be called 80 times a second.  It is this
behavior that makes HookRetrace ideal for anything that depends specifically on
the framerate.  Anyone needing a more consistant timer should look into
HookTimer.


Example Usage:
/**
 * Assume that this function exists somewhere in the system code.
 */

void tint_screen() 
{
    ColorFilter( CF_GREY, screen );
}

/**
 * Assume this line is in your map's startup function.
 */

HookRetrace( "tint_screen" );

/**
 * Now, when the map with the preceding line is run, what happens depends on 
 * It's renderstring.
 *
 * Since the function is only called when an 'R' is hit in the string, if your
string 
 * was "1E2R", everything would be grayscale since it was applied after 
 * everything else was rendered.
 *
 * However, if the renderstring was "12RE" the map would be grayscale, and the

 * entities on the map would be in color.  (This is how Paladin's Quest did
their 
 * flashbacks, for an obscure reference.)
 *
 * If your Rstring was "1ER2", then layer 1 and the entities would be gray, and

 * tile layer 2 would be in it's original colors.  See how it works?
 *
 * Finally, if the Rstring had no 'R' in it at all, like "1E2", then the
function specified
 * in HookRetrace would never be called!
 */



--------------------------------------------------------------------------------
void HookTimer (string funcname)
--------------------------------------------------------------------------------
Calls the specified function once every timer tick.

Documentation:
The specified function will be called every timer tick, 100 times per second. 

As with other Hook* functions, the function name is passed as a string and the
given function must be void and take no arguements. 

If the string passed does not resolve as a known function at run-time, no
hooking will occur.



Example Usage:
HookTimer("MyTimer");

void MyTimer()
{
   mytimer++;
}


--------------------------------------------------------------------------------
void Log (string logtext)
--------------------------------------------------------------------------------
Write a line of text to your logfile.  Essential for debugging.

Documentation:
Log() simply writes logtext to the verge.log file. This is an exceedingly useful
tool for debugging your VC code.


Example Usage:
Log("Initializing new game...");


--------------------------------------------------------------------------------
void MessageBox (string text)
--------------------------------------------------------------------------------
Pops up a windows Messagebox.

Documentation:
Pops up a windows messagebox, as with Exit, but without exiting the engine.
Primarily intended for debugging use, when you want a notification more
immediate than with Log().
Note that vc-execution pauses while the system waits for the user to press the
'ok' button on the MessageBox that pops up.


Example Usage:
MessageBox("Notification: Grue likes anuses");

MessageBox("Notification: vecna can't sit down painlessly right now...");


--------------------------------------------------------------------------------
int Random (int min, int max)
--------------------------------------------------------------------------------
Returns a random integer between min and max.

Documentation:
Returns a random integer between min and max.
You can seed this random number generator by using SetRandSeed()


Example Usage:
int rand = Random(0,10);


--------------------------------------------------------------------------------
void SetAppName (string name)
--------------------------------------------------------------------------------
Set the window's application name for your program.

Documentation:
Sets the application name shown in the taskbar and the verge3 application
window.


Example Usage:
SetAppName("verge3 ultra edition by VECNAR");


--------------------------------------------------------------------------------
void SetButtonJB (int button, int jb)
--------------------------------------------------------------------------------
Sets an internal VERGE button to a joystick button.

Documentation:
This function will set the default VERGE buttons (b1,b2,b3,b4) to the specified
joystick button. Useful for custom button mapping dialogues.

Example Usage:
SetButtonJB(1,5); //Sets internal VERGE button b1 to read from joystick button
5.


--------------------------------------------------------------------------------
void SetButtonKey (int button, int key)
--------------------------------------------------------------------------------
Binds an internal VERGE button to a key

Documentation:
The values used for the button variable are the same integers that are passed to
the unpress() function. The values for the key variable are from the SCAN
defines. 

i.e.
SetButtonKey(1, SCAN_Z);
//Would set button 1, which defaulted to [enter] to the 'Z' key on the
keyboard

SetButtonKey(2, SCAN_O);
//Would set button 2, which use to be [alt] to the 'O' key on the keyboard.

All of the button values are defined Here (-Ness)


Example Usage:
// Sets button 1 (which was enter) to Z on the keyboard
SetButtonKey(1, SCAN_Z);


--------------------------------------------------------------------------------
void SetInt (string intname, int value)
--------------------------------------------------------------------------------
Sets the value of an integer.

Documentation:
Sets the value of an integer variable. Does not work on integers inside structs
currently.

Example Usage:
int num;
string my_var="num"; //'my_var' now points to 'num'.
SetInt(my_var,176); //Sets the value of 'num' to 176.


--------------------------------------------------------------------------------
void SetIntArray (string intname, int index, int value)
--------------------------------------------------------------------------------
Sets the value of an index of an int array.

Documentation:
Sets the value of an index inside an integer array variable. Does not work on
integer arrays inside structs currently.



Example Usage:
int num[12];
string my_var="num"; //'my_var' now points to 'num'.
int my_index=7; //'my_index' is set to 7.
SetIntArray(my_var,my_index,1337); //Sets the value of 'num[7]' to 1337.


--------------------------------------------------------------------------------
void SetRandSeed (int seed)
--------------------------------------------------------------------------------
Initializes the random number generator

Documentation:

This function may be used to initialize the random number generator with the
seed of your choice.  If you are careful, you may be able to rig your game to
behave the same every time if you initialize it with the same random seed every
time.

Example Usage:
SetRandSeed(109);


--------------------------------------------------------------------------------
void SetResolution (int xres, int yres)
--------------------------------------------------------------------------------
Sets the screen's resolution.

Documentation:
Sets the screen resolution to the (xres, yres). This will always succeed in
windowed mode, but it may fail in fullscreen mode.

Come to think of it, I should probably make it return a value based on whether
or not it suceeds. If you see this, remind me! :D



Example Usage:
SetResolution(640, 480);


--------------------------------------------------------------------------------
void SetString (string strname, string value)
--------------------------------------------------------------------------------
Sets the value of a string.

Documentation:
Sets the value of an string variable. Does not work on strings inside structs
currently.

Example Usage:
string name;
string my_var="name"; //'my_var' now points to 'name'.
SetString(my_var,"Bob"); //Sets the value of 'name' to "Bob".


--------------------------------------------------------------------------------
void SetStringArray (string strname, int index, string value)
--------------------------------------------------------------------------------
Sets the value of an index of a string array

Documentation:
Sets the value of an index inside an string array variable. Does not work on
string arrays inside structs currently.



Example Usage:
string name[98];
string my_var="name"; //'my_var' now points to 'name'.
int my_index=21; //'my_index' is set to 21.
SetStringArray(my_var,"Ralph"); //Sets the value of 'name[21]' to "Ralph".


--------------------------------------------------------------------------------
void Unpress (int button)
--------------------------------------------------------------------------------
Causes a button to show as released until it is pressed again

Documentation:

This important function is used when you have handled a button press event and
are ready for the engine to not show it as being pressed any more.  After
calling unpress() for that button, the button will be read as being released. 
It will not read as being pressed until the user presses the button again.

This is most commonly used for buttons that operate as events, rather than
states.  For example, normally the [left] button will make a character be
walking as long as it is pressed down.  But if [left] is being used to control a
menu cursor, you do not want to move the cursor left for as long as it is
pressed (otherwise you will whiz across the menu in a split second).  You may
want to require each movement in the menu to be a separate press of the [left]
button.  In this case, you would use unpress() after you did each movement.

I have made this sound more complicated than it is.  Just look at the example.

This table shows the values to be given to unpress for each of verge's logical
buttons.  If you want to unpress left, you would use unpress(7).

0b1,b2,b3,b4
1b1
2b2
3b3
4b4
5up
6down
7left
8right


Example Usage:
if(b1) { confirm(); unpress(1); }


--------------------------------------------------------------------------------
void UpdateControls ()
--------------------------------------------------------------------------------
Updates all keyboard, joystick, and verge system input variables.

Documentation:
Updates all keyboard and joystick input variables, including the key[] array, as
well as the "Quick Keys", such as b1, b2..etc.


Example Usage:
UpdateControls();
// deal with input


================================================================================
b. String Functions
================================================================================


--------------------------------------------------------------------------------
string chr (int ascii)
--------------------------------------------------------------------------------
Returns a string representation of the ascii code given.

Documentation:
Returns a string representation of the ascii code given.
The following are some useful instances for this function in verge:


chr(34) is the DOUBLEQUOTE (")
chr(10) is the NEWLINE (that thing you get when you hit enter)



for a full list of ascii codes, go to asciitable.com


Example Usage:
string s;

s = chr( 35 ); // s is now equal to "#"


--------------------------------------------------------------------------------
string GetToken (string source, string delimiters, int index)
--------------------------------------------------------------------------------
Retrieves a token from a string

Documentation:
Given a source string and a set of delimiters, returns the token at the given
index.  The set of delimiters is in the form of a string containing each of the
delimiter characters concatenated.  For example, if you want to use space,
hyphen, and semicolon as delimeter characters, you would use "; -".


Example Usage:
GetToken("a-b-c","-",1); //returns token index 1
//        0 1 2


--------------------------------------------------------------------------------
string left (string s, int ofs)
--------------------------------------------------------------------------------
Crops off beginning of a string

Documentation:
Takes the given string and crops 'ofs' number of characters from the leftside of
the string going right.


Example Usage:
woot="All work and no play make jack a dull boy";
woot=left(woot,10);

woot == "All work a";


--------------------------------------------------------------------------------
int len (string s)
--------------------------------------------------------------------------------
Returns the length of a string.

Documentation:
Returns the length of a string.  


Example Usage:
int i;

i = len( "I LIKE TACOS." ); //i is now equal to 13.


--------------------------------------------------------------------------------
string mid (string s, int ofs, int len)
--------------------------------------------------------------------------------
Crops out a section of a string

Documentation:
Takes string 'str' and crops out characters from ofs to ofs+len or in other
words crops from ofs for len characters.

Example Usage:
string woot="All work and no play makes jack a dull boy";
woot=mid(woot,10,15);

woot == "nd no play make";


--------------------------------------------------------------------------------
string right (string s, int ofs)
--------------------------------------------------------------------------------
crops off end of a string

Documentation:
takes string 's' and crops out around ofs characters starting from the right
going left.

Example Usage:
string woot="All work and no play makes jack a dull boy.";
woot=right(woot, 10);

woot == " dull boy."


--------------------------------------------------------------------------------
string str (int val)
--------------------------------------------------------------------------------
Changes an int into it's string representation.

Documentation:
Changes an int into it's string representation.


Example Usage:
string s;

s = str( 42 ); 
//s is now equal to the string "42".  


--------------------------------------------------------------------------------
int strcmp (string s1, string s2)
--------------------------------------------------------------------------------
Compare two strings, checking for equality.

Documentation:
Strcmp compares two strings and returns 0 if they're equal, 1 if they're
inequal. This comparison is case-sensitive.
This may seem backwards for some as it returns a false value if the strings are
equal.  However, it's put in place this way so that it's forwards compatible
with any 'string distance' functionality that may be added in the future.
Always remember to put a ! in front of strcmp in if-statements if you're
checking to see if two strings are equal.


Example Usage:
if( !strcmp("bob","fred") ) 
{
    log( "This should never execute." );
}
else
{
    log( "Bob is not Fred.  Good show!" );
}


--------------------------------------------------------------------------------
string strdup (string s1, int times)
--------------------------------------------------------------------------------
Duplicates string over a number of times

Documentation:
Strdup returns a string composed of the string 's1' repeated times 'times'. 

Example Usage:
strdup("blah",1) returns blah. 
strdup("blah",3) returns blahblahblah.
strdup("blah",0) returns an empty string.


--------------------------------------------------------------------------------
int TokenCount (string source, string delimiters)
--------------------------------------------------------------------------------
Counts the number of tokens in a string

Documentation:

Given a string and a set of delimiters (see GetToken()), counts the number of
tokens that can be retrieved from it.

Example Usage:
//returns the last name
int count = TokenCount("john jacob jingleheimer smith" ," " ); 
string lastname = GetToken("john jacob jingleheimer smith" ," ", count-1);


--------------------------------------------------------------------------------
string ToLower (string source)
--------------------------------------------------------------------------------
Takes string and formats all the letters into lowercase form

Documentation:
Takes string and formats all the letters into lowercase form

Example Usage:
string blah="Hi! my name is BOB!";
blah=toLower(blah);
blah == "hi! my name is bob!"


--------------------------------------------------------------------------------
string ToUpper (string source)
--------------------------------------------------------------------------------
Takes string and formats all the letters into uppercase form

Documentation:
Takes string and formats all the letters into uppercase form

Example Usage:
string blah="hi! my NAME is BOB.";
blah=toUpper(blah);
blah == "HI! MY NAME IS BOB.";


--------------------------------------------------------------------------------
int val (string s)
--------------------------------------------------------------------------------
Attempts to convert a string into it's numeric value.

Documentation:
val attempts to convert a string representation of a number into its integer
value.
val is very clever.


Example Usage:
int i;

i = val( "25" ); // i is now equal to 25.
i = val( "77%" ); // i is now equal to 77.

i = val( "BOB" ); 
// i is now equal to 0, 
// because it failed to change bob into a number.


================================================================================
c. Map Functions
================================================================================


--------------------------------------------------------------------------------
int GetObs (int x, int y)
--------------------------------------------------------------------------------
Chekcs for obstructions at tile coords

Documentation:
Returns the index of the obstruction tile at the given coords.

Note: Coords in terms of tiles, not pixels.

Example Usage:
I'm not really sure how else to give an example so...

picture this as a map with the obstructions being an X:

     1   2  3

1   |O|O|O|
2   |O|O|O|
3   |O|X|X|

getObs(0,0)==0;
getObs(3,3)==1;
getObs(2,3)==1;
getObs(2,1)==0;


--------------------------------------------------------------------------------
int GetObsPixel (int x, int y)
--------------------------------------------------------------------------------
Check for obstruction pixels on the map

Documentation:
returns 0 if there is no obstruction at the map pixel. 

Note: Map pixel grid, not screen pixel grid.

Example Usage:
none


--------------------------------------------------------------------------------
int GetTile (int x, int y, int layer)
--------------------------------------------------------------------------------
Find specific VSP index of tile

Documentation:
Returns the vsp index of the tile at coords x,y on the given layer. Note: xy is
in terms of tiles.

Example Usage:
none


--------------------------------------------------------------------------------
int GetZone (int x, int y)
--------------------------------------------------------------------------------
Find index of zone at tile coords

Documentation:
Find index of zone at tile coords x,y.

Example Usage:
none


--------------------------------------------------------------------------------
void Map (string mapname)
--------------------------------------------------------------------------------
Loads the specified map.

Documentation:
This function loads a map.  If you are using maps in your game, which is not
strictly neccesary, this function is essential.
VERGE 3 format .MAP files are currently only created by MapEd 3.
 Upon execution of this function, all code execution halts completely, never to
be returned, and starts anew in the map's own vc's starting function.  For a
more in-depth discussion of the correlation between system-vc and map-vc, please
view [this section].


Example Usage:
//Example 1
/////////////////////////////////////////////

// this loads the map named "test.map" 
// located in the base verge directory.

map( "test.map" ); 



//Example 2
/////////////////////////////////////////////

// This demonstrate's map()'s ability to 
// stop all  functionality under it.

void grue_is_awesome() {
	map( "test.map" );
	exit( "GRUE SUXS!!!!" );
}

void autoexec() {
	grue_is_awesome();  
}

// When this program is executed, 
// as long as ./test.map exists, you will 
// load that map fine, and the program will 
// never exit with the "GRUE SUXS!!!!" 
// message.  This is because map() halts the
// function it was called in, and starts off anew in
// the map-vc.




--------------------------------------------------------------------------------
void Render ()
--------------------------------------------------------------------------------
Blits the map and entities to "screen"

Documentation:
Blits the map and entities to the variable screen.
Note: This also will run what ever function you have HookRetrace()'d.  Which
makes this a very bad function to ever call in a HookRetraced function (since it
would cause an infinite loop and crash the game.)

Example Usage:
render();
showpage();


--------------------------------------------------------------------------------
void RenderMap (int x, int y, int destimage)
--------------------------------------------------------------------------------
Renders the map to the target image

Documentation:
This function allows you to render the map and its entities to an image other
than the screen. The x and y are the screen offset in pixels, often making xwin
and ywin desirable arguments. If used in conjunction with curmap.rstring, you
could do some interesting things.

Example Usage:
//Make only Entities be rendered, and then...
curmap.rstring="E";
//...take a snapshot of the map...
RenderMap(xwin,ywin,img);
//...and copy it to the clipboard.
CopyImageToClipboard(img);


--------------------------------------------------------------------------------
void SetObs (int x, int y, int z)
--------------------------------------------------------------------------------
Place an obstruction on the map

Documentation:
Places an obstruction on the map in terms of tiles. Z represents the obstruction
set index.

Example Usage:
none


--------------------------------------------------------------------------------
void SetTile (int x, int y, int layer, int tile)
--------------------------------------------------------------------------------
Place a tile on the map

Documentation:
Place tile index 'tile' on map layer, at tile coords x,y

Example Usage:
none


--------------------------------------------------------------------------------
void SetZone (int x, int y, int z)
--------------------------------------------------------------------------------
Place a zone on the map

Documentation:
Changes the zone at tile-coordinates (x,y) to value z.
Note: zone z must exist on the map, or else SetZone will just set the zone at
tile-coordinates (x,y) to 0.  This is so v3 doesn't crash, which is, overall, a
good thing.

Example Usage:
SetZone( 5,13, 53 ); //the zone at tile (5,13) is now 53.


================================================================================
d. Entity Functions
================================================================================
For the corresponding Entity variables go here

--------------------------------------------------------------------------------
void ChangeCHR (int entity, string chr)
--------------------------------------------------------------------------------
Replaces an entity's imagefile on the map with a different one

Documentation:
Replaces entity 'entity' imagefile on the map with string 'chr's image file.
This will also effect the hotspots, animation, etc.

Example Usage:
int currentplayer=entitySpawn(10,10,"Me.chr");
changeChr(currentPlayer, "Him.chr");


--------------------------------------------------------------------------------
void EntityMove (int entity, string script)
--------------------------------------------------------------------------------
Sets the movecode of an entity - so moving them around on the map

Documentation:
With this function you can set actions for the entity (specified by int
reference) to follow using a 'movecode' string. In verge a movecode is a string
of instructions for an entity to follow, one after the other, like a 'script'.
Each command is a letter, sometimes followed by a number, here are a list of
what each does:
ulrd (followed by number) Move the entity either up, down, left or right by set
number of tiles.
xy (followed by number) Move an entity so a set x or y tile position
pt Changes movement to either pixel accurate, p, or tile accurate, t *CURRENTLY
BROKEN*
z (followed by number) Set the current frame of the entity, like setting
entity.specframe
w (followed by number) The entity pauses for set number of timer ticks (default
100 = 1 second)
f (followed by number) Sets the entity's facing: use directional 0 moves
instead, then you don't need to remember which number is which direction
b Loops the entire movecode, eternally

They can be either upper or lower case (which ever you think looks nicer) and
don't need a space or anything between commands. Verge processes entity
movecodes every call to Render() (???and ShowPage()???) so, if you need the game
to 'pause' for a textbox or something, make sure you use SetEntitiesPaused() so
the entities don't suddenly 'jump' to their next positions.
There are a few things to remember when moving entities around, firstly the
entity needs to have their specframe set to 0 to enable the walk animation,
rather than just sliding around. So if you change the frame, remember to set it
back with “z0” before moving. Also, any movement is ignorant of obstructions and
other entities, so make sure to test what you use to make sure it works as
expected.
Note, unlike PlayerMove(), verge does not wait for this to finish before running
the next line of code. So you can set several entities moving all at the same
time. However, it is likely you will sometimes want to wait untill a particular
entity has finished moving, so I recommend having a WaitForEntity() function.

Example Usage:
// Examples adapted from Parallel Seven

// Moves the first party member to the x position 77, 
// then to the y position 42, then faces upwards
EntityMove(party[0].ent, "x77y42u0");

// Animate drunk picking up broken bottle
EntityMove(2, "z24w80z25w100");
// Waits till the entity is done with the movecode before continuing
WaitForEntity(2);

void IdleAnimPlayer(int pparty)
// Sets a party member into the idle animation
{
	EntityMove(party[pparty].ent, "z4w100z2w100b");
}
// Note: The 'b' at the end repeats this movecode

// Sets the party member to animated movement frame
EnityMove(party[pparty].ent, “z0”)


--------------------------------------------------------------------------------
void EntitySetWanderDelay (int entity, int delay)
--------------------------------------------------------------------------------
Change the wander delay time.

Documentation:
This function changes the specified entity's wander delay to a new value.
The wander delay is how long the entity will wait before wandering around
again.
The value specified is in 1/100ths of a second.

This function is a part of a small family of Wander-mode effecting Entity
functions, which includes:
	EntitySetWanderDelay, 
	EntitySetWanderRect, 
	EntitySetWanderZone, and 
	EntityStop.


Example Usage:
//This sets entity 3 on the map to take a wander-step twice
//   a second (which is kinda fast)
EntitySetWanderDelay( 3, 50 );

//This sets entity 42 on the map to take a wander-step once
//   every 6 seconds (which is kinda slow)
EntitySetWanderDelay( 42, 600 );


--------------------------------------------------------------------------------
void EntitySetWanderRect (int entity, int x1, int y1, int x2, int y2)
--------------------------------------------------------------------------------
Sets an entity's wandermode to Rect.

Documentation:
This function changes the specified entity's wander mode to Rect.
The entity will wander within the bounds of the map coordinates specified. 
x1,y1 represents the tile coordinates of the top-left corner of the wander
rectangle area, and x2,y2 represents the bottom-right corner.
If the entity is outside the rectangle but adjacent to it he could move inside
it.  However, if the entity is completely not anywhere near the rectangle, it
will not be able to wander.
If anyone would like to report what happens if you use x1,y2 for any other
corner and x2,y2 for the opposite, please inform us.  I'm too tired to check.
-Grue

This function is a part of a small family of Wander-mode effecting Entity
functions, which includes:
	EntitySetWanderDelay, 
	EntitySetWanderRect, 
	EntitySetWanderZone, and 
	EntityStop.


Example Usage:
// This sets map entity index 1 to wander within an area between 
//  tile (0,0) and tile (10,10)

EntitySetWanderRect( 1,  0,0, 10,10 );


--------------------------------------------------------------------------------
void EntitySetWanderZone (int entity)
--------------------------------------------------------------------------------
Sets an entity to wander about in Zone 0.

Documentation:
This function changes the specified entity's wander mode to Zone.
This function tells an entity to wander around within the confines of the zone
it is currently standing in.  Other zones will act like obstructions to it.
For the curious, no zone data is stored concerning this functionality; The
entity just compares it's current zone to the zones of where it can move when
it's thinking about moving.

This function is a part of a small family of Wander-mode effecting Entity
functions, which includes:
	EntitySetWanderDelay, 
	EntitySetWanderRect, 
	EntitySetWanderZone, and 
	EntityStop.


Example Usage:
//let's pretend we're talking to Sor, Norse god of muscle fatigue!

void Talk_Sor() 
{
	//stop the entity so we can talk to him...
	EntityStop( event.entity );

	// Do the talking!
	//
	// TextBox( SOR_PRT, "Yeah yeah, well, I'm twice as Thor as he'll ever be.  Can
I get a massage here now?" );

	//now that we're done talking, set the entity to wander-zone mode so he can
wander around again.
	EntitySetWanderZone( event.entity ); 
}


--------------------------------------------------------------------------------
int EntitySpawn (int x, int y, string chr)
--------------------------------------------------------------------------------
spawn an entity onto the map

Documentation:
Spawn entity at tile x,y on currently loaded map using .chr file. EntitySpawn
will return the index of the entity for interface with entity variables.

Example Usage:
int currentplayer = EntitySpawn(10, 10, "Hero.chr");
SetPlayer(currentplayer);
entity.speed[currentplayer]=100;


--------------------------------------------------------------------------------
void EntityStalk (int stalker, int stalkee)
--------------------------------------------------------------------------------
Makes one entity follow another

Documentation:
NODESHELL

Example Usage:
// Make companion follow the player
EntityStalk(companion, player_ent);

// Stop following
EntityStalk(companion, 0-1);


--------------------------------------------------------------------------------
void EntityStop (int entity)
--------------------------------------------------------------------------------
Clears an entities movecode

Documentation:
Clears the movecode of an entity, set by PlayerMove() or  EntityMove() -
stopping whatever action the entity is currently taking.

Example Usage:
EntityMove(1, "u3"); // Move entity '1' up 3 tiles
Wait(100); // A function that waits for 1 second
EntityStop(1); // Stop entity 1 early


--------------------------------------------------------------------------------
void HookEntityRender (int entity, string func)
--------------------------------------------------------------------------------
Every time the specified entity would be rendered, calls the specified function
instead

Documentation:
This 'hooks' a function to be called each time a set entity is rendered, instead
of blitting the entity automatically. This would generally be during a Render()
call when the entity is in the viewable area.

As with all hook functions, it requires the string of a function name that
requires no passed values, and any return value is ignored. If no function
matching the name is found, the hook does nothing. The entity value needed is
the int value of their index. This is either set on the map, or returned by
EntitySpawn().

Also when within the hooked function, event.entity refers to the currently
rendered entity.

Remember to manually blit the current entity frame if you want to display the
entity as normal - this hook OVERRIDES the normal entity render, rather than
coming before or after. Be careful about blitting to to correct x,y coords on
the screen.

Example Usage:
int e;
// Hook all current map entities to PaperDollRender()
for(e = 0; e 


--------------------------------------------------------------------------------
void PlayerMove (string script)
--------------------------------------------------------------------------------
Sets a movecode for the player - taking control from the user

Documentation:
With this function you ignore what ever input the user gives, and set actions
for the player to follow using a 'movecode' string. In verge a movecode is a
string of instructions for an entity to follow, one after the other, like a
'script'. Each command is a letter, sometimes followed by a number, here are a
list of what each does:



ulrd (followed by number) Move the player either up, down, left or right by set
number of tiles.

xy (followed by number) Move an player so a set x or y tile position

pt Changes movement to either pixel accurate, p, or tile accurate, t *CURRENTLY
BROKEN*

z (followed by number) Set the current frame of the player, like setting
entity.specframe

w (followed by number) The player pauses for set number of timer ticks (default
100 = 1 second)

f (followed by number) Sets the entity's facing: use directional 0 moves
instead, then you don't need to remember which number is which direction

b Loops the player movecode, eternally – DO NOT DO THIS



They can be either upper or lower case (which ever you think looks nicer) and
don't need a space or anything between commands. Verge processes entity
movecodes every call to Render() (???and ShowPage()???) so, if you need the game
to 'pause' for a textbox or something, make sure you use SetEntitiesPaused() so
the entities don't suddenly 'jump' to their next positions.



There are a few things to remember when moving the player around, firstly the
player needs to have their specframe set to 0 to enable the walk animation,
rather than just sliding around. So if you change the frame, remember to set it
back with “z0” before moving. Also, as the program would go into an eternal loop
if the player got 'stuck' any movement will go straight through of obstructions
and other entities, so make sure to test what you use to make sure it works as
expected.


Example Usage:
// Examples adapted from Parallel Seven

// Player waits briefly then changes to 'glance right' frame
PlayerMove("w40z21");

// Player looks around
PlayerMove("d0w40r0w40");
// Parallel Seven specific textbox
TBox(party[0].port, 1, 1, party[0].name, "Where the hell is there a weapon when
you need one?");
// Player moves to x,y position then looks right and pauses
PlayerMove("y61x77r0w40");


--------------------------------------------------------------------------------
void SetEntitiesPaused (int pausestate)
--------------------------------------------------------------------------------
Halts all entity movement

Documentation:
This function stops entity movement codes from being processed until they are
unpaused.

pausestate is either 1 (on) or 0 (off).

You would use this in situations where the screen stops updating. For instance,
a textbox that halts the game until the player closes.

Not using this function would result in the entities moving around while the
screen isn't being updated. Once the textbox closes the things are being drawn
again, the enties will all appear to warp to their new locations.

Example Usage:
SetEntitiesPaused(1);
TextBox("Nobody's moving behind ME, that's for sure");
SetEntitiesPaused(0);


--------------------------------------------------------------------------------
void SetPlayer (int entity)
--------------------------------------------------------------------------------
Set up controls and camera for entity

Documentation:
SetPlayer(int ent) links the direction keys, enter, and the camera to the entity
specified.

Example Usage:
int currentPlayer=EntitySpawn(0,0,"nathan.chr");'
setPlayer(currentPlayer);


================================================================================
e. Graphics Functions
================================================================================


--------------------------------------------------------------------------------
void AdditiveBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Additive Blits an image onto another image.

Documentation:
Special version of Blit, this function Additively blits the sourceimage over the
destimage, creating some nice effects.


Example Usage:
int image;
image = LoadImage("mypic.pcx");

AdditiveBlit(0, 0, image, screen);


--------------------------------------------------------------------------------
void AlphaBlit (int x, int y, int srcimg, int alphaimg, int dest)
--------------------------------------------------------------------------------
Blit an image with an alpha mask

Documentation:
Before I go into this function let me explain what a mask is.


A mask is a grayscale(black and white essentially) image that is applied to
another image to tell the computer how much transparency is allowed in different
places. By using a mask you can blit anti-aliased images and whatever else for
higher image quality. If used properly you can elimate the hardedges you get so
often with tBlit.

AlphaBlit blits image 'srcimg' to image 'dest' at screen x,y with the alphamask
'alphaimg'.

Note: srcimg and alphaimg have to be the same size in pixels.

Example Usage:
int portrait=loadimage("Hero.png");
int portrait_mask=loadimage("Hero_mask.png");

aplhaBlit(0,0,portrait,portrait_mask,screen);


--------------------------------------------------------------------------------
void Blit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Draws an image onto another image, ignoring transparancy.

Documentation:
This function blits the image 'sourceimage' on to 'destimage' at the coordinates
x and y.  Screen is the builtin image object representing the physical screen.

Example Usage:
int image;
image = LoadImage("mypic.pcx");

Blit(100, 100, image, screen);


--------------------------------------------------------------------------------
void BlitEntityFrame (int x, int y, int e, int f, int dest)
--------------------------------------------------------------------------------
Blits a specified entity frame to the screen

Documentation:
Blits the frame number 'f' of entity 'e' to the 'dest' image at coords 'x','y'.
It will not draw transparent pixels, and abides SetLucent values.



If you add this to a HookEntityRender(), you can get the current entity being
referenced using event.entity.

Example Usage:
void PaperDollRender()  //add to a HookEntityRender
{
   //Blit current frame of the entity being referenced
   BlitEntityFrame(x, y, event.entity, frame_index, screen);
   //Blit Paper Doll Stuff
}


--------------------------------------------------------------------------------
void BlitLucent (int x, int y, int lucent, int source, int dest)
--------------------------------------------------------------------------------
Simple blit with constant translucency override

Documentation:
BlitLucent is a standard blit, with the exception that it will use the provided
alpha value for constant translucency.  This is exactly equivalent to the
following snippet of code:




SetLucent(newLucent);
Blit(x,y,source,dest);
SetLucent(oldLucent);


Example Usage:
BlitLucent(-5,-5,20,oldScreen,screen); //motion blur effect


--------------------------------------------------------------------------------
void BlitTile (int x, int y, int tile, int dest)
--------------------------------------------------------------------------------
Blit a tile from the vsp to the screen

Documentation:
Blits tile index 'tile' to image 'dest' at (x,y).  (x,y) are relative to the
destination image.

note:
blitTile is different from setTile in that setTile positions a tile into the map
it self on a tile grid while blitTile blits the tile to an image on a pixel
grid.

Example Usage:
BlitTile(50,50,1,screen); //blits tile 1 to screen at (50,50)


--------------------------------------------------------------------------------
void BlitWrap (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Draws an image in a repeating pattern onto another image.

Documentation:
This is a specialty-use blitter. This will blit an image to the destination
image, but instead of clipping, it will wrap around the edges. in other words.
if you blit a 50x50 image 25 pixels from the bottom/right corner, then 25 pixels
will also appear at the top/left corner.

There is no TBlitWrap, BlitWrap will not draw transparent pixels. BlitWrap does
not at this time abide either the clipping region (it wraps at the image
height/width) or values of SetLucent().

Example Usage:
BlitWrap(270, 150, myimage, screen);


--------------------------------------------------------------------------------
void Circle (int x, int y, int rx, int ry, int color, int destimage)
--------------------------------------------------------------------------------
Generate a ellipse/circle outline

Documentation:
Generates an elipse at x,y with horizontal radius 'rx' and vertical radius 'ry'
of the given color to image 'dest'

Example Usage:
none


--------------------------------------------------------------------------------
void CircleFill (int x, int y, int rx, int ry, int color, int destimage)
--------------------------------------------------------------------------------
Generate a filled circle/ellipse

Documentation:
draw a filled circle at x,y with horizontal radius 'rx' and verticle radius 'ry'
with given color to image 'dest'

Example Usage:
none


--------------------------------------------------------------------------------
void ColorFilter (COLOR_FILTER filter, int image)
--------------------------------------------------------------------------------
Applies the specified color filter to an image to tint it.

Documentation:
Applies the specified filter to the given image. The following filters are
valid:


CF_NONE does absolutely nothing!
CF_GREY converts the image to greyscale
CF_GREYINV converts the image to inverted greyscale.
CF_INV converts to full-color RGB inversion. For instance, the inverse of green
would be purple: RGB(0,255,0) -> RGB(255,0,255).
CF_RED gets an average luminosity and then applies that to the red channel
only.
CF_GREEN gets an average luminosity and then applies that to the green channel
only.
CF_BLUE gets an average luminosity and then applies that to the blue channel
only.


Note: All of these filters are built-in defines for ints.  See their section for
more detail.

Two notes about this function. It will abide by the clipping region, but you
will not gain the full speed benefit of a clip region. This may be optimized in
the future. It will abide by Lucency values: you can acheive some cool effects
this way. For instance a lucent percentage of a CF_GREY filter will provide a
washed-out, color-faded look.


Example Usage:
ColorFilter(CF_GREY, screen);


--------------------------------------------------------------------------------
void CopyImageToClipboard (int image)
--------------------------------------------------------------------------------
Copy an image pointer from VERGE into the clipboard.

Documentation:
Copies an image pointer from VERGE into the Windows clipboard.

Example Usage:
//if CTRL+C is pressed, copy the image to the clipboard
if(key[SCAN_CTRL] && key[SCAN_C])
{
 CopyImageToClipboard(img);
}


--------------------------------------------------------------------------------
int DuplicateImage (int image)
--------------------------------------------------------------------------------
Makes an exact, but seperate, copy of an image.

Documentation:
Duplicates the passed image object and returns a new handle for storage in a
different location.



Example Usage:
int image_a, image_b;

image_a = LoadImage("image.pcx"); // load an image
image_b = DuplicateImage(image_a); // put the image inside image_b as well.
// now both image_a and image_b have the image from image.pcx

RectFill( 0, 0, ImageWidth(image_b)/2, ImageHeight(image_b)/2, 0, image_b);
//now image_b has a black rectangle in it's upper-left quadrant, whereas image_a
does not.


--------------------------------------------------------------------------------
void FreeImage (int image)
--------------------------------------------------------------------------------
Frees the memory occupied by the image reference passed.

Documentation:
Frees the memory occupied by 'image', and sets the image pointer to 0.


Example Usage:
int myimage;
myimage = NewImage(320, 240); //this loads the image into memory

//
// let's pretend we actually used the image hereabouts...
//

FreeImage(myimage); //this frees the image from memory. 

//'myimage' cannot be used after this point without creating/loading a new image
into it



--------------------------------------------------------------------------------
int GetB (int color)
--------------------------------------------------------------------------------
Returns the value of the blue channel of a COLOR.

Documentation:
 Grabs the blue channel from 'color', and returns it's value.
 COLORs are special integers created by the RGB() function.


Example Usage:
int color, blue;
color = RGB(200, 100, 50);
blue = GetB(color); // blue will equal 50


--------------------------------------------------------------------------------
int GetG (int color)
--------------------------------------------------------------------------------
Returns the value of the green channel of a COLOR.

Documentation:
 Grabs the green channel from 'color', and returns it's value.
 COLORs are special integers created by the RGB() function.


Example Usage:
int color, green;
color = RGB(200,100,50);

green = GetG(color);  // green will equal 100


--------------------------------------------------------------------------------
int GetImageFromClipboard ()
--------------------------------------------------------------------------------
Retrieve an image pointer from the clipboard.

Documentation:
Returns an image pointer from the clipboard.

Example Usage:
//If CTRL+V is pressed, "paste" an image.
if(key[SCAN_CTRL] && key[SCAN_V])
{
  img=GetImageFromClipboard();
}


--------------------------------------------------------------------------------
int GetPixel (int x, int y, int sourceimage)
--------------------------------------------------------------------------------
Returns the COLOR from a specific pixel in the specified image.

Documentation:
Grabs the pixel at (x,y) from 'sourceimage', and returns it's color value.
This color value is the same type created by RGB() and used by GetR(), GetG(),
and GetB().


Example Usage:
int color;

color = GetPixel(10, 10, screen); // get what color is at x:10 y:10 on the
screen object


--------------------------------------------------------------------------------
int GetR (int color)
--------------------------------------------------------------------------------
Grabs the red channel from 'color', and returns it's value.

Documentation:
 Grabs the red channel from 'color', and returns it's value.
 COLORs are special integers created by the RGB() function.


Example Usage:
int red, color;

color = RGB(125, 50, 250);

red = GetR(color); // red will equal 125


--------------------------------------------------------------------------------
void GrabRegion (int sx1, int sy1, int sx2, int sy2, int dx, int dy, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Extracts a sub-rectangle from a given image

Documentation:
GrabRegion receives the rectangle that it should extract from the source image
in (sx1,sy1)->(sx2,sy2).  This rectangle is placed into the destination image at
(dx,dy).

This function is very useful for manually slicing up an image that contains a
strip of frames for an animation and extracting a single frame from it.  The
example will demonstrate this

Example Usage:
int edgar = loadimage("edgar.pcx");
int leftFrame = NewImage(16,24);

//the order of things is down/up/left/right in the world of verge
//that means we need the third frame
GrabRegion(16*2,0,16*2 +15,23,0,0,edgar,leftFrame);



--------------------------------------------------------------------------------
int ImageHeight (int image)
--------------------------------------------------------------------------------
Returns the height of an image object.

Documentation:
Returns the height of an image object.


Example Usage:
int image, height;
image = LoadImage("image.pcx");

height = ImageHeight(image);


--------------------------------------------------------------------------------
int ImageShell (int xofs, int yofs, int width, int height, int image)
--------------------------------------------------------------------------------
Creates a duplicate image handle referencing a rectangle in the original image

Documentation:

This extremely powerful function will allow you to take an image, define a
rectangle within it, and get an image handle referencing that rectangle within
the original image.  xofs, yofs, width, height indicate the position and
dimensions of the rectangle within the source image.  Clipping rectangles for
the two images are completely independent.  

*Rendering into one will render into the other.*  If that is what you want to
do, then this is the function you want to use.



Example Usage:
int window = ImageShell(110,60,100,100,screen);
// rendering into window will now be the same as rendering into a 100x100
// window in the middle of the screen!


--------------------------------------------------------------------------------
int ImageWidth (int image)
--------------------------------------------------------------------------------
Returns the width of an image object.

Documentation:
Returns the width of an image object.


Example Usage:
int image, width;
image = LoadImage("image.pcx");

width = ImageWidth(image);


--------------------------------------------------------------------------------
void Line (int x1, int y1, int x2, int y2, int color, int destimage)
--------------------------------------------------------------------------------
Draws a colored line onto an image.

Documentation:
Primitive drawing function, Line, draws a line from x1,y1 to x2,y2 on
'destimage' in color 'color'.


Example Usage:
Line(0, 0, 100, 100, RGB(255,255,255), screen);  // draws a line from 0,0 to
100,100 on the screen object


--------------------------------------------------------------------------------
int LoadImage (string filename)
--------------------------------------------------------------------------------
Reads an image file into memory, and returns an IMAGE handle.

Documentation:
Reads in the specified image file as an image object, and returns a handle to
the image object.  This handle is an int that represents the image to any
functions in the Graphics API that want an image.


Example Usage:
int myimage;
myimage = LoadImage("image.pcx");


--------------------------------------------------------------------------------
int LoadImage0 (string filename)
--------------------------------------------------------------------------------
Loads a paletted image and makes palette index 0 transparent.

Documentation:
Typically images are loaded in and magenta is used as the transparent color. 
LoadImage0 takes account for indexed color images, and treats color index 0 in
the palette as the transparent color.  Transparent pixels are only transparent
if you use the transparency blitting functions.

Example Usage:
int myimage;
myimage = LoadImage0("image.gif");


--------------------------------------------------------------------------------
int MixColor (int c1, int c2, int mix)
--------------------------------------------------------------------------------
Mixes two colors in the given proportion

Documentation:
Mixes c1 and c2 according to the proportion specified by mix.  A mix of zero
would yield a color identical to c1.  A mix of 255 would yield a color identical
to c2.  A mix of 128 would yield a color smack dab inbetween c1 and c2.

     c1      c2
     |--------|
mix: 0      255



Example Usage:
//mixing white and red 50/50 will yield a fabulous shade of pink
pink = MixColor(RGB(255,0,0),RGB(255,255,255),128); 


--------------------------------------------------------------------------------
void Mosaic (int xgran, int ygran, int destimage)
--------------------------------------------------------------------------------
Applies a mosaic effect to an image.

Documentation:
This will apply a mosaic effect, with a granularity size specified with
xgran/ygran, to the destination image. It abides clipping rectangle, but the
mosaic effect is absolute and ignores the value of SetLucent().

While this creates the same effect you remember from your super NES, it does it
in a slightly different way.  The effect is better than the super NES's; it is
also slower.  Super NES and GBA, I believe, select the pixel in the top-left
corner of each tile of the mosaic to use as the color for that entire tile of
the mosaic.  Verge's mosaic function will actually average every one of the
pixels in the tile and use that as the color for the entire tile.


Example Usage:
Mosaic(4, 4, screen);


--------------------------------------------------------------------------------
int NewImage (int width, int height)
--------------------------------------------------------------------------------
Creates a new, blank image.  Useful for drawing to.

Documentation:
NewImage() creates an image object of the size specified by parameters width and
height. The returned value is a handle to that image object which can be passed
to any graphics function. The clipping region for the image defaults to the
entire size of the image.


Example Usage:
int myimage;
myimage = NewImage(320, 240);


--------------------------------------------------------------------------------
void Rect (int x1, int y1, int x2, int y2, int color, int destimage)
--------------------------------------------------------------------------------
Draws a 1-pixel thick rectangle onto an image.

Documentation:
Draws an unfilled rectangle from x1,y1 to x2,y2 on 'destimage', in color
'color'.


Example Usage:
Rect(0, 0, 200, 200, RGB(255,255,255), screen); // draw a box from 0,0, to
200,200, on the screen object (in white)


--------------------------------------------------------------------------------
void RectFill (int x1, int y1, int x2, int y2, int color, int destimage)
--------------------------------------------------------------------------------
Draws a solid colored rectangle onto an image.

Documentation:
Draws a filled rectangle from x1,y1 to x2,y2 on 'destimage', in color 'color'


Example Usage:
RectFill(0, 0, ImageWidth(screen)-1, ImageHeight(screen)-1, RGB(255,255,255),
screen);  
// fill the screen with a full white rectangle


--------------------------------------------------------------------------------
int RGB (int red, int green, int blue)
--------------------------------------------------------------------------------
Returns a color in a format usable by other image functions.

Documentation:
Returns a color in the valid pixel format for V3's current video mode.  The
passed paramaters represent the red, green and blue channels used to form a
color.
The valid values for each parameter range from 0, which represents 0% of that
color, to 255 which represents 100% of that color.

Example Usage:
int white, red;

white = RGB(255, 255, 255);
red = RGB(255, 0, 0);


--------------------------------------------------------------------------------
void RotScale (int x1, int y1, int angle, int scalefactor, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Rotate and/or scale an image and draws it to another image.

Documentation:
This is a rotational scaler. The x and y coordinates specify the centerpoint of
the image destination. The angle field is in degrees from 0 to 360. Any value
for angle is valid, it will be wrapped around at 360. 

The scale factor is a whole-image divisor, in a fixed-point of sorts: it ranges
from 1 to infinity. 1000 is the centerpoint, equal to a scale factor of 1. A
scale of 100 is 10 times bigger than normal. A scale of 10000 is 1/10th the size
of normal. It abides clipping rectangles as well as SetLucent values. 

RotScale will not draw transparent pixels (there is no TRotScale).



Example Usage:
int face = LoadImage( "happy_face.gif" );

RotScale(160, 120, systemtime, 1000, face, screen); 


--------------------------------------------------------------------------------
void ScaleBlit (int x, int y, int dw, int dh, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Draws an stretched image to another image.

Documentation:
This function draws sourceimage onto destimage, as a normal blit would; only the
width and height of source image when it is blitted, is alterable. This allows
for scaling both down and up.


Example Usage:
int image;
image = LoadImage("image.pcx");

ScaleBlit(0, 0, ImageWidth(image) * 2, ImageHeight(image) * 2, image, screen); 
// draw the image 200% scale


--------------------------------------------------------------------------------
void SetClip (int x1, int y1, int x2, int y2, int image)
--------------------------------------------------------------------------------
Sets the current clipping rectangle on an image object.

Documentation:
Sets the current clipping rectangle on an image object.  All drawing to this
image object, will only appear within the specified clipping coordinates. New
images' clipping rectangle defaults to the entire image.


Example Usage:
SetClip(0, 0, 50, 50, image);  
// restrict drawing on image object 'image' to the box 
// between 0,0 and 50,50

Line( 0,0, 100,100, 0, image ); 
// attempts to draw a diagonal black line across the image... 
// but haha! It's stopeed at 50,50 by the magical Clipping rectangle!
// ALL GLORY TO THE SETCLIP()!


--------------------------------------------------------------------------------
void SetCustomColorFilter (int c1, int c2)
--------------------------------------------------------------------------------
Creates a custom color filter with colors in between c1 and c2.

Documentation:
Creates a custom color filter with colors in between c1 and c2. This filter can
then be used by ColorFilter, using CF_CUSTOM as the filter argument.

Example Usage:
//Make it a random color filter! Madness, I say!
SetCustomColorFilter(RGB(Random(0,255),Random(0,255),Random(0,255)),RGB(Random(0,255),Random(0,255),Random(0,255)));
//Now use the custom filter.
ColorFilter(CF_CUSTOM,screen);


--------------------------------------------------------------------------------
void SetLucent (int percent)
--------------------------------------------------------------------------------
Sets the Lucency value for all drawing functions.

Documentation:
Sets the current drawing lucency to the passed percent. 100% lucent means
invisible, 0% is fully opaque.


Example Usage:
SetLucent(75);
// draw stuff
SetLucent(0); // back to normal


--------------------------------------------------------------------------------
void SetPixel (int x, int y, int color, int destimage)
--------------------------------------------------------------------------------
Changes the color of a single pixel in the specified image.

Documentation:
Sets the pixel at (x,y) on destimage to 'color'.


Example Usage:
SetPixel(50, 50, RGB(255,255,255), screen); // draw a white pixel at x:50 y:50
on the screen


--------------------------------------------------------------------------------
void ShowPage ()
--------------------------------------------------------------------------------
Updates the screen with all the changes you made to it.

Documentation:
Basicly, Copies the contents of the 'screen' image object to the physical
screen.



...

ShowPage() also does a lot of secondary stuff in the background. 



This includes processing all entities (replacing manually having to call
ProcessEntities() ), and drawing the Verge3 'sprites'. 



It also updates the controls (just in case you forgot UpdateControls() ) and it
may also update the player if a player entity is set, but I'm not sure. 



It's a pretty handy function to have in a Verge loop. 



If you don't want to use all of ShowPage()'s features, then you have control
over how they are executed. Look in V3 Docs -> Function Reference -> Entity
Functions for SetEntitiesPaused(), which allows you to turn off entity
processing if you don't want ShowPage() to do it for you. This should also
prevent the player from moving. 



In addition, you can disable the Verge3 'sprites', or just plain not use them,
if you don't want them drawn. See V3 Docs -> Function Reference -> Sprite
Functions. 



There is no real way to disable the updating of input. Verge3 will always do
that now, which means even an empty eternal loop will bow down to ALT-X.
Although it is good coding practice to call UpdateControls(), in my opinion.



Example Usage:
Rect(0, 0, 100, 100, RGB(128, 128,128), screen);
ShowPage();


--------------------------------------------------------------------------------
void Silhouette (int x, int y, int color, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Draws a colored silhouette of one image onto another image.

Documentation:
Essentially, this is like a TBlit, except everywhere there's a non-transparent
pixel in the source image, it will place a pixel of the color you specify in the
destination image. In effect, a colored silhouette of the source image. 

Silhouette abides by the SetLucent() value, however to acheive the effect you
probably want with that, you will need to TBlit the source image directly first,
then do a lucent Silhouette on top of it.



Example Usage:
Silhouette(0, 0, hero, rgb(0,0,255), screen); //it's a blue silhouette of the
hero!


--------------------------------------------------------------------------------
void SubtractiveBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Subtractive blits one image onto another.

Documentation:
This function is very much like Blit(), but draws the pixels with subtractive
blending.  Subtractive blending has few uses, but when it is put to good use,
can be very handy.  The best way to become familiar with it's uses is purely
experimentation.


Example Usage:
int image;
image = LoadImage("mypic.pcx");

SubtractiveBlit(0, 0, image, screen);


--------------------------------------------------------------------------------
void TAdditiveBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
A transparent-conscious version of AdditiveBlit

Documentation:
Same as AdditiveBlit, with the exception that this function does not draw
transparent pixels.


Example Usage:
int image;
image = LoadImage("mypic.pcx");

TAdditiveBlit(0, 0, image, screen);


--------------------------------------------------------------------------------
void TBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Draws an image onto another, but lets the base image show through the
transparent parts of the source.

Documentation:
Identical to Blit() in every way, the only exception here is that transparent
colored pixels are not drawn to destimage.


Example Usage:
int image;
image = LoadImage("mypic.pcx");

TBlit(0, 0, image, screen);


--------------------------------------------------------------------------------
void TBlitLucent (int x, int y, int lucent, int source, int dest)
--------------------------------------------------------------------------------
Simple transparent blit with constant translucency override

Documentation:
Identical to LucentBlit() in every way, the only exception here is that
transparent colored pixels are not drawn to destimage. 

Example Usage:
BlitLucent(300,220,50,stationWatermark,screen); //station watermark


--------------------------------------------------------------------------------
void TBlitTile (int x, int y, int tile, int dest)
--------------------------------------------------------------------------------
Blit a tile from the vsp with transparency

Documentation:
Blit tile index 'tile' to x,y on image 'dest' with transparency

Example Usage:
none


--------------------------------------------------------------------------------
void TGrabRegion (int sx1, int sy1, int sx2, int sy2, int dx, int dy, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Extracts a sub-rectangle from a given image and blits with transparency

Documentation:
TGrabRegion receives the rectangle that it should extract from the source image
in (sx1,sy1)->(sx2,sy2). This rectangle is placed into the destination image
with transparency at (dx,dy). This function is very useful for manually slicing
up an image that contains a strip of frames for an animation and extracting a
single frame from it. The example will demonstrate this

Example Usage:
NODESHELLint edgar = loadimage("edgar.pcx");
int leftFrame = NewImage(16,24);

//the order of things is down/up/left/right in the world of verge
//that means we need the third frame
TGrabRegion(16*2,0,16*2 +15,23,0,0,edgar,leftFrame);


--------------------------------------------------------------------------------
void Triangle (int x1, int y1, int x2, int y2, int x3, int y3, int c, int dest)
--------------------------------------------------------------------------------
Renders a triangle

Documentation:

Triangle() will draw a triangle using the vertices (x1,y1); (x2,y2); (x3,y3).

This is a bad triangle routine, and if you try to assemble a more complicated
polygon from a number of triangles, some pixels will be overwritten along the
edge.  This creates undesirable artifacts in some cases, such as when
translucency is enabled (a seam will sometimes be visible).
We hesitate to improve this because you don't need to be making 3d games.  But
if you are making a starfox clone, please let us know and we can talk about
it.



Example Usage:
//a green, right, 3-4-5 triangle
triangle(0,0,0,40,30,0,rgb(0,255,0),screen);
// |\
// | \
// |  \
// +---



--------------------------------------------------------------------------------
void TScaleBlit (int x, int y, int dw, int dh, int sourceimage, int destimage)
--------------------------------------------------------------------------------
A transparency-conscious version of Scaleblit.

Documentation:
Indentical to ScaleBlit, with the exception that transparent pixels will not be
drawn to the destimage.


Example Usage:
int image;
image = LoadImage("image.pcx");

TScaleBlit(0, 0, ImageWidth(image) * 2, ImageHeight(image) * 2, image, screen);


--------------------------------------------------------------------------------
void TSubtractiveBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
A transparency-conscious version of SubtractiveBlit.

Documentation:
Identical to SubtractiveBlit, with the exception that transparent pixels will
not be drawn to the destimage.


Example Usage:
int image;
image = LoadImage("mypic.pcx");

TSubtractiveBlit(0, 0, image, screen);


--------------------------------------------------------------------------------
void TWrapBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
A transparency-conscious version of WrapBlit.

Documentation:
Identical to WrapBlit, with the exception that transparent pixels aren't
drawn.


Example Usage:
int mytile;
mytile = LoadImage("tile.pcx");

TWrapBlit(0, 0, mytile, screen);


--------------------------------------------------------------------------------
void WrapBlit (int x, int y, int sourceimage, int destimage)
--------------------------------------------------------------------------------
Blits a tiling pattern of an image onto another image.

Documentation:
WrapBlit can be a very useful function.  What it does is tiles sourceimage from
it's origin coordinates (x,y) until it fills all of destimage (respecting the
destination image's clipping rectangle).  

This can be used to create backgrounds that scroll around, while still keeping
the screen filled.



Example Usage:
int mytile;
mytile = LoadImage("tile.pcx");

WrapBlit(0, 0, mytile, screen);


================================================================================
f. Sprite Functions
================================================================================
For the corresponding sprite variables go 

--------------------------------------------------------------------------------
int GetSprite ()
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void ResetSprites ()
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


================================================================================
g. Sound/Music Functions
================================================================================


--------------------------------------------------------------------------------
void FreeSong (int h)
--------------------------------------------------------------------------------
Free the song from memory to prevent memory leakage

Documentation:
Free song 'h' from memory to prevent memory leakage

Example Usage:
int mysong=loadSong("mysong.mp3");
freeSong(mysong);


--------------------------------------------------------------------------------
void FreeSound (int handle)
--------------------------------------------------------------------------------
Releases a loaded sound from memory.

Documentation:
Use this to free the memory occupied by a WAV file.  It is good coding habit to
always free memory you fill.  If you do not, you could create system
degenerating memory leaks, and those are no good.


Example Usage:
int MySound;
MySound = LoadSound("file.wav"); // load a sound into the MySound handle...

// ..use MySound..

FreeSound(MySound); // ...done using it, free up the memory.



--------------------------------------------------------------------------------
int GetSongPos (int h)
--------------------------------------------------------------------------------
returns the current position of a song

Documentation:
returns the current position of song 'h'

Example Usage:
getSongPos(mysong); returns 10


--------------------------------------------------------------------------------
void GetSongVolume (int h)
--------------------------------------------------------------------------------
returns the volume of the song your playing

Documentation:
returns the volume of song 'h'

Example Usage:
getSongVolume(mysong); returns 100


--------------------------------------------------------------------------------
int LoadSong (string name)
--------------------------------------------------------------------------------
load a song into memory for playing

Documentation:
Load song 'name' into memory for playing.

Example Usage:
int mysong=loadSong("mysong.mp3");
playsong(mysong);


--------------------------------------------------------------------------------
int LoadSound (string wavfile)
--------------------------------------------------------------------------------
Loads a wav file into memory and returns a SOUND handle that the sound API can
use.

Documentation:
Loads a WAV file into the sound cache, and returns a handle for use when
directing sound effect-related function calls upon the WAV.

Example Usage:
int MySound;
MySound = LoadSound("myfile.wav");
// use MySound


--------------------------------------------------------------------------------
void PlayMusic (string songfile)
--------------------------------------------------------------------------------
Loads and plays the specified songfile.

Documentation:
This function loads and immediately plays the specified song.
This is the cornerstone of the 'simple' music API.  It does not return a handle,
it does no caching, it just loads and plays the song until you call PlayMusic()
again with a different song, or until you call StopMusic().
Important note is that it resets to volume to 100 whenever called, so make sure
to use SetMusicVolume() afterwards if you need to.

Example Usage:
PlayMusic("mysong.xm");
SetMusicVolume(music_volume);


--------------------------------------------------------------------------------
void PlaySong (int h)
--------------------------------------------------------------------------------
Play a song that you have loaded into memory

Documentation:
Play song 'h' that you have loaded into memory

Example Usage:
int mysong=loadSong("mySong.mp3");
playsong(mysong);


--------------------------------------------------------------------------------
void PlaySound (int handle, int volume)
--------------------------------------------------------------------------------
Plays the given sound effect at the given volume

Documentation:
Handle should be a handle obtained from loadsound()
Volume should be 0..100


Example Usage:
int MySound;
MySound = LoadSound("file.wav");

PlaySound(MySound, 100);


--------------------------------------------------------------------------------
void SetMusicVolume (int v)
--------------------------------------------------------------------------------
set the volume of the music playing

Documentation:
set the volume of currently playing music to 'v'

Example Usage:
setMusicVolume(50);


--------------------------------------------------------------------------------
void SetSongPaused (int h, int p)
--------------------------------------------------------------------------------
pause a song that's playing

Documentation:
pause song 'h' at position 'p'

Example Usage:
SetSongPaused(mysong, getSongPos(mysong));


--------------------------------------------------------------------------------
void SetSongPos (int h, int p)
--------------------------------------------------------------------------------
set the current position of a song playing

Documentation:
set the current position song 'h' to position 'p'

Example Usage:
setSongPos(mysong, 20);


--------------------------------------------------------------------------------
void SetSongVolume (int h, int v)
--------------------------------------------------------------------------------
Sets the current volume of a song playing

Documentation:
Sets the current volume of song 'h' to volume 'v'

Example Usage:
setSongVolume(mysong, 100);


--------------------------------------------------------------------------------
void StopMusic ()
--------------------------------------------------------------------------------
Halts current music playing completely.

Documentation:
Halts current music playing completely.
This is part  of the simple mucis API.


Example Usage:
PlaySong("mysong.xm");

// do stuff.

StopMusic();


--------------------------------------------------------------------------------
void StopSong (int h)
--------------------------------------------------------------------------------
Stop playing a song

Documentation:
Stop playing song 'h'

Example Usage:
int mysong=LoadSong("mysong.mp3");
playSong(mysong);
stopsong(mysong);


--------------------------------------------------------------------------------
void StopSound (int chan)
--------------------------------------------------------------------------------
stops playing a sound

Documentation:
stops playing sound 'chan'

Example Usage:
int mysound=loadSound("crack.wav");
playSound(mysound);
stopSound(mysound);


================================================================================
h. Font Functions
================================================================================
1. There is a predefined, tiny, white, variable-width font built-in to the
engine.  For any of these font functions, use the font handle 0 (zero) to access
this font.

--------------------------------------------------------------------------------
void EnableVariableWidth (int fonthandle)
--------------------------------------------------------------------------------
Turns variable-width mode on for the specified font.

Documentation:
This function enables variablewidth mode for the font passed. If you're not
familiar with variable-width fonts, this simply means that each character only
occupies as much space as it needs when printing. 

You should NOT call this with 0 as an arguement, as you might with other font
routines to denote the builtin font; the built-in font is always variable width,
and passing 0 to this function will generate an error.



Example Usage:
int MainFont;

MainFont = LoadFont( "my_font.gif" );

EnableVariableWidth( MainFont );


--------------------------------------------------------------------------------
int FontHeight (int font)
--------------------------------------------------------------------------------
Returns the height of a font

Documentation:
When passed a font handle it will return the height of a character. This is
constant, and will include any excess space that existed in the font graphic.

Example Usage:
font = LoadFont("font.png");
fontht = FontHeight(font);


--------------------------------------------------------------------------------
void FreeFont (int font)
--------------------------------------------------------------------------------
Frees a font that you have previously loaded

Documentation:
Just use this function to free a font that you don't need any more.

Example Usage:
int MainFont;
//load and use the font
FreeFont(MainFont);


--------------------------------------------------------------------------------
int LoadFont (string sourceimage)
--------------------------------------------------------------------------------
Loads a font from an image file and returns a FONT handle to be used by other
font functions..

Documentation:
Loads a font from an image file and returns a handle to the font.  sourceimage
should be a filename.  The width/height of the cells in the font will be
automatically detected.  Use LoadFontEx() if the autodetection is failing and
you need to manually specify a cell width

Example Usage:
int MainFont;
MainFont = LoadFont("myfont.pcx");


--------------------------------------------------------------------------------
int LoadFontEx (string sourceimage, int width, int height)
--------------------------------------------------------------------------------
Loads a font from an image file and returns a FONT handle to be used by other
font functions.. (advanced)

Documentation:
Loads a font from an image file and returns a handle to the font.  sourceimage
should be a filename, and width/height represent the cell width/height in the
image file.


Example Usage:
int MainFont;
MainFont = LoadFont("myfont.pcx", 10, 10);


--------------------------------------------------------------------------------
void PrintCenter (int x, int y, int destimage, int font, string text)
--------------------------------------------------------------------------------
Prints a center-justified string at the specified coordinates.

Documentation:
Prints centered text at (x,y). If you pass 0 for the font handle, a builtin font
will be used.

Example Usage:
PrintCenter(ImageWidth(screen) / 2, ImageHeight(screen) / 2, screen, MainFont,
"Hello World!");


--------------------------------------------------------------------------------
void PrintRight (int x, int y, int destimage, int font, string text)
--------------------------------------------------------------------------------
Prints a right-justified string with the rightmost point at the given
coordinates.

Documentation:
Prints 'text' at (x,y), with right justification. If you pass 0 for the font
handle, a builtin font will be used.


Example Usage:
PrintRight(ImageWidth(screen)-1, ImageHeight(screen)-1, screen, MainFont, "Hello
World!");


--------------------------------------------------------------------------------
void PrintString (int x, int y, int destimage, int font, string text)
--------------------------------------------------------------------------------
Prints a left-justified string at the given coordinates.

Documentation:
This function, which has a stupid order of arguments, prints text to the screen.
 All the arguments should be self-explanatory, even if they are in retarded
order. If you pass 0 for the font handle, a built-in font will be used.


Example Usage:
PrintString(0, 0, screen, MainFont, "Hello World!  Also Grue is sexy!");


--------------------------------------------------------------------------------
int TextWidth (int font, string text)
--------------------------------------------------------------------------------
Returns the width of a string rendered in a specific font.

Documentation:
Returns the width (in pixels) of the passed string using the passed font. If you
pass 0 for the font handle, it will return the width of the text baesd on the
builtin font.


Example Usage:
int text_w;

text_w = TextWidth(MainFont, "Hello World!");


================================================================================
i. Math Functions
================================================================================
Trigonometric functions use a certain convention for angles that you may think a
little odd.  Zero degrees points due east and ninety degrees is due north.  If
you are using another convention in your game--such as zero degrees due
north--then you will have to constantly convert between them when using the trig
functions.  I advise you not to use another convention in your game.  Some
things are worth fighting, but not this.

You will need to use Fixed-point numbers with these functions.

--------------------------------------------------------------------------------
int acos (int cos)
--------------------------------------------------------------------------------
Returns the arccosine of a given value in fixed-point notation.

Documentation:
Returns the arccosine of the input value. As implied by the example, acos()
takes its input value in 16.16 fixed point, so the input value should range from
-65535 to +65535. The output is in integer degrees.


Example Usage:
int z = acos(65535/2);

Exit( str(z) );  // acos of ".5" should be 60. 




--------------------------------------------------------------------------------
int asin (int sin)
--------------------------------------------------------------------------------
Returns the arcsine of the input value in fixed-point notation.

Documentation:
Returns the arcsine of the input value. As implied by the example, asin() takes
its input value in 16.16 fixed point, so the input value should range from
-65535 to +65535. The output is in integer degrees.

Example Usage:
int z = asin(sin(30));
Exit(str(z));


--------------------------------------------------------------------------------
int atan (int tan)
--------------------------------------------------------------------------------
Returns the arctangent of the given value in fixed-point notation.

Documentation:
Returns the arctangent of the given value. The input value should be in 16.16
fixed point (eg, multiplied by 65535).





Here is some code (use at your own risk) that will accomplish atan2() for you:

int atan2(int y, int x)
{
  int t;
  if(x = 0)
  {
    if(y>0) return 90;
    else return 270;
  }
  if(y = 0)
  {
    if(x 0 && y 


Example Usage:
int at = atan(tan(45));
Exit(str(at));


--------------------------------------------------------------------------------
void atan2 (int y, int x)
--------------------------------------------------------------------------------
Calculates arctan of y,x

Documentation:
This function will compute the arctan (tan-1) of y/x, and based upon the
coordinates of y and x, put the result into the proper quadrant.
Note the odd order of the arguments, y and x.  Thats backwards from usual. 
Beware...
Unlike the inputs to the other inverse trig functions, y and x do not need to be
fixed point *65536.  Although, it should not hurt anything if they are
This function will be released in a near-future version of verge

Example Usage:
int x = 0-2;
int y = 2;
//this point should be in quadrant II (northwest)

atan(y*65536/x); //-45
//-45 is in quadrant IV (southeast); not what we expected

atan2(y,x); //135
//135 is in quadrant II, just as we expected



--------------------------------------------------------------------------------
int cos (int angle)
--------------------------------------------------------------------------------
Returns the cosine of the specified angle in fixed-point notation.

Documentation:
Returns the cosine of the specified angle. Note that the angle input will be in
integer degrees (0..360, which will loop at values >=360), however the return
value will be in fixed point 16.16, meaning the value will be effectively
multiplied by 65535, thus the return value will range from -65535 to +65535.


Example Usage:
SetPixel(150+(sin(systemtime)*40/65535), 100+(cos(systemtime)*40/65535),
RGB(255,255,255), screen);


--------------------------------------------------------------------------------
int pow (int base, int exp)
--------------------------------------------------------------------------------
Raises base to exp power

Documentation:
Pow() will raise base to the power specified by exp.
This function is darn well near impossible to use with fixed point.


Example Usage:
int i;
int powerOfTwo;
for(i=0;i


--------------------------------------------------------------------------------
int sin (int angle)
--------------------------------------------------------------------------------
Returns the sine of a given angle in fixed-point notation.

Documentation:
This returns the sine of a given angle. Note that the angle input will be in
integer degrees (0..360, which will loop at values >=360), however the return
value will be in fixed point 16.16, meaning the value will be effectively
multiplied by 65535, thus the return value will range from -65535 to +65535.

Example Usage:
SetPixel(150+(sin(systemtime)*40/65535), 100, RGB(255,255,255), screen);


--------------------------------------------------------------------------------
int sqrt (int number)
--------------------------------------------------------------------------------
Returns the square root of the given number

Documentation:
sqrt() returns the square root of the given input number.
To use this with *65536 fixed-point, use the fixed-point number as an input and
multiply the result by 256.


Example Usage:
int x = 225 * 65536 / 100; //2.25 in fixed point

int result = sqrt(x)*256; 
//returns 98304, which is 1.5 in fixed-point, as we expected


--------------------------------------------------------------------------------
int tan (int angle)
--------------------------------------------------------------------------------
Returns the tangent of the given angle in fixed-point notation.

Documentation:
Returns the tangent of the given angle. The input angle is in integer degrees,
however the output is in 16.16 fixed point; to convert it to a usable format,
you should multiply the return value by your desired range, then divide it by
65535. Unlike sin/cos, this ranges from -infinity to +infinity.


Example Usage:
int z = tan(180);


================================================================================
j. File Functions
================================================================================

A quick overview of verge file i/o functions. The standard procedure is to pass
a filename to FileOpen() and get a file handle to use with the data read/write
functions, and the close the file with FileClose() at the end. A few important
points first. Opening a file in write mode will create a new file if one doesn't
exist, but will overwrite if one does exist - just opening the file wipes all
the data. Also, all read and write operations go from the current position in
the file, which starts at the beginning, and move the position onwards in the
process. Finally, the base unit of all everything here is the byte, 8 binary 1/0
switches, which equates to a number from 0 to 255 or one character of ascii
text. There are two main uses for file i/o in verge, there's a brief summary of
both below.

Reading from plain text data files
Useful for: Managing in-game data in an easy to access and alter form. Load-once
purposes.
FileReadLn() to get a sting of data from the file (be careful not to use lines
wider than 255 characters)
GetToken() to extract the information from the string
val() to turn string data into numbers where needed.

As it's easy to make the odd mistake when creating or editing datafiles by hand,
be sure to add some error checking in case of mistakes, and preferably allow for
extra non-data lines, so the file can be commented/explained where needed.

Writing and reading binary data files
Useful for: Recording and recalling data mid game. Fast read and write times.

FileWriteQuad() for writing any integer variables to file.
FileWriteString() for writing any string variables to file.
FileReadQuad() for reading integer variables from file.
FileReadString() for reading string variables from file.

There are several functions that do similar things, but these are relatively
safe and simple, just remember to match the read and write formats exactly, and
be aware changing either will cause big problems. For this reason, writing a
'version number' at the top of the file, and checking it is up to date on read
might be useful.


--------------------------------------------------------------------------------
void FileClose (int file)
--------------------------------------------------------------------------------
Releases a file handle when it is no longer needed

Documentation:

Pass a handle to an open file, and verge frees the file and... stuff. Make sure
you do this for each file you open, after you've finished using it. For... lots
of reasons.


Example Usage:
int count = 1;
int file = FileOpen("save"+str(count)+".dat", FILE_READ);
while(file)
{
	FileClose(file);
	count++;
	file = FileOpen("save"+str(count)+".dat", FILE_READ);
}
FileClose(file);
// Counts number of save games by opening them and checking if
// The file pointer returned is valid, stopping when it's not
// It's very important to remember to close the files after
// Opening them, so they can be used later


--------------------------------------------------------------------------------
int FileCurrentPos (int file)
--------------------------------------------------------------------------------
Returns the current byte position in an open file

Documentation:

Pass a file handle opened in either read or write mode, and it returns the
number of preceding bytes to the current position. As all read/write functions
automatically increment the position, this is will generally return the number
of the next byte to be read/written.


Example Usage:
int file = FileOpen("dump.dat", FILE_WRITE);
Log("Start: "+str(FileCurrentPos(file)));
FileWriteQuad(file, 97);
Log("After Quad: "+str(FileCurrentPos(file)));
FileWriteString(file, "Four");
Log("After String: "+str(FileCurrentPos(file)));
FileClose(file);
// Creates/overwrites a new file and writes some data
// Logging the position after each step, like so:
// "Start: 0"
// "After Quad: 4"
// "After String: 10"
// Position starts at 0
// After writing a quad byte position is 4
// After writing a string of length 4, with 2 byte header
// Incrememnts another 6, for a total position of 10


--------------------------------------------------------------------------------
int FileOpen (string filename, int mode)
--------------------------------------------------------------------------------
Opens a file in the directory system for reading or writing

Documentation:

Will open or create a file of the passed name, for either reading or writing,
depending on the mode passed. It returns a handle to the file as a non zero
integer. If the operation fails, it returns 0, which idealy you should check for
before reading from the file.


The mode pass is to determine if you want to read from or write to the file,
only one can be selected, and the file must be closed and re opened to change to
the other mode. The defines used by verge are:

#define FILE_READ 1
#define FILE_WRITE 2

Verge will always return 0 if you try to open a file in read mode that does not
exist, however write mode will create a new file with that name. More
importantly however, it will always overwrite any data if the file already
exists (that's CREATE_ALWAYS for windows programmers). This makes appending to
the end of an existing file rather annoying.


Verge does not let you access the directory structure oustside your current
branch. You can access sub folders, but no overwriting stuff in c:\windows...
unless of course verge is run from there.


Like most things in verge, case matters not a whit. You can pass upper or lower
case letters for a filename, and it will still find the right thing, even if you
are silly: "ReAdmE.tXT" will still open the file.



Example Usage:
int file = FileOpen("maped3.exe", FILE_WRITE);
FileClose(file);
// Oh dear! You've just replaced Maped 3 with a blank file
// Doh... I actually just did, time to download the verge engine again


--------------------------------------------------------------------------------
int FileReadByte (int file)
--------------------------------------------------------------------------------
Reads a byte from file into an integer

Documentation:
Pass a handle to a file opened in read mode, and returns the integer value of
the byte at the current position, and moves the position onto the next byte. The
returned number will always between 0 to 255.

Example Usage:
int file = FileOpen("readme.txt", FILE_READ);
Log(str(FileReadByte(file)));
FileClose(file);
// This read the first byte and logs the value
// First line is "Welcome to VERGE 3! " so logs
// The number '87' which is the value of 'W' in ascii


--------------------------------------------------------------------------------
string FileReadLn (int file)
--------------------------------------------------------------------------------
Returns data from a file as an ascii string, ending at a new line

Documentation:
Pass a handle to a file opened in read mode, and it reads bytes from the file as
ascii and returns a string. It starts reading at the current position in the
file, and stops when it reaches a new line marker, or after 255 characters,
which ever comes first. The current position in the file is incremented to the
start of the next line.

Example Usage:
int file = FileOpen("README.TXT", FILE_READ);
FileSeekPos(file, 1, SEEK_CUR);
Log(FileReadLn(file));
FileClose(file);
// If you have the same verge readme in the directory
// This will write the string below in the v3.log file
// "elcome to VERGE 3! "


--------------------------------------------------------------------------------
int FileReadQuad (int file)
--------------------------------------------------------------------------------
Reads four bytes from file into an integer

Documentation:

Pass a handle to a file opened in read mode, and returns the integer value of
the first four bytes at the current position, and moves the position onto the
following byte. The can be the full value of a verge integer, including negative
numbers. The least significant byte is read in first, so effectively
performing:


FileReadByte(file) + (FileReadByte(file) 

Example Usage:
int file = FileOpen("readme.txt", FILE_READ);
Log(str(FileReadWord(file)));
FileClose(file);
// This read the first two bytes and logs the value
// First line is "Welcome to VERGE 3! " so logs
// The number '1668048215' which is a compound
// Of the values of 'W', 'e', 'l', and 'c' in ascii
// Obviously this is more useful as a big number


--------------------------------------------------------------------------------
string FileReadString (int file)
--------------------------------------------------------------------------------
Reads a string from file as ascii with a two byte length header

Documentation:

Pass a handle to a file open in read mode, and it returns a string of bytes in
ascii, of length determined by a two byte header. The file reads from the
current position, and increments the position to the end of the string. Note the
string to be read must have been written using FileWriteString() as it needs the
two byte header to know how much of the file to read.


Example Usage:
string text = "Check me";
int file = FileOpen("test.txt", FILE_WRITE);
FileWriteString(file, text);
FileClose(file);
int file = FileOpen("test.txt", FILE_READ);
if (strcmp(FileReadString(file), text)) Log("LIES!");
else Log("Truth!");
FileClose(file);
// So, that should should always log the truth
// Don't let strcmp confuse you there, it's always
// The wrong way around, returns 0 on match


int file = FileOpen("readme.txt", FILE_READ);
Log(str(len(FileReadString(file))));
FileClose(file);
// This logs a length of 9318 for the string read
// As it wrongly interpreted the first two bytes
// As a length in word format. Make sure to only
// Use this when the data was written correctly


--------------------------------------------------------------------------------
string FileReadToken (int file)
--------------------------------------------------------------------------------
Reads a string from file as ascii stopping at whitespace

Documentation:
This works like GetToken. Each time you call this, it will return a string using
whitespace as a token delimiter. It automatically increments which token it will
return, so calling it repeatedly will return a sequence of strings.



Example Usage:
int thefile = loadfile("stuff.txt");

log(filereadtoken(thefile));


--------------------------------------------------------------------------------
int FileReadWord (int file)
--------------------------------------------------------------------------------
Reads two bytes from file into an integer

Documentation:

Pass a handle to a file opened in read mode, and returns the integer value of
the first two bytes at the current position, and moves the position onto the
following byte. The returned number will always between 0 to 65535. The least
significant byte is read in first, so effectively performing:


FileReadByte(file) + (FileReadByte(file) 

Example Usage:
int file = FileOpen("readme.txt", FILE_READ);
Log(str(FileReadWord(file)));
FileClose(file);
// This read the first two bytes and logs the value
// First line is "Welcome to VERGE 3! " so logs
// The number '25943' which is the value of 'W' in ascii
// plus the value of 'e' raised by one byte
// 87 + (101 


--------------------------------------------------------------------------------
void FileSeekLine (int file, int linenum)
--------------------------------------------------------------------------------
Sets the current position in the file based on newline markers

Documentation:

Pass a handle to a file open in read mode, and it will set the current position
in the file to the byte after the (linenum) new line is passed. Passing 0 sets
the position to the start of the file.


Example Usage:
int file = FileOpen("readme.txt", FILE_READ);
FileSeekLine(file, 12);
Log(FileReadLn(file));
FileClose(file);
// For the current verge readme this logs:
// "http://www.verge-rpg.com/docs/"
// Which is line number 13 as count starts at 0


--------------------------------------------------------------------------------
void FileSeekPos (int file, int pos, int mode)
--------------------------------------------------------------------------------
Sets the current position in the file based byte ofsets

Documentation:

Pass a handle to a file open in either read or write mode, an distance in bytes
to move, and a mode to determine the starting position.... Pants... I'll do this
later.

#define SEEK_SET 0
#define SEEK_CUR 1
#define SEEK_END 2


Example Usage:
int file = FileOpen("readme.txt", FILE_READ);
FileSeekPos(file, 25, SEEK_SET);
Log(str(FileReadByte(file)));
FileClose(file);
// Reads the 26th byte from the start of the readme
// Remeber newline markers are two characters
// Logs '97' which is the ascii value of little a
// "Welcome to VERGE 3! "
// "(Readme.txt, 2004.09.28 edition of v3)"
//     ^


int file = FileOpen("dump.txt", FILE_WRITE);
FileWrite(file, "Oh fuck!");
FileSeekPos(file, 0-4, SEEK_END);
FileWriteByte(file, '*');
FileClose(file);
// Going backwards from the end of the file
// We impose a little censorship! Yeay!


--------------------------------------------------------------------------------
void FileWrite (int file, string s)
--------------------------------------------------------------------------------
Writes a string to file as ascii with no padding

Documentation:

Pass a handle to a file that is opened in write mode, and a string to be
written. The string is written from the current position in the file,
overwriting any existing data. It uses a 1 byte ascii representation for each
character, with no padding or escape sequence - so bytes used is equal to
len(s).


Example Usage:
int file = FileOpen("datafile.dat", FILE_WRITE);
FileWrite(file, "a");
FileClose(file);
// This creates/overwrites a file one byte in size
// Opened in a hex editor the contents will be: '61'
// Which is the ascii code of a little a


int file = FileOpen("datafile.dat", FILE_WRITE);
FileWrite(file, "Hello Number 1");
FileClose(file);
// Always writes one byte per character
// So this is a 14 byte file. In hex:
// '48 65 6c 6c 6f 20 4e 75 6d 62 65 72 20 31'



--------------------------------------------------------------------------------
void FileWriteByte (int file, int byte)
--------------------------------------------------------------------------------
Writes an integer to file as one byte

Documentation:

Pass a handle to a file that is opened in write mode, and an integer to be
written. The byte will be written at the current position within the file, over
any data that was previously there, and position will move to the next byte. As
only one byte of the four that make up a verge integer is being written, any
numbers bigger than 255 or less than 0 will NOT be written correctly. Use
FileWriteQuad() unless sure the number being written will remain within these
bounds.


Verge is effectivly only writing the 8 least significant bits of the passed
integer, so performing a (integer & 255) operation before writing. Numbers
outside the range of 0 to 255 will be written as another number with the range,
depending on the value of the least significant byte.


Example Usage:
int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteByte(file, 97); // or $61 or 'a'
FileClose(file);
// Opens/Creats a file and writes one byte to it
// Opened in a hex editor gives '61' as value of the byte
// In a text editor it gives the ascii 'a'

int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteByte(file, 0 - 2);
FileClose(file);
// Negative numbers are not stored properly
// Opened in a hex editor gives 'fe' as value of the byte
// -2 in binary: 11111111111111111111111111111110
// Least significant byte: 11111110
// Decimal: 254


--------------------------------------------------------------------------------
void FileWriteLn (int file, string s)
--------------------------------------------------------------------------------
Writes a string to file as ascii with a newline at the end

Documentation:

Pass a handle to a file that is opened in write mode, and a string to be
written. The string is written from the current position in the file,
overwriting any existing data. It uses a 1 byte ascii representation for each
character, and appends a 2 byte newline sequence on the end of the string  - so
bytes used is equal to len(s) + 2.


Example Usage:
int file = FileOpen("datafile.dat", FILE_WRITE);
FileWriteLn(file, "a");
FileClose(file);
// This creates/overwrites a file three bytes in size
// Opened in a hex editor the contents will be: '61 0d 0a'
// Which is the ascii code of a little a
// With two characters added to denote the new line

int file = FileOpen("datafile.dat", FILE_WRITE);
FileWriteLn(file, "Hello");
FileWriteLn(file, "Peeps");
FileClose(file);
// Opened in a text editor this reads:
// "Hello
// "Peeps
// ""
// Three lines, with the last one blank


--------------------------------------------------------------------------------
void FileWriteQuad (int file, int quad)
--------------------------------------------------------------------------------
Writes an integer to file as four bytes

Documentation:

Pass a handle to a file that is opened in write mode, and an integer to be
written. Four bytes will be written at the current position within the file,
over any data that was previously there, and position will move to the next
byte. As this writes the full value of the verge integer, it will read back
exactly as it was stored.


Note that the bytes are stored in order of least significant to most
significant. In effect what happens is:


FileWriteByte(quad & 255);
FileWriteByte(quad & (255 

Example Usage:
int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteQuad(file, 97); // or $61 or 'a'
FileClose(file);
// Opens/Creats a file and writes four byte to it
// Opened in a hex editor gives '61 00 00 00'

int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteQuad(file, 0 - 2);
FileClose(file);
// All integers are stored in full
// -2 in binary: 11111111111111111111111111111110
// File opened in a hex editor gives 'fe ff ff ff'



--------------------------------------------------------------------------------
void FileWriteString (int file, string s)
--------------------------------------------------------------------------------
Writes a string to file as ascii with the length stored in a header

Documentation:

Pass a handle to a file that is opened in write mode, and a string to be
written. The string is written from the current position in the file,
overwriting any existing data. It uses a 1 byte ascii representation for each
character, and writes a 2 byte string length before the start of the string - so
bytes used is equal to len(s) + 2. By storing the length first like this, it is
possible to use FileReadString() to read a string of abritary length back.


Example Usage:
int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteString(file, "a");
FileClose(file);
// This creates/overwrites a file three bytes in size
// Opened in a hex editor the contents will be: '01 00 61'
// Which is the ascii code of a little a
// With two bytes before saying the string is length one
// Note the least significant bit comes first

int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteString(file, "A string here");
FileWriteString(file, "And another one");
FileClose(file);
// Because the length is stored before the characters
// You can write strings however, and still read back
// As distinct separate values


--------------------------------------------------------------------------------
void FileWriteWord (int file, int word)
--------------------------------------------------------------------------------
Writes an integer to file as two bytes

Documentation:

Pass a handle to a file that is opened in write mode, and an integer to be
written. Two bytes will be written at the current position within the file, over
any data that was previously there, and position will move to the next byte. As
only two bytes of the four bytes that make up a verge integer is being written,
any numbers bigger than 65535 or less than 0 will NOT be written correctly. Use
FileWriteQuad() unless sure the number being written will remain within these
bounds.


Verge is effectivly only writing the 16 least significant bits of the passed
integer, so performing a (integer & 65535) operation before writing. Numbers
outside the range of 0 to 65535 will be written as another number with the
range, depending on the value of the two least significant bytes. Note also that
the bytes are stored in order of least significant to most significant. In
effect what happens is:


FileWriteByte(quad & 255);
FileWriteByte(quad & (255 

Example Usage:
int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteByte(file, 97); // or $61 or 'a'
FileClose(file);
// Opens/Creats a file and writes one byte to it
// Opened in a hex editor gives '61 00' as value of the byte
// In a text editor it gives the ascii 'a'

int file = FileOpen("datafile.txt", FILE_WRITE);
FileWriteByte(file, 0 - 2);
FileClose(file);
// Negative numbers are not stored properly
// Opened in a hex editor gives 'fe ff' as value of the byte
// -2 in binary: 11111111111111111111111111111110
// Two least significant bytes: 1111111111111110
// Decimal: 65534


================================================================================
k. Window Managment Functions
================================================================================


--------------------------------------------------------------------------------
void WindowClose (int w)
--------------------------------------------------------------------------------
Closes a window

Documentation:
Closes window 'w'.

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");
int debugImage=windowGetImage(debugWindow);
closeWindow(debugWindow);

printString(0,0,debugImage,0,"This is my debug window!"); //ERROR!!!
//why was there an error? BECAUSE THE WINDOW WAS CLOSED DAMMIT!


--------------------------------------------------------------------------------
int WindowCreate (int x, int y, int w, int h, string title)
--------------------------------------------------------------------------------
Creates another window

Documentation:
Creates a window at x,y with witdh and height w,h and named title. The function
returns the pointer for the window.

NOTE: the window pointer is not the same as the image pointer. to write to the
window image you must use the windowGetImage() function.

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");
int debugImage=windowGetImage(debugWindow);

printString(0,0,debugImage,0,"This is my debug window!");


--------------------------------------------------------------------------------
int WindowGetHeight (int window)
--------------------------------------------------------------------------------
NODE

Documentation:
NODE

Example Usage:
NODE


--------------------------------------------------------------------------------
int WindowGetImage (int w)
--------------------------------------------------------------------------------
Returns the image pointer for a window

Documentation:
Returns the image pointer for window 'w'.

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");
int debugImage=windowGetImage(debugWindow);

printString(0,0,debugImage,0,"This is my debug window!");


--------------------------------------------------------------------------------
int WindowGetWidth (int window)
--------------------------------------------------------------------------------
NODE

Documentation:
NODE

Example Usage:
NODE


--------------------------------------------------------------------------------
int WindowGetXRes (int window)
--------------------------------------------------------------------------------
NODE

Documentation:
NODE

Example Usage:
NODE


--------------------------------------------------------------------------------
int WindowGetYRes (int window)
--------------------------------------------------------------------------------
NODE

Documentation:
NODE

Example Usage:
NODE


--------------------------------------------------------------------------------
void WindowHide (int w)
--------------------------------------------------------------------------------
Hides a window

Documentation:
Hides window 'w'. Does not close it, the window can be brought back with
windowShow().

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");
int debugImage=windowGetImage(debugWindow);

printString(0,0,debugImage,0,"This is my debug window!");
//NOW YOU SEE IT!
windowHide(debugWindow);
//NOW YOU DONT!
windowShow(debugWindow);
//WAIT... NOW YOU DO, AGAIN!


--------------------------------------------------------------------------------
void WindowSetPosition (int w, int x, int y)
--------------------------------------------------------------------------------
Move the window's position

Documentation:
Move window 'w' position to x,y.

NOTE: x,y is the position of the upper left corner pixel.

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");

//the window is at 0,0!

WindowSetPosition(debugWindow,100,100);

//the window is at 100,100!




--------------------------------------------------------------------------------
void WindowSetSize (int window, int w, int h)
--------------------------------------------------------------------------------
NODE

Documentation:
NODE

Example Usage:
NODE


--------------------------------------------------------------------------------
void WindowSetTitle (int w, string title)
--------------------------------------------------------------------------------
Set the new title for a window

Documentation:
Set title of window 'w' to 'title'.

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");
int debugImage=windowGetImage(debugWindow);

printString(0,0,debugImage,0,"This is my debug window!");

windowSetTitle(debugWindow, "Not my debug window");

rectFill(0,0,100,100,0,debugImage);
printstring(0,0,debugImage,0,"this is NOT my debug window ¬_¬...");


--------------------------------------------------------------------------------
void WindowShow (int w)
--------------------------------------------------------------------------------
Returns a window from hiding

Documentation:
Returns window 'w' from hiding.

Example Usage:
int debugWindow=windowCreate(0,0,100,100,"Debug");
int debugImage=windowGetImage(debugWindow);

printString(0,0,debugImage,0,"This is my debug window!");
//NOW YOU SEE IT!
windowHide(debugWindow);
//NOW YOU DONT!
windowShow(debugWindow);
//WAIT... NOW YOU DO, AGAIN!


================================================================================
l. Movie Playback Functions
================================================================================
Movies are complicated things in windows.  You can't just take any old movie
file and throw it in a game and expect it to work on other people's systems. 
Besides that, it is rude to put a big movie file in a game.  Most people will
reflexively hit ESC anyway because thats what they are accustomed to doing when
assaulted with an FMV.  However, movie functionality is provided for those who
have some legitimate need for it.  BUT YOU MUST FOLLOW THESE RULES:
DO NOT USE DIVX OR XVID OR MPEG2.  These codecs do not come with windows, and
the player might not have installed them manually.  Use cinepak, indeo, video-1,
or even RLE.  The compression might be cruddy, but at least it will work.
If you are thinking about making a video an integral part of your game, you MUST
CONTACT ME to discuss it so I can help you make sure you're doing it right.  If
you are including a video for some lame purpose like an intro screen are
something then I suggest that you not do it, and if you must indeed do it then I
suggest that you contact me to get advice on doing it right.

--------------------------------------------------------------------------------
void PlayMovie (string avi)
--------------------------------------------------------------------------------
NODE

Documentation:
NODE

Example Usage:
NODE


================================================================================
m. Netcode Functions
================================================================================


--------------------------------------------------------------------------------
int Connect (string hostname)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int GetConnection ()
--------------------------------------------------------------------------------
Nodeshell

Documentation:
Nodeshell

Example Usage:
Nodeshell


--------------------------------------------------------------------------------
int GetUrlImage (string url)
--------------------------------------------------------------------------------
Connects to a URL and returns an image.

Documentation:
Attempts to connect to the a given URL, and downloads and returns an image
pointer. If it fails, the the pointer will be 0.

Example Usage:
void AutoExec()
{
  //Get a picture of Grue wearing a Verge T-Shirt. Bleh.
  int
img=GetUrlImage"http://www.vergerpg.com/images/store/shirt_00_sidebar.jpg");
  while(1)
  {
   if(img!=0) Blit(0,0,img,screen);
   ShowPage();
  }
}


--------------------------------------------------------------------------------
string GetUrlText (string url)
--------------------------------------------------------------------------------
Return text from a specified URL

Documentation:
Attempts to connect to the a given URL, and returns the contents. If it fails,
it will instead return that site's Error 404 (File not Found) message. Could
possibly be used in conjunction with a PHP-enabled page, allowing cool stuff
like a dynamic online high-score chart, or something.

Example Usage:
//Log the current VergeC functions from vecna's website.
Log(GetUrlText("http://vecna.verge-rpg.com/v3vergec.txt"));


--------------------------------------------------------------------------------
void SocketClose (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketConnected (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
string SocketGetFile (int socket, string ovfname)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketGetInt (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketGetString (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketHasData (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void SocketSendFile (int socket, string fname)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void SocketSendInt (int socket, int i)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void SocketSendString (int socket, string str)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL

================================================================================
--------------------------------------------------------------------------------
g. Global Variables
--------------------------------------------------------------------------------
================================================================================
Some of these variable can be written to, some cannot. It's not always
immediately obvious which. If you get a "Unknown HVAR1" type of error, it's
probably because you a trying to assign to a read-only variable.



--------------------------------------------------------------------------------
int Connect (string hostname)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int GetConnection ()
--------------------------------------------------------------------------------
Nodeshell

Documentation:
Nodeshell

Example Usage:
Nodeshell


--------------------------------------------------------------------------------
int GetUrlImage (string url)
--------------------------------------------------------------------------------
Connects to a URL and returns an image.

Documentation:
Attempts to connect to the a given URL, and downloads and returns an image
pointer. If it fails, the the pointer will be 0.

Example Usage:
void AutoExec()
{
  //Get a picture of Grue wearing a Verge T-Shirt. Bleh.
  int
img=GetUrlImage"http://www.vergerpg.com/images/store/shirt_00_sidebar.jpg");
  while(1)
  {
   if(img!=0) Blit(0,0,img,screen);
   ShowPage();
  }
}


--------------------------------------------------------------------------------
string GetUrlText (string url)
--------------------------------------------------------------------------------
Return text from a specified URL

Documentation:
Attempts to connect to the a given URL, and returns the contents. If it fails,
it will instead return that site's Error 404 (File not Found) message. Could
possibly be used in conjunction with a PHP-enabled page, allowing cool stuff
like a dynamic online high-score chart, or something.

Example Usage:
//Log the current VergeC functions from vecna's website.
Log(GetUrlText("http://vecna.verge-rpg.com/v3vergec.txt"));


--------------------------------------------------------------------------------
void SocketClose (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketConnected (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
string SocketGetFile (int socket, string ovfname)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketGetInt (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketGetString (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
int SocketHasData (int socket)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void SocketSendFile (int socket, string fname)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void SocketSendInt (int socket, int i)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


--------------------------------------------------------------------------------
void SocketSendString (int socket, string str)
--------------------------------------------------------------------------------
NODESHELL

Documentation:
NODESHELL

Example Usage:
NODESHELL


================================================================================
a. General System Variables
================================================================================
int screen; // this is a hardcoded image handle for the screen
int systemtime; // read-only timer variable constantly increasing
int timer; // read/write timer variable
int key[scancode]; // read/write key-state array
int lastpressed; // scancode of last pressed key
int lastkey; // last key pressed in ASCII


To elaborate: 

screen - Is a pointer to a bitmap of the screen's current dimensions (set in
v3.cfg or by SetResolution() function at runtime). Anything you want to appear
in ther verge window should be blitted here with one of the graphics functions.
When ShowPage() is called the screen bitmap is transfered to the display. 


systemtime - Stores the current time as given by your computer's internal clock.
See the Date/Time variables for more. 


timer - A number than increases by 100 every second and very useful for anything
you need to happen within a set timeframe. As you can re-set this value whenever
you like, it's also possible to use it to work out how long ago something
happened. 


key[scancode] - Stores whether a key IS CURRENTLY PRESSED - so if the key was
down the last time ShowPage() or UpdateControls() was called. If you want to use
is like a HAS BEEN PRESSED state, you'll need to reset the value back to 0 each
time manually. Unlike standard ASCII methods key['a'] will not work - verge has
its own defines, look at the Scan Codes section to see them. 


lastpressed - Stores the verge scancode of the last keyboard key the player
pressed. See Scan Codes. 


lastkey - Same as above, but stores proper ASCII, so 'a' = 97 = little a 

================================================================================
b. Mouse Variables
================================================================================
int mouse.x; // current mouse x-coordinate
int mouse.y; // current mouse y-coordinate
int mouse.l; // read/write left-button status
int mouse.r; // read/write right-button status
int mouse.m; // read/write middle-button status
int mouse.w; // read/write mousewheel thingy

...
When using the mouse variables, keep in mind they correspond to the position of
the V3 window. 



So if you're using the Antialias/2xSAI/Eagle/whatever it is screen blitter,
remember that the actual V3 window size is doubled. You may have to divide
mousex and mousey by 2 to get the actual values to work with your code.

================================================================================
c. Joystick Variables
================================================================================
int joystick; // read/write anchor, current joystick # for joy.* struct (sticks
0-3 valid)
int joy.active; // 0/1 whether or not this joystick is connected and active
int joy.up; // 0/1 for joystick 'up' position
int joy.down; // 0/1 for joystick 'down' position
int joy.left; // 0/1 for joystick 'left' position
int joy.right; // 0/1 for joystick 'right' position
int joy.analogx; // analog position of joystick x-axis (0 center, -1000 max
left, +1000 max right)
int joy.analogy; // analog position of joystick y-axis (0 center, -1000 max up,
+1000 max down)
int joy.button[button]; // 0/1 for joystick button # depressed (buttons 0-31
valid)

================================================================================
d. Entity Variables
================================================================================
For the corresponding entity functions go here

int entities;
int entity.x[entity];
int entity.y[entity];
int entity.specframe[entity];
int entity.frame[entity];
int entity.hotx[entity];
int entity.hoty[entity];
int entity.hotw[entity];
int entity.hoth[entity];
int entity.movecode[entity];
int entity.face[entity];
int entity.speed[entity];
int entity.visible[entity];
int entity.obstruct[entity];
int entity.obstructable[entity];
string entity.script[entity];


entities: (read only) The number of entities currently on the map. Use this an
the upper bound any time you need to loop through and check entites for
something.

entity.x and entity.y: (read/write) The coordinates of the entity on the map.
This is a pixel value from the top left corner of the map to the top left corner
of the entity's hotspot. To get an x,y coord of the entity on the screen
subtract xwin and ywin.

entity.specframe: (read/write) Similar to setting a z movecode, this sets a
frame to display. Remember to set it back to 0 if you want movement
animations.

entity.frame: (?read only?) ?Just stores the entities current frame?

entity.hot(x/y/w/h): (read only) These four variables specify a rectangle on the
entity's frame used for collision detection, x,y coords from the top left corner
of the frame, width and height. They are read-only. Why, I don't know. You'll
need to set them in the .mak when you create your .chr file.

entity.movecode: (read only) reflects the current wandermode of the entity. 0 is
not moving, 1 is wander zone, 2 is wander rect, and 3 is movecode.  Attempting
to setting this variable manually will crash the system, so if you want to
change the wandermode, please use one of the following functions: EntityStop(),
EntitySetWanderZone(), EntitySetWanderRect(), or EntityMove().

entity.face: (read/write) Returns a number that corresponds to the direction the
entity is facing.  Changing this will change the direction the entity is facing.
 Setting it to an invalid value can crash the system.

      (up) 1
           |
(left) 3 --+-- 4 (right)
           |
           2 (down)           



entity.visible: (read/write) [NEW!] Whether or not the entity will be drawn to
the screen. A little testing seems to show it affects BlitEntityFrame() as well
as Render() and 0 is invisible.


entity.obstruct: (read/write) 1 if the entity's hotspot is an obstruction, 0 if
not.


entity.obstructable: (read/write) 1 if this entity cares about obstructions when
moving, 0 if not.


entity.script: (read/write) The movescript currently used by this entity.  See
EntityMove() for more details.

================================================================================
e. Sprite Variables
================================================================================
For the corresponding sprite functions go here

sprite.x[]
sprite.y[]
sprite.sc[] // 0 = map coordinates, 1 = screen coordinates
sprite.image[] // 0 = sprite off, else image handle to display
sprite.lucent[]
sprite.addsub[] // 0 = normal blit, -1 = subtractive blit, +1 = additive blit
sprite.alphamap[] // 0 = no alpha blit, else alpha map to use for sprite - alpha
overrides addsub

Sprite System isnt complete right now but when it is, I'll add more
documentation

================================================================================
f. Camera Variables
================================================================================
int xwin, ywin;
int cameratracking, cameratracker;
The camera variables are used to control where on the map the screen is looking.
By default cameratracking is set to 1, which means the screen will follow the
current player entity around as they move. The xwin and ywin hold the top left
corner of the screen position in map x,y pixel coordinates, and will update to
keep the player in the center of the screen on each Render().
Setting cameratracking to 0 turns off this behavior, so you can manually set the
xwin and ywin values, and verge will abide by them.
Setting cameratracking to 2 makes the camera follow the target of the
cameratracker instead, whatever that may be (entity perhaps?).

================================================================================
g. Map Variables
================================================================================
int curmap.w;
int curmap.h;
int curmap.startx;
int curmap.starty;
int curmap.tileset;
string curmap.name;
string curmap.rstring;
string curmap.music;

curmap.rstring: Sets the renderstring for the current map. This is in the format
"1,2,3,E,4,5,R" - but you can have whatever you want basically. Putting multiple
R characters in is useful, that way you can draw between several different
layers: use HookRetrace() at the end of each function to specify the next one,
or handle in one function with conditionals.



curmap.tileset: An image handle to the current map VSP, that you CAN draw to
(the image will be 16 pixels wide and 16*numtiles tall). NEEDS MOAR



...plus the rest


================================================================================
h. Layer Variables
================================================================================
int layer.lucent;
(more to come in future builds)

layer.lucent: Sets the lucency value of a layer. Just as with lucent blits, 100
is completely transparent and 0 is fully opaque.


================================================================================
i. Event Variables
================================================================================
int event.tx; // triggering tile x coord of this event, if applicable
int event.ty; // triggering tile y coord of this event, if applicable
int event.zone; // triggering zone of this event, if applicable
int event.entity; // triggering entity of this event, if applicable
int event.param; // parameter passed on event string

int event.entity refers to the entity who triggered the event as well as the
entity being rendered when hooking an entity render.

================================================================================
j. Date/Time Variables
================================================================================
int sysdate.year; // the system clock year
int sysdate.month; // current month
int sysdate.day; // current day-of-month
int sysdate.dayofweek; // current day of week (0=sunday, 6=saturday) 

int systime.hour; // system clock hour (24hour format)
int systime.minute; // current clock minute
int systime.second; // current clock second
================================================================================
--------------------------------------------------------------------------------
h. Built-in Defines
--------------------------------------------------------------------------------
================================================================================
For information on the nature of the built-in defines, read the Preprocessor
directives section of the manual.



================================================================================
a. Version
================================================================================
_version is a builtin define that will return, in string format, the version of
verge you're currently running.



Might be useful inorder to stop anyone from running your game with a different
version of verge... or something =p

================================================================================
b. Scan Codes
================================================================================
Verge doesn't use ASCII for reading and comparing keyboard input, but instead
uses the keyboard scan codes instead. You will generally only use the scan codes
when reading lastpressed or the key array.

EX:



if(key[SCAN_ESC]) exit("");

else if(key[SCAN_ENTER]) map("town.map");



or



switch(lastpressed){

    case SCAN_EXIT: exit("");

    case SCAN_ENTER: map("town.map");

}



from vergec.txt:

{"SCAN_ESC", "01" } 

{"SCAN_1", "02" } 

{"SCAN_2", "03" } 

{"SCAN_3", "04" } 

{"SCAN_4", "05" } 

{"SCAN_5", "06" } 

{"SCAN_6", "07" } 

{"SCAN_7", "08" } 

{"SCAN_8", "09" } 

{"SCAN_9", "10" } 

{"SCAN_0", "11" } 

{"SCAN_MINUS", "12" } 

{"SCAN_EQUALS", "13" } 

{"SCAN_BACKSP", "14" } 

{"SCAN_TAB", "15" } 

{"SCAN_Q", "16" } 

{"SCAN_W", "17" } 

{"SCAN_E", "18" } 

{"SCAN_R", "19" } 

{"SCAN_T", "20" } 

{"SCAN_Y", "21" } 

{"SCAN_U", "22" } 

{"SCAN_I", "23" } 

{"SCAN_O", "24" } 

{"SCAN_P", "25" } 

{"SCAN_LANGLE", "26" }
 
{"SCAN_RANGLE", "27" } 

{"SCAN_ENTER", "28" } 

{"SCAN_CTRL", "29" } 

{"SCAN_A", "30" } 

{"SCAN_S", "31" } 

{"SCAN_D", "32" } 

{"SCAN_F", "33" } 

{"SCAN_G", "34" } 

{"SCAN_H", "35" } 

{"SCAN_J", "36" } 

{"SCAN_K", "37" } 

{"SCAN_L", "38" } 

{"SCAN_SCOLON", "39" }
 
{"SCAN_QUOTA", "40" } 

{"SCAN_RQUOTA", "41" } 

{"SCAN_LSHIFT", "42" } 

{"SCAN_BSLASH", "43" } 

{"SCAN_Z", "44" } 

{"SCAN_X", "45" } 

{"SCAN_C", "46" } 

{"SCAN_V", "47" } 

{"SCAN_B", "48" } 

{"SCAN_N", "49" } 

{"SCAN_M", "50" } 

{"SCAN_COMMA", "51" }
 
{"SCAN_DOT", "52" } 

{"SCAN_SLASH", "53" } 

{"SCAN_RSHIFT", "54" } 

{"SCAN_STAR", "55" } 

{"SCAN_ALT", "56" } 

{"SCAN_SPACE", "57" } 

{"SCAN_CAPS", "58" } 

{"SCAN_F1", "59" } 

{"SCAN_F2", "60" } 

{"SCAN_F3", "61" } 

{"SCAN_F4", "62" } 

{"SCAN_F5", "63" } 

{"SCAN_F6", "64" } 

{"SCAN_F7", "65" } 

{"SCAN_F8", "66" } 

{"SCAN_F9", "67" } 

{"SCAN_F10", "68" } 

{"SCAN_NUMLOCK","69" }
 
{"SCAN_SCRLOCK","70" } 

{"SCAN_HOME", "71" } 

{"SCAN_UP", "72" } 

{"SCAN_PGUP", "73" } 

{"SCAN_GMINUS", "74" } 

{"SCAN_LEFT", "75" } 

{"SCAN_PAD_5", "76" } 

{"SCAN_RIGHT", "77" } 

{"SCAN_GPLUS", "78" } 

{"SCAN_END", "79" } 

{"SCAN_DOWN", "80" } 

{"SCAN_PGDN", "81" } 

{"SCAN_INSERT", "82" } 

{"SCAN_DEL", "83" } 

{"SCAN_F11", "87" } 

{"SCAN_F12", "88" } 


================================================================================
c. Color Filters
================================================================================
The defines are for use with:

void ColorFilter(COLOR_FILTER filter, int image)




Applies the specified filter to the given image. The following filters are
valid: 



CF_NONE does absolutely nothing! 

CF_GREY converts the image to greyscale 

CF_GREYINV converts the image to inverted greyscale. 

CF_INV converts to full-color RGB inversion. For instance, the inverse of green
would be purple: RGB(0,255,0) -> RGB(255,0,255). 

CF_RED gets an average luminosity and then applies that to the red channel only.


CF_GREEN gets an average luminosity and then applies that to the green channel
only. 

CF_BLUE gets an average luminosity and then applies that to the blue channel
only. 

CF_CUSTOM uses a user defined color filter set with SetCustomColorFilter(int c1,
int c2).


Example:

colorFilter(CF_BLUE, screen); // This will convert the screen image to a full
blue-scale image



To see the greyscale filter in action, and how it differs from other methods
this program is a good demonstration.



Two notes about this function. It will abide by the clipping region, but you
will not gain the full speed benefit of a clip region. This may be optimized in
the future. It will abide by Lucency values: you can acheive some cool effects
this way. For instance a lucent percentage of a CF_GREY filter will provide a
washed-out, color-faded look. 

================================================================================
--------------------------------------------------------------------------------
i. Appendix
--------------------------------------------------------------------------------
================================================================================

================================================================================
a. history of verge
================================================================================

1. Verge

2. Verge2

3. Much lameness

4. Verge3

================================================================================
--------------------------------------------------------------------------------
j. Credits
--------------------------------------------------------------------------------
================================================================================
================================================================================
--------------------------------------------------------------------------------
k. Colophon
--------------------------------------------------------------------------------
================================================================================
The Paradise Isle Matriculated Monovalve

The clam on the cover is the endangered, yet resilient Paradise Isle
Matriculated Monovalve.  This much-sullied clam has been blamed of every malady
in the Paradise Isle and Lesser Vicaria regions from clogging water lines and
polluting water supplies to supplying plucky adventurers with tools to further
their quest.  Although it's population is in the low odd prime numbers, we still
reserve hope that with proper care the species can make a recovery.
