Creation/Dev/GScript3

GScript3 (also known as GS3 or GraalScript3) is the latest version of the Graal's scripting language.
It introduces new syntax and semantic elements, and enable new features in Web browsers.

Quick Help for Server Staff

Enable GS3

To use GS3 you need to restart the npcserver and add the server option enablegs3=true. At the start of your script add the line

 //#GS3

Conversion Tool

To convert scripts from GS2 to GS3 you can use the online tool at http://graalscript3.graalonline.com/ It can help to convert scripts and also to check for correct syntax, although things like join will not work.

Extern Declarations

Important: for accessing other objects you need to 'include' the other scripts this way (objects are automatically also member of the class of the same name):

 extern global {
   var NPCName:NPCName;
 };

Interaction with GS2

When accessing GS2 objects then you need to declare what members and functions they have, otherwise you will not be able to access them:

 extern class GS2NPCName extends TServerNPC {
   var money:int;
   function addMoney(amount:int):void;
 }
 extern global {
   var GS2NPCName:GS2NPCName;
 }

This can be some work, but when the other object is also GS3 then it's much easier (see External Declarations).

Main changes

In GS3 you need to declare variable types, function return types and function parameter types. That way we can automatically check if you access the variable correctly or call a function with the good parameters, which means less errors.

You also need to declare variables of an NPC (at the start of the script):

 var myvar:string;
 var myvar2:number;

This makes it easier to understand a script and handle objects. If you need to store many dynamic variables for an NPC then you can use arrays or dictionaries.

Joining of classes is still possible but not dynamically. So you have to put the join-call outside of any function:

 join("myclass");
 function onCreated() {
   // Can't join here with this.join() or so!
 }

Advantages

Using types makes prototyping a little bit harder since you have to think about variable types and declare classes or similar to access data.

However for bigger projects (most Graal servers fall under this category) it is very important that scripts can be understood by other scripters, have some structure and don't contain bugs which break the economy or similar. By requiring types a lot of errors can already be detected when writing the script instead of at runtime when players are using the script.

So we have a few advantages:

• Helps to write code which is more reliable and readable
• The structure of objects can be analyzed for automatic script documentation
• Dependencies can be analyzed so you can know which scripts access an object or function
• GraalScript3 can be converted to other languages and platforms, we are preparing something interesting for this to show in a few weeks

Language Elements

Operators

addition (+) operator

Usage

numeric_expression1 + numeric_expression2

Adds together numeric_expression1 and numeric_expression2.
Both expressions must be numeric (int or number types).

To concatenate strings, the append (@) operator must be used instead.

Example

echo(1 + 2); // 3
echo(1.5 + 2.25); // 3.75

addition assignment (+=) operator

Usage

numeric_expression1 += numeric_expression2

Puts the result of numeric_expression1 + numeric_expression2 into numeric_expression1.
Both expressions must be numeric (int or number types).

This is a direct equivalent of the following expression:

numeric_expression1 = numeric_expression1 + numeric_expression2

To concatenate strings, the append assignment (@=) operator must be used instead.

Example

var result : int = 10;
[[result += 20;
echo(result); // 30

]]

append (@) operator

Usage

string_expression1 @ string_expression2

Concats together string_expression1 and string_expression2.
Both expressions must be string (string type).

To add numbers, the addition (+) operator must be used instead.

Example

echo("hello " @ "world"); // "hello world"

as operator

Usage

expression as target_type

Converts the source type of expression to target_type.
The target type must be an object type, not a basic type like int, number, string.
The source type must be a member of the target type.

Example

class Animal { ... }
class Cat extends Animal { ... }
class Dog extends Animal { ... }
var cat : Cat = new Cat();
var dog : Dog = new Dog();
var cat_as_animal : Animal =  cat as Animal; // OK as the Cat type is a member of the Animal type.
var cat_as_cat : Cat = cat_as_animal as Cat; // OK as the Cat type is a member of the Animal type.
var cat_as_dog : Dog = cat as Dog; // KO as the Cat type is not a member of the Dog type.
var cat_as_animal_as_dog : Dog = cat_as_animal as Dog; // null as the Cat as Animal type is not a member of the Dog type.

type (:) operator

Usage

var variable_name : type
function function_name(parameter : type, ...) : return_type { ... }

Specifies the type for a variable or function declaration.
For functions, this operator must be used to specify the return type, and the type of parameters if any.

Example

var language : string = "GScript";
var version : int = 3;

function sayHello() : void {
   echo("hello");
}

function addNumbers(a : int, b : int) : int {
   return a + b;
}

Types

boolean type

Enables to define variables, function parameters or return values with two possible values, true or false. These values represents the result of logical expressions.

Example

var graal_is_cool : boolean = true;
var is_dark : boolean = false;
var is_light : boolean = !is_dark;

int type

Enables to define variables, function parameters or return values with a 32-bit signed integer number type.

With this type, you can define integer numbers between -2,147,483,648 (-2 ^ 31) and 2,147,483,647 (2 ^ 31 - 1).
To work with floating-point numbers, or define numbers outside this range, the number type must be used instead.

Example

var integer_number : int = 123;

string type

Represents textual data using a string of characters.
A string cannot be null but may be empty (with a length of zero).

Example

var text : string = "hello";

void type

Usage

function function_name( ... ) : void { ... }

Specifies that a function does not return any value.
Only empty return statements must be used in functions with void type.

Example

function emptyFunction() : void {
}

function logMessage(message : string, hasLog : boolean) : void {
   if (!hasLog)
      return; // No returned value.
   echo(message);
}

Declaration Keywords

const keyword

Usage

const constant_name : type = constant_value;

Specifies a variable with a unique and constant value at compilation and execution time.
Constants are automatically inlined to their value by the compiler, so it is recommended for optimization purposes to prefer constants to normal variables when their value never changes.

Example

const winning_points : int = 1000;
const hello_text : string = "hello";
const world_text : string = "world";
const hello_world_text : string = hello_text @ world_text;
winning_points = 500; // KO as winning_points must be constant