The VERGE 2 Manual

The reference manual for the VERGE 2 and WinV2 game creation engines. No longer in development, but someone out there may benefit from this!

Variables

Integers

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

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?

Yes. You may only have up to 255 characters in a string.

Arrays

You can declare arrays of both ints and strings. You can only declare them in SYSTEM.VC (and any #included sub-files). Variables declared outside of any function are global and can be accessed by any system.vc OR map-based VC event at all. Arrays must be global.

Example:

int flags[8000];

Language Specification

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 (<<): The Left Bitshift operator generates a new number which is its first operand with all the bits shifted left a number of spaces equal to the value of the second operand. If this sounds confusing, here's an easier way to think about it: in the expression m<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 (<): Lesser Than returns true if the first operand is lesser than the second; otherwise, it returns false.

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 (<=): Lesser Than or Equal To returns true if the first operand is lesser than or equal to the second; otherwise, it returns false.

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

Comments

Just as in VC1, both C and C++ style comment conventions are supported.

Comments: Comments are not required in your VergeC code, but smart event coders will use them to help organize and make their event 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.

Example:
```
Event // #75: When Dexter joins
{
  Addcharacter(3);
}
```

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

Example:

Event
{
  /*  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.

Control Structures

VergeC 2.0 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 <list>)
{
  (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(<variable to be tested>)
{
    Case <result 1>: <command>;
    Case <result 2>: <command>;
    Case <result 3>: <command>;
}
```
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 (PartyIndex(1))
{
    case 1: Text(1,"My name's Darin and I'm leading this party!","","");
    case 2: Text(2,"I'm Sara and I'm here to pump you up!","","");
    case 3: Text(3,"Dexter is leading this party.","","");
}
```
WHILE loops:
It works much the same as a FOR loop, but can use nearly any condition to control how long it executes. The syntax is such:
```
while (<condition>)
{
    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.
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<5; i++)
{
    printstring(i,"This is font "+str(i)+".");
}
```

System and Map Code

There are two distinct types of VC in V2, and that is the system.vc, and everything else, which are MAP-based VC files. MAP based VC is very similar to how VC was in V1. You cannot declare your own functions or variables in a MAP vc. They use the familiar event { } style scripts. When they are compiled their pcode is attached directly into the MAPfile itself.

The other type is system.vc, which is compiled into the files system.vcs and system.idx, respectively. system.vc allows you to declare your own functions and variables - the trick comes in that any of your map VC can access any and all of the functions and variables set up in system.vc.

The only real problem arises that, because of the new relationship between system.vc and map-based VC, it's conceivable (quite likely, actually) that if you modify system.vc you'll break MAPs that you've already compiled. As such, VCC now has a 'vcc all' option, that will compile system.vc, and then recompile all maps it can find in the given directory. ME2 has a shortcut to do this right from inside MapEd - Just hit F6 and it'll rebuild all of your VC files. (of course, this means you can't have an ALL.MAP. Oh well, live with it. ^_-)

There is nothing like startup.vc or startup.scr in V2. When you execute verge.exe, it always starts execution at a MAP file. Which mapfile it starts at is determined in user.cfg, by the 'startmap' command. Additionally, you can start verge.exe at a specific map by specifying the mapfile on the command line, which MapEd makes use of to directly test out the mapfile you're currently working on.

Functions

There are two types of user declared functions, ones that return a value and those that don't. The simplist declaration for a function would be:

void MyFunc()
{ }

You can add passed parameters like so:

void MyFunc(int a, string b)
{ }

These parameters would be accessed inside this function as any other variable would be, but it only exists inside the function. You would call this function from map or other system.vc code with something like this:

MyFunc(5, "Hello.");

To make your function return a value, you'd declare it like so:

int MyAdd(int a, int b)
{
  return a+b;
}

You can now return strings as of 4.4.00 Version 2.5. Very useful:

string my_routine(int a, string b)
{
  int this;
  string that;
  return that + b;
}

Limits of passed parameters and local variables: For any given system.vc function, the total number of passed parameters and local variables cannot exceed 20, and the total number of passed and locally declared strings cannot exceed 10. However, if you have 10 strings, you can only have 10 ints, otherwise the total limit of 20 variables (int and otherwise) would be exceeded.

If there is a global variable and local variable of the same name, inside the function the local variable will be used instead. But in a function where that local var isn't declared, or a map-vc event, the global variable will be used instead.

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:

#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"
```
#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]; 
```

Engine

USER.CFG

The following are the available User.cfg commands to Verge 2:

mount (filename)  Mounts the specified .VRG packfile.
vidmode (xres) (yres) Sets screen resolution
log     Turns logging on.
startmap (filename) Chooses starting map
sound_device (0 - 3)  0 = autodetect, 3 = nosound
mixrate (frequency) Mixrate of sounds.
dmabufsize (size) ???
force8bit   Forces 8-bit quality sound output
forcemono   Forces monaural sound output
end     Denotes the end of the .CFG.

The following are the available commands to WinV2:

xres, yres          Pretty self-explanitory.
windowmode (0, 1)   Toggles fullscreen/windowed mode.
nosound (0, 1)          Toggles sound playback
eagle (0, 1)            Toggles the 2xSAI (yes the name is confusing) filter
paranoid (0, 1)         Toggles strict VC runtime error checking
arraycheck (0, 1)       Toggles VC array range checking, see above
appname (name)          Sets the name shown in the Window title
mount1 .. mount3 (file) Mounts the specified .VRG packfile.

Debug Console

Note: WinV2 does not have a console menu.

                     ===================================�
                     =    V2 Console Command Summary    =
                     ====================================
Current as of 5.9.99

Using the Command Console
================ ====== ==== == =
The command console is summoned by the ~ (tilde) key. Pressing the same key
a second time hide the console as well. If ~ does not bring the console down,
the game designer has disabled it via the AllowConsole(0); call.

You basically use it by just typing commands into it. The actual commands will
be detailed below. However, in addition to typing commands, it also supports
the following features:

  The UP/DOWN keys are a 10-entry Last Command Memory.
  The PGUP/PGDN keys allow you to use the scrollback features.
  TAB is command-name completion.

Console Command Reference
================ ====== ==== == =
========================================================================�
= ACTIVEENTS = Parameters: None                                         =
============== Usage: ACTIVEENTS                                        =
= Description: Lists the index numbers of all active (onscreen)         =
=  entities.                                                            =
=========================================================================
========================================================================�
= BROWSETILES = Parameters: None                                        =
=============== Usage: BROWSETILES                                      =
= Description: Displays the tileset currently loaded. Inside the browse =
=  interface, the up/down keys scroll through the tiles if there are    =
=  more than fit on the screen. The A key toggles tile animation, Q     =
=  exits the browse interface.                                          =
=========================================================================
========================================================================�
= CAMERATRACKING = Parameters: [on/off]                                 =
================== Usage: CAMERATRACKING [0/1]                          =
= Description: If CAMERATRACKING is executed with no parameters, the    =
=  status (0 or 1) will be returned. If 0 or 1 is specified as the 1st  =
=  parameter, that will set a new value for cameratracking. This        =
=  variable controls whether or not the camera follows the player       =
=  around at all times.                                                 =
=========================================================================
========================================================================�
= CD_OPEN  = Parameters: None                                           =
= CD_CLOSE = Usage: CD_OPEN                                             =
============ Usage: CD_CLOSE                                            =
= Description: Opens or closes the CD tray door, respectively.          =
=========================================================================
========================================================================�
= CD_PLAY = Usage: CD_PLAY                                    =
= CD_STOP = Usage: CD_STOP                                              =
=========== Description: CD_PLAY begins CD audio playback at the        =
= specified track number. CD_STOP stops all CD audio playback.          =
=========================================================================
========================================================================�
= CONSOLEBG = Parameters: None                                          =
============= Usage: CONSOLEBG                               =
= Description: Sets the specified image as the console background. The  =
=  image can be in PCX, GIF or BMP format, but must be 320x240.         =
=========================================================================
========================================================================�
= CPU_USAGE = Parameters: [on/off]                                      =
============= Usage: CPU_USAGE [0/1]                                    =
= Description: Turns on or off the CPU usage monitor. When it's on, it  =
=  displays an FPS report and shows CPU usage in the categories of      =
=  rendering, pageflipping, and game ai (etc).                          =
=========================================================================
========================================================================�
= CURPOS = Parameters: None                                             =
========== Usage: CURPOS                                                =
= Description: Returns the current coordinates of the player.           =
=========================================================================
========================================================================�
= ENITITY = Parameters: [index]                                         =
=========== Usage: ENTITY [ent num]                                     =
= Description: Returns the current coordinates of the given entity.     =
=========================================================================
========================================================================�
= ENITITYSTAT = Parameters: None                                        =
=============== Usage: ENTITYSTAT                                       =
= Description: Gives a report on the current entity stats.              =
=========================================================================
========================================================================�
= EXIT = Parameters: None                                               =
======== Usage: EXIT                                                    =
= Description: Exits to DOS.                                            =
=========================================================================
========================================================================�
= LISTCMDS = Parameters: None                                           =
============ Usage: LISTCMDS                                            =
= Description: Lists all registered console commands.                   =
=========================================================================
========================================================================�
= LISTMOUNTS = Parameters: None                                         =
============== Usage: LISTMOUNTS                                        =
= Description: Lists all currently mounted packfiles.                   =
=========================================================================
========================================================================�
= MAP = Parameters: [MAP name]                                          =
======= Usage: MAP [MAP name]                                           =
= Description: MAP with no parameters gives a statistics report about   =
=  the currently loaded MAP. Otherwise, it will attempt to map switch   =
=  to the map file specified.                                           =
=========================================================================
========================================================================�
= MOUNT = Parameters: [Packfile]                                        =
========= Usage: MOUNT [packfile name]                                  =
= Description: MOUNT will mount the specified packfile and add it to    =
=  VERGE's packfile search list.                                        =
=========================================================================
========================================================================�
= PACKINFO = Parameters: [Packindex]                                    =
============ Usage: PACKINFO [packindex]                                =
= Description: Packinfo returns a list of files and in a given packfile.=
=  To view the first packfile mounted, you would type "packinfo 0".     =
=========================================================================
========================================================================�
= PHANTOM = Parameters: [On/Off]                                        =
=========== Usage: PHANTOM [0/1]                                        =
= Description: Turns on or off Phantom mode (no clipping)               =
=========================================================================
========================================================================�
= PLAYER = Parameters: [Entity index]                                   =
========== Usage: PLAYER [idx]                                          =
= Description: Sets the player to the given entity number.              =
=========================================================================
========================================================================�
= PLAYERSPEED = Parameters: [speed]                                     =
=============== Usage: PLAYERSPEED [1-7]                                =
= Description: Sets the player speed                                    =
=========================================================================
========================================================================�
= SHOWOBS = Parameters: [on/off]                                        =
=========== Usage: SHOWOBS [0/1]                                        =
= Description: If this is turned on, grid will be drawn on top of the   =
= render process denoting where the obstruction are on the map.         =
=========================================================================
========================================================================�
= SHOWZONES = Parameters: [on/off]                                      =
============= Usage: SHOWZONES [0/1]                                    =
= Description: If this is turned on, grid will be drawn on top of the   =
=  render process denoting where the zones are on the map, color coded. =
=========================================================================
========================================================================�
= SPEEDDEMON = Parameters: None                                         =
============== Usage: SPEEDDEMON                                        =
= Description: This command will enable the "2x speed" cheat to allow   =
=  the player to move twice his normal velocity when the CTRL key is    =
=  held down.                                                           =
=========================================================================
========================================================================�
= VER = Parameters: None                                                =
======= Usage: VER                                                      =
= Description: Displays a V2 version report and build info.             =
=========================================================================
========================================================================�
= WARP = Parameters: [tile-x, tile-y]                                   =
======== Usage: WARP [x] [y]                                            =
= Description: Warps the player to the specified location.              =
=========================================================================

Special Commands: RV/SV
================ ====== ==== == =
These two additional console commands are extremely useful in the development
and debugging of your Verge game, especially with advanced VC. These commands
stand for ReadVariable and SetVariable, respectively; they allow you to access
the value of any user declared (system.vc global) variable (ints only, not
strings). You can access both single ints and array components.

For example, to read the value of a variable named "gold" you'd simply do:
RV GOLD
and the value of the variable would be printed out. To set the value of "gold"
to a really big value, you'd type:
SV GOLD 1500000

To use array variables, you simply add another parameter which is the array
offset, ie:
RV FLAGS 105
Would return the value of flags[105]. Likewise, to set the value of flags[20]
to 0, you'd type:
SV FLAGS 20 0

Have an idea for a console command you'd like to see implemented? Mail me
at aen@verge-rpg.com and We'll consider your request.

- Verge2 staff

Function Reference

General Utility Functions

AllowConsole

void AllowConsole (int flag)

Controls whether or not the ` key will summon the console or not.

Example usage:

AllowConsole(1); // Enable the console!

Controls whether or not the ` key will summon the console or not. 0 will disallow the console, 1 will activate it. Disabling the console is a good way to prevent cheating, however having it enabled will make developing and testing the game easier.

Note: This is function deprecated in WinV2. Having it in your code will cause it to be ignored.

CallEvent

int CallEvent (int which_event)

Calls the specified map event.

Example usage:

CallEvent(3);

Calls the specified map event.

Exit

void Exit (string message)

Exits Verge.

Example usage:

Exit("Thank you for playing!");

Completely exits out of the engine leaving the user with the specified message.

HookKey

void HookKey (int scancode, system script)

Binds an event to a specified keypress.

Example usage:

HookKey(1, Menu); // When Escape is pressed (key scancode 1), the function Men() in system.vc will be executed.

Binds an event to a specified keypress. This allows you to create menus and other types of key-based events easily.

HookRetrace

void HookRetrace (system script)

Execute the given VergeC event every render.

Example usage:

HookRetrace(my_script); // hook script
HookRetrace(1); // hook event

Given a non-zero event number, it will execute the given VergeC event (from the Map VC) each time a frame is rendered. Note that it will be called at the 'R' position in the Renderstring, so if there *is* no 'R' position, then it will never be executed. As in verge 1, HookRetrace is quite stable, and should be used instead of HookTimer whenever possible. You can pass zero to this event to turn off the HookRetrace.

HookTimer

void HookTimer (system event)

Executes a VC event each time tick.

Example usage:

HookTimer(my_script); // hook script
HookTimer(1); // hook event

Given a non-zero event number, it will execute the given VergeC event (from the Map VC) each timer tick (ie, 100 times per second). Note that, like verge 1, this is the more volatile of the Hook* family of functions, and HookRetrace should be used in place of HookTimer whenever possible. When using HookTimer, you should never call any rendering functions, and in general you should do as little as possible inside the hooked event as you can. As with HookRetrace, passing 0 to this function will turn off the HookTimer.

Log

void Log (string text)

Outputs a message to Verge.log

Example usage:

Log("VERGE 2");

Outputs a message to Verge.log (WinV2.log on WinV2), assuming verge.log is enabled by the user. This can be useful for debugging.

Message

void Message (string message, int duration))

Issues the specified system message.

Example usage:

Message("VERGE 2", 200);

Issues the specified system message, lasting the given duration in hundreths of a second. This message is displayed in the upper left corner of the screen for the given duration, and noted in the verge.log file.

Note: This is function deprecated in WinV2. Having it in your code will cause it to be ignored.

Random

int Random (int range)

Returns a random number between 0 and the range given.

Example usage:

if (Random(100) < 50)
{
  PrintString(0, "Heads!");
}
else
{
  PrintString(0, "Tails!");
}

Returns a random number between 0 and the range given.

ReadMouse

void ReadMouse ()

Updates the mouse status variables.

Example usage:

ReadMouse();

Updates the mouse status variables mx, my, and mb.

SetMousePos

void SetMousePos (int x, int y)

Sets the current mouse position.

Example usage:

SetMousePos(screenx/2, screeny/2);

Sets the current mouse position to the given x and y coordinates. Does no checking to make sure the coordinates are valid, so check that yourself, they should between 0 and screenx and 0 and screeny, respectively.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.

SetResolution

int SetResolution (int xres, int yres)

Sets the video mode to the specified resolution.

Example usage:

SetResolution(320, 240);

Sets the video mode to the specified resolution. Returns 1 if successful, 0 if the mode set failed. As of 4.4.00 V2.5 supports any 256-color resolution. Common video modes:

DOS:
- 320x200
- 320x240
- 360x240
- 256x256
- 640x480
Windows:
- 320x200
- 320x240
- 512x384
- 640x480
- ~~800x600~~
- ~~1024x768~~
Unpress
```
void Unpress (int control)
```
Causes a button to be unpressed until no longer held of and pressed again.
Example usage:
```
Unpress(0);
```
This will read a control currently being pressed as not pressed until it is released and then pressed again. The values of control are:
```
0: All buttons, not directionals
1: b1
2: b2
3: b3
4: b4
5: up
6: down
7: left
8: right
```
UpdateControls
```
void UpdateControls ()
```
Updates the control variables.
Example usage:
```
UpdateControls();
```
Updates the control variables up, down, left, right, b1, b2, b3, and b4.
String Functions
left
```
string left (string s, int n)
```
Returns the leftmost n characters of string.
Example usage:
```
string s = "JIMMY";
s = left(s, 2);
```
Returns the leftmost n characters of string.
mid
```
string mid (string s, int start, int run)
```
Returns a section of string.
Example usage:
```
string s = "JIMMY";
s = mid(s, 1, 2);
```
Returns a section of string, starting at the start character, run characters long.
right
```
void right (string s, int n)
```
Returns the rightmost n characters of string.
Example usage:
```
string s = "JIMMY";
s = right(s, 2);
```
Returns the rightmost n characters of string.
str
```
string str (int num)
```
Converts a numerical value into string form.
Example usage:
```
Log(str(4));
```
Converts a numerical value into string form.
strcmp
```
int strcmp (string str1, string str2)
```
Compares the two passed strings.
Example usage:
```
string_a = "alpha";
string_b = "zeta";
result = strcmp(string_a, string_b);
if (!result)
  PrintString(0, "Strings are equal");
else if (result < 0)
  PrintString(0, string_a+" comes before "+string_b);
else
  PrintString(0, string_b+" comes before "+string_a);
```
Compares the two passed strings. Returns 0 if they're identical, or a nonzero number porportional to the difference between the strings.
strlen
```
int strlen (string str)
```
Returns the length of the passed string.
Example usage:
```
my_string = "VERGE 2";
length = strlen(my_string);
```
Returns the length of the passed string.
val
```
int val (string s)
```
Attempts to convert a string back to an integer value.
Example usage:
```
int a;
a = val("42");
```
Attempts to convert a string back to an integer value. If the string has too many non-numerical characters in it, however, it may not be able to.
Map Functions
GetTile
```
int GetTile (int x, int y, int layer)
```
Returns the value of the given map layer at the given coordinates.
Example usage:
```
tile = GetTile(0, 0, 0);
```
Returns the value of the given map layer at the given coordinates. For layer, 0 through 5 are the first 6 possible map layers, a value of 6 will always denote the obstruction field, and 7 denotes zone information.
Map
```
void Map (string map_filename)
```
Loads the specified MAP file as the current map.
Example usage:
```
Map("TEST.MAP");
```
Loads the specified MAP file as the current map. Upon encountering this command, VC execution is immediately terminated completely and resumed at the new map's Autoexec event.
Render
```
void Render ()
```
Draws the map to the screen.
Example usage:
```
Render();
ShowPage();
```
Performs a render, per the render string, but does not copy the screen buffer to the visible screen, allowing you to draw additional items on top of the game screen.
SetRString
```
void SetRString (string rstring)
```
Updates the RenderString to the specified string.
Example usage:
```
SetRString("1E2");
```
Updates the RenderString to the specified string.
SetTile
```
void SetTile (int x, int y, int layer, int value)
```
Sets a new value to the given map layer at the given coordinates.
Example usage:
```
SetTile(0, 0, 0, 2);
```
Sets a new value to the given map layer at the given coordinates. For layer, 0 through 5 are the first 6 possible map layers, a value of 6 will always denote the obstruction field, and 7 denotes zone information.
Entity Functions
EntityMove
```
void EntityMove (int entity, string movescript)
```
Sets the given entity to the specified movement script.
Example usage:
```
ent = EntitySpawn(0, 1, "VECNA.CHR");
EntityMove(ent, "R2D2");
```
Sets the given entity to the specified movement script. As in V1, you cannot use 'B', the loop command, in an EntityMove given script.. But I should be able to work around that so that it will work eventually.
EntitySpawn
```
int EntitySpawn (int x, int y, string chrname)
```
Allocates a new entity at the given coordinates, using the specified CHR file.
Example usage:
```
ent = EntitySpawn(0, 1, "VECNA.CHR");
```
Allocates a new entity at the given coordinates, using the specified CHR file. The entity index of the new entity is returned.
PartyMove
```
void PartyMove (string movescript)
```
This command will have the party follow the specified movement script
Example usage:
```
PartyMove("U1R1D1L1");
```
This command will have the party follow the specified movement script; player control will resume after the script is completed.
ProcessEntities
```
void ProcessEntities ()
```
Processes one tick worth of entity movement.
Example usage:
```
ProcessEntities();
```
Processes one tick worth of entity movement. If you call this 100 times a second it will keep the game moving as normal. For example, it could be used to draw something on top of the normal map view.

Side-note: If memory serves correctly, this is not required in WinV2 games and might actually cause entities to move faster than usual under certain circumstances.
SetPlayer
```
void SetPlayer (int entityindex)
```
Sets the specified entity index as the active player.
Example usage:
```
SetPlayer(EntitySpawn(0, 1, "VECNA.CHR"));
```
Sets the specified entity index as the active player.
Graphics Functions
ChangeAll
```
void ChangeAll (int source, int width, int height, int source_color, int dest_color)
```
Changes all the pixels of source_color to dest_color.
Example usage:
```
im = LoadImage("blue.pcx");
ChangeAll(im, 200, 200, RGB(5, 200, 34), RGB(20, 20, 20));
```
Changes all the pixels of source_color in the source to the color in dest_color.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
Circle
```
void Circle (int x, int y, int radius, int color)
```
Draws a circle (outline only).
Example usage:
```
Circle(screenx/2, screeny/2, 50, 128);
```
Draws a circle (outline only) of the given radius, centered at the given coordinates, in the given color.
CircleFill
```
void CircleFill (int x, int y, int radius, int color)
```
Draws a circle.
Example usage:
```
CircleFill(screenx/2, screeny/2, 50, 128);
```
Draws a circle of the given radius, centered at the given coordinates, in the given color.
CopySprite
```
void CopySprite (int x, int y, int width, int height, int image)
```
Blits an image to the screen.
Example usage:
```
im = LoadImage("VECNA.PCX");
CopySprite(0, 0, image_width, image_height, im);
free(im);
```
Blits the image pointed to by image with the given dimensions at the given location on screen. No transparency, clipping is performed.
GetB
```
int GetB (int color)
```
Returns the blue value of the passed color.
Example usage:
```
int r, g, b, color;
color = 16;
r = GetR(color);
g = GetG(color);
b = GetB(color);
```
Returns the blue value of the passed color.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
GetG
```
int GetG (int color)
```
Returns the green value of the passed color.
Example usage:
```
int r, g, b, color;
color = 16;
r = GetR(color);
g = GetG(color);
b = GetB(color);
```
Returns the green value of the passed color.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
GetPixel
```
int GetPixel (int x, int y)
```
Returns the color of the specified pixel coordinate.
Example usage:
```
color = GetPixel(screenx/2, screeny/2);
```
Returns the color of the specified pixel coordinate.
GetR
```
int GetR (int color)
```
Returns the red value of the passed color.
Example usage:
```
int r, g, b, color;
color = 16;
r = GetR(color);
g = GetG(color);
b = GetB(color);
```
Returns the red value of the passed color.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
GrabRegion
```
void GrabRegion (int x1, int y1, int x2, int y2, int buffer)
```
Captures a region of the screen and copies it into a bitmap buffer.
Example usage:
```
save_screen = malloc(screenx * screeny);
GrabRegion(0, 0, screenx-1, screeny-1, save_screen);
// ** use save_screen here **
free(save_screen);
```
This routine captures a region of the screen and copies it into a bitmap buffer. The main trick with using this routine is that you are responsible for creating and destroying this buffer with the malloc/free commands, and to be sure that you allocate enough memory in your malloc call to contain the image. For instance, if you capture the region from (0,0) to (49,49), this is a 50x50 square, and you will need to allocate 2500 bytes.
HLine
```
void HLine (int x, int y, int x2, int color)
```
Draws a horizontal line using the specified coordinates in the given color.
Example usage:
```
HLine(0, screeny/2, screenx-1, 128);
```
Draws a horizontal line using the specified coordinates in the given color.
InitMosaicTable
```
int InitMosaicTable ()
```
Call this function to generate a mosaic palette-matching table.
Example usage:
```
table = InitMosaicTable();
```
If you wish to use the Mosaic() routine, you must call this function to generate a mosaic palette-matching table (store the value returned by this function and pass it to Mosaic each time you call it). We would precompute this table, however, it depends on the palette. The table calculations can take a while, it takes about 12 seconds on my P200. It is possible, of course, to precompute the table in VC and load it at runtime for people that want to use this feature and wish to avoid the long table computation time.
Line
```
void Line (int x, int y, int x2, int y2, int color)
```
Draws an arbitary-angled line from any two sets of coordinates in the given color.
Example usage:
```
Line(0,0, screenx-1,screeny-1, 128);
```
Draws an arbitary-angled line from any two sets of coordinates in the given color.
LoadImage
```
int LoadImage (string filename)
```
Loads the specified image.
Example usage:
```
im = LoadImage("CHEESE.GIF");
// ** use im here **
free(im);
```
Loads the specified image, allocating enough memory for it, and returns a pointer to the image. If you no longer need the image, you should free() it. The image can be any of the supported V2 image types, which are currently PCX, BMP, and GIF.
Mask
```
void Mask (int source, int mask, int width, int length, int dest)
```
Performs a bitwise AND operation on every byte in the image.
Example usage:
```
Mask(im, RGB(100,25,150), im_width, im_length, im2);
```
Mask() performs a bitwise AND operation on every byte (8-bits) in the specified image with the supplied integer value (every 16-bits when in hicolor mode). This is a more advanced command, and will find its use only in the hands of intermediate/veteran graphics programmers.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
Mosaic
```
void Mosaic (int xfocus, int yfocus, int tablepointer, int x1, int y1, int x2, int y2)
```
"Mosaics" the screen.
Example usage:
```
table = InitMosaicTable();
Mosaic(4,4, table, 0,0, screenx-1, screeny-1);
```
"Mosaics" the screen so far; The best way to describe it is as the mode7 effect used in FF2 and such to make the screen "blur out" during screen transitions. xfocus and yfocus control the "granularity" of this blurring, tablepointer must be the value returned by InitMosaicTable or a pointer to a precomputed table loaded in memory. The x1,y1,x2,y2 values specify the section of the screen to apply the mosaic effect to.

So, to apply the mosaic effect with a 3-to-1 pixel ratio to the whole screen, you'd use Mosaic(3, 3, MyMosaicTable, 0, 0, ScreenX, ScreenY);

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
PaletteMorph
```
void PaletteMorph (int r, int g, int b, int mix, int lighting)
```
Alters the entire game palette.
Example usage:
```
PaletteMorph(0,0,0,0, 63);
```
This command alters the entire game palette, which will effect the entire screen. It changes the 'tint' of the screen; the RGB values are the color you want to tint the screen with, and range from 0 to 63. So, 63,0,0 would be red, 0,63,0 is green, and 0,0,63 is blue. 0,0,0 is black and 63,63,63 is white. The mix value controls how 'thickly' the screen is tinted with this color. 0 would mean no mix whatsoever, while 100 would change the screen to be the color you specified solidly. The lighting value simply controls how light or dark the screen will be as a whole; 63 is normal brightness, 0 is black.
Rect
```
void Rect (int x, int y, int x2, int y2, int c)
```
Draws an outlined rectangle.
Example usage:
```
Rect(0, 0, screenx-1, screeny-1, 128);
```
Draws an outlined rectangle of the given coordinate set in the specified color.
RectFill
```
void RectFill (int x, int y, int x2, int y2, int c)
```
Draws a rectangle.
Example usage:
```
RectFill(0, 0, screenx-1, screeny-1, 128);
```
Draws a rectangle of the given coordinate set in the specified color.
RestoreRenderSettings
```
void RestoreRenderSettings ()
```
Restores the default clipping window for the given video mode.
Example usage:
```
RestoreRenderSettings();
```
Restores the default clipping window for the given video mode, and restores the render destination to the video buffer.
RGB
```
int RGB (int r, int g, int b)
```
Returns a color value.
Example usage:
```
SetPixel(screenx/2, screeny/2, RGB(100, 50, 90));
```
Returns a color value. Ranges are (0...255).

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
ScaleSprite
```
void ScaleSprite (int x, int y, int iw, int ih, int dw, int dh, int imageptr)
```
Draws a scaled image.
Example usage:
```
im = LoadImage("VECNA.PCX");
ScaleSprite(0,0, image_width,image_height, image_width*2,image_height*2, im);
free(im);
```
Draws a scaled image. A bit more complex than the other blitters to use. The x,y values give the upper-left corner of where the blit will start. iw,ih are the width and height of the *source* image. dw, dh are the width and height that the image should appear on screen. (ie, the end result bounding box of the image would be, x, y, x+dw, y+dh) Imageptr is, as with the other blit routines, a pointer to the image graphic.
SetClip
```
void SetClip (int clip)
```
You will never need to turn this off.
Example usage:
```
SetClip(1);
```
Determines whether clipping versions of general VC graphics routines are used. Defaults to 1; You will never need to turn this off, turn it offers no functional difference, except faster blitting routines, however, great care must be used when turning it off that no part of any blit or graphics call draws off screen boundaries.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
SetClipRect
```
void SetClipRect (int x1, int y1, int x2, int y2)
```
Sets the rectangle that image drawing will be clipped to.
Example usage:
```
im = LoadImage("PATTERN.PCX");
SetClipRect(screenx/4, screeny/4, screenx-(screenx/4), screeny-(screeny/4));
WrapBlit(0, 0, image_width, image_height, im);
RestoreRenderSettings();
free(im):
```
Sets the rectangle that image drawing will be clipped to.
SetLucent
```
void SetLucent (int lucent)
```
Determines whether translucent versions of general VC graphics routines are used.
Example usage:
```
SetLucent(1);
```
Determines whether translucent versions of general VC graphics routines are used. Defaults to 0.
SetPixel
```
void SetPixel (int x, int y, int c)
```
Sets the specified pixel coordinate to the given color.
Example usage:
```
SetPixel(screenx/2, screeny/2, 128);
```
Sets the specified pixel coordinate to the given color.
SetRenderDest
```
void SetRenderDest (int width, int height, int buffer)
```
This sets the video buffer that all VC video functions will draw into.
Example usage:
```
buffer = malloc(32 * 32);
SetRenderDest(32, 32, buffer);
Line(0,0, 15,15, 128);
Line(0,15, 15,0, 128);
Rect(0,0, 15,15, 128);
RestoreRenderSettings();
CopySprite(0, 0, 32, 32, buffer);
free(buffer);
```
This sets the video buffer that all VC video functions will draw into.
ShowPage
```
void ShowPage ()
```
Copys the screen buffer to the visible screen.
Example usage:
```
ShowPage();
```
Copys the screen buffer to the visible screen.
Silhouette
```
void Silhouette (int x, int y, int width, int height, int color, int image)
```
Renders a silhouette of the specified image.
Example usage:
```
im = LoadImage("GOAT.PCX");
Silhouette(0, 0, image_width, image_height, 128, im);
free(im);
```
Renders a silhouette of the specified image. The silhouette is generated by looking for all non-zero pixels in the image and replacing them with the specified color.
TCopySprite
```
void TCopySprite (int x, int y, int width, int height, int image)
```
Blits an image to the screen with transparency.
Example usage:
```
im = LoadImage("SLIME.PCX");
TCopySprite(0, 0, image_width, image_height, im);
free(im);
```
Blits the image pointed to by image with the given dimensions at the given location on screen. Transparency and clipping are performed.
TScaleSprite
```
void TScaleSprite (int x, int y, int iw, int ih, int dw, int dh, int imageptr)
```
Draws a scaled image.
Example usage:
```
im = LoadImage("SLIME.PCX");
TScaleSprite(0,0, image_width,image_height, image_width*2,image_height*2, im);
free(im);
```
Draws a scaled image. A bit more complex than the other blitters to use. The x,y values give the upper-left corner of where the blit will start. iw,ih are the width and height of the *source* image. dw, dh are the width and height that the image should appear on screen. (ie, the end result bounding box of the image would be, x, y, x+dw, y+dh) Imageptr is, as with the other blit routines, a pointer to the image graphic. This routines draws the image with transparency, unlike ScaleSprite().
TWrapBlit
```
void TWrapBlit (int xofs, int yofs, int width, int height, int image)
```
Blits an image of any size repeatedly so that it fills the entire screen.
Example usage:
```
im = LoadImage("PATTERN.PCX");
TWrapBlit(0, 0, image_width, image_height, im);
free(im);
```
Blits an image of any size repeatedly so that it fills the entire screen; This version is color-0 transparent unlike the normal WrapBlit version.
VLine
```
void VLine (int x, int y, int y2, int color)
```
Draws a vertical line from the specified coordinates in the given color.
Example usage:
```
VLine(screenx/2, 0, screeny-1, 128);
```
Draws a vertical line from the specified coordinates in the given color.
WrapBlit
```
void WrapBlit (int xofs, int yofs, int width, int height, int image)
```
Blits an image of any size repeatedly so that it fills the entire screen.
Example usage:
```
im = LoadImage("PATTERN.PCX");
WrapBlit(0, 0, image_width, image_height, im);
free(im);
```
Blits an image of any size repeatedly so that it fills the entire screen.
Sound/Music Functions
CacheSound
```
int CacheSound (string filename)
```
Loads a specified sound effect.
Example usage:
```
snd_shriek = CacheSound("SHRIEK.WAV");
```
Loads a specified sound effect (8-bit, mono, un-compressed WAV file), and returns the slot number that you'll access this sound with for PlaySound.
CD_Play
```
void CD_Play (int track)
```
Begins playing CD audio at the specified track number.
Example usage:
```
CD_Play(6);
```
Begins playing CD audio at the specified track number.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
CD_Stop
```
int CD_Stop ()
```
Stops all CD audio playing.
Example usage:
```
CD_Stop();
```
Stops all CD audio playing.

Note: This is function deprecated in WinV2. Having it in your code will trigger an error.
FreeAllSounds
```
void FreeAllSounds ()
```
Frees all sound effect slots.
Example usage:
```
FreeAllSounds();
```
Frees all sound effect slots.
PlayMusic
```
void PlayMusic (string filename)
```
Plays the specified music file.
Example usage:
```
PlayMusic("AURORA.MOD");
```
Plays the specified music file. In this version of V2, only MODs, MTMs, S3Ms, and XMs are supported.

Note: WinV2 allows you to also play IT files as well, and fixes some issues with the audio playback of certain formats.
PlaySound
```
void PlaySound (int soundslot, int volume, int pan)
```
Plays the specified sound effect at the given slot index.
Example usage:
```
shriek = CacheSound("SHRIEK.WAV");
PlaySound(shriek, 64, 128);
```
Plays the specified sound effect at the given slot index; volume is a value from 0 to 64 indicating the volume the sound file will be played at, and pan is a value from 0 to 255; 0 is all the way left, and 255 is all the way right, 128 is in the center.
StopMusic
```
void StopMusic ()
```
Stops currently playing music.
Example usage:
```
StopMusic();
```
Stops currently playing music.
Font Functions
FontHeight
```
int FontHeight (int fontidx)
```
Returns the height of the font at the given font index.
Example usage:
```
height = FontHeight(0);
```
Returns the height of the font at the given font index.
FontWidth
```
int FontWidth (int fontidx)
```
Returns the width of the font at the given font index.
Example usage:
```
width = FontWidth(0);
```
Returns the width of the font at the given font index.
GotoXY
```
string GotoXY (int x, int y)
```
Sets the current text output "cursor" to the given location.
Example usage:
```
GotoXY(screenx/2, screeny/2);
PrintString(0, "Hyuck.");
```
Sets the current text output "cursor" to the given location. This is where calls to PrintString will be displayed at.
LoadFont
```
int LoadFont (string filename)
```
Loads the specified font file.
Example usage:
```
my_font = LoadFont("MYFONT.FNT");
```
Loads the specified monospace FNT file and returns the font slot which is used by PrintString.
PrintString
```
void PrintString (int font, string text)
```
Displays the given string in the specified font index.
Example usage:
```
PrintString(0, "VERGE 2");
```
Displays the given string in the specified font index, at the location last given by GotoXY.
Math Functions
cos
```
int cos (int degree)
```
Returns the cosine of the given degree.
Example usage:
```
result = cos(45);
```
Returns the cosine of the given degree of measure (0-360) in 16.16 fixed point.
pow
```
int pow (int base, int exp)
```
Raises base to the exp power and returns that value.
Example usage:
```
result = pow(16, 3); // 4096
```
Raises base to the exp power and returns that value.
sin
```
int sin (int degree)
```
Returns the sine of the given degree.
Example usage:
```
result = sin(180);
```
Returns the sine of the given degree of measure (0-360) in 16.16 fixed point.
sqrt
```
int sqrt (int number)
```
Returns the square root of number.
Example usage:
```
result=sqrt((x*x)+(y*y));
```
Returns the square root of number.
tan
```
int tan (int degree)
```
Returns the tangent of the given degree.
Example usage:
```
result = tan(270);
```
Returns the tangent of the given degree of measure (0-360) in 16.16 fixed point.
File Functions
fclose
```
void fclose (int filehandle)
```
Closes the file given by the specified file handle.
Example usage:
```
file = fopen("EXAMPLE.DAT");
// ** use file here **
fclose(file);
```
Closes the file given by the specified file handle.
fdelete
```
void fdelete (string filename)
```
Deletes the specified file.
Example usage:
```
fdelete("EXAMPLE.TXT");
```
Deletes the specified file. (uhm.. obviously, be careful with this command. This doesn't send it to the recycle bin or anything, the file is GONE after this command is executed. Like all the other file I/O vc commands, this will ONLY work on files in the main directory VERGE is being run from)
fgetbyte
```
int fgetbyte (int filehandle)
```
Gets a single byte from the specified file and returns its value.
Example usage:
```
file = fopen("TEST.DAT");
Message("First byte in TEST.DAT is: "+str(fgetbyte(file)), 200);
fclose(file);
```
Gets a single byte from the specified file and returns its value.
fgetline
```
void fgetline (string variable, int filehandle)
```
Grabs the next line from the specified text file handle.
Example usage:
```
file = fopen("EXAMPLE.TXT");
fgetline(my_string, file);
Message("First line in EXAMPLE.TXT is: "+my_string, 200);
fclose(file);
```
Grabs the next line from the specified text file handle and returns it in the string variable passed.

Note: String support is a bit sketchy in V2 at the moment, and this command, only accepts global strings as valid parameters. It also will not read correctly into string arrays.
fgetquad
```
int fgetquad (int filehandle)
```
Gets a single quad (4 bytes) from the specified file and returns it's value.
Example usage:
```
file = fopen("TEST.DAT");
Message("First quad in TEST.DAT is: "+str(fgetquad(file)), 200);
fclose(file);
```
Gets a single quad (4 bytes) from the specified file and returns it's value.
fgettoken
```
void fgettoken (string variable, int filehandle)
```
Grabs the next token from the specified text file handle.
Example usage:
```
file = fopen("EXAMPLE.TXT");
fgettoken(my_string, file);
Message("First token in EXAMPLE.TXT is: "+my_string, 200);
fclose(file);
```
Grabs the next token (space delimited) from the specified text file handle and returns it in the string variable passed.

Note: String support is a bit sketchy in V2 at the moment, and this command, only accepts global strings as valid parameters. It also will not read correctly into string arrays.
fgetword
```
int fgetword (int filehandle)
```
Gets a single word (2 bytes) from the specified file and returns it's value.
Example usage:
```
file = fopen("TEST.DAT");
Message("First word in TEST.DAT is: "+str(fgetword(file)), 200);
fclose(file);
```
Gets a single word (2 bytes) from the specified file and returns it's value.
fopen
```
int fopen (string filename)
```
Opens the given file and returns a unique file handle integer.
Example usage:
```
file = fopen("EXAMPLE.TXT");
fclose(file);
```
Opens the given file and returns a unique file handle integer.
fread
```
void fread (int buffer, int length, int filehandle)
```
Reads in a given amount of data from the specified file into the given buffer
Example usage:
```
file = fopen("TEST.DAT");
buffer = malloc(100);
fread(buffer, 100, file);
fclose(file);
```
Reads in a given amount of data from the specified file into the given buffer. Thus buffer must be pre-allocated by the user.
frename
```
void frename (string filename, string newname)
```
Renames the specified file to the new name.
Example usage:
```
frename("EXAMPLE.TXT", "TEST.TXT");
```
Renames the specified file to the new name.
fseekline
```
void fseekline (int line, int filehandle)
```
Moves the file pointer to the given line number in a pre-opened text file.
Example usage:
```
file = fopen("EXAMPLE.TXT");
fseekline(3, file);
fgetline(my_string, file);
Message("Line #3 in EXAMPLE.TXT is: "+my_string, 200);
fclose(file);
```
Moves the file pointer to the given line number in a pre-opened text file.
fseekpos
```
void fseekpos (int pos, int filehandle)
```
Moves the file pointer to the given byte position in a pre-opened binary file.
Example usage:
```
file = fopen("TEST.DAT");
fseekpos(20, file);
Message("Byte #20 in TEST.DAT is: "+str(fgetbyte(file)), 200);
fclose(file);
```
Moves the file pointer to the given byte position in a pre-opened binary file.
fwclose
```
void fwclose (int filehandle)
```
Closes the given file that was open for writing.
Example usage:
```
file = fwopen("EXAMPLE.TXT");
// ** use file here **
fwclose(file);
```
Closes the given file that was open for writing. Be *sure* not to mix file handles that were opened for reading and those that were opened for writing.
fwopen
```
int fwopen (string filename)
```
Opens the specified filename for writing.
Example usage:
```
file = fwopen("EXAMPLE.TXT");
// ** use file here **
fwclose(file);
```
Opens the specified filename for writing.
fwrite
```
void fwrite (int ptr, int length, int filehandle)
```
Writes the data at the given data pointer to the specified file.
Example usage:
```
file = fwopen("EXAMPLE.TXT");
buffer = malloc(screenx * screeny);
GrabRegion(0,0, screenx-1,screeny-1, buffer);
fwrite(buffer, screenx * screeny, file);
fwclose(file);
free(buffer);
```
Writes the data at the given data pointer to the specified file.
fwritebyte
```
void fwritebyte (int b, int filehandle)
```
Writes the passed byte to the specified file.
Example usage:
```
file=fwopen("SAVEDAT.000");
fwritebyte(hp[0],file);
fwclose(file);
```
Writes the passed byte to the specified file.
fwritequad
```
void fwritequad (int q, int filehandle)
```
Writes the passed quad to the specified file.
Example usage:
```
file=fwopen("SAVEDAT.000");
fwritequad(money,file);
fwclose(file);
```
Writes the passed quad to the specified file.
fwritestring
```
void fwritestring (string text, int filehandle)
```
Writes the passed string to the specified file.
Example usage:
```
file = fwopen("EXAMPLE.TXT");
my_string = "VERGE 2";
fwritestring(my_string, file);
fwclose(file);
```
Writes the passed string to the specified file. The string is written in text mode format, with a CR/LF pair at the end.
fwriteword
```
void fwriteword (int w, int filehandle)
```
Writes the passed word to the specified file.
Example usage:
```
file=fwopen("SAVEDAT.000");
fwriteword(money,file);
fwclose(file);
```
Writes the passed word to the specified file.
LoadRaw
```
int LoadRaw (string filename)
```
Loads the specied file as raw data.
Example usage:
```
raw = LoadRaw("SPEECH.SPC");
// ** use raw here **
free(raw);
```
Loads the specied file as raw data into an allocated buffer and returns a pointer to that buffer.
ReadVars
```
void ReadVars (int filepointer)
```
Reads all the global variables that have been written to a file.
Example usage:
```
file = fopen("SAVE.DAT");
ReadVars(file);
fclose(file);
```
Reads all the global variables that have been written to a file by WriteVars(). You're responsible for opening and closing the file for reading, mainly used for savegames.
WriteVars
```
void WriteVars (int filepointer)
```
Writes all global variables to the specified file.
Example usage:
```
file = fwopen("SAVE.DAT");
WriteVars(file);
fwclose(file);
```
Writes all global variables (ints and strings) to the specified file. You must take care of opening and closing the file for writing. Mostly used for savegames.
Global Variables
General System Variables
b1, b2, b3, b4, up, down, left, right

These represent primary control buttons. They are updated by the UpdateControls() function. [read-only].

key

Returns or set the on/off flag of the specified key scancode.

screen

Single-dimensional array access to the video virtual buffer. [read/write]

screenx, screeny

Return the x and y dimensions of the current video mode. [read-only]

timer

This variable is incremented 100 times per second. It can be used to for timing purposes. [read/write]

vctrace

This is a 0/1, off/on variable that defaults to 0; when it is turned on, VERGE.LOG will contain dumps tracing the code flow of system.vc function calls. However, this log can get very big very quickly, so it's recommended that you turn it on to track and debug a particular section of code and then turn it off afterwards.

pal[]

Active palette array (256 RGB entries; 768 bytes). Changes made will only be enforced when PaletteMorph() is next called.

Example:
```
// greyscale the active palette
for (i=0; i<256; i++)
{
  r=pal[i*3+0];
  g=pal[i*3+1];
  b=pal[i*3+2];
  average=(r+g+b)/3;
  pal[i*3+0]=average;
  pal[i*3+1]=average;
  pal[i*3+2]=average;
}
PaletteMorph(0, 0, 0, 0, 63);
```
Camera Variables
xwin, ywin

These control the camera, if cameratracking is 0. Otherwise, the camera will follow the player. [read/write]

cameratracking, tracker

If cameratracking is 0, the camera is free to be altered by the xwin/ywin variables. If cameratracking is 1, the camera will always follow the player. If cameratracking is 2, the camera will always follow the entity specified in tracker. [read/write]
Map Variables
vsp

Array of tile image data. Sequential ordering of 256 byte (16*16) blocks.
Entity Variables
entity.x, entity.y

x/y coordinates of the specified entity in world-coordinates (pixel-accurate). [read/write]

entity.tx, entity.ty

x/y coordinates of the specified entity in tile coordinate. [read/write]

entity.facing, entity.moving, entity.specframe, entity.speed, entity.movecode, entity.visible, entity.on

Various variables effecting the specified stats of the given entity. entity.visible dedicates whether or not the entity is drawn to the screen. entity.on determines whether it is proccessed.

entsonscreen[]

Array of entity indexes which are currently onscreen.

lastent

The last entity that called a VC event, either via movement script or activation. (Note: vergec.txt says this is untested.)

numents

Returns total amount of entities on the screen.

numentsonscreen

Number of entities currently on screen, number of values in entsonscreen array that are valid.

player

Returns which entity index number is currently the active player. [read-only]

Mouse Variables
mx, my, mb

mx and my are the x and y coordinates of the mouse pointer. mb returns the mouse button status.
Useful Defines
Key Scancodes
Here are some keycode definitions:
```
#define SCAN_ESC        1
#define SCAN_1          2
#define SCAN_2          3
#define SCAN_3          4
#define SCAN_4          5
#define SCAN_5          6
#define SCAN_6          7
#define SCAN_7          8
#define SCAN_8          9
#define SCAN_9          10
#define SCAN_0          11
#define SCAN_MINUS      12
#define SCAN_EQUALS     13
#define SCAN_BACKSP     14
#define SCAN_TAB        15
#define SCAN_Q          16
#define SCAN_W          17
#define SCAN_E          18
#define SCAN_R          19
#define SCAN_T          20
#define SCAN_Y          21
#define SCAN_U          22
#define SCAN_I          23
#define SCAN_O          24
#define SCAN_P          25
#define SCAN_LANGLE     26
#define SCAN_RANGLE     27
#define SCAN_ENTER      28
#define SCAN_CTRL       29
#define SCAN_A          30
#define SCAN_S          31
#define SCAN_D          32
#define SCAN_F          33
#define SCAN_G          34
#define SCAN_H          35
#define SCAN_J          36
#define SCAN_K          37
#define SCAN_L          38
#define SCAN_SCOLON     39
#define SCAN_QUOTA      40
#define SCAN_RQUOTA     41
#define SCAN_LSHIFT     42
#define SCAN_BSLASH     43
#define SCAN_Z          44
#define SCAN_X          45
#define SCAN_C          46
#define SCAN_V          47
#define SCAN_B          48
#define SCAN_N          49
#define SCAN_M          50
#define SCAN_COMA       51
#define SCAN_DOT        52
#define SCAN_SLASH      53
#define SCAN_RSHIFT     54
#define SCAN_GREY_STAR  55
#define SCAN_ALT        56
#define SCAN_SPACE      57
#define SCAN_CAPS       58
#define SCAN_F1         59
#define SCAN_F2         60
#define SCAN_F3         61
#define SCAN_F4         62
#define SCAN_F5         63
#define SCAN_F6         64
#define SCAN_F7         65
#define SCAN_F8         66
#define SCAN_F9         67
#define SCAN_F10        68
#define SCAN_NUMLOCK    69
#define SCAN_SCRLOCK    70
#define SCAN_HOME       71
#define SCAN_UP         72
#define SCAN_PGUP       73
#define SCAN_GREY_MINUS 74
#define SCAN_LEFT       75
#define SCAN_PAD_5      76
#define SCAN_RIGHT      77
#define SCAN_GREY_PLUS  78
#define SCAN_END        79
#define SCAN_DOWN       80
#define SCAN_PGDN       81
#define SCAN_INSERT     82
#define SCAN_DEL        83
#define SCAN_F11        84
#define SCAN_F12        85
```

The VERGE 2 Manual

Variables

Integers

Strings

Arrays

Language Specification

Operators

Comments

Control Structures

System and Map Code

Functions

Preprocessor Directives

Engine

USER.CFG

Debug Console

Function Reference

General Utility Functions

AllowConsole

CallEvent

Exit

HookKey

HookRetrace

HookTimer

Log

Message

Random

ReadMouse

SetMousePos

SetResolution

Unpress

UpdateControls

String Functions

left

mid

right

str

strcmp

strlen

val

Map Functions

GetTile

Map

Render

SetRString

SetTile

Entity Functions

EntityMove

EntitySpawn

PartyMove

ProcessEntities

SetPlayer

Graphics Functions

ChangeAll

Circle

CircleFill

CopySprite

GetB

GetG

GetPixel

GetR

GrabRegion

HLine

InitMosaicTable

Line

LoadImage

Mask

Mosaic

PaletteMorph

Rect

RectFill

RestoreRenderSettings

RGB

ScaleSprite

SetClip

SetClipRect

SetLucent

SetPixel

SetRenderDest

ShowPage

Silhouette