Graal Bible - User contributions [en]

Template:Playerworld Administration Team

2011-01-04T01:17:18Z

Twinny:

[[Category:Administration]][[Category:Global Staff]]
* [[User:Tigairius|Tig]]
**[http://forums.graalonline.com/forums/private.php?do=newpm&u=5380 Forum PM: Tigairius]
** AIM: Tigairius
** E-mail: [mailto:Tig@graalonline.com Tig@graalonline.com]
* [[User:Xor|Xor]]
**[http://forums.graalonline.com/forums/private.php?do=newpm&u=6109 Forum PM: Xor]
** E-mail: [mailto:xor@graalonline.com xor@graalonline.com]
* [[User:benpoke103|Ben]]
**[http://forums.graalonline.com/forums/private.php?do=newpm&u=1901 Forum PM: benpoke103]
** E-mail: [mailto:ben@graalonline.com ben@graalonline.com]
* [[User:Twinny|Twinny]]
**[http://forums.graalonline.com/forums/private.php?do=newpm&u=4853 Forum PM: Twinny]
** E-mail: [mailto:twinny@graalonline.com twinny@graalonline.com]

You can also contact the Playerworld Administration Team via [mailto:accounts@graalonline.com accounts@graalonline.com] and [mailto:support@graalonline.com support@graalonline.com].

Creation/Dev/Excalibur's scripting guide

2007-07-01T07:56:24Z

Twinny:

== '''Excalibur's Scripting Guide''' ==
I'm hoping this allows people to learn how to script a bit easier, I believe all staff should know some scripting basics, and I find other GS2 guides hard to follow. This should help you get started out. I'm afraid it isn't complete and there are a few typos in it. I'm working on it.

Starting:

Level NPCs:

A level NPC is an npc that functions in a specific level. These are the most common on most servers. They are also a very important part of developement.

A script:
<pre>
//this is a note
/*

this is also a note, these help make scripts more clear
this type of note can go on as longe as it's inclosed
*/
//#CLIENTSIDE
//This tells the computer that the following
//script will be on the players client,
//as opposed to the server, this is very important.
function onPlayerTouchsMe()
//this checks if the player has touched the NPC
{ // starting bracket
this.chat = "Hey!"; //displays a message above the NPC
}//closing bracket
</pre>
The above script checks to see if the event, playertouchsme is true, then acts on what is in the bracket. It is important to include this clientside, because too many serverside scripts can cause problems for an NPC server, however they are more secure. If you wanted to do the last script serverside, you would omit the //#CLIENTSIDE , and add the shape to the NPC:
<pre>
function onCreated()
{
setshape(1,32,32);
setimg("block.png");
//img can also be done in the box above the script
}
function onPlayertouchsme()
{
this.chat = "You made a serverside script!";
}
</pre>
This takes a bit longer than clientside commands, and it takes up serverside script time, however, for secure actions, it may be necessary.
A secure script example:
<pre>
function onCreated()
{
this.account="Excaliber7388";
setshape(1,32,32);
this.chat="Excaliber's Chest";
}
function onPlayertouchsme()
{
if(player.account==this.account)
{
this.chat="This is a secure message!";
}
}
</pre>
First, I would like to quickly point out the 'if' statement. Some guides go into this a lot, but it's actually quite simple. The if statement is a very important part of scripting. It's what allows the NPC to make choices. The code withing the brackets of an if statement will only execute if the statement is true. Also, there is a catchall statement you can use, else. If the if statement is not true, the else will exectue it's script, other wise it is ignored.
Example:
<pre>
//#CLIENTSIDE
function onCreated()
{
this.a=1;
}
if(this.a==1)
//always use '==' for comparasons, NEVER just '=' as '=' is for assignments
{
this.b=2;
}
else if(this.a==2) //will only execute if first is false, AND this.a==2
{
this.b=3;
}
else //catch all if above 2 statements are false
{
this.b=4;
}
</pre>
Now, in the above example, this.b will always be 2, however, it's the format that's important.
<pre>
if(statement)
else if(statement)
else if(statement //may be used many times
else //catch all
</pre>
Now, back to serverside and clientside scripts:
By putting the checks on serverside, you disable a hackers ability to send an action from their client. So, this script is much more secure, and can only be accessed by the specified account (Excaliber7388 in this case). Most playerworlds and classic servers do these checks serverside as well, but we also apply a different method, to avoid having too much serverside script time:
<pre>
function onCreated()
{
this.account="Excaliber7388";
setshape 1,32,32;
this.chat="Excaliber's Chest";
}
function onActiontouched()
{
if(player.account==this.account)
{
this.chat="Yup, this is still secure, yay!";
}
}
//#CLIENTSIDE
function onPlayertouchsme()
{
triggeraction(x,y,"Touched","Touched");//no params needed
}
</pre>
This script will take up more time, but the playertouchsme check is clientside. Would this help much? Probably not, in fact, sending the action in this case would probably create more lag than having the script serverside. However, if a large portion of the script is serverside, and can be moved to clientside without risking security, it may be a good idea.
Serverisde timeouts=bad idea.
You shouldn't send to many actions to serverside, especially if you do so quickly. You should always limit the serverside timeouts, and the amount of time between actions to the server from client should be spaced out. Also, you should never have a timeout shorter than .05 on serverside, though it is possible, please do not do it. Many playerworlds have expierenced problems from serverside timeouts which can lead to NPC server crashing or lagging.

Here are two examples of serverside scripts, the first is [b]VERY[/b] bad, the second is more productive:
<pre>
function onCreated()
{
setshape 1,32,32;
}
function onActiontime()
{
for(server.i=0;server.i<5;server.i++)
//WHY use server for this???
//for loops, use this. it works only for this NPC
{
sleep(.01);
//WAY to short of a sleep time for the server
}
server.time+=.1;
}
//#CLIENTSIDE
function onCreated()
{
settimer(.05); //minimum clientside timeout
}
function onTimeout()
{
trigegraction(x,y,"time","time");
settimer(.05);
//Will cause a loop through the timeout, sending action
//to serverside TOO quickly, AND while the server is
//still working on the last action. This WILL cause the
//server to crash.
}
</pre>
If you put the above script on a server, say goodbye to your NPC server, because it will crach pretty quickly!
A better version:
<pre>function onCreated()
{
setshape 1,32,32;
//setshape is needed for all level NPCs triggeractions
//this sets it to a square of tiles 32x32 pixels.
}
function onActiontime()
{
server.time++;
//no need for incredible accuracy
}
//#CLIENTSIDE
function onCreated()
{
settimer(1);
}
function onTimeout()
{
triggeraction(x,y,"time","time");
settimer(1);
}
</pre>
This will execute the script less often, however, it still is an unlimited loop. Don't have too many of these NPCs, or you could have problems!

Now, you may have noticed this line in the bad script:
<pre>
for(server.i=0;server.i<5;server.i++)
</pre>
This is a 'for' loop. There are many types of loops, however the for loop isn't the easiest to learn first. Therefore, I will show you the 'while loop' first.
The while loop executes whatever is held within it's brackets as long as the statement within it is true. The while loop is just like an if statement, but you cannot use else with a with statement.
format:
<pre>
while(statments)
{
//commands
}
//if statment is still true, it will loop
</pre>
here's a script example:
<pre>
//#CLIENTSIDE
function onCreated()
{
this.size=10;
}
while(this.size<=20) //while this.size is less than or equal to 20
{
this.chat="The fish was " @this.size@ " centimeters long!";
//as the story is retold....
sleep(.5);
this.size=this.size+1;
//increment the size
}
</pre>
The above script will run through the loop until this.size is equal or greater than 20.
Some important things to know:
<pre>
if(a==b) means if a is equal to b
if(a<b) means if a is less than b
if(a>b) means if a is greater than b
if(a<=b) means if a is less than or equal to be
if(a>=b) means if a is greater than or equal to be
a++ is the same as a=a+1
a-- is the same as a=a-1
a+=b means a=a+b
a-=b means a=a-b
a*=b means a=a*b (multiplied by b)
a/=b means a=a/b
++a is just like a, but it will add to a before anything else in the line,
this is not important to know now
--a just like ++a, but with subtraction
a%b Modulus, basically, its a/b and th remainder is the output
for example 10%3=1
</pre>
These may be helpfull in loops, or in any other rational expressions you may use. (Well, it's important for all scripting!)
Now, recall this line:
<pre>
this.chat="The fish was " @this.size@ " centimeters long!";
</pre>
The output for this is: The fish was (size here) centimeters long!
The script NEEDS to know where a variable is, so if you want to put it in between a string you surround it with the '@' symbol. Or if it's at the end, you only put the '@' at the beggining of the variable. The variable and the '@' do NOT go in the quotes. Example:
<pre>
//#CLIENTSIDE
function onPlayertouchsme()
{
this.chat="Well hi there, " @player.account@ " I like your sword, " @player.swordimg;
}
</pre>
This would display the player's account, and sword image.

Now, back to the 'for' loop.
This a very interesting loop it's format is as follows:
<pre>
for(command;expression;command)
{
}
</pre>
Here's an example:
<pre>
//#CLIENTSIDE
function onPlayertouchsme()
{
for(this.i=0;this.i<10;this.i++)
{
this.chat="Loops: " @this.i;
sleep(.5);
}
}
</pre>
This loop would be activated when the player touchs it.
It would go through 10 loops, displaying the count, and taking .5 seconds for each loop (due to the sleep() command)
Now remember this while loop?
<pre>
function onCreated()
{
this.size=10;
}
while(this.size<=20)
{
this.chat="The fish was " @this.size@ " centimeters long!";
//as the story is retold....
sleep(.5);
this.size=this.size+1;
//increment the size
}
</pre>
There's an easier way of doing it with a for loop, in fact all loops done with while can be replaced by for.
<pre>
for(this.size=10;this.size<=20;this.size++)
{
this.chat="The fish was " @this.size@ " centimeters long!";
sleep(.5);
}
</pre>
See? Much shorter and easier to use!
Once you know the format of a for loop, you can make longer and more complex loops as well, and they'll take less time to script, which is always a bonus.

Some more detail on actions:
An action is an effective way to use a portion of script more than once, have one script act on another script, more script to serverside from clientside (and the other way) and more.
So how do you use them? Here's the format:
<pre>
triggeraction(x,y,"params[0]","params[1]");
</pre>
You must have two parameters, but you can have as many as you want a quick example:
<pre>
function onCreated()
{
setshape 1,32,32;
}
function onActiontrigger()
{
player.chat="Account: " @params[1]@ " Sword " @params[2]@ " head: " @params[3];
}
//#CLIENTSIDE
function onPlayerchats()
{
if(player.chat=="Who am I?") //amnesia? multiple identities?
{
triggeraction(x,y,"trigger",player.account,player.swordimg,player.headimg);
}
}
</pre>
See? You can make more than one parameter.
Now, there are a few differences between a level NPC with a triggeraction, and a weapon with a triggeraction. Weapons need their location (serverside or clientside) as the first parameter, params[0] is the one after it. Here, you can have just one parameter, and the x and y is always 0 (because the npc server is at 0,0), and you need to include the name of the weapon in the action.
here's an example:
<pre>
//weapon script with a triggeraction
//Weapon name: Fire Ball
function onActionserverside()
{
if(params[0]=="mp")
{
playermp-=10
}
}
//#CLIENTSIDE
function onWeaponfired()
{
if(playermp>=10)
{
shootfireball(playerdir);
triggeraction(0,0,"serverside","Fireball","mp");
}
else
{
player.chat="Not enough mp!";
}
}
</pre>
This nifty little weapon will cost 10 mp per use, and fires a fireball in the direction the player is facing. Hopefully, you can learn to make many weapons of your own!
Triggeractions can be used in shops as well (and these are the scripts people ask for the most).
<pre>
//a shop script, yay!
function onCreated()
{
setshape 1,32,32;
}
function onActionbuy()
{
if(playerrupees>=100)
{
addweapon Fire Ball;
playerrupees-=100;
}
}
//#CLIENTSIDE
function onPlayerchats()
{
if(player.chat=="buy fire ball")
{
triggeraction(x,y,"buy","buy");
//the level npc triggeraction type
}
}
</pre>
There, now you can make a little shop that sells a Fire Ball weapon. Have fun with it, search the commands, there's plenty of easy weapons you can make, and the weapon script is easy to follow and modify as well. Hopefully, you know enough about parameters to make more than one weapon for sale in the same NPC, just make the weapon name part of the action, then check for that parameter before they can buy.
Now there are other types of loops. One I commonly see is a timeout loop. You should understand why. Back with GS1, it was a bit easier to tell what was happening in the script. In GS1 the script for function onTimeout() would be displayed as if(timeout). It was a bit easier to tell that when a timeout was done, it set a flag that if(timeout) would check. function onTimeout does the same thing, however, for new users this may be harder to tell. here's an example of an NPC that uses a timeout loop:
<pre>
//#CLIENTSIDE
function onCreated()
{
settimer(1);
}
function onTimeout()
{
player.chat="Counter: " @this.time;
this.time++;
settimer(1);
//after 1 second, the timeout loop will restart
}
</pre>
This would cause the player to count up every second.
You may have noticed that the variables often start of with client. or this. There are actually a few prefixes, each does a different thing:
<pre>
client. variable is saved to the client, it can be modified on the clientside or serverside, and read from either.
clientr. variables can be rad from server or clientside, but only written from serverside. This is more secure, but only if you use it right.
server. variables are saved to the server, can only be written on the serverside, read on either side
serverr. more secure version of server. read only on clientside
this. is a variable that only functions in the NPC it is in. This prevents NPCs from morifying each others variables
temp. only exists in between the brackets of a function
</pre>
To use scripts effectivly, you should know how to use each of these.
I will add more over time.

Some important commands can be found here:
page:http://wiki.graal.net/index.php/Creation/Dev/Script/Starting_Guide#Introduction
Which is also helpful for learning how to script. Enjoy!

Vectors

2007-07-01T07:56:00Z

Twinny:

'''Vectors''' are mathematical representations of any thing that has a length, or magnitude, and direction. Positions are also described using vectors which start at the origin of the coordinate system (0,0,0).

== Definition ==
In GraalScript, a vector is limited to three dimensions, however, mathematics allows for analyses of vectors in n-dimensions. Vectors do not have positions. Two vectors are said to be parallel if they have the same direction (u || v), and are said to be equal if they are parallel and have the same magnitude (u = v). Vectors are generally described by their terminal points with respect to the origin (0,0,0).

The basic format of a vector in GraalScript is {x,y,z} where x, y, and z are all floating points in reference to the axis to which they correspond. Built into GraalScript are several functions which can be used to analyze these vectors.

In mathematics, vectors are often written
v = <v1,v2,v3>
for a vector in three dimensions. They can also be written as the sum of unit vectors, i = <1,0,0>, j = <0,1,0>, and k = <0,0,1> on the x, y, and z axes, respectively. In this case, the vector would be written as
v = v1i + v2j + v3k
where the values of v are treated as scalars (numerical multipliers) of the unit vectors.

To denote the difference between a scalar and a vector, vectors are often written with a directional arrow above them, which looks like the top half of an arrow pointing right. In GraalScript, a scalar and a vector are impossible to confuse: a scalar is a floating point whereas a vector is a string.

=== Vector Length (Magnitude) ===
Being as vectors are merely written by terminal point coordinates, there is no immediate way to determine the magnitude of the vector. Mathematically, the terminal point lies on a sphere that has the same radius as the vector's magnitude. Thus, we can use the equation of a sphere to calculate the magnitude. 
r2 = x2 + y2 + z2 
r = √(x2 + y2 + z2)
where r is the magnitude. Generally, the magnitude is denoted as |v| or ||v||. This was chosen, because absolute value refers to distance from the origin, thus the marks were suitable. In GraalScript, however, the magnitude of any vector can be calculated simply by plugging a vector string into the '''vectorlen({{graycourier|v}})''' function.

=== Unit Length ===
A vector is said to have "unit length" when it's magnitude is one. '''i''', '''j''', and '''k''' are each unit vectors because their magnitudes are each one. To make a vector of unit length, the vector must merely be divided by it's magnitude.
Let v be a vector and u be the direction (unit vector) of v.
v = <1,7,1>
|v| = √(12 + 72 + 12) = √51
u = v/|v| = <1/√51,7/√51,1/√51>

Graalscript has a built-in function, '''vectornormalize({{graycourier|1=v}})''',to perform such a calculation.

== Vector Modification ==
Along with vectorlen are a plethora of functions built into GraalScript all for the purpose of modifying vectors.

=== Vector Addition ===
[[Image:Vectors-addition.png|thumb|right|Vector addition]]
Given the vectors u and v, we could create a third vector that has the magnitude of u and v, were the two vectors to be placed tip-to-end. This is called vector addition and can be done with the function '''vectoradd({{graycourier|u}},{{graycourier|v}})'''. This takes the terminal coordinates and adds them together. to make a new vector: 
w = <u1+v1, u2+v2, u3+v3>.
 

=== Vector-Scalar Multiplication ===
[[Image:Vectors-scalar-multiplication.png|thumb|left|Vector-scalar multiplication]]
With a vector, v, and a scalar, s, we could make a new vector that is s times larger than v. This can be accomplished in GraalScript with the function '''vectorscale({{graycourier|v}},{{graycourier|s}})'''. The vector is thus extended in the following manner: 
s·v = s·<v1,v2,v3> = <s·v1,s·v2,s·v3>.
 

=== Vector Subtraction ===
[[Image:Vectors-subtraction.png|thumb|right|Vector subtraction]]
With these two properties, we find that vector subtraction is possible, and no longer a new idea. This is done in GraalScript with the use of the '''vectorsub({{graycourier|u}},{{graycourier|v}})''' function. 
u-v = u + (-v) = u + (-1)·v
You can imagine this as the two vectors placed tip-to-end, but the second is facing the opposite direction.
 

=== Distance Between Terminal Points ===
Without creating a third vector, it is simple in GraalScript to find the distance between the two points at which two vectors end. This function is '''vectordist({{graycourier|u}},{{graycourier|v}})'''. 
The return value would be
√((u1-v1)2+(u2-v2)2+(u3-v3)2)
The mathematical operation is the pythagorean theorem (or a combination of two). As may be evident, the distance is the magnitude of '''u'''-'''v'''.

== Other functions ==
vectordot({{graycourier|u}},{{graycourier|v}}): see [[Dot Product]]. 
vectorcross({{graycourier|u}},{{graycourier|v}}): see [[Cross Product]].

Creation/Dev/GScript/Understanding GUI Profiles

2007-07-01T07:55:37Z

Twinny:

== Introduction ==
GUI profiles are a set of characteristics that define how a GUI control looks. By default when you create a GUI control, it will be using the default profile for the control type; for example, "GuiButtonControl" by default uses "GuiButtonProfile".

This profile tells the program that this button needs to be red with a golden border and have orange text. It can define various things such as font face, size, colour, background colour, borders, images, etc.

A GUI profile is created in a similar way to a GUI control itself.
<pre>new GuiControlProfile("ProfileName")
{
attr = value;
attr = value;
}</pre>

It can then be applied to a control like so:
<pre>new GuiControl("ControlName")
{
profile = "ProfileName";
}</pre>

The control will then be formatted as is directed by the GUI profile.

An example profile looks like this:
<pre>new GuiControlProfile("MyProfile")
{
fillColor = {255, 0, 0};
fontColor = {255, 255, 255};

bitmap = "myEvilImage.png";

opaque = false;
transparency = 0.5;
}</pre>

You can copy existing profiles to create a new one. Instead of creating a "GuiControlProfile" just use the name of the existing profile which you want to copy:
<pre>new GuiButtonProfile("MyButtonProfile") {
fontsize = 20;
}
</pre>

== Available Attributes ==

See [[Creation/Dev/Script/Client/GuiControlProfile|GuiControlProfile]].

== Editing control-specific profile information ==
You can also edit the profile attributes of a single control. This is using the "profile" object of each GUI control.

The profile object contains members exactly the same as a normal GUI profile (i.e. "transparency" => "controlname.profile.transparency". This provides a way to edit the profile.

However! You must be careful. A variable, "useOwnProfile", plays an important role here. useOwnProfile tells the control not to share any changes made to the profile.

For example, if you did the following:
<pre>profile = "MyProfile";
profile.transparency = 1;</pre>
... then every control using the profile "MyProfile" would set transparency to 1.

useOwnProfile stops this happening:
<pre>profile = "MyProfile";
useOwnProfile = true;
profile.transparency = 1;</pre>
... causes only the current control to have transparency set to 1.

Creation/Dev/Local Database NPC Communication

2007-07-01T07:54:01Z

Twinny: Undo revision 8867 by Special:Contributions/Anti-up (User talk:Anti-up)

= Introduction =
What exactly is the purpose of database communication? You might have seen the telephone scripts on Era, where anyone can talk to anyone else on another phone on the server. The method that these phones use to transfer messages is database communication. Database communication is really useful for passing data between database instances of NPCs on a server, while at the same time, giving them a friendlier ID. But first, you must understand a couple of things about database NPCs.

Note: This article '''expects''' a certain degree of knowledge of new engine scripting, using classes and database NPCs, etc.

=== What are Database NPCs? ===
There are two major types of DB NPC: these are DB NPCs created using [[NC]], and putnpc2()-style NPCs created using scripting, and having your script joined to them using join(). In this tutorial, we will be using both putnpc2()-style NPCs, and DB NPCs. We'll be giving each putnpc2()-style NPC we create a nice friendly identifier.

=== Important concepts ===
DB NPCs each have a unique identifier.

[[Image:rc_classlist_normal.png]] NPCs created using putnpc2() each have a unique identifier, which is dynamically generated when the NPC is created. An example of one of these IDs is "localnpc_era_present_32673165_8". Don't worry about remembering these - we will write methods to save these identifiers automatically.

[[Image:rc_localnpcs_normal.png]] NPCs created using NC have a specified identifier that you assign. Again, these must be unique. An example of one of these might be "DB_Phones", or "SkyldTest".

In either a database NPC or a putnpc2() NPC, the ID can be found with the '''this.name''' variable.

= Objective =
The objective for this tutorial is to create a system where NPCs created using putnpc2() can communicate with each other. So, let's start by designing the system.

You will want:
* One Database NPC with a sensible and easy name. For example, if you are creating a system for phones, a suitable name may be "DB_Phones". Try to avoid using "-" in names, since this makes it harder to link to them.
* One script class with your scripting in. In the example of creating phones, you will want to have your phone scripting in here.
* A weapon to place putnpc2() instances of your script class with.

=== Database NPC ===
The Database NPC will be one of the core parts of your system. As we've said already, each putnpc2() we have will be assigned a friendly ID, like a phone number. The Database NPC is where these identifiers will be stored, where any NPC can access them. In this case, it's important that our putnpc2() NPCs can read them!

Create a Database NPC. For this example, we'll use "DB_Identifiers".

=== Script classes ===
The majority of your scripting will be in these script classes. However, there are a few fundamental things that must be inside this class before you can begin.

==== Saving the ID of the class ====
When the NPC is placed, it must save it's ID into the database so that we can later access it. In this case, we will generate a random four digit number which will identify the NPC, and then save it to DB_Identifiers.

<pre>function onCreated()
{
while (this.number == NULL)
{
temp.try = int(random(1000, 9999);

if (DB_Identifiers.("class_" @ temp.try) == NULL)
{ // Okay, the number is free, let's save it
DB_Identifiers.("class_" @ temp.try) = this.name;

// Now save the number locally so we know it
this.number = temp.try;

break;
}
}
}</pre>

==== Creating a method to find the NPCs by their new ID ====

So far, the NPC will assign itself a four digit number and save that number into the database. But there are still a few complications. You need a way to find the ID of a class by just it's four digit number. So, we write a function to retrieve a number if it's available. We'll call it findClass().

<pre>function findClass(temp.number)
{
// Perform a little sanity check on the number
if (!(temp.number >= 1000 && temp.number <= 9999))
{
return -1; // Invalid number, so stop!
}

// Make sure the number is an integer
temp.number = int(temp.number);

// Check if the database has the number saved
if (DB_Identifiers.("class_" @ temp.number) != NULL)
{ // Database has got this identifier, let's return the object ID
return DB_Identifiers.("class_" @ temp.number);
}
else
{ // Database hasn't got the ID, no such NPC?
return -1;
}
}</pre>

Now, from inside your class, you can see if there is a class on the server with your ID just by using findClass().

To better explain, say you created two NPCs. The first NPC named itself with the number 3209. The second NPC named itself with 5563. If you wanted to find the object for the first NPC, you would use:
<pre>with (findClass(3209))
{
// code
}</pre>
... And likewise for the second NPC:
<pre>with (findClass(5563))
{
// code
}</pre>

This is exactly how we will make the NPCs communicate.

==== Creating a function to be run remotely ====
Now, to give the NPC an entry point from other NPCs, we'll create a public function. Public functions can be run by any NPC on the same side (serverside or clientside).

So, let's define a public function called entryPoint(). This is where instances of your class will send data to other instances. This is also where the commands will be interpreted to do something useful.

<pre>public function entryPoint(temp.data)
{
// Code
}</pre>

Now, the creation of this function means that you can do this:

<pre>findClass(5563).entryPoint("I am sending this data!");</pre>

Now, does this help you? Well, this has given you a foundation to allow your classes to communicate. Hold on, though. There are still some complications.

==== Destroying class instances correctly ====
If you just this.destroy() an instance of your class without first removing the identifier, the identifier will stay there until someone removes it. So, let's make sure that your routine clears out the identifier properly.

<pre>function destroyInstance()
{
DB_Identifiers.("class_" @ temp.number) = NULL;
this.destroy();
}</pre>

Now you can use destroyInstance() to correctly remove your NPC '''and''' it's identifier.

==== An example use of what you've created ====
Here's an example of something you might want to put in your class to test if it works.

<pre>function onCreated()
{
while (this.number == NULL)
{
temp.try = int(random(1000, 9999);

if (DB_Identifiers.("class_" @ temp.try) == NULL)
{ // Okay, the number is free, let's save it
DB_Identifiers.("class_" @ temp.try) = this.name;

// Now save the number locally so we know it
this.number = temp.try;

break;
}
}
}

function findClass(temp.number)
{
// Perform a little sanity check on the number
if (!(temp.number >= 1000 && temp.number <= 9999))
{
return -1; // Invalid number, so stop!
}

// Make sure the number is an integer
temp.number = int(temp.number);

// Check if the database has the number saved
if (DB_Identifiers.("class_" @ temp.number) != NULL)
{ // Database has got this identifier, let's return the object ID
return DB_Identifiers.("class_" @ temp.number);
}
else
{ // Database hasn't got the ID, no such NPC?
return -1;
}
}

public function entryPoint(temp.data)
{
if (temp.data == "explode")
{
putexplosion(2, this.x, this.y);
return 1; // Let's let the other NPC know that the command was received
}
}

function onPlayerChats()
{
temp.tok = player.chat.tokenize();

if (temp.tok[0] == "explode")
{
if (findClass(temp.tok[1]).entryPoint("explode") == 1)
{
player.say2("You successfully exploded the NPC!");
}
else
{
player.say2("Maybe the NPC doesn't exist?");
}
}
}</pre>

You could then say "explode 5563" from any other NPC of your instance, and cause it to explode!

=== Weapon to place your instances ===
Let's actually create a method to place your NPCs now. For this, you'll need a weapon. The name of the weapon isn't really important. The code for this is simple.

<pre>function onActionserverside()
{
if (params[0] == "place")
{
putnpc2(player.x, player.y, "join yourclassname;");
}
}

//#CLIENTSIDE

function onPlayerChats()
{
if (player.chat == "drop")
{
triggeraction(0, 0, "serverside", "yourweaponname", "place");
}
}</pre>

= Conclusion =
So, you've got your framework. You could easily now create your system on a framework of these functions by giving each of your NPCs a friendly name. The reason we used four digit numbers here is because they are easy to work with. You might decide to make it 7 digit numbers to resemble phone numbers, or even email addresses!

Creation/Dev/GScript/Constants

2007-07-01T07:53:52Z

Twinny: Undo revision 8675 by Special:Contributions/Anti-Up (User talk:Anti-Up)

As one might be able to deduce, a '''constant''' has a single value and will retain that value as long as that constant exists. A constant is ''not'' a variable for one very important reason: it's value is not variable!

const intVar = 3;
intVar = 4; // will not work
player.chat = intVar; // displays 3

The value of the constant cannot change even in conjunction with the use of the "=" operator. This is the power of a constant. However, player.variables cannot be defined as a constant (client(r).variables, too, possibly).

A constant may be used most likely to keep a variable that is available to any script from changing its value due to any foreign script interfering. It can also be used to give some cryptic value an easy to understand name, and by putting the const definition at the beginning of the script it can easily be configured.

A constant is only accessible in the script where you have defined it, they
are not shared between the server-side and client-side parts either.

A special type of constants are enumerators:

enum {
enum0,
enum1,
enum2
};

When you put names in an enumerator list, then it is automatically generating constants by enumarating the names - enum0 will be zero, enum1 will be 1, enum2 will be 2.

enum modes {
IDLE,
WALK
};

By giving a name to the enumerator list you can group enumerations - you can access the constants by modes.IDLE and modes.WALK.

enum {
enum10 = 10,
enum11,
enumstr = "string"
};

You can assign values to the constants like you do for normal constants. It will automatically enumerate the following entries by adding one to the last value, so enum11 will be 11. You can also assign a sring value.

Creation/Dev/Using Classes Effectively

2007-07-01T07:53:48Z

Twinny: Undo revision 8674 by Special:Contributions/Anti-Up (User talk:Anti-Up)

Note: Code examples in this article use new engine scripting.
= Why classes? =
Classes are a very useful concept in Gscript. They allow many instances of the same code to be run and even dynamically placed. They are also an effective means of sharing functions between scripts. You can attach them to the player, too, where the player is treated as the current object.

= Using classes as standalone NPCs =
Objects, including NPCs from levels or database NPCs, can join a class. That class is then controlling the behaviour of the object. The class can so act either as level NPC, when being joined from a level NPC, or as database NPC, when joined from a database NPC. Many objects can join the same class, which is useful e.g. for ATMs.

=== Joining from a level ===
To let a level NPC join a class, simply create an NPC and put:
<pre>this.join("classname");</pre>
The NPC will then join the class once created. When updating a class with RC that is joined by level NPCs, you may have to update the level in order to see the update.
=== Joining using putnpc2 ===
To create a databased NPC, you can use the function putnpc2() on serverside:
<pre>putnpc2(x, y, "join(\"classname\");");</pre>
... replacing x and y with coordinate values, or variable names containing these values. A putnpc2() NPC is called a "database NPC", being that it is databased in the NPC-Server, and does not belong to a specific level. Database NPCs usually receive updates when the script is updated with RC immediately. They can also warp to other levels.
=== About database NPCs (including putnpc2 NPCs) ===
When you are finished with a DB NPC and want to destroy it, you should use this.destroy(); serverside. The NPC will then be totally removed from memory. Note that the class will of course still remain on the server.

DB NPCs have unique identifiers, which can be read using this.name. This identifier can be used to locate the NPC on the serverside, like shown:
<pre>with (findnpc(identifier))
{
// foo
}</pre>
<pre>findnpc(identifier).foo();</pre>
This allows other scripts to interact with the database NPCs that you have placed. With the new scripting engine you can also access those npcs directly by using identifier.foo.

Like mentioned previously, database NPCs are not specific to one level, and such you can use the warpto() command to move the NPC into a new level:
<pre>this.warpto("levelname", x, y);</pre>
This enables great portability.

= Using classes to share functions =
If you write a set of functions that you wish to use in more than one NPC, then you can define them in a class, and let each npc join the class instead of copying the functions into each. It also means that you can update your functions across all your scripts, too.
=== Define your functions ===
Open up your class, and define your functions like you normally would!
<pre>function funcName(parameters)
{
// code
}</pre>
Then save your class. This will provide these functions to any NPC that joins the class, and will allow you to easily update functions between several NPCs.
=== Using your functions ===
Now, before you can use the functions in your other scripts, you must let the current NPC join the class. Like a level NPC, you use the following command:
<pre>this.join("classname");</pre>
Then, you can use your functions.

You can easily let an NPC join more than one class, for example:
<pre>this.join("classone");
this.join("classtwo");</pre>
However, this can cause problems where there is more than one function with the same name. You can specify which class you want to use the function from by using the :: operator. The :: tells the scripting engine to look in that specific class, like so:
<pre>classtwo::myFunction();</pre>
This means that you do not have to worry about using the same function name more than once. If function names are colliding, then the first function found will be used, which means either from the script of the npc itself or of the class joined first.

= Using "player classes" =
Player classes are classes joined by players. A player-joined class treats the player as the current object (this.). Also, you can create functions available to other scripts through the player object, for example, creating a function that damages the player called doDamage() and then calling it from any script using:
<pre>player.doDamage();</pre>
This allows the player to be treated easier using different functions.

=== Join the class ===
You can let the player join the class on serverside like this:
<pre>player.join("classname");</pre>
You could do this in your Control-NPC to, say, join the classes whenever the player logs onto the game server.

Player classes are no different to ordinary classes - you should edit them in RC the same way as you do with normal classes.

=== Define your functions ===
For functions to be useable by other NPCs, they must be public:
<pre>public function funcName(parameters)
{
// code
}</pre>
This means that other NPCs can run the function, for example:
<pre>player.funcName(1, "Hello!");</pre>
Non-public functions will not be useable from outside the current script, so you can define normal functions to create a function that you don't want to be called externally, for example:
<pre>function funcName()
{
// code
}</pre>

=== Using your functions ===
If your functions are public, then other scripts can easily call the functions that you have defined in your class, for example:
<pre>player.funcName();</pre>

=== this. object ===
Player classes work in a different focus, where the current object (that's the '''this.''' object) becomes the player. So, if you wanted to change the player's chat text in a player joined class, you would use the following:
<pre>this.chat = "Chat text!";</pre>
Calling functions using this. will also call functions from player joined classes, for example:
<pre>player.join("classname");</pre>
<pre>this.playerFunction();
this.anotherFunction();</pre>

Creation/Dev/Output Methods

2007-07-01T07:51:19Z

Twinny:

== Introduction ==
With the addition of the [[GScript|new scripting engine]], there are a number of new methods in which you can create output from an NPC. In this article, I will discuss a couple of ways.

== Useful Things To Know ==
If you've played with the new engine for a while, you're probably aware of the string concationation operators. If not, here they are.
<pre>String Concatenation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b</pre>
What these operators do is join values together to form one value.

An example of using @ would be:
<pre>"Hello, " @ player.account</pre>
... which would produce "Hello, accountnamehere".

The SPC, NL and TAB operators work using the same principal - except that they insert a Space, New Line or Tab Space respectively.

If you don't put a space at the end of the first value or at the beginning of the second value when using @, you don't get a visible space, for example:
<pre>"Hello" @ "World"</pre>
... will produce "HelloWorld".

However! If you use SPC, you'll get a space in place of the operator:
<pre>"Hello" SPC "World"</pre>
... producing "Hello World".

You can use these operators just about anywhere that a variable is requested, i.e. setting a variable, or sending to a function.

== format() function ==
Or, if you aren't so interested in using the concationation operators, you can use the ''format()'' function.

What this function does, is that it takes a sort of template from the first parameter you give it, and replaces % codes with other parameters you give it.

Now, the template format primarily uses the following % characters:
<pre>%d %i - Integer
%f - Float (number with decimal)
%s - String
%c - Single character
%% - Literal "%" character
%x %X - Print an integer as a hexadecimal</pre>
There are more, since the function is made to be compatible with C's ''printf()'' function.

In the template, every % code will be replaced with the respective parameter.

Say you want to produce "Hello, '''Mr. Skyld'''. You ate '''4''' apples today!" using format(). First, your format would be this:
<pre>"Hello, %s. You ate %i apples today!"</pre>
... and you must not forget to give the parameters containing the values:
<pre>format("Hello, %s. You ate %i apples today!", "Mr. Skyld", 4);</pre>
You can give the format() functions as many parameters as necessary to build up your value. If you use a % code and a value isn't present for it, a 0 (zero) will appear in it's place.

You can also use ''format2()'', which acts just like format() with the exception that instead of passing variables as separate parameters, they are sent as an array to the 2nd parameter.
The example above would become
<pre>format2("Hello, %s. You ate %i apples today!", {"Mr. Skyld", 4});</pre>

Along with format2() came the indexing of the parameters. This method will work with both format() and format2() functions. It allows us to choose which parameter to place in which position in the format string. The problem of parameters being placed in the wrong order will not exist if each parameter has a different data type, however.

<pre>format2("Hello, %2$s. You ate %1$s apples today!", {"four","Mr. Skyld"});</pre>
In the example, both parameters are strings, so it would be necessary to give them an index when trying to insert them in a different order than they were passed. ''%1$s'' refers to the 1st object in the array inserted as a string. ''%n$T'' is general; the nth parameter inserted with datatype of ''T''.

Now, let's continue on various ways of outputting data.

== Outputs ==
=== Direct Output ===
Direct Output is sending an output directly to the game client, or to RC/NC. There are a number of functions for these tasks.

==== echo() ====
The echo() function will, on the serverside, send data to NC, so RC users who have the NPC-Control right will see the message in RC chat, and on the clientside, sends the message to the F2 window. It expects one parameter, and that's the message you're sending. For example:
<pre>echo("This is a message!");</pre>
The message "This is a message!" will appear either in RC or the F2 window using this example.

==== sendtorc() ====
The sendtorc() function works in the same way that the echo() function does, however, it only usually works on the serverside. It will appear to all RC users. For example:
<pre>sendtorc("This is a message!");</pre>
... will send "NPC-Server (Server): This is a message!" to RC.

'''Note''' that this function can only be used on the clientside when Client-RC is active.

==== sendtonc() ====
The sendtonc() function works in exactly the same way as echo() does serverside.

==== sendrpgmessage() ====
The sendrpgmessage() works much the same as echo() does clientside. It will result in a message appearing in the player's F2 log window. For example:
<pre>sendrpgmessage("This is a message!");</pre>
... will send "This is a message!" to the player's F2 window.

=== Working with Files ===
==== loadstring() ====
loadstring() is an object function which loads the contents of a given file.

Say that the file "levels/file.txt" contains the message "HELLO WORLD". If you want to load that value into a variable called "myVar", you should use this function:
<pre>myVar.loadstring("levels/file.txt");</pre>
You can easily check the contents of the file:
<pre>echo(myVar);</pre>

==== savestring() ====
savestring() is another object function, however, instead of loading the contents of a file, it writes the contents instead.

Consider this with the previous example:
<pre>myVar = "HELLO PLANET";
myVar.savestring("levels/file.txt", 0);</pre>
... would write "HELLO PLANET" to "levels/file.txt".

The second operator, which is 0 (zero) in that example, is the '''Append''' function, and decides whether the file should be overwritten with the new value, or whether the new value should be added onto the end of the file. If you specify '''1''', then the value will be appended, if not, it will overwrite the file.

==== savevars() ====
savevars() is an object function which saves the variables of an object into a file. Consider this example:
<pre>myVar = new TStaticVar(); // Create a TStaticVar
myVar.variable = "Hello";
myVar.secondvariable = "World";
myVar.saveVars("levels/test.txt", 0);</pre>
This will save the variables inside the "myVar" object into "levels/test.txt". You can then recall these variables using loadvars();

Like savelines(), the second parameter controls whether the variables are to be appended to the file. '''0''' will overwrite the file, and '''1''' will append to the file.

==== loadvars() ====
loadvars() is another object function which loads savevars()-style variables from a file into an object. Let's say you used the previous example from savevars(), then you could restore these values using the following:
<pre>myNewVar.loadvars("levels/test.txt");
echo(myNewVar.secondvariable);</pre>
... which will output "World".

=== Private Messages (PMs) ===
From the serverside, you can send PMs to players. They appear from the NPC-Server.

If you wanted to send a PM to the player "Skyld" (if the player is online), the you would use the following example:
<pre>findPlayer("Skyld").sendPM("This is a PM");</pre>
... and then the specified player, in this case Skyld, would receive the PM "This is a PM".

If you want to send a PM to the current player, you would simply use:
<pre>player.sendPM("This is a PM");</pre>

Creation/Dev/Troubleshooting Graal v4 IRC

2007-07-01T07:50:14Z

Twinny: Undo revision 8679 by Special:Contributions/Anti-Up (User talk:Anti-Up)

Written by [[Skyld]], 28/08/2005.

== Introduction ==
After a rising number of people are having problems using the IRC and events system in their scripting, I have decided to write this document to assist in troubleshooting problems.

== No IRC server connection ==
If you are finding that commands like:
<pre>sendtext("irc", "login", "EventsBot");
sendtext("irc", "privmsg", {"IRCBot", "!resetevents"});</pre>
... in your events bots are not returning any responses, then your server might not be GScript2-enabled. You will need to use the old style scripting as described in [[Creation/Dev/Graal_v4_IRC#IRCBots_for_Old_Scripting|Bots using old scripting]].

== IRC Bot appears to be online but does not receive data ==
If your IRC Bot is logging in and joining channels properly but not returning any information, the most simple problem is that you have made a spelling error.
<pre>function onRecieveText(texttype, textoptions, textlines)</pre>
This won't work because onReceiveText is spelt wrong. Ensure that it is spelt correctly.
<pre>function onReceiveText(texttype, textoptions, textlines)</pre>

== EventsBot will not register ==
If you used the EventsBot start script from the [[Creation/Dev/Graal_v4_IRC|Graal 4 IRC]] Wiki page, then you may encounter a problem where the EventsBot will not login correctly.
This is simply fixed, by replacing this:
<pre>textlines[1] == "!eventsbotlogin"</pre>
With this:
<pre>textlines[2] == "!eventsbotlogin"</pre>
Thanks to napo_p2p for discovering this this and [http://forums.graalonline.com/forums/showpost.php?p=1103844&postcount=20 posting the error].

== EventsBot is registered, but no admin control is available in the serverlist ==
When you receive a '''PRIVMSG''' from '''IRCBot''' saying "!eventsbotlogin", you must provide two important details about your setup.
* Send the account names of those who should have admin access: <pre>sendtext("irc", "privmsg", {"IRCBot", {"!eventadmins", "AccountName", "AccountName2"}});</pre>
* Send the discussion channel for your events: <pre>sendtext("irc", "privmsg", {"IRCBot", {"!eventchannel", "#ChannelName"}});</pre>
When the EventsBot logs in, after sending the above data, the listed account names should have access to the Admin tab for events when they log onto the game server.

== My IRC bot occasionally disappears and does not reappear until script update ==
This could be for a couple of reasons:
* The IRC server was reloaded and connections were reset
* The IRC server fails or a problem arises
* The gserver/npcserver has been restarted
To ensure that the IRC bot always restores it's connection, you should put your connect routine in a seperate function, and use something like this:
<pre>function onCreated() IRCConnect();
function onInitialized() IRCConnect();
function onServerListerConnect() IRCConnect();</pre>
Also, ensure that the IRC bot is correctly resetting it's connection by logging out in your connect routine:
<pre>// Logout first
sendtext("irc", "logout", "");
// Then login and do stuff
sendtext("irc", "login", "Nickname");</pre>

== My IRC bot does not accept name changes properly on script update ==
This occurs because you have tried to use a new name without freeing your previous one. Just logging in again with a new name will not work.
Instead, you have to log out and '''then''' log in using the new name.
<pre>sendtext("irc", "logout", "");
sendtext("irc", "login", "Nickname");</pre>
In fact, it's probably a good idea to make your IRC bot log out and in again on every connection.

== Randomly, my IRC bot reports everyone in the channel joining again ==
'''ADDCHANNELUSER''' is sent to IRC scripts every time a user joins a channel that you or your IRC bot is also in. This allows making of a user list for that channel, or simply monitoring who joins and leaves.
It has been known for this to occasionally occur, listing everyone in the channel at once. This could happen for a number of reasons:
* You have reset your connection to the IRC server, maybe by a script update, and the IRC server is telling you again who is in the channel
* The IRC server has been reloaded, and as a result, connections have been dropped
This is not a problem as such, but if this is a problem for you specifically, consider removing any messages that occur on this event, or if you are listing users, make sure your list does not show any user more than once.

== My IRC bot is not setting it's name correctly ==
You may find that in an attempt to set your IRC bot's name, it may be named IRCBot_N instead. There is a simple reason for this.
IRC connections from the serverside demand the nickname to begin with the following:
* IRCBot_
* EventsBot_
* Graal_
Any other nicknames will not be accepted.

'''Note:''' This is not the case with IRC connections from the clientside.

== Other problems ==
If you are having a problem that is not listed here, [[Skyld]] may be able to help you. Contact details are available on [[Skyld|Skyld's user page]], and may be able to help solve the problem. New problems will also be added here when found.

Creation/Dev/Graal IRC

2007-07-01T07:49:46Z

Twinny:

Written by [[User:Skyld|Skyld]], 26/07/2005. Edits made by [[User:Stefan|Stefan]] since. Hooray for [[User:Stefan|Stefan]]!
= IRC Information =
== Introduction ==
Graal 4 comes with a built-in form of IRC to allow people to chat between servers in rooms. Like IRC. But not, if you get my point. Now, there are ways in which you can use this IRC system to your advantage. Perhaps you want to script some kind of client for your players to use, or perhaps you want to script some kind of bot. Either way, the communication is simple.

=== Links===
* [http://forums.graalonline.com/forums/showthread.php?t=60809 Graal v4 IRC Problem Information Thread]
* [[Creation/Dev/Troubleshooting Graal v4 IRC|Troubleshooting Graal v4 IRC]]

== Logging In ==
To use the IRC, you just need to have basic knowledge of sendtext() and onReceiveText(). The fundamentals are that you have three parameters for each outgoing and incoming message. If you have used onReceiveText() before, you are likely to know
it has a structure like this:
<pre>function onReceiveText(texttype, textoptions, textlines)</pre>
The texttype will always equal "irc" if it is an IRC command. This helps to filter out unwanted commands from, say, the scripted RC. The textoptions will always equal the command that you've sent, and the textlines will equal any parameters necessary for that command.

An important thing to note is that the IRC server will not throw any errors at you if you make a mistake with a command, so you should ensure throughly that your requests are correct.

You send requests like this:
<pre>sendtext("irc", "command", "params");</pre>
Like any other IRC server, you need to log in before you can use it.
This is quite simply done. From your NPC, use the following command:

<pre>sendtext("irc", "login", "nickname");</pre>

'''NOTE:''' The nickname behaviour is different on the serverside. If you are logging in from the serverside, your nickname MUST begin with Graal, EventsBot or IRCBot. If you do not provide a valid nickname, then a suitable name (like IRCBot_2) will be automatically assigned and your nickname ignored.
Now, with any luck, you will have been logged in successfully! 
'''NOTE2:''' There is also the command requesttext(texttype,textoption), but it is not used for irc communication since most irc commands require additional data.

== Joining a Channel ==
Now, you could probably get away with not joining a channel if you felt it necessary, but that would make communicating with you hard. So, why not join a channel? Joining and leaving channels is much like, again, in normal IRC. You sendtext("irc", "join", "#channame") to join a channel, and you sendtext("irc", "part", "#channame") to leave one.

You can be in multiple channels, however, if you are writing a bot, you should probably make sure that you are always replying to the correct channel. I suppose the same applies to if you are writing a client - make sure you are sending to the right channel!

== Receiving Information ==
Information from the IRC server comes to you in the form of onReceiveText(),providing you have logged into the server first. So, you will want to make sure that your script is receiving the information, or you might as well talk to a nice stone. I am not sure that it will help you, however.

Now, earlier in the document, I said about the onReceiveText structure.
Just for reference, it looks like this:
<pre>function onReceiveText(texttype, textoptions, textlines)</pre>
To ensure that you are only receiving information from the IRC server, you should put an if check to check that the texttype is always "irc":
<pre>if (texttype == "irc")
{
// Let's do this if we get IRC data
}
else
{
echo("I am receiving non-IRC data!");
}</pre>
'''NOTE:''' Commands like "privmsg" will be broadcasted to the whole channel, and will be sent back to you in the process. "join" and "part" are also sent to you to confirm that you have joined a channel, but can also be used for kicking.

The textoptions will equal the command type, such as "join", "part" or whatever.

So, you will want next to check what kind of information is being sent to you:
<pre>if (textoptions == "join") echo("You joined the channel successfully!");
if (textoptions == "part") echo("You left successfully");
if (textoptions == "privmsg") echo("Message!");</pre>
"privmsg" differs here - it contains messages from anyone, not just yourself. I'll explain about "privmsg" in a second. To know who is joining or leaving your channel you need to handle the "addchanneluser" and "deletechanneluser" types.

You may also receive information of the "notice" or "topic" types. These aren't so important yet and will be explained later.

== Working With Messages Specifically ==
The type you will most likely be interested in receiving is the "privmsg" command. This is the most complicated, as if it isn't used correctly, you'll end up no further forward then you were at the beginning of this section.
* When you send a "privmsg", you send the destination and the message.
* When you receive a "privmsg", you receive the source, destination and message.

So, let's assume that you've joined the channel #test. If you want to send a message to #test, you would use the following command:
<pre>sendtext("irc", "privmsg", {"#test", "THIS IS MY MESSAGE"});</pre>

A sensible idea would be to create a function that makes that mildly less tedious, so let's use this for example:
<pre>function send(dest, msg)
{
sendtext("irc", "privmsg", {dest, msg});
}</pre>
Now, you can just use send("#test", "lolmsg"); to send a message to a channel or user.

However! Like I said before with "privmsg", what you get back will not be the same!

Instead of receiving {"destination","message"}, you will get {"source","destination","message"}, where source is the nickname that you logged in with. This allows you to find out who sent a message in the case that you are writing a client script, or for using people's names as an identity, say, with a bot.

So, what about parsing an incoming privmsg?
<pre>function onReceiveText(texttype, textoptions, textlines)
{
if (texttype == "irc")
{
if (textoptions == "privmsg")
{
// Do some stuff here
}
}
}</pre>
In the function, you can read who sent the message with textlines[0], where it was directed to with textlines[1] (say, #test) and the actual message with textlines[2].

== Logging Out ==
If you are writing a client, or a bot that might have a reason to log out of the IRC server, you send a "logout" command like this:
<pre>sendtext("irc", "logout", "");</pre>
'''NOTE:''' The third parameter is ignored in this case.

== Other IRC Commands ==
There are a couple of other IRC commands, such as ''TOPIC'' and ''NOTICE''.

=== topic (Channel Topic) ===
''TOPIC'' commands are used to set the topic of a channel. This might be useful for you if you are writing a client, and simply uses this format:
<pre>sendtext("irc", "topic", {"#channel", "Topic goes here"});</pre>
You should also receive any ''TOPIC'' commands in the same format.

=== notice (Notices) ===
''NOTICE'' is similar to ''PRIVMSG'', but is considered less important, and while ''PRIVMSG'' to a single player is automatically converted into a regular [[PM]], ''NOTICE'' is not, and can so be used for sending information back to the user. The events bot is using ''NOTICE'' commands for event management.

=== addchanneluser (Channel Join Notifications) ===
''ADDCHANNELUSER'' is received when a new user joins a channel. The received data contains the channel name, irc nick, [[Server|Graal server]] and account name of the new user.

=== deletechanneluser (Channel Part Notifications) ===
''DELETECHANNELUSER'' is received when a user leaves a channel. Only the channel name and the irc nick of the leaving user are received.

== Multiple bots on one machine ==
It is possible to have more than one irc bot per machine - on the client you need to use two different weapon scripts which both login to the irc, on serverside you must use two independent database npcs or weapon scripts which both login to the irc and possibly use different nicknames.

= Extra Information =
== Events Bots ==
For making it possible that events from your [[server]] are displayed on the global events list of [[Graal4]], the server needs to have an '''EventsBot'''. That is an irc bot with a name starting with EventsBot. That [[NPC|npc]] or weapon npc automatically gets information about when events should be started. It needs to login to the irc and then wait for instructions using '''onReceiveText'''. If there is no EventsBot for the server, then events will not work for it. The EventsBot also needs to send some information to the IRCBot about who is [[Events Team|Events Admin]] on the server, and which channel should be used for talking about the events. That must be done as answer to a "!eventsbotlogin" message from the IRC Bot:

<pre>
function onCreated() doConnect();
function onInitialized() doConnect();
function onServerListerConnect() doConnect();

function doConnect()
{
sendtext("irc", "login", "EventsBot");
sendtext("irc", "privmsg", {"IRCBot", "!resetevents"});
}

function onReceiveText(texttype,textoption,textlines)
{
if (texttype == "irc" && textoption == "privmsg" &&
textlines[0] == "IRCBot" && textlines[2] == "!eventsbotlogin")
{
sendtext("irc", "privmsg", {"IRCBot", {"!eventadmins", "AccountName", "AccountName2"}});
sendtext("irc", "privmsg", {"IRCBot", {"!eventchannel", "#ChannelName"}});
}
}
</pre>

The EventsBot will also need to start events on the server, and tell the IRCbot about the status of the events.

== Quick Reference ==
Here are some quick reference notes.

=== Outgoing data ===
Usage:
<pre>sendtext("irc", command, parameters)</pre>
Format:
* '''command:''' ''parameters'' - description
Outgoing data:
* '''login:''' ''name'' - Connects to the IRC using name as the connection's nickname
* '''logout:''' ''""'' - Disconnects from the IRC
* '''privmsg:''' ''{destination, message}'' - Sends a message to a channel or user
* '''notice:''' ''{destination, message}'' - Sends a "notice" message to a channel or user
* '''join:''' ''channelname'' - Join channelname
* '''part:''' ''channelname'' - Leave channelname
* '''topic:''' ''{channel, topic}'' - Set the topic for the channel

=== Incoming data ===
Usage:
<pre>function onReceiveText(texttype, textoptions, textlines)</pre>
Format:
* '''textoptions:''' ''textlines'' - description
Note:
''The texttype will always be "irc" when information is sent from the IRC server.''
Incoming data:
* '''privmsg:''' ''{source, destination, message}'' - Sends the ''source'' of a message, where the message was directed to (''destination'') and the message
* '''notice:''' ''{source, destination, message}'' - Sends the ''source'' of a notice, where the notice was directed to (''destination'') and the notice
* '''addchanneluser:''' ''{channel, name, (servername), (account)}'' - Mechanism used to alert IRC scripts when users have joined the current channel, and lists users in the channel upon join. Shows the ''channel'' that ''name'' joined.
* '''deletechanneluser:''' ''{channel, name}'' - Mechanism used to alert IRC scripts when users have left the current channel
* '''join:''' ''{channel}'' - Mechanism used to confirm that you have joined ''channel''
* '''part:''' ''{channel}'' - Mechanism used to confirm that you have left ''channel''

=== Nickname Rules ===
If you are connecting from the serverside, you must start your nickname with one of the following:
* IRCBot_
* EventsBot_
* Graal_
If an invalid nickname is provided from the serverside, you will automatically be assigned with an IRCBot_'''n''' nickname.

Nicknames should not contain spaces.

== IRCBots for Old Scripting ==
It is now possible for servers using the old scripting engine to do IRCBots using the commands sendtext, requesttext, and the "if (receivetext)" event. A script example for a simple EventsBot:

<pre>
if (created || initialized || serverlisterconnect) {
doConnect();
}

function doConnect() {
sendtext irc,logout,;
sendtext irc,login,EventsBot_OldScript;
setstring this.options,;
addstring this.options,IRCBot;
addstring this.options,!resetevents;
sendtext irc,privmsg,#s(this.options);
sendtext irc,join,#OldScriptTest;
}

if (receivetext) {
sendtonc irc: #p(0) - #p(1) - #p(2) - #p(3) - #p(4) - #p(5) - #p(6) - #p(7);
if (strequals(#p(0),irc) && strequals(#p(1),privmsg) &&
strequals(#p(2),IRCBot)) {
if (strequals(#p(4),!eventsbotlogin)) {
setstring this.options,;
addstring this.options,IRCBot;
setstring this.options2,;
addstring this.options2,!eventadmins;
addstring this.options2,Stefan;
addstring this.options2,Spark910;
addstring this.options,#s(this.options2);
sendtext irc,privmsg,#s(this.options);

setstring this.options,;
addstring this.options,IRCBot;
setstring this.options2,;
addstring this.options2,!eventchannel;
addstring this.options2,#OldScriptTest;
addstring this.options,#s(this.options2);
sendtext irc,privmsg,#s(this.options);
} else if (strequals(#p(4),!startevent)) {
} else if (strequals(#p(4),!resetevent)) {
}
}
}
</pre>

You also need to add a few script lines to the Control-NPC because in old scripting only the Control-NPC gets an event if the serverlister (=irc server) is reconnecting:

<pre>
if (serverlisterconnect) {
with (getnpc(EventsBot)) {
// Forwarding the event to the Events Bot
callnpc -1,serverlisterconnect;
}
}
</pre>

Particle Engine

2007-07-01T07:49:13Z

Twinny: Undo revision 8678 by Special:Contributions/Anti-Up (User talk:Anti-Up)

==Introduction==

The particle engine in Graal v4 is an extension of the SHOWIMG feature. With the command "showimg" scripts can display graphics, text, polygons and even animations on the screen. That command is mainly meant for client-side effects, but can also partially used on the serverside, and they can also be made visible on other player's screens. Graphics or texts displayed using this command will be called SHOWIMGs in this paper.

Each SHOWIMG can be used as emitter for particles. That way all kind of scripts can use the new particle engine - just display a SHOWIMG and set the attributes of the SHOWIMG so that the particle emitter is activated and is emitting particles. A particle can be seen as an independent graphic object that is put at the position of the emitter once it is emitted, then travelling over the screen, and disappearing once its lifetime is over or it is outside the allowed screen bounds. Actually a particle is itself a SHOWIMG and can so be used for any kind of graphical effect, and can theoretically even be used as emitter for other particles.

The reason for using a particle engine is speed: theoretically all graphical effects could be done by using scripts which call commands to display graphics or text. But often such effects contain several hundreds or even thousands of graphics, which must be moved and animated several times each second. If there are many objects using scripted particle effects that can slow down the game quite a lot. That's why it is possible in Graal v4 to use a built-in particle engine with many possible options to influence the look and behaviour of the particles so that most graphics effects can be displayed using that engine.

==Create a SHOWIMG==

To use the particle engine, you first need a SHOWIMG as emitter:

with (findimg(200)) {
x = player.x;
y = player.y;
}

The function findimg(index) is searching for an existing SHOWIMG with the index of 200 and then using that for setting the other attributes, otherwise it is automatically creating a new SHOWIMG with index 200 for the current object (npc, or player if its a weapon/gui-script). Afterwards it is setting the position of the SHOWIMG to position of the player.

==Configure emitter and particle==

Once the SHOWIMG is setup, you need to configure the emitter and the default attributes of the particle that should be emitted:

with (findimg(200)) {
x = player.x;
y = player.y;
emitter.attribute = value;
emitter.particle.attribute = value;
}

Possible attribute names are
(you can run "Graal4.exe -listscriptfunctions" to get the latest list of script functions):

TParticleEmitter (TGraalVar):
attachposition - boolean - says if the particle is moved with the emitter (true), or can fly freely (false)
autorotation - boolean - for making the particle heading into the direction it flies (rotation=angle)
checkbelowterrain - boolean - destroys the particles if they are below the terrain height (or zero on flat maps)
clippingbox - {xd1,yd1,zd1, xd2,yd2,zd2} - defines a box, if particles leave this box then they are destroyed
cliptoscreen - boolean - automatically resizes the clipping box to the visible area
delaymin - float - minimum delay till the next automatic emission (>= 0.05 seconds)
delaymax - float - maximum delay till the next automatic emission
emissionoffset - {xd,yd,zd} - by default {0,0,0}, says at which position the particles should be emitted, relative to the current emitter position
emitautomatically - boolean - enables or disabled the automatic emission of particles after delaymin/delaymax time
firstinfront - boolean - says if the first emitted particle should be displayed in front (true by default)
maxparticles - integer - can be used to limit the total particle count
nrofparticles - integer - specifies how many particles are emitted at once
particle - object (read only) - defines the default attributes of the next emitted particle
wraptoclippingbox - boolean - if a particle leaves on one side, it appears on the other side (use with "cliptoscreen" option)

TParticle (TGraalVar):
angle - float - the movement angle of the particle (horizontally on the (x,y) plane)
lifetime - float - in seconds, the particle will be destroyed when the lifetime is over
movementvector - string - says in which direction the particles moves, this is a combination of angle and zangle
speed - float - tiles per second
spin - float - automatic rotation of the particle (radiants each second)
zangle - float - the vertical movement angle - says if the particles goes up or down

Particle attributes that are the same like for a SHOWIMG:
alpha - float - transparency
ani - string - a gani file (use "projectile.actor" for changing the attributes)
blue - float - blue color value (0-1)
code - string - the old representation as 'font@style@text'
dimension - integer - polygon dimension (2 or 3)
dir - integer - animation direction
emitter - object (read only) - for specifying the attributes of a sub-emitter
font - string - text font name
green - float - green color value (0-1)
image - string - image filename
layer - integer - 4 or higher for particle which move in screen coordinates, below 4 for level coordinates
mode - integer - the image drawing mode (0 - add, 1 - transparent, 2 - subtract, 3 - daynight)
playerlook - boolean - if the animation should take it's head, body, sword, shield and attr[] from the owner (playerlook), set this to false if you want to set the images yourself by changing showimg.actor.head etc.
polygon - object - array of coordinates for displaying a 2 or 3 dimensional polygon
red - float - red color value (0-1)
rotation - float - defines in which direction the particle graphics is facing
stretchx - float - horizontal particle graphics stretch factor (default 1)
stretchy - float - vertical particle graphics stretch factor (default 1)
style - string - text style (e.g. "b" for bold text)
text - string - a text that should be displayed on the SHOWIMG position
zoom - float - zoom factor of the particle graphics or text

==Add particle modifiers==

Once you have setup the SHOWIMG and specified the attributes of the emitter and default particle, you can also specify particle modifiers so that the particles are not always flying into the same direction and look the same. There are 3 different functions, for modifying the default particle addemitmodifier(), for modifying all existing particles addglobalmodifier(), and for modifying the attributes for each particle individually addlocalmodifier(). The local modifiers are the most often used modifier.
Parameters are:
modifier type - once,impulse or range - modifies the particle one time, periodically or only in the given time range
rangemin - seconds, minimum delay until first modification or start of modification range (if modifier is "range")
rangemax - seconds, maximum delay until first modification or end of modification range (if modifier is "range")
variable - x,y,z,movex,movey,movez,angle,zangle,speed,rotation,spin,stretchx,stretchy,red,green,blue,alpha or zoom
variable modification type - replace,add or multiply (if modifier type is "range" then only "replace" and "add" are valid)
valuemin - range start of the random value or first value to set/add (if modifier is "range")
valuemax - range end of the random value or last value to set/add (if modifier is "range")

Those 3 functions addemitmodifier(), addglobalmodifier() and addlocalmodifier() are returning a modifier object which can be used to attach more variable modifications to the same impulse:

with (addlocalmodifier("impulse",1,2,"angle","replace",0,pi)) {
addmod("zoom","add",0.1,0.2);
}

This example is modifying the angle each 1-2 seconds, and at the same time it is zooming the particle so that it grows bigger. If you don't need to have the two modifiers act at the same moment, then you could have called addlocalmodifier("impulse",1,2,"zoom","add",0.1,0.2) which looks quite the same, but is not guaranteed to happen at the same moment like the first modifier. Most of the time you don't need the addmod-function though.

==Manually emitting particles==

If you have done the things mentioned in the previous steps, then the particle emitter is automatically emitting particles after the time specified with delaymin and delaymax. If you don't want that particles are automatically emitted, then set emitautomatically to false and call emitter.emit() directly.

==Controlling the particle emitter==

You can modify the particle emitter at any time by using the "with (findimg(index))" construct again as mentioned in "Create a SHOWIMG" chapter. To change the position where the particles are emitted you can just change the position of the SHOWIMG, e.g. moving it to the player position so that the particles are always emitted where the player stands.

It can also be interesting to watch the number of particles that the emitter has emitted, you can read the variables "currentparticlecount" and "emittedparticles" for that:

TParticleEmitter (TGraalVar):
currentparticlecount - integer (read only) - for watching how many particles exist
emittedparticles - integer (read only) - for seeing how many particles have been emitted in total

==Reference==

emitter
attachposition - Tells whether or not x/y position of particles is relative to the position of the emitter. Also tells if particles should move when the emitter is moved.
autorotation - Must be ture for making the particle heading into the direction it flies (rotation=angle)
checkbelowterrain - If true, the particle will be destroyed if it falls below the terrain height (0 for flat GMaps)
clippingbox - Format of {x1,y1,z1,x2,y2,z2}, particles that leave this box will be destroyed
cliptoscreen - boolean - automatically resizes the clipping box to the visible area
currentparticlecount - Current number of particles that exist
delaymin - Minimum time before another particle is emitted
delaymax - Maximum time before another particle is emitted
emissionoffset - How far away from the emitter (or the level if attachposition=false) to emit particles. Format: {x,y,z}
emittedparticles - Total number of particles that have been emitted
firstinfront - Tells whether particles drawn after the first particle should draw on top or below the first
maxparticles - Maximum number of particles that can exist at once
nrofparticles - Number of particles to release at once
isfrozen - Boolean, stops all particles if true
wraptoclippingbox - boolean - if a particle leaves on one side, it appears on the other side (use with "cliptoscreen" option)
particle
lifetime - Time (in seconds) before a particle is destroyed
image - Image to use for the particle
mode - Drawing mode of the image. (0 = add, 1 = replace, 2 = subtract, 3 = daynight) See changeimgmode
alpha - Alpha transparency of a particle (0 = invisible, 1 = opaque)
zoom - Zoomfactor of a particle
angle - Movement angle for the particle (for x/y)
zangle - Up/down movement angle for the particle
speed - How many tiles or pixels the particle should move (depends on if its in a level or on the GUI)
rotation - Angle for rotating the image (set autorotation=true to automatically set rotation=angle)
spin - How much the image should be rotated each second, can be postive and negative
stretchx - How much to stretch the particle image horizontally
stretchy - How much to stretch the particle image vertically
red, green, blue - Used to change color of particle
dimension - Polygon dimension (2 or 3)
movementvector - Format is {float,float,float}, a combination of x, y and z

Emitter functions:
addlocalmodifier("string",float,float,"string","string",float,float)
Parameters:
First - Tells when to do an action
once - Do it once
range - Do the action during the range of time param2-param3
impulse - Do it randomly
Second - Tells the minimum time to wait before doing an action (except for 'range')
Third - Tells the maximum time to wait before doing an action (except for 'range')
Fourth - Tells what action to perform
Everything under "particle" except for the following can be changed: image , text, ani, font, movementvector, style
x - x position of the particle
y - y position of the particle
z - z position of the particle
movex - How far the particle should move horizontally in its lifetime
movey - How far the particle should move vertically in its lifetime
movez - How far the particle should move above the ground in its lifetime
Fifth - Tells what to do with parameters 6 and 7
add - Add the amount (use negatives to subtract)
replace - Set a new amount
multiply - Multiply the amount (use negatives to divide)
Sixth - Minimum amount
Seventh - Maximum amount
addglobalmodifier() - Same as addlocalmodifier, except it affects all particles at once
addemitmodifier() - Same as addlocalmodifier, except it only affects emitter.particle
addmod() - Used in conjunction with addlocalmodifier, same parameters except no parameters 1-3
emit() - Do one emission
removemodifiers() - Remove modifiers set
removeparticles() - Remove particles

Creation/Dev/GS1 To GS2

2007-07-01T07:49:10Z

Twinny: Undo revision 8677 by Special:Contributions/Anti-Up (User talk:Anti-Up)

== Introducing the new scripting engine ==

This document is describing some problems and solutions
when switching from the old Graal scripting engine (GS1) to
the new engine (GS2). The new scripting engine has been
designed to on the one hand be compatible to the old
engine, and on the other hand provide new functionality
to make it easier to write Graal scripts and do more
interesting things with it. Those new things include
a windowing system (GUI), a particle engine, multi-dimensional
arrays, function parameter passing, true object orientation.

Since the old engine has been designed 7 years ago, a lot
of functionality has been added to that engine while the basic
design has not been changed, so a lot of modifications can be
more seen as a "hack" and are not very easy to use. For example
numeric variables and string variables must be accessed
in a different way, even more complex operations need to be
used to access numeric arrays and string lists.
The new scripting engine tries to stay compatible with the old
functions, but also add easier ways to access the variables.
Numeric and string variables can now be accessed the same way,
as well as numeric arrays and string lists.

To make the new functionality easy to use, some old "hacky" ways of
accessing variables are not supported anymore. If scripts are
written correctly without using those methods, then they will work
fine in the new engine. If not, then they need to be fixed manually.
In generally there are not a lot of scripts using those problematic
ways of accessing variables, but sometime scripters just use
copy & paste and so also copy the error to a lot of scripts. Then
the only solution will be to edit those scripts manually, copying
the fixed code part to the other affected scripts, or directly use
classes and the ''join'' function.

== Using the correct syntax ==

The new scripting engine finally reports syntax errors, when
modifying scripts you see the error output on RC chat (RC is
short for [[RC|RemoteControl]], an admin tool for Graal). If there
are errors while the npcserver is starting up, then the errors
are written in to logs/syntaxerrors.txt.
The new engine also reports errors while running the scripts,
including endless loops (loops are limited to 10000 cycles)
and call of non-existing functions. On clientside those
errors are output into the F2 window, on serverside they
are displayed on RC chat, but can also be redirected to
file using the [[server options|server option]] ''logscripterrorstofile=true'',
the errors will then appear in logs/scripterrors.txt.

While some people might get headache when seeing a lot of
script errors, that error reporting is actually giving you
the possibility to track errors easily. While the new engine
is not accepting as many syntax hacks as the old engine,
it is actually easier now to fix them.

=== Closing brackets ===

An error that often happens is a missing opening bracket or
missing closing bracket. The best way to not accidently do
that error is to follow a constant and ordered scripting
style, indenting scripting lines, using spaces between
operators. Each time you open a '''{''' bracket you indent the
following lines by 2 spaces. You can also use 4 spaces, that
doesn't matter as long as you keep the same number of spaces
in the whole script. Tabulators are not recommended since
special characters are automatically removed by the engine.
When you afterwards use a '''}''', then you stop the indenting.
That way you can check the correct number of opening and closing
brackets by just watching if the last closing bracket appears
at the very beginning of a line.
The Graal script compiler doesn't require that indenting, but it
is still recommended.

=== Semicolon ===

A thing that is quite simple to keep care of but is often
done wrong is to add semicolons behind commands. That must
be done to separate the commands from each other.
In the old scripting engine it was possible to forget the
semicolon if the next character was a closing bracket '''}'''.
The bracket was automatically finishing the last command.
In the new engine that it possible too as long as the last
command is a function call, it's not working if the last
command is an assignment:

<pre>
Bad: if (playerenters) {x=3}
Good: if (playerenters) {x=3;}
</pre>

Scripters also often think that a closing bracket '''}'''
never needs a semicolon behind it, although the semicolon is
required if the brackets are used for defining an array or
subscript:

<pre>
Bad: setshape2 2,2,{0,0,0,0}
Good: setshape2 2,2,{0,0,0,0};
</pre>

That mainly affects the function calls ''setshape2'', ''showpoly''
and ''putnpc2''. Those always require a semicolon at the end,
no matter if the function parameters are finishing with a
closing bracket '''}'''.

=== Syntax incompatibilities ===

While most old scripts compile fine when having no syntax
error, there is one exception when a correct old script
is not working with the new scripting engine: the
in-operator is different:

<pre>
Works in GS1: i = (playerx,playery in <20,40>);
Works in both: i = (playerx in <20,40> && playery in <20,40>);
Works in GS2: i = ({playerx,playery} in <20,40>);
</pre>

== Variable lookup ==

As described in chapter one, the variable lookup has been
changed in the new scripting engine. Lookup means the
behaviour how variable names are translated into actual
object attributes, or to be more close to the hardware,
lookup is the translation into memory addresses.
That means that a variable that was formerly connected
to one value, is now connected to another value, and
eventually having different behaviour when modifying it,
and is so changing the logic of the script or even
mess it up.

=== Example ===

Several scripts were using the variable ''this.x'' to store
temporary data, or just as for-loop variable.
While in the old engine ''this.x'' was just a numeric scripting
variable, it is now redirecting to the ''x'' value of the
current script object (''this''). So if you modify it, then
the npc is magically starting to move, which was
probably not the intention of the scripter.
In that case the variable name must be modified to something
like ''i'' or ''temp.i''.

=== Variable types in the new scripting engine ===

The new scripting engine (GS2) has basicly 3 types of variables:

* Object variables: objectname.variablename Object can be ''this'' for the current object, or ''player'' or an NPC name like ''DB_Items''. The variable will then access the attributes of the object if there is a built-in attribute with that name (e.g. ''this.x''), or a script variable belonging to that object (e.g. ''this.i'')

* Attributes of the active object: attributename If there is no leading, then the attributes of the current script object (for which the script is executed) are accessed, if there is an attribute with that name, e.g. ''x''.

* Global variables: variablename If the variable name has no leading and is not matching a built-in attribute of the current script object, then it is taken from the global variable pool. This is different to most other scripting languages where variables without leading are seen as local variables, but this behaviour is required to be compatible with the old scripting engine. Also it is a simple way to share data between scripts - you can set a flag in one script and read the flag in another script without needing to know where it is stored. Global variables are not saved, so they are not persistent and disappear after a server restart.

There are a few exceptions to this lookup scheme, e.g.
function parameters can be accessed without a leading in
front of the variable name. Also the ''with'' operator can
temporary modify the current script object (''this'').
In generally you don't need to care about those exceptions,
to be sure that everything is working fine you should
prefer to add a leading in front of variable names
though.

=== Change of variable lookup ===

==== Attributes of the current object ====

As described in chapter 3.1., the built-in attributes of the
current object can be accessed by ''this.x'', ''this.y'' etc. now.
In the old scripting engine that was not possible, those
variable names were used for normal variables. That means
if your scripts are using such variables, make sure that it is
used for the correct thing. That includes numeric variables
(''this.x = 3;'') as well as string variables (''setstring this.x,3;'');

Most common variables that need to be changed:
* ''this.x'', ''this.y'', ''this.dir'', ''this.hp'', ''this.ap''
* ''this.hp'' on serverside
* ''this.width'', ''this.height'', ''this.image''

==== Global variables ====

Variables without leading are global now. While on clientside
that was already the case in the old scripting engine, on
serverside those variables were formerly only accessible in the
current script. If you are using such variables, don't trust
that other scripts are not modifying it. Eventually rename
those variables, or use ''this.variables'' which are only working
for the current object, or ''temp.variables'' which are only working
in the current function body.

==== With-Operator ====

The ''with'' operator is temporary changing the current
script object (''this''): all ''this.'' variables inside the
opening and closing bracket are redirected to the
with-object instead of the executing script object.
Example:

<pre>
this.myvar = 3;
with (findplayer("Max")) {
this.myvar = 5;
}
</pre>

After executing that code, ''myvar'' of the npc has
the value 3, while ''myvar'' of the player "Max" has 5.
The player "Max" is the with-object in this case.
While both variables are accessed using the same
variable name, they are directing to different
variables.
In the old scripting engine ''this'' was only modified
when the with-object is another npc. In the new
engine any script object can overwrite ''this''.

Another thing that you need to keep care of is that you
can also access the built-in variables of the with-object
without using the ''this'' leading:

<pre>
x = 20;
with (findnpc("Turret")) {
x = 30;
}
</pre>

In this case the ''x'' position of the current npc will
be changed to 20, while the ''x'' position of the Turret
will be changed to 30.
The only exceptions for this behaviour are the variables
''x'', ''y'', ''dir'' and ''ap'' when using a player as
with-object: an ''x'' without leading will never direct
to the ''player.x'' variable, it will always take the
npc for which the script is executed, or the npc that is
positioned highest in the ''with''-stack when using several
''with''-operations inside each other.

=== Numeric variables, string variables and array using the same name ===

One major improvement in the new scripting engine is that
you can easier access string variables and arrays. One
drawback is that if you have used numeric variables, arrays or
string variables with the same name, those are now directing to
the same variable. So you will need to modify the variable
names if they are supposed to hold different data:

<pre>
Bad:
this.myvar = 1;
setstring this.myvar,2;
this.myvar = {1,2,3};

Good:
this.mynumericvar = 1;
this.mystringvar = "2";
this.myarrayvar = {1,2,3};
</pre>

== Easier access to string variables ==

You only need to read this chapter if you want to use the
new way of accessing string variables, it is not
required to make old scripts compatible.

String variables can be accessed easier now: 
Writing string variables:
<pre>
Old: setstring this.myvar,text;
New: this.myvar = "text";
</pre>

Reading string variables:
<pre>
Old: #s(this.mvyar)
New: this.myvar
</pre>

You can see that string variables can now be accessed
similar to numeric variables. Sometimes the variable
name must have a different leading though to access
the same variable:
<pre>
Old: setstring varwithoutleading,text;
New: player.varwithoutleading = "text";
</pre>

Also constructing dynamic variable names for string
variables is different now, you need to use the
new syntax. This documentation is not for explaining
the complete syntax, but it might help to lead you
to the correct path:
<pre>
Old: setstring this.item#v(itemnumber),apple;
New: this.("item" @ itemnumber) = "apple";
</pre>

You need to keep care on following things:
* you concat strings using @
* if you want to concat a string to another variable, don't forget to put "" around it to mark it as string
* never put a dot inside the dynamic variable name:
<pre>
Bad: ("this.item" @ itemnumber)
Good: this.("item" @ itemnumber)
Good: ("Party" @ partynumber).name
</pre>
* never use array brackets in the dynamic variable name:
<pre>
Bad: this.("item[" @ index @ "]")
Good: this.item[index]
Good: this.("itemstats_" @ itemnumber)[index]
</pre>

== Server-side and client-side ==

The new scripting engine is reporting the calls of
non-existing functions. As described in chapter 2,
you can redirect those error reports to file using
[[server options|server option]] ''logscripterrorstofile=true'', or you
set the variable ''this.scriptlogmissingfunctions'' to
false in case a script wants to call functions of
unknown objects and doesn't want to flood the
RC chat.
Still it is not good to call non-existing functions,
most of the time that function call actually
was meant to have a purpose and is causing problems
if it's not executed. In some cases the object
might have disappeared or was accessed using a
bad name.
It might also be possible that the function
actually doesn't exist: on many servers scripts
are executed on server-side which are meant for
client-side, and vice-versa. There are lists of
available scripting functions, check those if
you are not sure if the function is existing
([[Creation/Dev/Script Functions: NPC Server|Script Functions: NPC Server]], [[Creation/Dev/Script/Client|Script Functions: Client]]).

You can add a line ''//#CLIENTSIDE'' in front of a
script if it's meant for clientside execution,
or remove that line if its meant for serverside
executing. If you call the non-existing function
on the bad side but rely on executing that function,
then you will need to send a trigger to the other
side or modify a variable, which can be read on
the other side and reacted probably.

Common functions that are client-side only:
* '''play'''(soundfile);
* '''hurt'''(hurtpower);
* '''addtiledef'''(image,levelstart,tilestype)
* '''addtiledef2'''(image,levelstart,x,y)
* '''showtext'''(index,x,y,font,style,text); also ''showani'', ''showpoly'' etc. those might be added soon to serverside though, currently only ''showimg'' and ''changeimgcolors'' etc. is available on serverside

Common functions that are server-side only:
* '''setlevel2'''(levelname,newx,newy);
* '''putnpc2'''(newx,newy,script);

Creation/Dev/Script/Client

2007-07-01T07:49:05Z

Twinny:

=Client Supported Script Features=

==Settings==
{| border="1" cellpadding="2" width="100%"
| '''Name'''
| '''Type'''
| '''Description'''
|-
| $camera::movementspeed
| float
|
|-
| $pref::audio::choosenvoicecodec
| integer
|
|-
| $pref::audio::microactivatebyvolume
| boolean
|
|-
| $pref::audio::microactivationlevel
| integer
|
|-
| $pref::audio::microinputdevice
| integer
|
|-
| $pref::audio::microon
| boolean
|
|-
| $pref::audio::microvolumefactor
| integer
|
|-
| $pref::audio::midivolume
| integer
|
|-
| $pref::audio::mp3volume
| integer
|
|-
| $pref::audio::radiovolume
| integer
|
|-
| $pref::audio::reversestereo
| boolean
|
|-
| $pref::audio::sfxvolume
| integer
|
|-
| $pref::audio::voicevolume
| integer
|
|-
| $pref::graal::allowglobalpms
| boolean
|
|-
| $pref::graal::automapping
| boolean
|
|-
| $pref::graal::defaultfontsize
| integer
| Change showtext zoom: $pref::graal::defaultfontsize/24
|-
| $pref::graal::dontconnectlevels
| boolean
|
|-
| $pref::graal::dontloadlistheads
| boolean
|
|-
| $pref::graal::dontsavepasswords
| boolean
|
|-
| $pref::graal::dontsavepms
| boolean
|
|-
| $pref::graal::fixedport
| boolean
|
|-
| $pref::graal::fixedudpport
| integer
|
|-
| $pref::graal::language
| string
|
|-
| $pref::graal::limitnicknames
| boolean
|
|-
| $pref::graal::loadbuddylistfromserver
| boolean
|
|-
| $pref::graal::nicknamelimit
| integer
|
|-
| $pref::graal::nomassmessages
| boolean
|
|-
| $pref::graal::notoalls
| boolean
|
|-
| $pref::graal::noudp
| boolean
|
|-
| $pref::graal::showyourselfonbuddylists
| boolean
|
|-
| $pref::input::mousesensitivity
| float
|
|-
| $pref::interior::lockarrays
| boolean
|
|-
| $pref::terrain::enabledetails
| boolean
|
|-
| $pref::video::detailfactor
| float
|
|-
| $pref::video::fogdistance
| float
|
|-
| $pref::video::fullscreenmode
| string
|
|-
| $pref::video::screenshotformat
| string
|
|-
| $pref::video::visibledistance
| float
|
|-
| $pref::video::windowmode
| string
|
|-
| $scenelighting::lightingprogress
| float (read only)
|
|}

==Variables==
{| border="1" cellpadding="2" width="100%"
| '''Name'''
| '''Type'''
| '''Description'''
|-
| allfeatures
| integer (read only)
| for use with enablefeatures(), it's the default unless it is changed.
|-
| allplayerscount
| integer (read only)
| The size of the allplayers array.
|-
| allrenderobjecttypes
| integer (read only)
|
|-
| allstats
| integer (read only)
| A bitflag of all stats currently enabled
|-
| canspin
| boolean (read only)
| True if the player has spin attack
|-
| carriesblackstone
| boolean (read only)
| True if the player is carrying a black stone
|-
| carriesbush
| boolean (read only)
| True if the player is carrying a bush
|-
| carriesnpc
| boolean (read only)
| True if the player is carrying an NPC.
|-
| carriessign
| boolean (read only)
| True if a player is carrying a sign.
|-
| carriesstone
| boolean (read only)
| True if a player is carrying a stone.
|-
| carriesvase
| boolean (read only)
| True if a player is carrying a vase.
|-
| downloadfile
| string (read only)
| Name of the file currently being downloaded
|-
| downloadpos
| integer (read only)
| Amount of download file already downloaded
|-
| downloadsize
| integer (read only)
| Size of the file being downloaded
|-
| editingmission
| boolean
|
|-
| emoticonchar
| string (read only)
| The letter of the emoticon being displayed by the player
|-
| focusx
| float (read only)
| X coordinate of the center of playing screen in the level, offset -1.5
|-
| focusy
| float (read only)
| Y coordinate of the center of playing screen in the level, offset -2
|-
| graalversion
| float (read only)
| Graal version
|-
| gravity
| float
| Downward acceleration for projectiles ejected with the shoot() function.
|-
| iscarrying
| boolean (read only)
| True if the player is carrying anything
|-
| isfocused
| boolean (read only)
|
|-
| isgraal3d
| boolean (read only)
| True if you are running graal 3D
|-
| isleader
| boolean (read only)
| signifies that the player is the first person in the level
|-
| isonmap
| boolean (read only)
| signifies that the player is on a map
|-
| jpegquality
| integer
|
|-
| lastdownloadfile
| string (read only)
|
|-
| leftmousebutton
| boolean (read only)
| True if the left mouse button is down
|-
| levelorgx
| float (read only)
| The x-value of the levels' origin (may deviate with attachplayertoobj)
|-
| levelorgy
| float (read only)
| The y-value of the levels' origin (may deviate with attachplayertoobj)
|-
| lighteffectsenabled
| boolean (read only)
| signifies that the player has enabled light effects
|-
| weathereffectsenabled
| boolean (read only)
| signifies that the player has enabled weather effects
|-
| particleeffectsenabled
| boolean (read only)
| signifies that the player has enabled particle effects
|-
| middlemousebutton
| boolean (read only)
| True if the middle mouse button is down
|-
| mousebuttons
| integer (read only)
| Counts the amount of mousebuttons pressed
|-
| mousescreenx
| integer
| X coordinate of the mouse on the GUI layer
|-
| mousescreeny
| integer
| Y coordinate of the mouse on the GUI layer
|-
| mousewheeldelta
| integer (read only)
| Amount that the mouse scroll wheel was scrolled [(-) is up, (+) is down]
|-
| mousex
| float
| X coordinate of the mouse on the tile layer
|-
| mousey
| float
| Y coordinate of the mouse on the tile layer
|-
| musiclen
| integer (read only)
| The duration of the playing sound file
|-
| musicpos
| integer (read only)
| The position in the file at which the sound file is
|-
| rightmousebutton
| boolean (read only)
| True if the right mouse button is down
|-
| screenheight
| integer (read only)
| Height of the Graal window
|-
| screenwidth
| integer (read only)
| Width of the Graal window
|-
| scriptedcontrols
| boolean (read only)
|
|-
| scriptedplayerlist
| boolean (read only)
|
|-
| selectedlistplayers
| object
| an array of players highlighted on the playerlist
|-
| selectedsword
| integer
|
|-
| selectedweapon
| integer
| Index of player.weapons that references the player's current weapon
|-
| servername
| string (read only)
| Name of the current server
|-
| serverstartconnect
| string
|
|-
| serverstartparams
| string
|
|-
| shotbybaddy
| boolean (read only)
| True if the player was shot by a baddy
|-
| shotbyplayer
| boolean (read only)
| True if the player was shot by another player
|-
| showterraingrid
| boolean
|
|-
| timevar
| integer (read only)
| A timer which is increased each 5 seconds and is snychronized between server and clients; The timer started exactly on 2001-02-01 at 18:33:34 Paris time (opening of Graal2001); on serverside the unixtime (timevar2) is around 981048814 + timevar*5
|-
| timevar2
| float (read only)
| Unix-time with a very high precision, not synchronized between server and client
|-
| timevar3
| float (read only)
| synchronized time which works on both server- and client-side, precision is milliseconds, only available for Graal3D right now
|-
| wasshooted
| boolean (read only)
|
|-
| waterheight
| float
| The height of water at the player's (x,y) on a terrain
|-
| weapons
| object (read only)
| An array of weapon objects
|-
| weaponsenabled
| boolean
| Are weapons enabled? (Player can trigger onWeaponFired...)
|-
| worldclockstopped
| boolean
|
|-
| worldhour
| integer
|
|-
| worldminute
| float
|
|-
| worldminutesofday
| float
|
|-
| worldrealsecondsperday
| float
|
|}

==Variable Prefixes==
{| border="1" cellpadding="2" width="100%"
| '''Prefix'''
| '''Description'''
|-
| object.var
| accesses the variables of the object. The object can be retrieved by using the case-sensitive name of the object or a variable pointing to the object.
|-
| this.var
| variables that belong to the current script object, on the server-side they are saved to file when the object is a database npc
|-
| thiso.var
| refer to the this. variables of the executing npc ('o' stands for original) when you use the with () command: with (findnpc("npc2")) thiso.temp = this.temp; will copy 'this.temp' from npc2 to the current npc
|-
| temp.var
| variables that belong to the current function. They can be used anywhere in the function even when referencing another object. Function parameters are declared as temp variables if they do not have a prefix. Temp variables will be destroyed at the end of the function.
|-
| player.var
| variables of the current player object, when the event was invoked by a player (e.g. playertouchsme), or you do with (findplayer(accountname))
|-
| playero.var
| variables of the original player object, in generally the player who has invoked the event (e.g. playertouchsme)
|-
| client.var
| short for player.client.var, variables that can be changed on server-side and client-side
|-
| clientr.var
| short for player.clientr.var, variables that can only be changed on server-side but can be read on client-side
|-
| server.var
| variables that only exists on server-side and can be accessed by all npcs
|-
| serverr.var
| variables that can only be changed on server-side and is server wide, but can also be read by all clients, so it can be used for storing the state of global activities that need client-side actions like displaying weather; like server. vars they can also be changed with remotecontrol.exe by administrators that have the right to change server. variables
|-
| level.var
| variables of the current level, which is the level the executing npc stands in (on server-side) or the player is in (on client-side)
|}

==Functions==
''Note: Currently this doesn't list the functions which are optimized at compile time, see [[Creation/Dev/Script/Starting_Guide#Standard_functions|Starting Guide: Standard functions]] for those.''

===Common===
* aindexof(float, array) - returns integer, better use array.index(float) instead
* echo(str text) - prints text in the F2 window (clientside) or RC chat (serverside)
* getbasepackage() - returns [[Creation/Dev/Script/Client/TUpdatePackage|TUpdatePackage]] object
* getdownloadedupdatepackagesize() - returns integer
* getdownloadingpackage() - returns [[Creation/Dev/Script/Client/TUpdatePackage|TUpdatePackage]] object
* getdownloadingpackagescount() - returns integer
* gethttprequest(str, int, str) - returns [[Creation/Dev/Script/Client/THTTPRequest|THTTPRequest]] object
* getkeycode(str keyname) - returns integer
* getpackagesdownloadcomplete() - returns boolean
* getpackagesdownloaded() - returns boolean
* getplatform() - returns string
* getservername() - returns string
* gettotalupdatepackagesize() - returns integer
* getupdatepackage(str) - returns object
* isadminguild(str guildname) - returns boolean
* isobject(str objectname) - returns boolean, checks if an object is existing
* keydown(int keynumber) - returns if the specified key is pressed (0..10: up, left, down, right, S, A, D, M, tab, Q, P)
* keydown2(int keycode, bool ignorecase) - returns boolean
* keyname(int keycode) - returns string
* opengraalurl(str url) - opens a website of www.graalonline.com and automatically lets the player login to it (e.g. for the upgrade page or screenshot section)
* openurl(str url)
* openurl2(str url, int width, int height) - deprecated, width and height are ignored
* requesthttp(str, int, str) - returns [[Creation/Dev/Script/Client/THTTPRequest|THTTPRequest]] object
* requesttext(str type, str option)
* requesturl(str url) - returns [[Creation/Dev/Script/Client/THTTPRequest|THTTPRequest]] object
* savelog(str text)
* savelog2(str filename, str text) - adds a log entry to "logs/filename"
* sendrpgmessage(str text) - adds text to the F2 window
* sendtext(str type, str option, params...)
* sendtorc(str text) - serverside only, displays text on the RC chat
* serverwarp(str servername) - the name can either be the internal name (graal2002) or part of the server name on the serverlist

====Files====
* extractfilebase(str filepath) - returns string, '/an/example/path/and/file' would return '/an/example/path/and/'
* extractfileext(str filepath) - returns string, 'filename.ext' would return '.ext'
* extractfilename(str filepath) - returns string, '/an/example/path/and/file' would return 'file'
* extractfilepath(str filepath) - returns string, '/an/example/path/and/file' would return '/an/example/path/and/'
* fileexists(str filepath) - returns boolean, checks if a file exists
* filesize(str filepath) - returns integer, returns the size of a file
* fileupdate(str filepath) - returns boolean, checks if a file is existing and requests an update from the server if it has not been checked yet
* findfiles(str filenamepattern, flags) - returns array of strings, flags can be either 1 for recursive search or 0 for non-recursive
* freefileresources(str)
* getextension(str filepath) - returns string, 'filename.ext' would return '.ext'
* requestfiledeletion(str filepath), requests a file to be deleted on the server
* requestfilerename(str filepath, str newfilepath), requests a file to be renamed on the server
* requestfilesmove(str filepath, str newfilepath), requests a file to be moved on the server
* selectfilefordownload(str filter)
* selectfileforupload()

''Watch the [[Creation/Dev/Script/Client/TGraalVar|TGraalVar]] object for loading and saving of files (loadlines etc.)''

''See more information about input/output at [[Creation/Dev/Output Methods|Output methods]]''

====Math====
* degtorad(float value) - returns float
* radtodeg(float value) - returns float

=====Matrices=====
GraalScript [[Matrix|matricies]] are arrays of seven elements: three describing translation (position), three describing the rotation axis, and one describing the angle.
* [[Matrix#matrixcreate()|matrixcreate]](str vector, str rotation) - returns matrix string
* matrixcreatefromeuler(str eulerrotation) - returns matrix string
* matrixmulpoint(str, str) - returns string
* matrixmultiply(str matrix, str matrix) - returns matrix string
* matrixmulvector(str matrix, str vector) - returns vector string

=====Vectors=====
Each [[Vectors|vector]] is basicly an array of format {x,y,z} but is passed as string for simplicity. Click on the function names to see more information about the vector operations.
* [[Vectors#Vector_Addition|vectoradd]](vector, vector) - returns vector
* [[Cross Product|vectorcross]](vector, vector) - returns vector
* [[Vectors#Distance_Between_Terminal_Points|vectordist]](vector, vector) - returns float
* [[Dot Product|vectordot]](vector, vector) - returns float
* [[Vectors#Vector_Length_.28Magnitude.29|vectorlen]](vector) - returns float
* [[Vectors#Unit_Length|vectornormalize]](vector) - returns vector, scales the vector to length 1
* vectororthobasis(vector) - returns vector
* [[Vectors#Vector-Scalar_Multiplication|vectorscale]](vector, float) - returns vector
* [[Vectors#Vector_Subtraction|vectorsub]](vector, vector) - returns vector

====Strings====
* base64decode(str text) - returns decoded string
* base64encode(str text) - returns encoded string
* checksum(str text) - returns checksum float
* contains(str haystack, str needle) - returns boolean, you should probably do haystack.contains(needle) instead
* getascii(str character) - returns ascii value integer
* getstringkeys(str leading) - searchs for variables which start with the specified string and returns and array of their ending
* lowercase(str text) - returns lowercased string, it is recommended to use string.lower() though
* md5(str text) - returns md5 hash string
* randomstring(array of strings) - returns string
* strcmp(str text1, str text2) - returns integer
* strequals(str text1, str text2) - returns boolean, you probably should do text1.equals(text2) instead
* uppercase(str text) - returns uppercased string, it is recommended to use string.upper() though

===GUI===
* addcontrol(obj) - adds a GUI control or a 3D-object to the scene
* cursoroff()
* cursoron()
* iscursoron() - returns boolean
* popdialog() - removes the top dialog control
* pushdialog(obj) - displays a control on top of all other controls, this control gains all focus until it is removed again
* setcontentcontrol(obj) - replaces the current content control (usually named GUIContainer) with another one

===Graal 2D===
{| border="1" cellpadding="2" width="100%"
| '''Name'''
| '''Type'''
| '''Description'''
|-
| addtiledef(str tilesetimage, str prefix, int tilesettype)
|
| Sets the tileset image for levels beginning with the specified prefix.
Tileset type 0 is for pics1.png style tilesets.
Tileset type 1 is for the new tileset format (Era's tiles for example)
|-
| addtiledef2(str tilesetimage, str prefix, int x, int y)
|
| Replaces a section of the tileset (x, y) image for levels beginning with the specified prefix.
|-
| attachplayertoobj(int objtype, int id)
|
| Attaches a player to the specified object. Using attachpayertoobj(0, id); the player will be attached to the current NPC.
|-
| callnpc(int npcindex, params...)
|
| Invokes an event on an npc, better use npcs[npcindex].trigger(event, params) instead; you can only trigger objects this way that are on your side of clientside/serverside
|-
| callweapon(int weaponindex, params...)
|
| Invokes a trigger on a weapon, better use weapons[weaponindex].trigger(event, params) instead
|-
| detachplayer()
|
| Puts the player back on the level (after using attachplayertoobj).
|-
| disabledefmovement()
|
| Disables the default movement.
|-
| disablemap()
|
| Disables the default map
|-
| disablepause()
|
| Disables pausing.
|-
| disableselectweapons()
|
| Disables the default Q menu.
|-
| disableweapons()
|
| Disables weapons.
|-
| enabledefmovement()
|
| Enables default movement
|-
| enablefeatures(int flags)
|
| Enable/disable client features

Flags can consist of:
{| border="1" cellpadding="2" width="100%"
| '''Value'''
| '''Description'''
|-
| 1
| M key (map)
|-
| 2
| P key (pause)
|-
| 4
| Q key (weapon select)
|-
| 8
| R key (show ratings)
|-
| 0x10
| S+A key combination for dropping items
|-
| 0x20
| S+D key combination for switching weapons
|-
| 0x40
| TAB key (if disabled then you cannot switch to the chat field with TAB)
|-
| 0x80
| Display of chat text
|-
| 0x100
| Display of the hearts over player heads
|-
| 0x200
| Display of nicknames
|-
| 0x400
| Toall/PM-icons on the minimap
|-
| 0x800
| Right-click on players opens their profile
|-
| 0x1000
| Emoticons (disable it if you want to do other stuff with control+keys)
|-
| 0x2000
| Alt+5 for making snapshots ''(deprecated)''
|-
| 0x4000
| Alt+8/9 for zooming ''(deprecated)''
|-
| 0x8000
| Allows F2 output (savelog()/echo())
|-
| allfeatures
| All of the previously stated feature flags enabled
|}
|-
| enablemap()
|
| Enables default map.
|-
| enablepause()
|
| Enables pausing.
|-
| enableselectweapons()
|
| Enables default Q menu.
|-
| enableweapons()
|
| Enables weapons.
|-
| explodebomb(int bombindex)
|
| Explodes a bomb with the specified index.
|-
| findani(str)
| [[Creation/Dev/Script/Client/TGraalAni|TGraalAni]] object
|
|-
| findlevel(str levelfilename)
| [[Creation/Dev/Script/Client/TServerLevel|TServerLevel]] object
|
|-
| findplayer(str accountname)
| [[Creation/Dev/Script/Client/TServerPlayer|TServerPlayer]] object
| Returns player object of Account specified. Player must be online.
|-
| findplayerbyid(int playerid)
| [[Creation/Dev/Script/Client/TServerPlayer|TServerPlayer]] object
| Returns player object of id specified. If id isn't available, returns false.
|-
| findweapon(str weaponname)
| [[Creation/Dev/Script/Client/TServerWeapon|TServerWeapon]] object
| Returns weapon object of the specified name if the player has that weapon.
|-
| findweaponnpc(str weaponname)
| [[Creation/Dev/Script/Client/TServerWeapon|TServerWeapon]] object
| Returns weapon object if it exits on the server, only works on server-side. You can normally also access weapons by just typing their name though (e.g. MyWeapon.functionname() instead of findweaponnpc("MyWeapon").functionname())
|-
| freezeplayer(float seconds)
|
| Freezes player for a specific amount of time.
|-
| getimgheight(str imagefilename)
| integer
| Returns the height (in pixels) of an image.
|-
| getimgwidth(str imagefilename)
| integer
| Returns the width (in pixels) of an image.
|-
| getmapx(str levelname)
| integer
| X coordinate of the level on a map (top-left level is 0)
|-
| getmapy(str levelname)
| integer
| Y coordinate of the level on a map (top-left level is 0)
|-
| gettextheight(float, str, str)
| integer
| Returns the height of the font. Format:
gettextheight(zoom, font, style)
|-
| gettextwidth(float, str, str, str)
| integer
| Returns the width of a specified text in a certain font. Format:
gettextwidth(zoom, font, style, text)
|-
| getz(float x, float y)
| float
| Returns the z value of a terrain at (x,y).
|-
| graalcontrolhasfocus(bool)
| boolean
| parameter says if it should also check if the chat bar has the focus
|-
| hideplayer(float seconds)
|
| Hides the player for ''seconds'' seconds.
|-
| hidesword(float seconds)
|
| Hides the player's sword for ''seconds'' seconds.
|-
| hitnpc(int, float, float, float)
|
|
|-
| hitobjects(float, float, float)
|
|
|-
| hitplayer(int, float, float, float)
|
|
|-
| lay2(str extraname, float x, float y)
|
|
|-
| loadmap(str mapfilename)
|
| Preloads a gmap on clientside, speeds up entering of new maps but is not required.
|-
| noplayerkilling()
|
| Disables killing of other players. This also lets players walk through other players (players are not blocking anymore).
|-
| onwall(float x, float y)
| boolean
| Returns true if the specified x and y is a blocking tile.
|-
| onwall2(float x, float y, float width, float height)
| boolean
| Returns true if a blocking tile exists in the specified area.
|-
| onwater(float x, float y)
| boolean
| Returns true if the specified x and y is water.
|-
| onwater2(float x, float y, float width, float height)
| boolean
| Returns true if water exists in the specified area.
|-
| play(str soundfilename)
|
| Plays the specified sound file.
|-
| play2(str soundfilename, float x, float y, float volume)
|
| Plays the specified sound file at location x, y with the specified volume. Volume should be between 0 and 1, if volume is set to 1 default volume is used (depending on how far away the player is).
|-
| playlooped(str soundfilename)
|
| Plays the specified sound file in a loop until stopsound() is called.
|-
| playlooped2(str soundfile, float x, float y, float volume)
|
| Plays the specified sound file at location x, y with the specified volume in a loop until stopsound() is called. Volume should be between 0 and 1, if volume is set to 1 default volume is used (depending on how far away the player is).
|-
| putleaps(int leapstype, float x, float y)
|
|
|-
| removetiledefs(str prefix)
|
| Remove tile definitions set by addtiledef and addtiledef2 for the specified prefix.
|-
| replaceani(str defaultaniname, str newaniname)
|
| replaces the player's default ani with the new ani.
|-
| resetfocus()
|
| Sets the screen focus to the player (default focus behaviour).
|-
| say(int signindex)
|
|
|-
| say2(str text)
|
|
|-
| screenx(float x, float y)
| integer
| returns the x of the screen layer for a location on the tiles layer.
|-
| screeny(float x, float y)
| integer
| returns the y of the screen layer for a location on the tiles layer.
|-
| worldx(float x, float y)
| float
| returns the x of the tiles layer for a location on the screen layer.
|-
| worldy(float x, float y)
| float
| returns the y of the tiles layer for a location on the screen layer.
|-
| setani(str aniname, str aniparams)
|
| Sets the gani of a player.
|-
| setbeltcolor(str color)
|
|
|-
| setcoatcolor(str color)
|
|
|-
| seteffect(float red, float green, float blue, float alpha)
|
| Displays a 'day-night' effect on top of the game. Default value is (0,0,0,0). Change alpha to make the screen darker. You can reach the same effect if you use a polygon (showpoly()) and set the mode to 3. To manipulate the color of a single npc, see setcoloreffect() for [[Creation/Dev/Script/Client/TServerNPC|TServerNPC]].
|-
| setfocus(float x, float y)
|
| Sets the screen focus to the specified x and y. Use resetfocus() to switch back to the default focus behaviour.
|-
| setgender(str gendername)
|
| Sets the gender of a player.
|-
| sethead(str imagefilename)
|
| Sets the head of a player
|-
| setletters(str imagefilename)
|
| Sets the image to use for sign background and text.
|-
| setmap(str, str, float, float)
|
|
|-
| setminimap(str, str, float, float)
|
|
|-
| setmusicvolume(float, float)
|
|
|-
| setplayerdir(str)
|
|
|-
| setshield(str imagefilename, int shieldpower)
|
|
|-
| setshoecolor(str color)
|
|
|-
| setshootparams(str params)
|
|
|-
| setskincolor(str color)
|
|
|-
| setsleevecolor(str color)
|
|
|-
| setsword(str imagefilename, int swordpower)
|
|
|-
| showstats(int statsflag)
|
| With this you can show/hide parts of the status bar / game

Examples:
<pre>
// Shows all
showstats(allstats);

// Enable everything except minimap
showstats(allstats & ~0x100);

// Enable everything except AP and MP bars
showstats(allstats & ~(0x40 | 0x80));

// Enable only players and right-click profile
showstats(0x400 | 0x800);

// Hides all
showstats(0);
</pre>

Flags can consist of:
{| border="1" cellpadding="2" width="100%"
| '''Value'''
| '''Description'''
|-
| 1
| ASD
|-
| 2
| Icons (for rupees, bombs, arrows)
|-
| 4
| Rupees count
|-
| 8
| Bombs count
|-
| 0x10
| Arrows count
|-
| 0x20
| Hearts
|-
| 0x40
| Alignment (ap) bar
|-
| 0x80
| Magic points (mp) bar
|-
| 0x100
| Minimap (you can only hide it, you can't show it when the player pressed Alt+3)
|-
| 0x200
| Inventory NPCs
|-
| 0x400
| Players
|-
| 0x800
| Right-click on players opens their profile
|-
| allstats
| All of the previously stated stats flags enabled
|}
|-
| spyfire(int length, int power)
|
| Shoots a line of fire in the direction of the player with the specified tile length, and fire power (1 - bomb, 2 - super bomb, 3 - jolt bomb).
|-
| stopmidi()
|
|
|-
| stopsound(str soundfilename)
|
| Stop playing a sound started by playlooped
|-
| takeplayercarry()
|
|
|-
| takeplayerhorse()
|
|
|-
| testplayer(float x, float y)
| integer
| checks if there is a player on that position and returns the index of the player in players[], or -1 if there is none
|-
| triggeraction(float x, float y, str eventname, params...)
|
| Invokes an "onActionEventname" event on objects at the specified position, can be used to invoke events on objects from clientside to serverside and vice versa.
Special eventnames are "serverEventname" which will invoke an event on the Control-NPC (onActionEventname), or "serverside" which will invoke an onActionServerSide event on the weapon script specified by the first following parameter (the fourth parameter). It is recommended to use triggerserver() for that though.

Example:
<pre>
triggeraction(30, 30, "explode", 5);
triggeraction(0, 0, "serverchat", player.chat);
triggeraction(0, 0, "serverside", "PlasmaGun", "activate");
</pre>
|-
| triggerserver(str objecttype, str objectname, str params)
|
| Invokes an event on a serverside object, currently objecttype can only be "gui" or "weapon" (which is the same), objectname is the name of the weapon script, the invoked event will be "onActionServerSide".
On Graal3D the event will be "onActionParam0" instead.
For invoking events on the clientside use player.triggerclient(objecttype,objectname,params) instead.

Example:
<pre>
triggerserver("weapon", "PlasmaGun", "activate");
</pre>
|-
| updateboard(int x, int y, int width, int height)
|
|
|-
| updateratings(obj)
| object
| Updates an array of {rating1,ratingdeviation1, rating2,ratingdeviation2, ...}, init them at 1500 and 350.
Example:
<pre>
newratings = updateratings({winner.rating,winner.ratingd,loser.rating,loser.ratingd});
winner.rating = newratings[0];
winner.ratingd = newratings[1];
loser.rating = newratings[2];
loser.ratingd = newratings[3];
</pre>
|-
| wraptext(int fontsize, str format, str text)
| array of strings
|
|-
| wraptext2(int pixelwidth, float zoom, str delimiters, str text)
| array of strings
| wraps the text so that it fits in the specified number of pixels and returns an array of text lines
|}

===Graal 3D===
* getboxcenter(str box) - returns string
* get3dobjectat(float x, float y, bool doboxcollision) - returns object - gets the 3d object at the specified screen position, third parameter says if it should do box collision
* get3dobjectatmouse(bool doboxcollision) - returns object - gets the 3d object at the mouse, specify if it should do box collision (true)
* get3dobjectbyray(str vector, str vector) - returns object
* lightscene() - returns boolean
* setfogcolors(array)
* setinteriorrendermode(int)
* setskybandcolors(array)
* setskybandsizes(array)
* setsuncolors(array)
* setterrainrendermode(int)
* synctimeofday(float hour, float minute)
* updateterrain()
* updatevisibledistance()

===Other===
* adventure_installgraal(str, bool, bool)
* adventure_openexternaloptions() - returns boolean
* adventure_openexternalpm(obj) - returns boolean
* adventure_openserverlist()
* adventure_quit()
* adventure_reconnect()
* adventure_savegraaloptions()
* adventure_selectpath(str) - returns object
* adventure_setaccountname(str)
* adventure_setchat(str)
* adventure_setnickname(str)
* adventure_setpassword(str)
* adventure_startofflinemode()
* adventure_updateaccountfield()
* adventure_updatemicroactivationlevel()
* adventure_updatemidivolume()
* adventure_updatemp3volume()
* adventure_updateplayermuted()
* adventure_updateplayerprofile(bool, str, str, int, str, str, str, str, str, str)
* adventure_updateradiovolume()

''(these functions are only available to privileged scripts from the Login server)''

==Classes / Object Types==
* [[Creation/Dev/Script/Client/TGraalVar|TGraalVar]]
** [[Creation/Dev/Script/Client/ActionMap|ActionMap]]
** [[Creation/Dev/Script/Client/DTSAniThread|DTSAniThread]]
** [[Creation/Dev/Script/Client/GameMovementInterpolate|GameMovementInterpolate]]
*** [[Creation/Dev/Script/Client/GameMovementRigid|GameMovementRigid]]
** [[Creation/Dev/Script/Client/GameMovementList|GameMovementList]]
** [[Creation/Dev/Script/Client/GameShape|GameShape]]
*** [[Creation/Dev/Script/Client/GameShape3DS|GameShape3DS]]
*** [[Creation/Dev/Script/Client/GameShapeDIF|GameShapeDIF]]
*** [[Creation/Dev/Script/Client/GameShapeDTS|GameShapeDTS]]
*** [[Creation/Dev/Script/Client/GameShapeFT|GameShapeFT]]
** [[Creation/Dev/Script/Client/GuiControl|GuiControl]]
*** [[Creation/Dev/Script/Client/GuiArrayCtrl|GuiArrayCtrl]]
**** [[Creation/Dev/Script/Client/GuiTextListCtrl|GuiTextListCtrl]]
**** [[Creation/Dev/Script/Client/GuiTreeViewCtrl|GuiTreeViewCtrl]]
*** [[Creation/Dev/Script/Client/GuiBitmapButtonCtrl|GuiBitmapButtonCtrl]]
*** [[Creation/Dev/Script/Client/GuiBitmapCtrl|GuiBitmapCtrl]]
**** [[Creation/Dev/Script/Client/GuiMapOverviewCtrl|GuiMapOverviewCtrl]]
*** [[Creation/Dev/Script/Client/GuiButtonBaseCtrl|GuiButtonBaseCtrl]]
**** [[Creation/Dev/Script/Client/GuiButtonCtrl|GuiButtonCtrl]]
**** [[Creation/Dev/Script/Client/GuiCheckBoxCtrl|GuiCheckBoxCtrl]]
***** [[Creation/Dev/Script/Client/GuiRadioCtrl|GuiRadioCtrl]]
*** [[Creation/Dev/Script/Client/GuiChunkedBitmapCtrl|GuiChunkedBitmapCtrl]]
*** [[Creation/Dev/Script/Client/GuiContextMenuCtrl|GuiContextMenuCtrl]]
*** [[Creation/Dev/Script/Client/GuiDrawingPanel|GuiDrawingPanel]]
*** [[Creation/Dev/Script/Client/GuiFlash|GuiFlash]]
*** [[Creation/Dev/Script/Client/GuiFrameSetCtrl|GuiFrameSetCtrl]]
*** [[Creation/Dev/Script/Client/GuiGraal3DCtrl|GuiGraal3DCtrl]]
*** [[Creation/Dev/Script/Client/GuiGraalCtrl|GuiGraalCtrl]]
*** [[Creation/Dev/Script/Client/GuiMenuCtrl|GuiMenuCtrl]]
*** [[Creation/Dev/Script/Client/GuiMLTextCtrl|GuiMLTextCtrl]]
**** [[Creation/Dev/Script/Client/GuiMLTextEditCtrl|GuiMLTextEditCtrl]]
***** [[Creation/Dev/Script/Client/GuiPMEditCtrl|GuiPMEditCtrl]]
**** [[Creation/Dev/Script/Client/GuiPMCtrl|GuiPMCtrl]]
**** [[Creation/Dev/Script/Client/GuiPMHistoryCtrl|GuiPMHistoryCtrl]]
*** [[Creation/Dev/Script/Client/GuiPlayerView|GuiPlayerView]]
*** [[Creation/Dev/Script/Client/GuiProgressCtrl|GuiProgressCtrl]]
*** [[Creation/Dev/Script/Client/GuiScrollCtrl|GuiScrollCtrl]]
*** [[Creation/Dev/Script/Client/GuiShapeNameHud|GuiShapeNameHud]]
*** [[Creation/Dev/Script/Client/GuiShowImgCtrl|GuiShowImgCtrl]]
*** [[Creation/Dev/Script/Client/GuiSliderCtrl|GuiSliderCtrl]]
*** [[Creation/Dev/Script/Client/GuiStretchCtrl|GuiStretchCtrl]]
*** [[Creation/Dev/Script/Client/GuiTabCtrl|GuiTabCtrl]]
*** [[Creation/Dev/Script/Client/GuiTextCtrl|GuiTextCtrl]]
**** [[Creation/Dev/Script/Client/GuiPopUpEditCtrl|GuiPopUpEditCtrl]]
**** [[Creation/Dev/Script/Client/GuiPopUpMenuCtrl|GuiPopUpMenuCtrl]]
**** [[Creation/Dev/Script/Client/GuiTextEditCtrl|GuiTextEditCtrl]]
***** [[Creation/Dev/Script/Client/GuiTextEditSliderCtrl|GuiTextEditSliderCtrl]]
**** [[Creation/Dev/Script/Client/GuiWindowCtrl|GuiWindowCtrl]]
*** [[Creation/Dev/Script/Client/TerrainEditor|TerrainEditor]]
*** [[Creation/Dev/Script/Client/WorldEditor|WorldEditor]]
** [[Creation/Dev/Script/Client/GuiControlProfile|GuiControlProfile]]
** [[Creation/Dev/Script/Client/GuiCursor|GuiCursor]]
** [[Creation/Dev/Script/Client/GuiTabCtrlEntry|GuiTabCtrlEntry]]
** [[Creation/Dev/Script/Client/GuiTextListEntry|GuiTextListEntry]]
** [[Creation/Dev/Script/Client/GuiTreeViewNode|GuiTreeViewNode]]
** [[Creation/Dev/Script/Client/MRandomGenerator|MRandomGenerator]]
*** [[Creation/Dev/Script/Client/MRandomLCG|MRandomLCG]]
*** [[Creation/Dev/Script/Client/MRandomR250|MRandomR250]]
** [[Creation/Dev/Script/Client/SimObject|SimObject]]
*** [[Creation/Dev/Script/Client/SceneObject|SceneObject]]
**** [[Creation/Dev/Script/Client/fxSunLight|fxSunLight]]
**** [[Creation/Dev/Script/Client/GameObject|GameObject]]
***** [[Creation/Dev/Script/Client/Camera|Camera]]
***** [[Creation/Dev/Script/Client/DynamicShapeReplicator|DynamicShapeReplicator]]
****** [[Creation/Dev/Script/Client/DynamicGrass|DynamicGrass]]
****** [[Creation/Dev/Script/Client/DynamicGrassReplicator|DynamicGrassReplicator]]
**** [[Creation/Dev/Script/Client/Sky|Sky]]
**** [[Creation/Dev/Script/Client/TerrainBlock|TerrainBlock]]
**** [[Creation/Dev/Script/Client/twSurfaceReference|twSurfaceReference]]
**** [[Creation/Dev/Script/Client/WaterBlock|WaterBlock]]
*** [[Creation/Dev/Script/Client/SimGroup|SimGroup]]
**** [[Creation/Dev/Script/Client/GameConnection|GameConnection]]
*** [[Creation/Dev/Script/Client/Sun|Sun]]
** [[Creation/Dev/Script/Client/TDrawableObject|TDrawableObject]]
*** [[Creation/Dev/Script/Client/TBaddy|TBaddy]]
*** [[Creation/Dev/Script/Client/TLevelObject|TLevelObject]]
**** [[Creation/Dev/Script/Client/TExplosion|TExplosion]]
**** [[Creation/Dev/Script/Client/TGaniObject|TGaniObject]]
***** [[Creation/Dev/Script/Client/TProjectile|TProjectile]]
***** [[Creation/Dev/Script/Client/TServerHorse|TServerHorse]]
***** [[Creation/Dev/Script/Client/TServerPlayer|TServerPlayer]]
****** [[Creation/Dev/Script/Client/TPlayer|TPlayer]]
****** [[Creation/Dev/Script/Client/TServerNPC|TServerNPC]]
******* [[Creation/Dev/Script/Client/TServerWeapon|TServerWeapon]]
**** [[Creation/Dev/Script/Client/TServerBomb|TServerBomb]]
**** [[Creation/Dev/Script/Client/TServerCarry|TServerCarry]]
**** [[Creation/Dev/Script/Client/TServerChest|TServerChest]]
**** [[Creation/Dev/Script/Client/TServerExtra|TServerExtra]]
**** [[Creation/Dev/Script/Client/TServerFlying|TServerFlying]]
**** [[Creation/Dev/Script/Client/TServerLeap|TServerLeap]]
**** [[Creation/Dev/Script/Client/TServerSign|TServerSign]]
**** [[Creation/Dev/Script/Client/TShowImg|TShowImg]]
** [[Creation/Dev/Script/Client/TDrawingPanel|TDrawingPanel]]
** [[Creation/Dev/Script/Client/Terraformer|Terraformer]]
** [[Creation/Dev/Script/Client/TFrameDetail|TFrameDetail]]
** [[Creation/Dev/Script/Client/TGaniParam|TGaniParam]]
** [[Creation/Dev/Script/Client/TGraalAni|TGraalAni]]
** [[Creation/Dev/Script/Client/TGraalAniPart|TGraalAniPart]]
** [[Creation/Dev/Script/Client/TGraalAniSound|TGraalAniSound]]
** [[Creation/Dev/Script/Client/TGraalAniSprite|TGraalAniSprite]]
** [[Creation/Dev/Script/Client/TGraalAniStep|TGraalAniStep]]
** [[Creation/Dev/Script/Client/TGraalSpriteAttachment|TGraalSpriteAttachment]]
** [[Creation/Dev/Script/Client/THTTPRequest|THTTPRequest]]
** [[Creation/Dev/Script/Client/TMovementRigid|TMovementRigid]]
** [[Creation/Dev/Script/Client/TParticle|TParticle]]
** [[Creation/Dev/Script/Client/TParticleEmitter|TParticleEmitter]]
** [[Creation/Dev/Script/Client/TParticleModifier|TParticleModifier]]
** [[Creation/Dev/Script/Client/TServerLevel|TServerLevel]]
** [[Creation/Dev/Script/Client/TServerLevelLink|TServerLevelLink]]
** [[Creation/Dev/Script/Client/TShapeMaterial|TShapeMaterial]]
** [[Creation/Dev/Script/Client/TShowImg_Values|TShowImg_Values]]
*** [[Creation/Dev/Script/Client/TShowImg_Flash|TShowImg_Flash]]
*** [[Creation/Dev/Script/Client/TShowImg_Gani|TShowImg_Gani]]
*** [[Creation/Dev/Script/Client/TShowImg_Image|TShowImg_Image]]
*** [[Creation/Dev/Script/Client/TShowImg_Shape|TShowImg_Shape]]
*** [[Creation/Dev/Script/Client/TShowImg_Poly|TShowImg_Poly]]
*** [[Creation/Dev/Script/Client/TShowImg_Text|TShowImg_Text]]
** [[Creation/Dev/Script/Client/TStaticVar|TStaticVar]]
** [[Creation/Dev/Script/Client/TTilesLayer|TTilesLayer]]
** [[Creation/Dev/Script/Client/TUpdatePackage|TUpdatePackage]]

Creation/Dev/Script/Starting Guide

2007-07-01T07:47:42Z

Twinny:

== Introduction ==

=== Why scripts ===

Scripts bring life into objects and make it easy to
customize the game. Instead of just placing a stone
into your world, you can make it so that the stone
can be lifted or kicked. Instead of being limited to
some fixed player movement you can rescript it
to let the player jump, strafe and duck. To let the
player inspect and organize his/her items you can
create some dialogs and display those by script,
e.g. when the player presses a special key.

In Graal the scripting is done in 'Graal Script',
it's looking like Java/C++, but brings some
additional features for making things easier
for game creators, while on the other hand
running in a sandbox and limiting access to
game-related stuff only.

Graal Script is almost fully compatible to
the 'old' Graal script used in Graal v1.0 - 3.0,
and is partially compatible to Torque script.

=== NPCs and 'weapons' ===

There are generally two types of objects in Graal
which have scripts: The first type are the
non-player-characters (NPCs). The name 'NPC' is
actually used for all visible objects in the game:
monsters, stones, bushes, houses, ships, plants etc.
Scripts for npcs are most of the time containing
code for moving the npc or for reacting to
activities of the player, e.g. giving money to
the player when he/she grabs the npc.
The other type of script-holding objects are the
'weapons'. Those are items in the inventory of
the player, not necessary being weapons. Most of
the time they are actually just scripts which
control the movement of the player, display weapon
graphics, or display menus.

So there are objects in the game which have
their own script, and players which have a set
of scripts in their invisible backpack.

=== Server-side and client-side ===

Graal is an online game, and there are differences
to standard scripting in offline games.
In offline programs you have access to everything,
anytime. In online games everything is divided
into two parts: the server-side which controls
most things in the game, and the client-side which
displays the game to the player.
Since the client only displays things, it is not
possible to cheat by hacking the client. On client-side
you mainly have code for displaying special effects,
for displaying the GUI (windows, status bars, item menus),
playing sound effects and music. Also the player
movement is done on client-side.
On the server-side scripts are used to do the more
secure parts of the game engine,
and things that are the same for all players -
npcs are added, moved, npcs interact with players,
the stats of the players are calculated, the
communication between players is handled.

All scripts for npcs and weapons can contain
server-side code and client-side code. The server-side
code is executed directly on the server, the
client-side code is sent to the client when he/she
logins and executed separately for each player on
their own computer. Usually the two parts of the script
are divided by a line that only contains "//#CLIENTSIDE",
like this:

<pre>// Server-side part which is setting the image
// of the npc when it is created
function onCreated() {
setimg("door.png");
}

//#CLIENTSIDE

// Here follows the client-side part,
// which plays a sound effect when the player
// touchs the npc
function onPlayerTouchsme() {
play("chest.wav");
}</pre>

=== Events ===

In general scripts are made for reacting to
events - when the npc is created then the script
initializes the attributes of the npc,
when the player says something then the npc is
moving to the player, when the player grabs the
npc then the npc is giving the player some money etc.
So the script is basicly a collection of actions
that are done when special events are happening.
Events can e.g. be the "created" event when the npc
is created, the "playertouchsme" event when the
player touchs the npc, or the "playerchats" event
when the player says something. To write code that reacts
to one of those event, you define an event
function like this:

<pre>function onEVENTNAME() {
// actions
}</pre>

When the event is happening, then Graal executes
that scripting function and all commands you
have added there.
Sometimes the event gives some parameters to the
event function, then change your function to:

<pre>function onEVENTNAME(parameter1, parameter2, ...) {
// actions
}</pre>

By accessing 'parameter1' etc. (you can name
them differently) you can react to the event more
exactly.

Instead of reacting to events, the npcs and
weapons can also invoke new events. That way
you can let other npcs doing things. You also
need that if you want to coninuously doing things -
use timeout events for that.

<pre>function onCreated() {
setTimer(1);
}

function onTimeout() {
// actions
setTimer(1);
}</pre>

In the onCreated event function the script is
setting the timer to 1 second. When that second is
over, then the "timeout" event is invoked on the
npc and the onTimeout event function is executed.
Because it is setting the timer to 1 second
again, the onTimeout event will occur again after
one second, and so on.

Compatibility note:
In older Graal scripts you will also find the
deprecated way of receiving events:

<pre>if (EVENTNAME) {
// actions
}</pre>

That is an if-command outside of any brackets. If
Graal sees that you use such an if-command, then
it will execute the whole script so that the actions
you have written inside the if-command will be
executed too.

== Basics ==

=== Accessing variables ===

Graal Script variables are 'variant', that means they are objects
that hold values of different types.
When you assign a value to the variable then it automatically
switches to the right type:

Numeric (floating point):
var = 1;
String (text):
var = "hello";
Object link:
var = player;
Array (list of objects):
var = {1,2,3};

You can check the current type with the
type()-function - obj.type() returns
0,1,2,3 for numeric, string, object or array.

=== Operators ===
<pre>
Addition a + b
Substraction a - b
Mulitplication a * b
Division a / b
Modulus a % b
Power a ^ b
String Concationation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b
Bool-And a && b
Bool-Or a || b
Bool-Not !a
Negative -a
Equal a == b
Not-Equal a != b
Less a b
Less-Equal a <= b, a == b, a => b
In-Range a in <b,c>, a in |b,c>, a in <b,c|, a in |b,c|
In-Array a in {b,c,...}, {a,b,...} in {c,d,...}
Bitwise-Or a | b
Bitwise-And a & b
Bitwise-Shift left a <> b
Bitwise-Invert ~a
Bitwise-Xor a xor b (operator ^ already used for power)
Array-Constructor {a,b,...}
Empty Array new [count], new[countdim1][countdim2]...
Array Member a[index]
Function call a(), a(b,c,...)
Object Attribute a.b, a.(b)
Post Increment a++
Post Decrement a--
Pre Increment ++a
Pre Decrement --a
Old String Function #a
Conditional a? b : c
Assignment a = b, a := b
Additive Assignment a += b
Substractive Assignment a -= b
Multiplicative Assignment a *= b
Division Assignment a /= b
Modulus Assignment a %= b
Power Assignment a ^= b
Bitwise-Or Assignment a |= b
Bitwise-And Assignment a &= b
Shift Left Assignment a <<= b
Shift Right Assignment a >>= b
String Append a @= b
</pre>

=== Standard object functions ===

Here only some of the built-in functions:
<pre>
obj.type() - gets the type of the var (float 0, string 1, object 2, array 3)
obj.length() - string length
obj.trim() - removes spaces from the front and back of a string
obj.lower() - converts a string to lower case
obj.upper() - converts a string to upper case
obj.tokenize([delimiters])
obj.charat(pos)
obj.pos(substring)
obj.positions(substring)
obj.starts(string)
obj.ends(string)
obj.substring(index[,length])
obj.size() - array length
obj.add(obj2)
obj.delete(index)
obj.remove(obj2)
obj.replace(index,obj2)
obj.insert(index,obj2)
obj.clear()
obj.subarray(index[,length])
obj.addarray(obj2)
obj.insertarray(index,obj2)
obj.index(obj2) - position of obj2 in the array
obj.indices(obj2) - positions of obj2 in the array
</pre>

Also see [[Creation/Dev/Script/Client/TGraalVar|TGraalVar]] for more functions for objects.

=== Standard functions ===
<pre>
_(string) - translates a text on serverside
to the language of the current player,
if translations are enabled
abs(float)
arctan(float) - arcus tangens
char(ascii) - gets the character for an ascii code (char(65) returns 'A')
cos(angle) - cosinus of a radiant angle
exp(float)
float(string) - for explicitely converting a string
to number (normally done automatically though
when accessing a string with numeric operators)
format(format,parameters,...) - formats a "%s %d" string,
inserts the parameters, and returns a string
getangle(delta x,delta y)
getdir(delta x,delta y) - returns 0 for up, 1 for left,
2 for down, 3 for right
int(a) - gets the integer part of a floating point number
log(base,a)
max(a,b)
min(a,b)
printf(format,parameters,...) - same as
echo(format(format,parameters,...))
random(rangestart,rangeend)
sin(angle) - sinus of a radiant angle
sleep(time) - suspends the current script for some time
vecx(direction 0..3)
vecy(direction 0..3)
waitfor(objectname,event[,timeout]) - suspends the current script
and waits until an event is invoked on the specified object,
returns false when the parameters are wrong or the event
was not received before the timeout;
only available in the latest versions of npcserver
</pre>

Also see [[Creation/Dev/Script/Client#Functions|Client Functions]] for more functions.

== Events ==

The events for GUI controls are listed in the description of the different object types:
[[Creation/Dev/Script/Client#Classes_.2F_Object_Types|Object types]]

== Old script compatibility ==

=== Removed functionality ===
<pre>
- toinventory
- followplayer
- playersays()
- setbackpal
</pre>
=== Supported old scripting commands and their mapping to new script ===
<pre>
addstring oldstring, oldstring;
list.add(string);
addtiledef oldstring, oldstring, float;
addtiledef(string,string,float);
addtiledef2 oldstring, oldstring, float, float;
addtiledef2(string,string,float,float);
attachplayertoobj float, float;
attachplayertoobj(float,float);
blockagain;
blockagain();
blockagainlocal;
blockagainlocal();
callnpc float, oldstring;
callnpc(float,string);
callweapon float, oldstring;
callweapon(float,string);
canbecarried;
canbecarried();
canbepulled;
canbepulled();
canbepushed;
canbepushed();
cannotbecarried;
cannotbecarried();
cannotbepulled;
cannotbepulled();
cannotbepushed;
cannotbepushed();
canwarp;
canwarp();
canwarp2;
canwarp2();
carryobject oldstring;
carryobject(string);
changeimgcolors float, float, float, float, float;
changeimgcolors(float,float,float,float,float);
changeimgmode float, float;
changeimgmode(float,float);
changeimgpart float, float, float, float, float;
changeimgpart(float,float,float,float,float);
changeimgvis float, float;
changeimgvis(float,float);
changeimgzoom float, float;
changeimgzoom(float,float);
deletestring oldstring, float;
deletestring(string,float);
destroy;
destroy();
detachplayer;
detachplayer();
disabledefmovement;
disabledefmovement();
disablemap;
disablemap();
disablepause;
disablepause();
disableselectweapons;
disableselectweapons();
disableweapons;
disableweapons();
dontblock;
dontblock();
dontblocklocal;
dontblocklocal();
drawaslight;
drawaslight();
drawoverplayer;
drawoverplayer();
drawunderplayer;
drawunderplayer();
enabledefmovement;
enabledefmovement();
enablefeatures float;
enablefeatures(float);
enablemap;
enablemap();
enablepause;
enablepause();
enableselectweapons;
enableselectweapons();
enableweapons;
enableweapons();
explodebomb float;
explodebomb(float);
followplayer;
followplayer();
freezeplayer float;
freezeplayer(float);
freezeplayer2;
freezeplayer2();
hide;
hide();
hideimg float;
hideimg(float);
hideimgs float, float;
hideimgs(float,float);
hidelocal;
hidelocal();

hitcompu float, float, float, float;
hitcompu(float,float,float,float);
hitnpc float, float, float, float;
hitnpc(float,float,float,float);
hitobjects float, float, float;
hitobjects(float,float,float);
hideplayer float;
hideplayer(float);
hidesword float;
hidesword(float);
hitplayer float, float, float, float;
hitplayer(float,float,float,float);
hurt float;
hurt(float);
insertstring oldstring, float, oldstring;
insertstring(string,float,string);
join oldstring;
join(string);
lay oldstring;
lay(string);
lay2 oldstring, float, float;
lay2(string,float,float);
loadmap oldstring;
loadmap(string);
message oldstring;
message(string);
move float, float, float, float;
move(float,float,float,float);
noplayerkilling;
noplayerkilling();
openurl oldstring;
openurl(string);
openurl2 oldstring, float, float;
openurl2(string,float,float);
play oldstring;
play(string);
play2 oldstring, float, float, float;
play2(string,float,float,float);
playlooped oldstring;
playlooped(string);
putbomb float, float, float;
putbomb(float,float,float);
putcomp oldstring, float, float;
putcomp(string,float,float);
putexplosion float, float, float;
putexplosion(float,float,float);
putexplosion2 float, float, float, float;
putexplosion2(float,float,float,float);
puthorse oldstring, float, float;
puthorse(string,float,float);
putleaps float, float, float;
putleaps(float,float,float);
putnewcomp oldstring, float, float, oldstring, float;
putnewcomp(string,float,float,string,float);
putnpc oldstring, oldstring, float, float;
putnpc(string,string,float,float);
putnpc2 float, float, oldstring;
putnpc2(float,float,string);
reflectarrow float;
reflectarrow(float);
removearrow float;
removearrow(float);
removebomb float;
removebomb(float);
removecompus;
removecompus();
removeexplo float;
removeexplo(float);
removehorse float;
removehorse(float);
rmeoveitem float;
removeitem(float)
removestring oldstring, oldstring;
removestring(string,string);
removetiledefs oldstring;
removetiledefs(string);
replaceani oldstring, oldstring;
replaceani(string,string);
replacestring oldstring, float, oldstring;
replacestring(string,float,string);
resetfocus;
resetfocus();
savelog oldstring;
savelog(string);
savelog2 oldstring, oldstring;
savelog2(string,string);
say float;
say(float);
say2 oldstring;
say2(string);
sendrpgmessage oldstring;
sendrpgmessage(string);
sendpm oldstring;
sendpm(string);
sendtonc oldstring;
sendtonc(string);
sendtorc oldstring;
sendtorc(string);
serverwarp oldstring;
serverwarp(string);
set oldstring;
set(string);
setani oldstring, oldstring;
setani(string,string);
setarray float, float;
setarray(var,float);
setbeltcolor oldstring;
setbeltcolor(string);
setbow oldstring;
setbow(string);
setcharani oldstring, oldstring;
setcharani(string,string);
setchargender oldstring;
setchargender(string);
setcharprop oldstring, oldstring;
string = string;
setcoatcolor oldstring;
setcoatcolor(string);
setcoloreffect float, float, float, float;
setcoloreffect(float,float,float,float);
setcursor float;
setcursor(float);
setcurcor2 oldstring;
setcursor2(string);
seteffect float, float, float, float;
seteffect(float,float,float,float);
seteffectmode float;
seteffectmode(float);
setfocus float, float;
setfocus(float,float);
setgender oldstring;
setgender(string);
sethead oldstring;
sethead(string);
setlevel oldstring;
setlevel(string);
setlevel2 oldstring, float, float;
setlevel2(string,float,float);
setmap oldstring, oldstring, float, float;
setmap(string,string,float,float);
setminimap oldstring, oldstring, float, float;
setminimap(string,string,float,float);
setmusicvolume float, float;
setmusicvolume(float,float);
setimg oldstring;
setimg(string);
setimgpart oldstring, float, float, float, float;
setimgpart(string,float,float,float,float);
setletters oldstring;
setletters(string);
setplayerdir oldstring;
setplayerdir(string);
setplayerprop oldstring, oldstring;
string = string;
setpm oldstring;
setpm(string);
setshape float, float, float;
setshape(float,float,float);
setshape2 float, float, float;
setshape2(float,float,float);
setshield oldstring, float;
setshield(string,float);
setshoecolor oldstring;
setshoecolor(string);
setshootparams oldstring;
setshootparams(string);
setskincolor oldstring;
setskincolor(string);
setsleevecolor oldstring;
setsleevecolor(string);
setstring oldstring, oldstring;
setstring(string,string);
setsword oldstring, float;
setsword(string,float);
seturllevel oldstring;
seturllevel(string);
setz float, float, float, float, float, float, float, float;
setz(float,float,float,float,float,float,float,float);
setzoomeffect float;
setzoomeffect(float);
shoot float, float, float, float, float, float, oldstring, oldstring;
shoot(float,float,float,float,float,float,string,string);
shootarrow float;
shootarrow(float);
shootball;
shootball();
shootfireball float;
shootfireball(float);
shootfireblast float;
shootfireblast(float);
shootnuke float;
shootnuke(float);
show;
show();
showani float, float, float, float, oldstring;
showani(float,float,float,float,string);
showani2 float, float, float, float, float, oldstring;
showani2(float,float,float,float,float,string);
showcharacter;
showcharacter();
showfile oldstring;
showfile(string);
showimg float, oldstring, float, float;
showimg(float,string,float,float);
showimg2 float, oldstring, float, float, float;
showimg2(float,string,float,float,float);
showlocal;
showlocal();

showpoly float, float;
showpoly(float,array);
showpoly2 float, float;
showpoly2(float,array);
showstats float;
showstats(float);
showtext float, float, float, oldstring, oldstring, oldstring;
showtext(float,float,float,string,string,string);
showtext2 float, float, float, float, oldstring, oldstring, oldstring;
showtext2(float,float,float,float,string,string,string);
sleep float;
sleep(float);
spyfire float, float;
spyfire(float,float);
stopmidi;
stopmidi();
stopsound oldstring;
stopsound(string);
take oldstring;
take(string);
take2 float;
take2(float);
takehorse float;
takehorse(float);
takeplayercarry;
takeplayercarry();
takeplayerhorse;
takeplayerhorse();
throwcarry;
throwcarry();
timereverywhere;
timereverywhere();
timershow;
timershow();
toinventory oldstring;
toinventory(string);
tokenize oldstring;
tokens = string.tokenize();
tokenize2 oldstring, oldstring;
tokens = string.tokenize(" ," @ string);
toweapons oldstring;
toweapons(string);
triggeraction float, float, oldstring, oldstring;
triggeraction(float,float,string,string);
unfreezeplayer;
unfreezeplayer();
unset oldstring;
unset(string);
updateboard float, float, float, float;
updateboard(float,float,float,float);
updateterrain;
updateterrain();
wraptext float, oldstring, oldstring;
tokens = wraptext(float," ," @ string,string);
wraptext2 float, float, oldstring, oldstring;
tokens = wraptext2(float,float," ," @ string,string);
</pre>

=== Supported old string operations ===
These old string operators can be used in string parameters
for the old commands, also you can use them directly as operators, e.g.
#c = "hello"
is actually doing
player.chat = "hello"
It is recommended to use the new scripting style though.

<pre>
#a player.account
#a(float) players[float].account
#m player.ani
ani
#m(float) players[float].ani
#K(float) char(float)
#8 player.bodyimg
bodyimg
#8(float) players[float].bodyimg
#c player.chat
chat
#c(float) players[float].chat
#C0 player.colors[0]
colors[0]
#C0(float) players[float].colors[0]
#C1 player.colors[1]
colors[1]
#C1(float) players[float].colors[1]
#C2 player.colors[2]
colors[2]
#C2(float) players[float].colors[2]
#C3 player.colors[3]
colors[3]
#C3(float) players[float].colors[3]
#C4 player.colors[4]
colors[4]
#C4(float) players[float].colors[4]
#C5 player.colors[5]
colors[5]
#C5(float) players[float].colors[5]
#D downloadfile()
#E emoticonchar()
#e(float,float,oldstring)
string.substring(float,float)
#g player.guild
guild
#g(float) players[float].guild
#3 player.headimg
headimg
#3(float) players[float].headimg
#5 player.horseimg
horseimg
#5(float) players[float].horseimg
#k(float) keyname(float)
#L player.level
#I(oldstring,float)
getstring(string)[float]
#n player.nick
nick
#n(float) players[float].nick
#f image
#f(float) npcs[float].image
#F level
#p(float) params[float]
#P(float) player.attr[float]
attr[float]
#P(float_1,float_2)
players[float_2].attr[float_1]
#P1 player.attr[1]
attr[1]
#P1(float) players[float].attr[1]
#P2 player.attr[2]
attr[2]
#P2(float) players[float].attr[2]
#P3 player.attr[3]
attr[3]
#P3(float) players[float].attr[3]
#P4 player.attr[4]
attr[4]
#P4(float) players[float].attr[4]
#P5 player.attr[5]
attr[5]
#P5(float) players[float].attr[5]
#P6 player.attr[6]
attr[6]
#P6(float) players[float].attr[6]
#P7 player.attr[7]
attr[7]
#P7(float) players[float].attr[7]
#P8 player.attr[8]
attr[8]
#P8(float) players[float].attr[8]
#P9 player.attr[9]
attr[9]
#P9(float) players[float].attr[9]
#R(oldstring) string.random()
#2 player.shieldimg
shieldimg
#2(float) players[float].shieldimg
#s(oldstring) getstring(string)
#1 player.swordimg
swordimg
#1(float) players[float].swordimg
#S player.sword.script
#t(float) tokens[float]
#T(oldstring) string.trim()
#v(float) float
#W player.weapon.image
#W(float) weapons[float].image
#w player.weapon.name
#w(float) weapons[float].name
</pre>
Compatibility note:
When you use the command setcharprop then the first parameter
is handled differently: instead of changing 'player.chat' it
is changing 'chat', the chat text of the npc. So 'setcharprop #c,hello'
would be translated into
chat = "hello"
while 'setplayerprop #c,hello' is translated into
player.chat = "hello"
In the list above both possibilities are listed.

Creation/Dev/Script/Client/GuiControls List

2007-07-01T07:46:42Z

Twinny: Undo revision 8676 by Special:Contributions/Anti-Up (User talk:Anti-Up)

Creation/Dev/GScript

2007-07-01T07:42:09Z

Twinny: Undo revision 8680 by Special:Contributions/Anti-Up (User talk:Anti-Up)

'''GScript''' is [[Graal]]'s scripting language.

Its syntax and some of its semantics might seem familiar to those who program in [[WikiPedia:C (Programming Language) |C]] or [[WikiPedia:Java_programming_language|Java]]. In some ways it is more dynamic, e.g. supporting dynamicly joining and leaving of classes, and brings support for easy management of online game content.

GScript started as a very limited language ([[Creation/Dev/Old GScript|Old GScript]]) and has since kept up with improvements to the game engine and can now be used for pretty sophisticated scripts that greatly customise the gaming experience.

It is used, with minor differences, for [[Clientside]] tasks like [[GUI | GUI programming]], special effects with nifty 3d lighting and custom [[NPC weapon|NPC Weapons]] or "engines", and [[Serverside]] systems like player housing, complex baddies or pets.

GScript can be discussed in the non-official [[GScript IRC channel]].

'''If you would like to contribute to the GraalBible's GScript documentation, you might want to [[Creation/Dev/GScript/Contribute|read this article]].'''

In your scripting quest, you may find the following articles to be of use:

'''Basic information'''
* [[Creation/Dev/Script/Starting Guide|Starting Guide]]
* [[Creation/Dev/Script/Client|Functions, variables and objects (clientside)]]
* [[Creation/Dev/Script/Client/GuiControls_List|GUI Controls]]

'''Specific Features'''
* [[Creation/Dev/GS1_To_GS2|GS1 To GS2: Guide for fixing scripts to work with the new engine]]
* [[Particle Engine|Particle Engine]]
* [[Creation/Dev/Graal v4 IRC|Graal IRC Scripting: Graal IRC Scripting Reference]]
* [[Creation/Dev/Troubleshooting Graal v4 IRC|Graal IRC Scripting: Troubleshooting Scripting Reference]]
* [[Creation/Dev/Output Methods|Output methods]]
* [[Creation/Dev/Using Classes Effectively|Use of classes]]
* [[Creation/Dev/GScript/Understanding GUI Profiles|GUI Features: Understanding GUI profiles]]
* [[Creation/Dev/GScript/Constants|Constants]]
* [[Vectors]] (3D)

'''Tutorials'''
* [[Creation/Dev/Creating Tabbed Window Panes|Creating Tabbed Window Panes]]
* [[Creation/Dev/Database_Communication|Indexed Database Communication]]
* [[Creation/Dev/Excalibur's scripting guide|Excalibur's Scripting Guide]]
* [http://twinny.vip.graal.net Twinny's Scripting Page]
'''Script Functions'''

These are frequently updated, to get the latest list run Graal with the -listscriptfunctions option:
* [[Creation/Dev/Script/Clientside_Functions|Client side]]
* [[Creation/Dev/Script Functions: NPC Server|Server side]]

[[Creation/Dev/Script/Index |Related Artices]]

Creation

2007-07-01T07:40:56Z

Twinny:

Something that makes Graal very interesting is that you can create your own online game. You can become staff at a server and upload your own graphics, maps, add monsters or even create a new style of game. To make it possible for everyone to participate we created the possibility to rent your own playerworld space.
Follow those links to find more documentation about server managment and the development tools:

[[Creation/Playerworld Renting|Rent a Playerworld]]

Management
* [[Creation/Management/Playerworld_Guide|Playerworld Guide]]
* [[Server options|Server Options]]
* [[Creation/Management/Contacts|Staff Contacts]]
* [[Creation/Dev/Basics_of_NPC-Control|NPC-Control]]

Development
* [[Creation/Dev/GScript|Scripting]]
* Tools:
** [[Creation/Dev/Level editor|Level Editor]]
** [[Creation/Dev/Gani|Gani Editor]]
* Help pages:
** [[Creation/Dev/Tileset|Information on Tilesets]]
** [[Creation/Dev/Player|Information on Player Looks]]
** [[Creation/Dev/Update Packages|Update Packages]]
* [[Creation/Dev/Client_Releases|Client Changelog]]

Inspection
* [[Creation/Inspection/Playerworld_Scripting|Playerworld Scripting]]

Creation/Dev/Script/Client/WheeledVehicleData

2007-07-01T07:38:50Z

Twinny: Undo revision 8915 by Special:Contributions/Anti-up (User talk:Anti-up)

Inherits [[Creation/Dev/Script/Client/VehicleData|VehicleData]].

=Variables=
{| border="1" cellpadding="2" width="100%"
| '''Name'''
| '''Type'''
| '''Description'''
|-
| enginesound
| object
|
|-
| jetsound
| object
|
|-
| squealsound
| object
|
|-
| tireemitter
| object
|
|-
| wheelimpactsound
| object
|
|}

Local Staff Positions

2007-07-01T07:38:31Z

Twinny: Undo revision 8917 by Special:Contributions/Anti-up (User talk:Anti-up)

There are four common local staff positions:

*'''GP''' ''(Graal Police)'' - in charge of enforcing the rules and maintaining order in the server.

*'''LAT''' ''(Levels Administration Team)'' - the development team, contains tilers, scripters and graphics makers.

*'''FAQ''' ''(Frequently Asked Questions)'' - the server's source of knowledge, in charge of anwering players' questions.

*'''Events Team''' - in charge of hosting events to entertain the players. Known as Game Coordinator on Classic.

Creation/Dev/Script/Client/GuiCursor

2007-07-01T07:38:22Z

Twinny: Undo revision 8918 by Special:Contributions/Anti-up (User talk:Anti-up)

Inherits [[Creation/Dev/Script/Client/TGraalVar|TGraalVar]].

Creation/Dev/GScript

2007-06-10T09:24:05Z

Twinny: Added a link to my 'learn gs2' website :D

Creation/Dev/Excalibur's scripting guide

2006-11-17T00:12:59Z

Twinny: /* '''Excalibur's Scripting Guide''' */

== '''Excalibur's Scripting Guide''' ==
I'm hoping this allows people to learn how to script a bit easier, I believe all staff should know some scripting basics, and I find other GS2 guides hard to follow. This should help you get started out. I'm afraid it isn't complete and there are a few typos in it. I'm working on it.

Starting:

Level NPCs:

A level NPC is an npc that functions in a specific level. These are the most common on most servers. They are also a very important part of developement.

A script:
<pre>
//this is a note
/*

this is also a note, these help make scripts more clear
this type of note can go on as longe as it's inclosed
*/
//#CLIENTSIDE
//This tells the computer that the following
//script will be on the players client,
//as opposed to the server, this is very important.
function onPlayertouchesme()
//this checks if the player has touched the NPC
{ // starting bracket
this.message("Hey!"); //displays a message above the NPC
}//closing bracket
</pre>
The above script checks to see if the event, playertouchsme is true, then acts on what is in the bracket. It is important to include this clientside, because too many serverside scripts can cause problems for an NPC server, however they are more secure. If you wanted to do the last script serverside, you would omit the //#CLIENTSIDE , and add the shape to the NPC:
<pre>
function onCreated()
{
setshape(1,32,32);
setimg("block.png");
//img can also be done in the box above the script
}
function onPlayertouchsme()
{
this.message("You made a serverside script!");
}
</pre>
This takes a bit longer than clientside commands, and it takes up serverside script time, however, for secure actions, it may be necessary.
A secure script example:
<pre>
function onCreated()
{
this.account="Excaliber7388";
setshape(1,32,32);
this.chat="Excaliber's Chest";
}
function onPlayertouchsme()
{
if(player.account==this.account)
{
this.chat="This is a secure message!";
}
}
</pre>
First, I would like to quickly point out the 'if' statement. Some guides go into this a lot, but it's actually quite simple. The if statement is a very important part of scripting. It's what allows the NPC to make choices. The code withing the brackets of an if statement will only execute if the statement is true. Also, there is a catchall statement you can use, else. If the if statement is not true, the else will exectue it's script, other wise it is ignored.
Example:
<pre>
//#CLIENTSIDE
function onCreated()
{
this.a=1;
}
if(this.a==1)
//always use '==' for comparasons, NEVER just '=' as '=' is for assignments
{
this.b=2;
}
else if(this.a==2) //will only execute if first is false, AND this.a==2
{
this.b=3;
}
else //catch all if above 2 statements are false
{
this.b=4;
}
</pre>
Now, in the above example, this.b will always be 2, however, it's the format that's important.
<pre>
if(statement)
else if(statement)
else if(statement //may be used many times
else //catch all
</pre>
Now, back to serverside and clientside scripts:
By putting the checks on serverside, you disable a hackers ability to send an action from their client. So, this script is much more secure, and can only be accessed by the specified account (Excaliber7388 in this case). Most playerworlds and classic servers do these checks serverside as well, but we also apply a different method, to avoid having too much serverside script time:
<pre>
function onCreated()
{
this.account="Excaliber7388";
setshape 1,32,32;
this.chat="Excaliber's Chest";
}
function onActiontouched()
{
if(player.account==this.account)
{
this.chat="Yup, this is still secure, yay!";
}
}
//#CLIENTSIDE
function onPlayertouchsme()
{
triggeraction(x,y,"Touched","Touched");//no params needed
}
</pre>
This script will take up more time, but the playertouchsme check is clientside. Would this help much? Probably not, in fact, sending the action in this case would probably create more lag than having the script serverside. However, if a large portion of the script is serverside, and can be moved to clientside without risking security, it may be a good idea.
Serverisde timeouts=bad idea.
You shouldn't send to many actions to serverside, especially if you do so quickly. You should always limit the serverside timeouts, and the amount of time between actions to the server from client should be spaced out. Also, you should never have a timeout shorter than .05 on serverside, though it is possible, please do not do it. Many playerworlds have expierenced problems from serverside timeouts which can lead to NPC server crashing or lagging.

Here are two examples of serverside scripts, the first is [b]VERY[/b] bad, the second is more productive:
<pre>
function onCreated()
{
setshape 1,32,32;
}
function onActiontime()
{
for(server.i=0;server.i<5;server.i++)
//WHY use server for this???
//for loops, use this. it works only for this NPC
{
sleep(.01);
//WAY to short of a sleep time for the server
}
server.time+=.1;
}
//#CLIENTSIDE
function onCreated()
{
settimer(.05); //minimum clientside timeout
}
function onTimeout()
{
trigegraction(x,y,"time","time");
settimer(.05);
//Will cause a loop through the timeout, sending action
//to serverside TOO quickly, AND while the server is
//still working on the last action. This WILL cause the
//server to crash.
}
</pre>
If you put the above script on a server, say goodbye to your NPC server, because it will crach pretty quickly!
A better version:
<pre>function onCreated()
{
setshape 1,32,32;
//setshape is needed for all level NPCs triggeractions
//this sets it to a square of tiles 32x32 pixels.
}
function onActiontime()
{
server.time++;
//no need for incredible accuracy
}
//#CLIENTSIDE
function onCreated()
{
settimer(1);
}
function onTimeout()
{
triggeraction(x,y,"time","time");
settimer(1);
}
</pre>
This will execute the script less often, however, it still is an unlimited loop. Don't have too many of these NPCs, or you could have problems!

Now, you may have noticed this line in the bad script:
<pre>
for(server.i=0;server.i<5;server.i++)
</pre>
This is a 'for' loop. There are many types of loops, however the for loop isn't the easiest to learn first. Therefore, I will show you the 'while loop' first.
The while loop executes whatever is held within it's brackets as long as the statement within it is true. The while loop is just like an if statement, but you cannot use else with a with statement.
format:
<pre>
while(statments)
{
//commands
}
//if statment is still true, it will loop
</pre>
here's a script example:
<pre>
//#CLIENTSIDE
function onCreated()
{
this.size=10;
}
while(this.size<=20) //while this.size is less than or equal to 20
{
this.chat="The fish was " @this.size@ " centimeters long!";
//as the story is retold....
sleep(.5);
this.size=this.size+1;
//increment the size
}
</pre>
The above script will run through the loop until this.size is equal or greater than 20.
Some important things to know:
<pre>
if(a==b) means if a is equal to b
if(a<b) means if a is less than b
if(a>b) means if a is greater than b
if(a<=b) means if a is less than or equal to be
if(a>=b) means if a is greater than or equal to be
a++ is the same as a=a+1
a-- is the same as a=a-1
a+=b means a=a+b
a-=b means a=a-b
a*=b means a=a*b (multiplied by b)
a/=b means a=a/b
++a is just like a, but it will add to a before anything else in the line,
this is not important to know now
--a just like ++a, but with subtraction
a%b Modulus, basically, its a/b and th remainder is the output
for example 10%3=1
</pre>
These may be helpfull in loops, or in any other rational expressions you may use. (Well, it's important for all scripting!)
Now, recall this line:
<pre>
this.chat="The fish was " @this.size@ " centimeters long!";
</pre>
The output for this is: The fish was (size here) centimeters long!
The script NEEDS to know where a variable is, so if you want to put it in between a string you surround it with the '@' symbol. Or if it's at the end, you only put the '@' at the beggining of the variable. The variable and the '@' do NOT go in the quotes. Example:
<pre>
//#CLIENTSIDE
function onPlayertouchsme()
{
this.chat="Well hi there, " @player.account@ " I like your sword, " @player.swordimg;
}
</pre>
This would display the player's account, and sword image.

Now, back to the 'for' loop.
This a very interesting loop it's format is as follows:
<pre>
for(command;expression;command)
{
}
</pre>
Here's an example:
<pre>
//#CLIENTSIDE
function onPlayertouchsme()
{
for(this.i=0;this.i<10;this.i++)
{
this.chat="Loops: " @this.i;
sleep(.5);
}
}
</pre>
This loop would be activated when the player touchs it.
It would go through 10 loops, displaying the count, and taking .5 seconds for each loop (due to the sleep() command)
Now remember this while loop?
<pre>
function onCreated()
{
this.size=10;
}
while(this.size<=20)
{
this.chat="The fish was " @this.size@ " centimeters long!";
//as the story is retold....
sleep(.5);
this.size=this.size+1;
//increment the size
}
</pre>
There's an easier way of doing it with a for loop, in fact all loops done with while can be replaced by for.
<pre>
for(this.size=10;this.size<=20;this.size++)
{
this.chat="The fish was " @this.size@ " centimeters long!";
sleep(.5);
}
</pre>
See? Much shorter and easier to use!
Once you know the format of a for loop, you can make longer and more complex loops as well, and they'll take less time to script, which is always a bonus.

Some more detail on actions:
An action is an effective way to use a portion of script more than once, have one script act on another script, more script to serverside from clientside (and the other way) and more.
So how do you use them? Here's the format:
<pre>
triggeraction(x,y,"params[0]","params[1]");
</pre>
You must have two parameters, but you can have as many as you want a quick example:
<pre>
function onCreated()
{
setshape 1,32,32;
}
function onActiontrigger()
{
player.chat="Account: " @params[1]@ " Sword " @params[2]@ " head: " @params[3];
}
//#CLIENTSIDE
function onPlayerchats()
{
if(player.chat=="Who am I?") //amnesia? multiple identities?
{
triggeraction(x,y,"trigger",player.account,player.swordimg,player.headimg);
}
}
</pre>
See? You can make more than one parameter.
Now, there are a few differences between a level NPC with a triggeraction, and a weapon with a triggeraction. Weapons need their location (serverside or clientside) as the first parameter, params[0] is the one after it. Here, you can have just one parameter, and the x and y is always 0 (because the npc server is at 0,0), and you need to include the name of the weapon in the action.
here's an example:
<pre>
//weapon script with a triggeraction
//Weapon name: Fire Ball
function onActionserverside()
{
if(params[0]=="mp")
{
playermp-=10
}
}
//#CLIENTSIDE
function onWeaponfired()
{
if(playermp>=10)
{
shootfireball(playerdir);
triggeraction(0,0,"serverside","Fireball","mp");
}
else
{
player.chat="Not enough mp!";
}
}
</pre>
This nifty little weapon will cost 10 mp per use, and fires a fireball in the direction the player is facing. Hopefully, you can learn to make many weapons of your own!
Triggeractions can be used in shops as well (and these are the scripts people ask for the most).
<pre>
//a shop script, yay!
function onCreated()
{
setshape 1,32,32;
}
function onActionbuy()
{
if(playerrupees>=100)
{
addweapon Fire Ball;
playerrupees-=100;
}
}
//#CLIENTSIDE
function onPlayerchats()
{
if(player.chat=="buy fire ball")
{
triggeraction(x,y,"buy","buy");
//the level npc triggeraction type
}
}
</pre>
There, now you can make a little shop that sells a Fire Ball weapon. Have fun with it, search the commands, there's plenty of easy weapons you can make, and the weapon script is easy to follow and modify as well. Hopefully, you know enough about parameters to make more than one weapon for sale in the same NPC, just make the weapon name part of the action, then check for that parameter before they can buy.
Now there are other types of loops. One I commonly see is a timeout loop. You should understand why. Back with GS1, it was a bit easier to tell what was happening in the script. In GS1 the script for function onTimeout() would be displayed as if(timeout). It was a bit easier to tell that when a timeout was done, it set a flag that if(timeout) would check. function onTimeout does the same thing, however, for new users this may be harder to tell. here's an example of an NPC that uses a timeout loop:
<pre>
//#CLIENTSIDE
function onCreated()
{
settimer(1);
}
function onTimeout()
{
player.chat="Counter: " @this.time;
this.time++;
settimer(1);
//after 1 second, the timeout loop will restart
}
</pre>
This would cause the player to count up every second.
You may have noticed that the variables often start of with client. or this. There are actually a few prefixes, each does a different thing:
<pre>
client. variable is saved to the client, it can be modified on the clientside or serverside, and read from either.
clientr. variables can be rad from server or clientside, but only written from serverside. This is more secure, but only if you use it right.
server. variables are saved to the server, can only be written on the serverside, read on either side
serverr. more secure version of server. read only on clientside
this. is a variable that only functions in the NPC it is in. This prevents NPCs from morifying each others variables
temp. only exists in between the brackets of a function
</pre>
To use scripts effectivly, you should know how to use each of these.
I will add more over time.

Some important commands can be found here:
page:http://wiki.graal.net/index.php/Creation/Dev/Script/Starting_Guide#Introduction
Which is also helpful for learning how to script. Enjoy!

Creation/Dev/Excalibur's scripting guide

2006-11-17T00:06:26Z

Twinny: /* '''Excalibur's Scripting Guide''' */

== '''Excalibur's Scripting Guide''' ==
I'm hoping this allows people to learn how to script a bit easier, I believe all staff should know some scripting basics, and I find other GS2 guides hard to follow. This should help you get started out. I'm afraid it isn't complete and there are a few typos in it. I'm working on it.

Starting:

Level NPCs:

A level NPC is an npc that functions in a specific level. These are the most common on most servers. They are also a very important part of developement.

A script:
<pre>
//this is a note
/*

this is also a note, these help make scripts more clear
this type of note can go on as longe as it's inclosed
*/
//#CLIENTSIDE
//This tells the computer that the following
//script will be on the players client,
//as opposed to the server, this is very important.
function onPlayertouchesme()
//this checks if the player has touched the NPC
{ // starting bracket
message("Hey!"); //displays a message above the NPC
}//closing bracket
</pre>
The above script checks to see if the event, playertouchsme is true, then acts on what is in the bracket. It is important to include this clientside, because too many serverside scripts can cause problems for an NPC server, however they are more secure. If you wanted to do the last script serverside, you would omit the //#CLIENTSIDE , and add the shape to the NPC:
<pre>
function onCreated()
{
setshape(1,32,32);
setimg("block.png");
//img can also be done in the box above the script
}
function onPlayertouchsme()
{
message("You made a serverside script!");
}
</pre>
This takes a bit longer than clientside commands, and it takes up serverside script time, however, for secure actions, it may be necessary.
A secure script example:
<pre>
function onCreated()
{
this.account="Excaliber7388";
setshape(1,32,32);
chat="Excaliber's Chest";
}
function onPlayertouchsme()
{
if(player.account==this.account)
{
chat="This is a secure message!";
}
}
</pre>
First, I would like to quickly point out the 'if' statement. Some guides go into this a lot, but it's actually quite simple. The if statement is a very important part of scripting. It's what allows the NPC to make choices. The code withing the brackets of an if statement will only execute if the statement is true. Also, there is a catchall statement you can use, else. If the if statement is not true, the else will exectue it's script, other wise it is ignored.
Example:
<pre>
//#CLIENTSIDE
function onCreated()
{
this.a=1;
}
if(this.a==1)
//always use '==' for comparasons, NEVER just '=' as '=' is for assignments
{
this.b=2;
}
else if(this.a==2) //will only execute if first is false, AND this.a==2
{
this.b=3;
}
else //catch all if above 2 statements are false
{
this.b=4;
}
</pre>
Now, in the above example, this.b will always be 2, however, it's the format that's important.
<pre>
if(statement)
else if(statement)
else if(statement //may be used many times
else //catch all
</pre>
Now, back to serverside and clientside scripts:
By putting the checks on serverside, you disable a hackers ability to send an action from their client. So, this script is much more secure, and can only be accessed by the specified account (Excaliber7388 in this case). Most playerworlds and classic servers do these checks serverside as well, but we also apply a different method, to avoid having too much serverside script time:
<pre>
function onCreated()
{
this.account="Excaliber7388";
setshape 1,32,32;
chat="Excaliber's Chest";
}
function onActiontouched()
{
if(player.account==this.account)
{
chat="Yup, this is still secure, yay!";
}
}
//#CLIENTSIDE
function onPlayertouchsme()
{
triggeraction(x,y,"Touched","Touched");//no params needed
}
</pre>
This script will take up more time, but the playertouchsme check is clientside. Would this help much? Probably not, in fact, sending the action in this case would probably create more lag than having the script serverside. However, if a large portion of the script is serverside, and can be moved to clientside without risking security, it may be a good idea.
Serverisde timeouts=bad idea.
You shouldn't send to many actions to serverside, especially if you do so quickly. You should always limit the serverside timeouts, and the amount of time between actions to the server from client should be spaced out. Also, you should never have a timeout shorter than .05 on serverside, though it is possible, please do not do it. Many playerworlds have expierenced problems from serverside timeouts which can lead to NPC server crashing or lagging.

Here are two examples of serverside scripts, the first is [b]VERY[/b] bad, the second is more productive:
<pre>
function onCreated()
{
setshape 1,32,32;
}
function onActiontime()
{
for(server.i=0;server.i<5;server.i++)
//WHY use server for this???
//for loops, use this. it works only for this NPC
{
sleep(.01);
//WAY to short of a sleep time for the server
}
server.time+=.1;
}
//#CLIENTSIDE
function onCreated()
{
settimer(.05); //minimum clientside timeout
}
function onTimeout()
{
trigegraction(x,y,"time","time");
settimer(.05);
//Will cause a loop through the timeout, sending action
//to serverside TOO quickly, AND while the server is
//still working on the last action. This WILL cause the
//server to crash.
}
</pre>
If you put the above script on a server, say goodbye to your NPC server, because it will crach pretty quickly!
A better version:
<pre>function onCreated()
{
setshape 1,32,32;
//setshape is needed for all level NPCs triggeractions
//this sets it to a square of tiles 32x32 pixels.
}
function onActiontime()
{
server.time++;
//no need for incredible accuracy
}
//#CLIENTSIDE
function onCreated()
{
settimer(1);
}
function onTimeout()
{
triggeraction(x,y,"time","time");
settimer(1);
}
</pre>
This will execute the script less often, however, it still is an unlimited loop. Don't have too many of these NPCs, or you could have problems!

Now, you may have noticed this line in the bad script:
<pre>
for(server.i=0;server.i<5;server.i++)
</pre>
This is a 'for' loop. There are many types of loops, however the for loop isn't the easiest to learn first. Therefore, I will show you the 'while loop' first.
The while loop executes whatever is held within it's brackets as long as the statement within it is true. The while loop is just like an if statement, but you cannot use else with a with statement.
format:
<pre>
while(statments)
{
//commands
}
//if statment is still true, it will loop
</pre>
here's a script example:
<pre>
//#CLIENTSIDE
function onCreated()
{
this.size=10;
}
while(this.size<=20) //while this.size is less than or equal to 20
{
this.chat="The fish was " @this.size@ " centimeters long!";
//as the story is retold....
sleep(.5);
this.size=this.size+1;
//increment the size
}
</pre>
The above script will run through the loop until this.size is equal or greater than 20.
Some important things to know:
<pre>
if(a==b) means if a is equal to b
if(a<b) means if a is less than b
if(a>b) means if a is greater than b
if(a<=b) means if a is less than or equal to be
if(a>=b) means if a is greater than or equal to be
a++ is the same as a=a+1
a-- is the same as a=a-1
a+=b means a=a+b
a-=b means a=a-b
a*=b means a=a*b (multiplied by b)
a/=b means a=a/b
++a is just like a, but it will add to a before anything else in the line,
this is not important to know now
--a just like ++a, but with subtraction
a%b Modulus, basically, its a/b and th remainder is the output
for example 10%3=1
</pre>
These may be helpfull in loops, or in any other rational expressions you may use. (Well, it's important for all scripting!)
Now, recall this line:
<pre>
this.chat="The fish was " @this.size@ " centimeters long!";
</pre>
The output for this is: The fish was (size here) centimeters long!
The script NEEDS to know where a variable is, so if you want to put it in between a string you surround it with the '@' symbol. Or if it's at the end, you only put the '@' at the beggining of the variable. The variable and the '@' do NOT go in the quotes. Example:
<pre>
//#CLIENTSIDE
function onPlayertouchsme()
{
this.chat="Well hi there, " @player.account@ " I like your sword, " @player.swordimg;
}
</pre>
This would display the player's account, and sword image.

Now, back to the 'for' loop.
This a very interesting loop it's format is as follows:
<pre>
for(command;expression;command)
{
}
</pre>
Here's an example:
<pre>
//#CLIENTSIDE
function onPlayertouchsme()
{
for(this.i=0;this.i<10;this.i++)
{
chat="Loops: " @this.i;
sleep(.5);
}
}
</pre>
This loop would be activated when the player touchs it.
It would go through 10 loops, displaying the count, and taking .5 seconds for each loop (due to the sleep() command)
Now remember this while loop?
<pre>
function onCreated()
{
this.size=10;
}
while(this.size<=20)
{
chat="The fish was " @this.size@ " centimeters long!";
//as the story is retold....
sleep(.5);
this.size=this.size+1;
//increment the size
}
</pre>
There's an easier way of doing it with a for loop, in fact all loops done with while can be replaced by for.
<pre>
for(this.size=10;this.size<=20;this.size++)
{
chat="The fish was " @this.size@ " centimeters long!";
sleep(.5);
}
</pre>
See? Much shorter and easier to use!
Once you know the format of a for loop, you can make longer and more complex loops as well, and they'll take less time to script, which is always a bonus.

Some more detail on actions:
An action is an effective way to use a portion of script more than once, have one script act on another script, more script to serverside from clientside (and the other way) and more.
So how do you use them? Here's the format:
<pre>
triggeraction(x,y,"params[0]","params[1]");
</pre>
You must have two parameters, but you can have as many as you want a quick example:
<pre>
function onCreated()
{
setshape 1,32,32;
}
function onActiontrigger()
{
player.chat="Account: " @params[1]@ " Sword " @params[2]@ " head: " @params[3];
}
//#CLIENTSIDE
function onPlayerchats()
{
if(player.chat=="Who am I?") //amnesia? multiple identities?
{
triggeraction(x,y,"trigger",player.account,player.swordimg,player.headimg);
}
}
</pre>
See? You can make more than one parameter.
Now, there are a few differences between a level NPC with a triggeraction, and a weapon with a triggeraction. Weapons need their location (serverside or clientside) as the first parameter, params[0] is the one after it. Here, you can have just one parameter, and the x and y is always 0 (because the npc server is at 0,0), and you need to include the name of the weapon in the action.
here's an example:
<pre>
//weapon script with a triggeraction
//Weapon name: Fire Ball
function onActionserverside()
{
if(params[0]=="mp")
{
playermp-=10
}
}
//#CLIENTSIDE
function onWeaponfired()
{
if(playermp>=10)
{
shootfireball(playerdir);
triggeraction(0,0,"serverside","Fireball","mp");
}
else
{
player.chat="Not enough mp!";
}
}
</pre>
This nifty little weapon will cost 10 mp per use, and fires a fireball in the direction the player is facing. Hopefully, you can learn to make many weapons of your own!
Triggeractions can be used in shops as well (and these are the scripts people ask for the most).
<pre>
//a shop script, yay!
function onCreated()
{
setshape 1,32,32;
}
function onActionbuy()
{
if(playerrupees>=100)
{
addweapon Fire Ball;
playerrupees-=100;
}
}
//#CLIENTSIDE
function onPlayerchats()
{
if(player.chat=="buy fire ball")
{
triggeraction(x,y,"buy","buy");
//the level npc triggeraction type
}
}
</pre>
There, now you can make a little shop that sells a Fire Ball weapon. Have fun with it, search the commands, there's plenty of easy weapons you can make, and the weapon script is easy to follow and modify as well. Hopefully, you know enough about parameters to make more than one weapon for sale in the same NPC, just make the weapon name part of the action, then check for that parameter before they can buy.
Now there are other types of loops. One I commonly see is a timeout loop. You should understand why. Back with GS1, it was a bit easier to tell what was happening in the script. In GS1 the script for function onTimeout() would be displayed as if(timeout). It was a bit easier to tell that when a timeout was done, it set a flag that if(timeout) would check. function onTimeout does the same thing, however, for new users this may be harder to tell. here's an example of an NPC that uses a timeout loop:
<pre>
//#CLIENTSIDE
function onCreated()
{
settimer(1);
}
function onTimeout()
{
player.chat="Counter: " @this.time;
this.time++;
settimer(1);
//after 1 second, the timeout loop will restart
}
</pre>
This would cause the player to count up every second.
You may have noticed that the variables often start of with client. or this. There are actually a few prefixes, each does a different thing:
<pre>
client. variable is saved to the client, it can be modified on the clientside or serverside, and read from either.
clientr. variables can be rad from server or clientside, but only written from serverside. This is more secure, but only if you use it right.
server. variables are saved to the server, can only be written on the serverside, read on either side
serverr. more secure version of server. read only on clientside
this. is a variable that only functions in the NPC it is in. This prevents NPCs from morifying each others variables
temp. only exists in between the brackets of a function
</pre>
To use scripts effectivly, you should know how to use each of these.
I will add more over time.

Some important commands can be found here:
page:http://wiki.graal.net/index.php/Creation/Dev/Script/Starting_Guide#Introduction
Which is also helpful for learning how to script. Enjoy!