Creation/Dev/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:

//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

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:

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

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:

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

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:

//#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;
}

Now, in the above example, this.b will always be 2, however, it's the format that's important.

if(statement)
else if(statement)
else if(statement //may be used many times
else //catch all

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:

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
}

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:

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

If you put the above script on a server, say goodbye to your NPC server, because it will crach pretty quickly! A better version:

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

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:

  for(server.i=0;server.i<5;server.i++)

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:

while(statments)
{
  //commands
}
//if statment is still true, it will loop

here's a script example:

//#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
}

The above script will run through the loop until this.size is equal or greater than 20. Some important things to know:

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

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:

  this.chat="The fish was " @this.size@ " centimeters long!";

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:

//#CLIENTSIDE
function onPlayertouchsme()
{
  this.chat="Well hi there, " @player.account@ " I like your sword, " @player.swordimg;
}

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:

for(command;expression;command)
{
}

Here's an example:

//#CLIENTSIDE
function onPlayertouchsme()
{
  for(this.i=0;this.i<10;this.i++)
  {
    this.chat="Loops: " @this.i;
    sleep(.5);
  }
}

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?

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
}

There's an easier way of doing it with a for loop, in fact all loops done with while can be replaced by for.

for(this.size=10;this.size<=20;this.size++)
{
  this.chat="The fish was " @this.size@ " centimeters long!";
  sleep(.5);
}

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:

triggeraction(x,y,"params[0]","params[1]");

You must have two parameters, but you can have as many as you want a quick example:

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

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:

//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!";
  }
}

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

//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
  }
}

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:

//#CLIENTSIDE
function onCreated()
{
  settimer(1);
}
function onTimeout()
{
  player.chat="Counter: " @this.time;
  this.time++;
  settimer(1); 
//after 1 second, the timeout loop will restart
}

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:

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

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!