Table of Contents

1. Dedication
2. Introduction
3. Variables
1. Integers
2. Fixed-point
3. Strings
4. Arrays
5. Structs
4. Language Specification
1. basic syntax
2. Operators
3. Comments
4. preprocessor directives
5. control structures
6. functions
7. system and map code
8. DMA
5. Engine
1. verge.cfg options
2. changelog
3. planned features
4. known issues
6. Function Reference
1. General Utility Functions
2. String Functions
3. Map Functions
4. Entity Functions
5. Graphics Functions
6. Sprite Functions
7. Sound/Music Functions
8. Font Functions
9. Math Functions
10. File Functions
11. Window Managment Functions
12. Movie Playback Functions
13. Netcode Functions
7. Global Variables
1. General System Variables
2. Mouse Variables
3. Joystick Variables
4. Entity Variables
5. Sprite Variables
6. Camera Variables
7. Map Variables
8. Layer Variables
9. Event Variables
10. Date/Time Variables
8. Built-in Defines
1. Version
2. Scan Codes
3. Color Filters
9. Appendix
1. history of verge
2. archived related sites
10. Credits
11. Colophon

1. Dedication

   

   For Sully

   VERGE is dedicated to erudite marine life everywhere.
   
   
2. 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.

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

   
   
1. 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.
   
   
2. 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!

   
   
3. 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.
   
   
4. 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!
   

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

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

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

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

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

   1. 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);
      }
      

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

   
   
4. 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];
   
   
   
   
5. control structures

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

   1. 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)
      }
      

   2. 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.","","");
      }
      

   3. 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)+".");
      }
      

   4. 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.
   
   
6. 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 */
   }
   

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

Description:

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)

Description:

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)

Description:

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);




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

Description:

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)

Description:

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)

Description:

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);




1. 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.
   
   
2. 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. ^_^
   
   

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

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

   
   
6. Function Reference
   
   
1. General Utility Functions

   For the General System Variables, go [here].
   
   

void CallFunction (string funcname)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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 ()

Description:

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




2. String Functions
   
   

string chr (int ascii)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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.




3. Map Functions
   
   

int GetObs (int x, int y)

Description:

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)

Description:

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)

Description:

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)

Description:

Find index of zone at tile coords

Documentation:

Find index of zone at tile coords x,y.

Example Usage:

none





void Map (string mapname)

Description:

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 ()

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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.




4. Entity Functions

   For the corresponding Entity variables go here

   
   

void ChangeCHR (int entity, string chr)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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);




5. Graphics Functions
   
   

void AdditiveBlit (int x, int y, int sourceimage, int destimage)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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 ()

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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 ()

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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);




6. Sprite Functions

   For the corresponding sprite variables go

   Sound/Music Functions

   
   

void FreeSong (int h)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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 ()

Description:

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)

Description:

Stop playing a song

Documentation:

Stop playing song 'h'

Example Usage:

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





void StopSound (int chan)

Description:

stops playing a sound

Documentation:

stops playing sound 'chan'

Example Usage:

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




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

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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!");




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

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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);




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

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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)

Description:

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




10. Window Managment Functions
    
    

void WindowClose (int w)

Description:

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)

Description:

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)

Description:

NODE

Documentation:

NODE

Example Usage:

NODE





int WindowGetImage (int w)

Description:

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)

Description:

NODE

Documentation:

NODE

Example Usage:

NODE





int WindowGetXRes (int window)

Description:

NODE

Documentation:

NODE

Example Usage:

NODE





int WindowGetYRes (int window)

Description:

NODE

Documentation:

NODE

Example Usage:

NODE





void WindowHide (int w)

Description:

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)

Description:

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)

Description:

NODE

Documentation:

NODE

Example Usage:

NODE





void WindowSetTitle (int w, string title)

Description:

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)

Description:

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!




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

Description:

NODE

Documentation:

NODE

Example Usage:

NODE




12. Netcode Functions
    
    

int Connect (string hostname)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int GetConnection ()

Description:

Nodeshell

Documentation:

Nodeshell

Example Usage:

Nodeshell





int GetUrlImage (string url)

Description:

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)

Description:

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)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketConnected (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





string SocketGetFile (int socket, string ovfname)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketGetInt (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketGetString (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketHasData (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





void SocketSendFile (int socket, string fname)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





void SocketSendInt (int socket, int i)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





void SocketSendString (int socket, string str)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL




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

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int GetConnection ()

Description:

Nodeshell

Documentation:

Nodeshell

Example Usage:

Nodeshell





int GetUrlImage (string url)

Description:

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)

Description:

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)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketConnected (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





string SocketGetFile (int socket, string ovfname)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketGetInt (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketGetString (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





int SocketHasData (int socket)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





void SocketSendFile (int socket, string fname)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





void SocketSendInt (int socket, int i)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL





void SocketSendString (int socket, string str)

Description:

NODESHELL

Documentation:

NODESHELL

Example Usage:

NODESHELL




1. 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
   
   
2. 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.
   
   
3. 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)

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

   
   
5. 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
   
   
6. 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?).

   
   
7. 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
   
   
8. 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.
   
   
   
9. 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.
   
   
10. 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

    
    
8. Built-in Defines

   For information on the nature of the built-in defines, read the Preprocessor directives section of the manual.
   
   
1. 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
   
   
2. 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" }
   
   
   
3. 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.
   
   
9. Appendix
   
   
1. history of verge

   1. Verge
   2. Verge2
   3. Much lameness
   4. Verge3
   

   
   
10. Credits
    
    
11. 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.