Main

Writing Expressions

Note: Scripting has been enhanced with features not documented below, see this link for what is new: http://www.emix8.org/forum/viewtopic.php?t=704

Scripts and expressions.

ZGameEditor has a simple scripting language. The general syntax is based upon "C"-dialects.

The following syntax is supported.

Comments

// this is a single line comment

/*
   this is a 
   multi line 
   comment
*/

Assignments

[objectname].[propertyname].[propertyindex] = value ;
[localvariable] = value;
[array] = value;

objectname - The name of a component is the value of its "Name"-property and is set in the editor. The special objectname "CurrentModel" can be used if the expression written has a Model-component as a parent.

propertyname - The name of the property to assign.

propertyindex - If the property is an indexed property, then the name of the index must be specified.

For Color-values, this is "R","G","B","A" for the Red/Green/Blue/Alpha components of the color in the range 0 to 1.

For position or vertex-values (such as Model.Position/Rotation/Velocity) the propertyindex is "X","Y","Z" for the value of its corresponding axis.

Example assignments

PlayerModel.Position.X = 42;
PlayerModel.Position.X = PlayerModel.Position.Y / 2;
MyMaterial.Color.R = 0.5;

PlayerScore += 500;

Other C-style assignments are supported also:

  • = - normal assignment
  • += - plus-assign: x+=1 is the same as x=x+1
  • -= - minus-assign: x-=1 is the same as x=x-1
  • *= - multiply-assign: x*=1 is the same as x=x*1
  • /= - divide-assign: x/=1 is the same as x=x/1
  • ++ - pre or post increment of local variables: i++, ++i
  • -- - pre or post decrement of local variables: --i, i--

When assigning a property with several components (such as the x,y and z of Scale or Rotation) to the same value a shorter syntax is allowed.The following assigment:

CurrentModel.Scale=1;

Give the same result as:

CurrentModel.Scale.X=1;
CurrentModel.Scale.Y=1;
CurrentModel.Scale.Z=1;

IF-statements

if( [condition] )

  [one line expression] ;
if( [condition] ) {
  //do something if condition is true
} else {
  //do something else if condition is false
}

condition - An expression which is evaluated to true or false.

Operators that are valid in conditions:

  • == - equal
  • != - not equal
  • > - greater than
  • >= - greater than or equal
  • < - less than
  • <= - less than or equal
  • || - OR, statement is true if any of the conditions are true
  • && - AND, statement is true if both conditions are true
  • ! - NOT, statement is true if condition(s) is/are false

Example IF-statements:

if(PlayerScore>5000)
  PlayerLives += 1;

if( (App.Time>5) && (PlayerLives<2) ) {
  Difficulty *= 1.2;
  Speed *= 1.2;  
}

Loops

For-loops

C-style for-loops can be used:

for ( (defVar optional) <EXPR1> ; <EXPR2> ; <EXPR3> )
{  
  //do something;
}

The expression <EXPR1> is evaluated, then <EXPR2> is checked, if it's true, then the loop body is executed. After the first iteration, the <EXPR3> is evaluated, <EXPR2> is checked again, if it's true, the loop body is executed, etc...

When you want to use a global variable that is already defined by the DefineVariable Component, you can simply write ..

for(x = 0; x<4; ++x){expression;}

In case you want to use a local variable (only exists within the scope that it is defined in), initializing the variable as you need it is more convenient

for(int x = 0; x<4; ++x){expression;}

Change "int" into "float" when you want to use a floating point variables.

While-loops

while(i<42)
{
   //do something;
   i++;    
}

While statements can also be defined using the Repeat component.

Break and continue

Use break to break out of a loop before it has finished execution:

while(i<42)
{
   if(i==10)
     break;  //exit loop
   i++;    
}

Use continue to jump directly to the next loop iteration:

for(int i=0; i<10; i++)
{
   if(i>=5)
     continue;  //keep looping and skip the rest of the loop body
   sum+=i;  //this line only executes when i<5
}

Switch statement

