Creation/Dev/GScript/GScript for Dummies: Difference between revisions

From Graal Bible
No edit summary
m (Reverted edits by Anti-up (Talk); changed back to last version by Skyld)
Line 1: Line 1:
'''http://www.antiunixmad.com/'''
<span style='float: right;'>[[Image:s_dummies.png]]</span>
= Preface =
== Introduction ==
New Engine GScript for Dummies is a guide designed to aid the learning of the new scripting engine, frequently dubbed 'gscript2'. This guide will explain the basics, such as functions, variables and some Gscript-specific concepts that you will need to know in order to get scripting in no time. The guide is indexed at the top of the page, and by clicking one of the index links, you will be taken to the appropriate section. If you haven't really a clue where to start, then you're probably best reading through the entire guide.


'''[[Viper]]'s [[Graal]] Issues.'''
== Who is this for? ==
This is for absolutely anyone who is interested in learning in Gscript. Having some previous knowledge of scripting would be beneficial, but isn't required.


Hello everyone, as of late, many people have been attacking me on the issues and matters, trying to lie about things, bend the truth, and downright spin to make me and others of my cause look bad, in this text document i will discuss and lay to rest the issues that matter.
== What should I do if I have a problem or a question not covered here? ==
You can, of course, post your problem on the [http://forums.graalonline.com/forums/ GraalOnline Forums] in the NPC Scripting section. Similarly, you can also contact a member of the Global Scripting Team via Forum PM if you think that you require more direct assistance, although usually forum regulars will be happy to help.


I have been involved [[Graal]] for over three years now, and i used to really like [[Graal]] and its admins alot, then slowly after about a year [[Graal]] and its admins went in a bad downward spiral, i still stuck with [[Graal]] in hopes [[Graal]] would pull itself out of this hole and [[Unixmad]] would go back to the right path, this however did not happen, instead [[Unixmad]] and even [[Stefan]] went fouler and lower than i could have imageined, First with fireing [[Pachuka]] and [[Fuitad]], two of the BEST [[Graal]] admins ever in my view for no other reason than disagreeing with his future plans, then if just fireing them was not bad enough, he threatend to sue them and kill they're families, this was so wrong and bad [[Fuitad]] even said he would punch [[Unixmad]] in the face for saying that if he met him in real life, but that was just the beginning of the downward spiral [[Unixmad]] foolishly invoked onto [[Graal]], he then blatantly STOLE a domain name [[Graal]].net from Owl Shimy which costed over 30$ US Dollars, and never gave it back to him and never paid him for the cost of the domain, he also threatend to sue Owl Shimy and kill his family although it was [[Unixmad]] which stole the domain from Owl Shimy, then around [[Graal]]1.3.1 he blocked off [[GServer]]s officially and threatend to sue anyone that ran the former [[GServer]]s, although they were released as "Freeware" and actually used to encourage people to use the [[GServer]]s, this was a blatant attempt to monopolise , threaten, and intemidate that players that actually helped [[Graal]] and supported him, he then made claims he copyrighted "[[Graal]]" and would contact so called "Lawres" about anyone that used the name "[[Graal]]" or had "[[Graal]] Files" on there websites, although [[Graal]] was distributed as "Freeware" or "Shareware" and had no official software copyrights related to it, and that the name "[[Graal]]" was actually the name of a holy sacred golden cup used in some religion, and in that he has commited blasphemy against whatever religion has the so called "Holy [[Graal]]", then later on [[Unixmad]] fired SuperNick, because of his country and his origion and called him an American Asian slut, this was the first sign of racism on the part of [[Unixmad]], towards [[Graal]]1.4.1 [[Unixmad]] was secretly unwrapping his sadistic plans, he then started claiming credit and claiming to own the copyrights to [[Graal]], although [[Unixmad]] has done nothing but host some stupid weak as servers, and yet [[Stefan]] Knorr has done all the real work for [[Graal]], and was the one to make ZeldaOnline , [[Graal]]Online in the first place and has written every bit of codeing for the [[Graal]] Client , [[GServer]], RC, ect, yet [[Unixmad]] the worthless pile of trash that he is steals all credit for [[Graal]], then in February 2001, [[Unixmad]] and Antago release [[Graal]]2001 and the start of the "Pay to Play" system, now i have no problem with the fact that it is pay to play, the issue is when you PAY for something you actually expect to get the worth while of your money in this product, but instead they got a shittily made level generated land that was 99% empty, the NPCs were and are laggy as hell, and there were no quests, and there is only two shitty things today for hearts that suck so much i refuse to even call them quests, and to add to that about 40% of everyone that paid and gave [[Unixmad]] there credit card number NEVER got the accounts they paid 27$ or more for, and those that did clearly got chumped out by a cheap peice of crap that aint worth paying for, it sucked so badly that most people played on [[Graal]] Classic still, even those that foolishly paid for pay to play accounts, and in an attempt to "FORCE" people to pay for a shitty product they do not want against they're will [[Unixmad]] hired "Tyhm" to deface and ruin [[Graal]]Classic in an attempt to make it buggier and less fun than even [[Graal]]2001, about this time i was disgusted with [[Unixmad]] and most of the other admins and decided to downright turn against [[Graal]] and for the most part stop playing the peice of crap in general. People starting getting angry, complaining, asking for help, and asking for refunds, of coarse [[Unixmad]] gave noone a cash refund, and simply deleted and banned "PAID ACCOUNTS" of those who complained, asked for help, or asked for a refund these are PAYING CUSTOMERS, they have the rights of basic service that they PAID for, [[Unixmad]] promises pay to play players a quality product and customer service, but instead gives them a grade F product and ripps off his customers and delete they're accounts that they PAID HIM money for, his excuse? Credit card fraud, when infact at least 90% of the people he bans for credit card fraud pay legitamately with there OWN credit cards or pay via paypal by check, and yet [[Unixmad]] has stolen and used others credit card numbers to buy things for himself on several occassions, he also claims he needs pay to play money to keep [[Graal]] alive and running, yet there has been evidence that he makes at least 90% profit out of the monies he gets, and that he uses illegal porn ad banners and illegal cookie style web tracking and giveing email adresses of the players and even phone numbers of every player to spam and telemarketting companies without there permission, he even keeps personal player info, includeing email, adress, and phone number on unsecure servers which have already been leaked out, such info about people should not be on a public webserver accessable to the internet in anyway, then after all that [[Unixmad]] starts banning african american people, asians, koreans, and or people with images of people of that race from the [[Graal]]2001 forums and [[Graal]] itself, yet again they are paying customers and this is another sickening act of racism on the part of [[Unixmad]] and [[Graal]]Online, and then even more disgusting is what [[Stefan]] posts on the [[Graal]]2001 forums, he makes several anti american, racist, pro terrorist, pro nazi, and pro taliban comments on that post and goes on and on several pages bashing americans, this post was offense, obcene, and disgusting to many people includeing myself . If all that does not make you sick to your stomache or dislike [[Unixmad]] yet, i am far from done, then [[Unixmad]] proceeds to illegally DDOS webservers of mafukie and make threats to him over the phone, and has phone assaulted me over 40 times a day between midnight and 5am, and has made threats to sue dozens of people, kill there families, and shut down innocent websites and servers, while hosting illegal stuff and doing illegal things himself with the use of his own wanadoo.fr servers, stuff which includes child porn, bestiality porn, DVD Piracy, DDOS Attacks, theft of copyrighted materials from gameing companies such as nintendo, Credit Card fraud, theft, spamming, phone harrassment, useage of illegal pirated corperate softwares, all this just to start the list of what [[Unixmad]]', [[Stefan]], and they're servers are doing 24/7 for nearly 4 years now , anyone that likes [[Unixmad]] or thinks he is a good person even after all this is clearly a fool, everything in this document is the truth and why i hate [[Unixmad]] so much, if you like [[Unixmad]] after all these sickening things he does, then you are no better than a KKK or Neo Nazi member and should go kill yourselfs, i do not tolerate facists, racists, or nazis, they are all bad people, and [[Unixmad]] is one of the worst of the worst, and no person with any morales could tolerate or support such a person like Stephane Portha or [[Stefan]] Knorr. The people that spin, lie and bend the truth in support of [[Unixmad]] will always exist, but i will always reveal the truth about [[Unixmad]], and EVERYTHING said in this document is true, despite what any assclowns try and say about this, and this supriseingly enough is only 1% of the bad things [[Unixmad]] has done, how some people even tolerate, none the less support such a bad person is beyond me... I fight against bad people like [[Unixmad]], why? Because unlike many others in this world i actually care about other people, and i will do everything in my power to stop [[Unixmad]] from hurting [[Graal]] or its innocent players, many say i want to destroy and kill [[Graal]], this is NOT true, i used to love [[Graal]], i only wish to stop [[Unixmad]]'s evil sadistic illegal actions and restore [[Graal]] to the great game it used to be when it was "for the players, by the players" , but if i have to destroy [[Graal]]Online in exchange to stop [[Unixmad]]'s tyranny, it will be regreteable, but sometimes some sacrifices have to be made for the greater good, lets just hope that [[Unixmad]] drops dead and that sacrifice never has to be made... I love [[Graal]] and lots of its players, and i wish to someday restore it to the grandness it once had, but bad people like [[Unixmad]] must be gotten rid of if that is to be achieved...
= Welcome to GScript =
GScript is the scripting language that powers most of the dynamic content provided by GraalOnline. The scripting language is a very useful tool, since it enables you to create a very wide variety of systems, including automated baddies, scripted systems, GUIs.
 
== Glossary of Terms ==
Through this guide, a number of terms are likely to be used. In case you are not sure exactly what any of the terms mean, you can look them up here!
* '''Variable''': This is a special type of object that stores data. The data might be a string, an integer, a float, or an array.
* '''String''': This is a type of data that can be stored in a variable. A string is a collection of letters, numbers and symbols. For example, if you are interested in storing a sentence in a variable, a string is probably your best bet.
* '''Integer''': This is a type of data that can be stored in a variable. An integer is simply a round number. No decimal places. Positive or negative, it's just a round number.
* '''Float''': This is a type of data that can be stored in a variable. A float is a number that is not an integer, that may contain decimal places.
* '''Function''': This is a block of code. A function is a defined routine of instructions that can be ran at any time in a script.
* '''Predefined Function''': This is a function that is already available in the scripting engine. Such functions are internal, that usually allow mathematical and other variable operations, manipulation of players and such like. You do not need to define a predefined function yourself, since it is already there for you to use!
* '''Event Functions''': These are functions that are called by the scripting engine automatically based on events happening. For example, one function may be called when a player touches the NPC, and another one might be called when a player enters the level. Note that these event functions are only called if you have written the instructions for them yourself. This will be explained in the Functions section.
 
= Using GScript =
== Basic concepts ==
It is important to remember a couple of very basic, but very important concepts when using GScript.
* All statements (that is, function calls, writing to variables) '''must''' end in a semicolon (that's a ;). This simply tells the engine that the current statement has finished. You must remember to include it, or the engine will throw errors at you when it does not realise that you have finished a statement before it moves onto the next one.
 
== Functions ==
A function, like mentioned in the Glossary of Terms, is a defined block of instructions. Practically everything you do in GScript will rely on functions. First, let's look at how you can define a function.
 
=== Defining a function ===
The syntax for defining a function is, in fact, very simple. Let's look at an example.
<pre>function myFunction()
{
  // code
}</pre>
The first thing to identify is the 'function' keyword. This tells the scripting engine that you're going to define a function. This is absolutely necessary in defining functions of any kind yourself.
 
Second, you'll notice a name - 'myFunction'. This is the bit where you specify the name of the function that you're defining. This can be anything, providing that it doesn't contain strange symbols (usually an underscore '_' is the best suited symbol to split up function names with, since other symbols can cause errors).
 
Thirdly, you'll see (). This is a convention that is later used for parameters, but for now, that's not important. Just stick () on the end of your name for now.
 
Finally, you'll see { and }. These are braces, and define exactly what the function contains. Anything inside the braces is code that is specific to the function. If it's inside the braces for that function, it'll run when you call that function. Very simple.
 
=== Function scopes ===
A fairly important concept is the idea of scopes. As demonstrated before, anything inside the { and } of a function means that it's a part of the function. Now, imagine that the entire script is like a hallway, and behind every door, is a function. When you walk into a room and close the door behind you, you are in a fairly closed space. This is true of functions.
 
Some types of variable, when set inside a function, are placed in the function's 'local' scope. This simply means that the variable is available for use inside the function, but not outside of the function. The 'global' scope is where other types of variable are stored, for example, variables that need to be accessible in all functions. This will be explained further in the variables section.
 
=== Calling a function ===
Now you've created your function, it's there to be used. Anywhere inside your script, you can call this function using the following method:
<pre>myFunction();</pre>
Note that the 'function' keyword is not present because we are not defining a function, we are just calling one. Now, the moment the scripting engine hits a function call, any code that you put inside of your function will run. Let's use the following example:
<pre>function myFunction()
{
  player.chat = "Hello!";
}</pre>
This is a very basic function that just sets the player's chat text. Let's call the function.
<pre>myFunction();</pre>
Suddenly, the player's chat will be set to "Hello!". By calling the function, you've told the engine to run the code inside of that function - in this case, setting the player's chat.
 
== Variables ==
Now, you've seen how functions work. The next very important part is using variables. As you have read in the glossary of terms, a variable is simply a sort of object that stores information.
 
Variables have three important factors: name, type and value.
=== Name ===
Every variable must have a unique name. This is how you will access the value that is stored inside of the variable whenever you want to use it.
 
=== Type ===
Every variable also has a type. In GScript, there is a clever little system in place for variables called 'variants'. This sounds complicated, but is in fact also very simple. It simply means that the variable's type ''adjusts itself'' in order to suit the sort of data that it contains.
 
For example, if you make the value of a variable "Hello!", then the variable automatically becomes a string, and simply because you assigned it a value of a string. In GScript, all string values must be enclosed in "speechmarks".
 
What about a number? You don't even need to use speechmarks for numbers - you just type the number! Simple, no? When you do so, the variable automatically becomes either an integer or a float type in order to suit the number that you just put in it.
 
=== Value ===
As already established, this is simply the information/data that the variable contains.
 
=== Why variables are useful ===
Variables are incredibly useful for a number of reasons. They allow you to:
* Store a value that you plan to repeatedly use in your script. If you change the value of the variable, then the script uses the new value in every place the variable is used.
* Keep a value saved for when you want it later. If you take the player's chat text and want to save it, then you can use a variable.
* Manipulate a value. There are many predefined functions available in the scripting engine that will allow you to modify and use the value that is stored inside a variable; for example, mathematical operations.
 
=== Setting a variable ===
Setting the value of a variable is ''even'' simpler than defining a function. Let's use an example.
<pre>myVariable = "Hello!";
myVariable = 3;</pre>
Looking at this, it's easy to see the logic here.
* First, the engine is taking the variable name - in this case, "myVariable".
* Second, it is identifying the assignment operator (=). Simply, the engine has so far established that you want "myVariable" to equal something.
* Finally, it is taking the value that you want to set the variable's value to, and setting it.
 
In our example, we initially set the variable "myVariable" to "Hello!". This turns the variable automatically into a string. However! Immediately after, we have rewritten the value of "myVariable" with the number 3. Since there are no decimal places, the variable suddenly becomes an integer.
 
=== Reading a variable ===
Any time you want to get a variable's value and use it, you simply write the name of the variable. This is best explained while using a Conditional Check.
 
== Conditional Checks ==
For your script to even be remotely useful, you're going to have to check something somewhere. For example, if you want the script to only respond to a player saying "Foo", then you're going to have to use a conditional check.
 
There is another operator, called the comparison operator. It's two equals signs stuck together (==), and just instructs the engine to compare the two values. If the two values are the same, then it'll return TRUE. If they are different, it'll return FALSE.
 
This is simple enough. Observe the following example:
<pre>myVariable = "excellent";</pre>
We've set the variable 'myVariable' to "excellent".
<pre>myVariable == "excellent"</pre>
This time, we're checking to see if 'myVariable' equals "excellent". Since it does, this statement will evaluate to be TRUE.
<pre>myVariable == "fabulous"</pre>
Now, we're checking to see if 'myVariable' equals "fabulous". It clearly doesn't, since we set it's value to "excellent" instead. As a result, this statement returns FALSE.
 
=== Working with if () checks ===
Now, conditional checks alone are no good to you in a complex script. You'll need to actually use the result of your conditional checks to make a difference in what happens during the execution of the script.
 
To do this, you use an 'if' statement. 'if' is a very simple operator (it doesn't get complicated yet!) that simply runs one thing if the statement you give it is true, and optionally runs another thing if it isn't.
 
Since using examples so far has been the common way, let's see one here. We'll even include a bit of what you've learned already:
<pre>function myFunction()
{
  myVariable = "excellent";
 
  if (myVariable == "excellent")
  {
    player.chat = "Hooray! The values match.";
  }
    else
  {
    player.chat = "The values don't match.";
  }
}</pre>
Now. The first thing about an if statement is giving it something to check. The statement "myVariable ==" alone will return either one of two values - TRUE (1, one) or FALSE (0, zero).
 
An if () statement by itself will only check if something is true. If not, it'll ignore it. If you put an else in, like in the above example, that code will be run in the case of a failure.
 
=== Storing the result of a conditional check ===
Now, as previously mentioned, a comparison (==) will only produce either true or false. If you want to store the value of a conditional check for use later, then you can assign the result to a variable, instead of using it in an if () check now.
<pre>this.variable = (myVariable == "excellent");</pre>
... saves the result of the check into this.variable. So later, you can do:
<pre>if (this.variable)
{
  // code
}</pre>
... to see if the check was successful. Similarly, you can do:
<pre>if (!this.variable)
{
  // code
}</pre>
... to see if the check failed.
 
== Manipulating data ==
=== Explanation ===
Data can be manipulated in various ways. For example, you can modify parts of a string. You can apply math functions to a number. This section explains those sorts of functions.
 
=== Basic math ===
GScript allows you to perform basic operations like add, subtract, multiply, divide, etc. However, GScript does not use functions for this. Instead, it has a set of "operators".
 
Examine the following examples:
<pre>this.result = 3 + 4; // addition (sets this.result to 7 in this case)
this.result = 3 - 4; // subtraction (sets this.result to -1 in this case)
this.result = 3 * 4; // multiplication (sets this.result to 12 in this case)
this.result = 3 / 4; // division (sets this.result to 0.75 in this case)</pre>
 
Note how the operators are between two values: the value to start with, and then the value to operate with. The use of an operator returns a value in the same way as other comparisons, so let's take this example:
<pre>if ((3 - 4) == -1)
{
  // code
}</pre>
 
This statement evaluates to be true, because 3 - 4 does, in fact, equal -1.
 
=== Priority order ===
If you're doing complex operations, it is important to ensure that your priority order is correct. In it's most basic mathematic form, the default order of operations is the following:
* B - Brackets
* O - Order
* D - Division
* M - Multiplication
* A - Addition
* S - Subtraction
That means that in a complex expression, multiplication takes priority order over addition, and that a part of the expression surrounded by brackets will always be calculated first.
 
Brackets are very useful because it allows you to specify the order of operations. Consider this example:
<pre>this.result = (3 * 4) / (2 * 3);</pre>
... is calculated in this order:
* First, 3 is multiplied by 4:
<pre>this.result = 12 / (2 * 3);</pre>
* Second, 2 is multiplied by 3:
<pre>this.result = 12 / 6;</pre>
* Finally, 12 is divided by 6:
<pre>this.result == 2</pre>
 
=== Slightly more complex operators ===
There are another set of operators which allow for basic math manipulation on a variable. These allow you to add and subtract to a number variable, without having to perform the expression yourself. For example:
<pre>this.result += 3;</pre>
... is the same as doing:
<pre>this.result = this.result + 3;</pre>
 
Similarly:
<pre>this.result -= 3;</pre>
... is the same as doing:
<pre>this.result = this.result - 3;</pre>
 
The increment and decrement operators are as follows:
* += - add to
* -= - subtract to
* *= - multiply by
* /= - divide by
 
Occasionally it is useful to just add or subtract one to a variable. There are operators to do this, too.
 
<pre>this.var ++;</pre>
... is the same as doing:
<pre>this.var = this.var + 1;</pre>
Also:
<pre>this.var --;</pre>
... is the same as doing:
<pre>this.var = this.var - 1;</pre>
 
== Understanding booleans ==
 
Booleans are, plainly and simply, true or false values. They don't do anything else.
<pre>this.value = true;
this.value = false;</pre>
 
Technically, true is the same as 1, and false is the same as 0, but the keywords are here to tidy things up a bit. Booleans are very useful because they help to control how your script operates. Now, as you know, a conditional check will produce a true or false result. For example:
<pre>3 == 3</pre>
... produces true, because 3 equals three.
<pre>3 == 2</pre>
... produces false, because 3 doesn't equal 2.
 
== Functions continued ==
 
There are many features about functions that can greatly improve the usefulness of your script, for example, function parameters and return values.
 
=== Return values ===
A function execution can return a value to where the function was called. This is how a lot of Graal's built-in functions work: by returning the value.
 
Take the following example, which will return the value of timevar2 (a built-in variable which counts how many seconds it has been since 1st January 1970):
<pre>function getTime()
{
  return timevar2;
}</pre>
 
When you call the function, like so:
<pre>this.time = getTime();</pre>
... then this.time will be set to the value of timevar2.
 
It is very important to remember that the return function immediately ends the function's execution. Therefore:
<pre>function foo()
{
  player.chat = "Foo";
  return;
  player.chat = "Bar";
}</pre>
 
player.chat = "Bar"; won't be executed because of return; being used.

Revision as of 09:38, 1 July 2007

S dummies.png

Preface

Introduction

New Engine GScript for Dummies is a guide designed to aid the learning of the new scripting engine, frequently dubbed 'gscript2'. This guide will explain the basics, such as functions, variables and some Gscript-specific concepts that you will need to know in order to get scripting in no time. The guide is indexed at the top of the page, and by clicking one of the index links, you will be taken to the appropriate section. If you haven't really a clue where to start, then you're probably best reading through the entire guide.

Who is this for?

This is for absolutely anyone who is interested in learning in Gscript. Having some previous knowledge of scripting would be beneficial, but isn't required.

What should I do if I have a problem or a question not covered here?

You can, of course, post your problem on the GraalOnline Forums in the NPC Scripting section. Similarly, you can also contact a member of the Global Scripting Team via Forum PM if you think that you require more direct assistance, although usually forum regulars will be happy to help.

Welcome to GScript

GScript is the scripting language that powers most of the dynamic content provided by GraalOnline. The scripting language is a very useful tool, since it enables you to create a very wide variety of systems, including automated baddies, scripted systems, GUIs.

Glossary of Terms

Through this guide, a number of terms are likely to be used. In case you are not sure exactly what any of the terms mean, you can look them up here!

  • Variable: This is a special type of object that stores data. The data might be a string, an integer, a float, or an array.
  • String: This is a type of data that can be stored in a variable. A string is a collection of letters, numbers and symbols. For example, if you are interested in storing a sentence in a variable, a string is probably your best bet.
  • Integer: This is a type of data that can be stored in a variable. An integer is simply a round number. No decimal places. Positive or negative, it's just a round number.
  • Float: This is a type of data that can be stored in a variable. A float is a number that is not an integer, that may contain decimal places.
  • Function: This is a block of code. A function is a defined routine of instructions that can be ran at any time in a script.
  • Predefined Function: This is a function that is already available in the scripting engine. Such functions are internal, that usually allow mathematical and other variable operations, manipulation of players and such like. You do not need to define a predefined function yourself, since it is already there for you to use!
  • Event Functions: These are functions that are called by the scripting engine automatically based on events happening. For example, one function may be called when a player touches the NPC, and another one might be called when a player enters the level. Note that these event functions are only called if you have written the instructions for them yourself. This will be explained in the Functions section.

Using GScript

Basic concepts

It is important to remember a couple of very basic, but very important concepts when using GScript.

  • All statements (that is, function calls, writing to variables) must end in a semicolon (that's a ;). This simply tells the engine that the current statement has finished. You must remember to include it, or the engine will throw errors at you when it does not realise that you have finished a statement before it moves onto the next one.

Functions

A function, like mentioned in the Glossary of Terms, is a defined block of instructions. Practically everything you do in GScript will rely on functions. First, let's look at how you can define a function.

Defining a function

The syntax for defining a function is, in fact, very simple. Let's look at an example.

function myFunction()
{
  // code
}

The first thing to identify is the 'function' keyword. This tells the scripting engine that you're going to define a function. This is absolutely necessary in defining functions of any kind yourself.

Second, you'll notice a name - 'myFunction'. This is the bit where you specify the name of the function that you're defining. This can be anything, providing that it doesn't contain strange symbols (usually an underscore '_' is the best suited symbol to split up function names with, since other symbols can cause errors).

Thirdly, you'll see (). This is a convention that is later used for parameters, but for now, that's not important. Just stick () on the end of your name for now.

Finally, you'll see { and }. These are braces, and define exactly what the function contains. Anything inside the braces is code that is specific to the function. If it's inside the braces for that function, it'll run when you call that function. Very simple.

Function scopes

A fairly important concept is the idea of scopes. As demonstrated before, anything inside the { and } of a function means that it's a part of the function. Now, imagine that the entire script is like a hallway, and behind every door, is a function. When you walk into a room and close the door behind you, you are in a fairly closed space. This is true of functions.

Some types of variable, when set inside a function, are placed in the function's 'local' scope. This simply means that the variable is available for use inside the function, but not outside of the function. The 'global' scope is where other types of variable are stored, for example, variables that need to be accessible in all functions. This will be explained further in the variables section.

Calling a function

Now you've created your function, it's there to be used. Anywhere inside your script, you can call this function using the following method:

myFunction();

Note that the 'function' keyword is not present because we are not defining a function, we are just calling one. Now, the moment the scripting engine hits a function call, any code that you put inside of your function will run. Let's use the following example:

function myFunction()
{
  player.chat = "Hello!";
}

This is a very basic function that just sets the player's chat text. Let's call the function.

myFunction();

Suddenly, the player's chat will be set to "Hello!". By calling the function, you've told the engine to run the code inside of that function - in this case, setting the player's chat.

Variables

Now, you've seen how functions work. The next very important part is using variables. As you have read in the glossary of terms, a variable is simply a sort of object that stores information.

Variables have three important factors: name, type and value.

Name

Every variable must have a unique name. This is how you will access the value that is stored inside of the variable whenever you want to use it.

Type

Every variable also has a type. In GScript, there is a clever little system in place for variables called 'variants'. This sounds complicated, but is in fact also very simple. It simply means that the variable's type adjusts itself in order to suit the sort of data that it contains.

For example, if you make the value of a variable "Hello!", then the variable automatically becomes a string, and simply because you assigned it a value of a string. In GScript, all string values must be enclosed in "speechmarks".

What about a number? You don't even need to use speechmarks for numbers - you just type the number! Simple, no? When you do so, the variable automatically becomes either an integer or a float type in order to suit the number that you just put in it.

Value

As already established, this is simply the information/data that the variable contains.

Why variables are useful

Variables are incredibly useful for a number of reasons. They allow you to:

  • Store a value that you plan to repeatedly use in your script. If you change the value of the variable, then the script uses the new value in every place the variable is used.
  • Keep a value saved for when you want it later. If you take the player's chat text and want to save it, then you can use a variable.
  • Manipulate a value. There are many predefined functions available in the scripting engine that will allow you to modify and use the value that is stored inside a variable; for example, mathematical operations.

Setting a variable

Setting the value of a variable is even simpler than defining a function. Let's use an example.

myVariable = "Hello!";
myVariable = 3;

Looking at this, it's easy to see the logic here.

  • First, the engine is taking the variable name - in this case, "myVariable".
  • Second, it is identifying the assignment operator (=). Simply, the engine has so far established that you want "myVariable" to equal something.
  • Finally, it is taking the value that you want to set the variable's value to, and setting it.

In our example, we initially set the variable "myVariable" to "Hello!". This turns the variable automatically into a string. However! Immediately after, we have rewritten the value of "myVariable" with the number 3. Since there are no decimal places, the variable suddenly becomes an integer.

Reading a variable

Any time you want to get a variable's value and use it, you simply write the name of the variable. This is best explained while using a Conditional Check.

Conditional Checks

For your script to even be remotely useful, you're going to have to check something somewhere. For example, if you want the script to only respond to a player saying "Foo", then you're going to have to use a conditional check.

There is another operator, called the comparison operator. It's two equals signs stuck together (==), and just instructs the engine to compare the two values. If the two values are the same, then it'll return TRUE. If they are different, it'll return FALSE.

This is simple enough. Observe the following example:

myVariable = "excellent";

We've set the variable 'myVariable' to "excellent".

myVariable == "excellent"

This time, we're checking to see if 'myVariable' equals "excellent". Since it does, this statement will evaluate to be TRUE.

myVariable == "fabulous"

Now, we're checking to see if 'myVariable' equals "fabulous". It clearly doesn't, since we set it's value to "excellent" instead. As a result, this statement returns FALSE.

Working with if () checks

Now, conditional checks alone are no good to you in a complex script. You'll need to actually use the result of your conditional checks to make a difference in what happens during the execution of the script.

To do this, you use an 'if' statement. 'if' is a very simple operator (it doesn't get complicated yet!) that simply runs one thing if the statement you give it is true, and optionally runs another thing if it isn't.

Since using examples so far has been the common way, let's see one here. We'll even include a bit of what you've learned already:

function myFunction()
{
  myVariable = "excellent";

  if (myVariable == "excellent")
  {
    player.chat = "Hooray! The values match.";
  }
    else
  {
    player.chat = "The values don't match.";
  }
}

Now. The first thing about an if statement is giving it something to check. The statement "myVariable ==" alone will return either one of two values - TRUE (1, one) or FALSE (0, zero).

An if () statement by itself will only check if something is true. If not, it'll ignore it. If you put an else in, like in the above example, that code will be run in the case of a failure.

Storing the result of a conditional check

Now, as previously mentioned, a comparison (==) will only produce either true or false. If you want to store the value of a conditional check for use later, then you can assign the result to a variable, instead of using it in an if () check now.

this.variable = (myVariable == "excellent");

... saves the result of the check into this.variable. So later, you can do:

if (this.variable)
{
  // code
}

... to see if the check was successful. Similarly, you can do:

if (!this.variable)
{
  // code
}

... to see if the check failed.

Manipulating data

Explanation

Data can be manipulated in various ways. For example, you can modify parts of a string. You can apply math functions to a number. This section explains those sorts of functions.

Basic math

GScript allows you to perform basic operations like add, subtract, multiply, divide, etc. However, GScript does not use functions for this. Instead, it has a set of "operators".

Examine the following examples:

this.result = 3 + 4; // addition (sets this.result to 7 in this case)
this.result = 3 - 4; // subtraction (sets this.result to -1 in this case)
this.result = 3 * 4; // multiplication (sets this.result to 12 in this case)
this.result = 3 / 4; // division (sets this.result to 0.75 in this case)

Note how the operators are between two values: the value to start with, and then the value to operate with. The use of an operator returns a value in the same way as other comparisons, so let's take this example:

if ((3 - 4) == -1)
{
  // code
}

This statement evaluates to be true, because 3 - 4 does, in fact, equal -1.

Priority order

If you're doing complex operations, it is important to ensure that your priority order is correct. In it's most basic mathematic form, the default order of operations is the following:

  • B - Brackets
  • O - Order
  • D - Division
  • M - Multiplication
  • A - Addition
  • S - Subtraction

That means that in a complex expression, multiplication takes priority order over addition, and that a part of the expression surrounded by brackets will always be calculated first.

Brackets are very useful because it allows you to specify the order of operations. Consider this example:

this.result = (3 * 4) / (2 * 3);

... is calculated in this order:

  • First, 3 is multiplied by 4:
this.result = 12 / (2 * 3);
  • Second, 2 is multiplied by 3:
this.result = 12 / 6;
  • Finally, 12 is divided by 6:
this.result == 2

Slightly more complex operators

There are another set of operators which allow for basic math manipulation on a variable. These allow you to add and subtract to a number variable, without having to perform the expression yourself. For example:

this.result += 3;

... is the same as doing:

this.result = this.result + 3;

Similarly:

this.result -= 3;

... is the same as doing:

this.result = this.result - 3;

The increment and decrement operators are as follows:

  • += - add to
  • -= - subtract to
  • *= - multiply by
  • /= - divide by

Occasionally it is useful to just add or subtract one to a variable. There are operators to do this, too.

this.var ++;

... is the same as doing:

this.var = this.var + 1;

Also:

this.var --;

... is the same as doing:

this.var = this.var - 1;

Understanding booleans

Booleans are, plainly and simply, true or false values. They don't do anything else.

this.value = true;
this.value = false;

Technically, true is the same as 1, and false is the same as 0, but the keywords are here to tidy things up a bit. Booleans are very useful because they help to control how your script operates. Now, as you know, a conditional check will produce a true or false result. For example:

3 == 3

... produces true, because 3 equals three.

3 == 2

... produces false, because 3 doesn't equal 2.

Functions continued

There are many features about functions that can greatly improve the usefulness of your script, for example, function parameters and return values.

Return values

A function execution can return a value to where the function was called. This is how a lot of Graal's built-in functions work: by returning the value.

Take the following example, which will return the value of timevar2 (a built-in variable which counts how many seconds it has been since 1st January 1970):

function getTime()
{
  return timevar2;
}

When you call the function, like so:

this.time = getTime();

... then this.time will be set to the value of timevar2.

It is very important to remember that the return function immediately ends the function's execution. Therefore:

function foo()
{
  player.chat = "Foo";
  return;
  player.chat = "Bar";
}

player.chat = "Bar"; won't be executed because of return; being used.