//Switch-statement example
switch(i) {
  case 0 :
  case 1 :
  case 2 :
     //When i is 0, 1 or 2.
     doSomething();
     break;
  case 3 :
     //When i is 3.
     doSomethingElse();
     break;
  default :
    //The default case when i is none of the above
}

Conditional statement

//Conditional statement example
//Give 1000 in bonus when time<100, otherwise bonus will be zero
int bonus= time<100 ? 1000 : 0; 

Bit manipulation operators

  • Hex-values: int x=0x0f; //15
  • Binary AND: int x=0xff & 0x0f; //0xf (15)
  • Binary OR: int x=1 | 2 | 4; //7
  • Binary Shift left: int x=1 << 1; //2
  • Binary Shift right: int x=2 >> 1; //1

Built in functions

  • sin(x) - returns the sine of the angle x in radians
  • sqrt(x) - square root of x
  • cos(x) - cosine of the angle x in radians.
  • tan(x) - tangent of x
  • abs(x) - absolute (positive) value of x
  • rnd() - returns values in the range: 0 <= Number < 1.0
  • random(base,variance) - random number in the range base-variance to base+variance
  • atan2(y,x) - arctangent angle and quadrant of a given number
  • noise2(x,y)
  • noise3(x,y,z) - 2 and 3 dimensional Perlin Noise. Return values in an approximate range of -0.3 to 0.3 so you need to scale it to get a -1 to 1 range. More info: Hugo Elias article about noise.
  • frac(x) - fractional (decimal) part of x
  • exp(x) - the exponential of x
  • clamp(x,min,max) - clamps the value x to be in the range min to max
  • pow(base,exponent) - raises base to any power
  • centerMouse() - centers the mouse cursor
  • setRandomSeed(x) - set the random seed value to x, returns the old seed.
  • getSystemTime() - returns seconds elapsed since midnight.
  • floor(x) - returns the floor of x (the highest integer less than or equal to x)
  • ceil(x) - returns the ceiling of x (the smallest integer larger than x)
  • acos(x) - returns the inverse cosine of x
  • asin(x) - returns the inverse sine of x
  • round(x) - rounds a floating point Number to an Integer value.
  • quit() - quit the application
  • joyGetAxis(joyId,axisNr) - return position of joystick axis
  • joyGetButton(joyId,buttonNr) - return state of joystick button
  • joyGetPOV(joyId) - return position of joystick POV-control
  • trace(message) - shows a message in the log-window. Useful for debugging.
  • also see string-functions in the string section below

User defined functions

Define functions using the ZLibrary component. Call external modules (dll:s) using the ZExternalLibrary component

Predefined constants

  • PI

Variables

Global variables can be defined with the DefineVariable component.

Arrays can be defined with the DefineArray component.

Local variables can be defined with the following syntax:

  • float x1,x2,x3; //define three local variables
  • float x=1.5; //define and initialize one local variable
  • int i=1; //define and initialize one local variable of integer type

Note that local variables and arrays are not initialized, you need to assign a value before using them:

//S is unitialized, this will generate a runtime error
string s;
s=s + "x";

//Ok initialize S before use
string s="";
s=s + "x";

Strings

The scripting language also handles strings.

Example - RenderText component named ScoreJimmy
int Sc=5;
ScoreJimmy.Text = "Score: "+intToStr(1+Sc);//"Score: 6"//Jimmy padded!

There are a number of built-in functions for strings:

  • string s = intToStr(42); //"42" //convert from integer
  • int i = strToInt("42"); //42 //convert to integer
  • string s = chr(65); //"A" //chr(charcode) : return character from ansi-code
  • int i=ord("A"); //65 //ord(string) : return ansi-code from character
  • int i = length("1234"); //4 //returns length of string
  • int i = indexOf("lo","hello",0); //3 //indexOf(substr, str, startpos) : returns position of substring in string from a start position. Startpos must be less than length of string.
  • string s = subStr("hello",0,2); //"he" //subStr(source, startpos, length) : returns substring. Startpos and length must be within source-string bounds.

Special characters in string literals

  • "\"" : double quote character
  • "\n" : newline character
  • "\\" : backslash character

Green Marinee theme adapted by David Gilbert, powered by PmWiki