Script language keywords

Arrays
Data types
Operators
Constants
Version checking
if, else statements
while
function
struct
enum
this
import
export
noloopcheck

Arrays

Arrays allow you to easily create several variables of the same type. For example, suppose you wanted to store a health variable for all the different characters in the game. One way would be to declare several different variables like this:

int egoHealth;
int badGuyHealth;
int swordsmanHealth;

int health[50];

Here's an example of using the array:

  health[3] = 50;
  health[4] = 100;
  health[player.ID] = 10;

See Also: Dynamic arrays

Data types

You will normally only need to use the int and String data types. The smaller types are only useful for conserving memory if you are creating a very large number of variables.

To declare a variable, write the type followed by the variable name, then a semicolon. For example:

int my_variable;

declares a new 32-bit integer called my_variable

WARNING: When using the float data type, you may find that the == and != operators don't seem to work properly. For example:

float result = 2.0 * 3.0;
if (result == 6.0) {
  Display("Result is 6!");
}

float result = 2.0 * 3.0;
if ((result > 5.99) && (result < 6.01)) {
  Display("Result is 6!");
}

Operators

WARNING: When using operators of equal precedence, AGS by default evaluates them right-to-left. So, the expression a = 5 - 4 - 2; evaluates as a = 5 - (4 - 2); which is not what you might expect. Always use parenthesis to make it clear what you want.
The "Left-to-right operator precedence" option on the General Settings pane allows you to control this behaviour.

Operator  Description              Example

  !    NOT                        if (!a) 
  *    Multiply                   a = b * c;
  /    Divide                     a = b / c;
  %    Remainder                  a = b % c;
  +    Add                        a = b + c;
  -    Subtract                   a = b - c;
  <<   Bitwise Left Shift         a = b << c;
       (advanced users only) 
  >>   Bitwise Right Shift        a = b >> c;
       (advanced users only) 
  &    Bitwise AND                a = b & c;
       (advanced users only) 
  |    Bitwise OR                 a = b | c;
       (advanced users only) 
  ^    Bitwise XOR                a = b ^ c;
       (advanced users only) 
  ==   Is equal to                if (a == b)
  !=   Is not equal to            if (a != b)
  >    Is greater than            if (a > b)
  <    Is less than               if (a < b)
  >=   Is greater than or equal   if (a >= b)
  <=   Is less than or equal      if (a <= b)
  &&   Logical AND                if (a && b)
  ||   Logical OR                 if (a || b)

if (!a && b < 4)

which will execute the 'if' block if a is 0 and b is less than 4.

However, it is always good practice to use parenthesis to group expressions. It's much more readable to script the above expression like this:

if ((!a) && (b < 4))

Constants

You can check for whether a macro is defined or not by using the #ifdef and #ifndef keywords:

#ifndef STRICT
  // only compile the MoveCharacter command if not using object-based scripting
  MoveCharacter(EGO, 30, 40);
#endif
#ifdef DEBUG
  // only display this when the game is compiled in debug mode
  Display("Debugging information");
#endif

#ifndef AGS_NEW_STRINGS
#error This script requires at least AGS 2.71
#endif

int invWeights[AGS_MAX_INV_ITEMS];

Version checking

For this purpose there are two directives:

#ifver 2.72
// do stuff for 2.72 and above
#endif
#ifnver 2.72
// do stuff for 2.71 and below
#endif

if, else statements

If expression is true, then statements1 are run.

If expression is not true, and there is an else clause present, then statements2 are run instead.

For example:

if (GetGlobalInt(5) == 10) {
  Display("Globalint 5 is 10.");
}
else {
  Display("Globalint 5 is not 10.");
}

if statements can be nested inside else statements to produce an "else if" effect. For example:

if (GetGlobalInt(5) == 1) {
  Display("Globalint 5 is 1.");
}
else if (GetGlobalInt(5) == 2) {
  Display("Globalint 5 is 2.");
}
else {
  Display("Globalint 5 is not 1 or 2.");
}

while

Runs statements continuously, while expression is true.

For example:

while (cEgo.Moving) {
  Wait(1);
}

function

Declares a custom function in your script. A function is a way in which you can separate out commonly used code into its own place, and thus avoid duplicating code.

For example, suppose that you quite often want to play a sound and add an inventory item at the same time. You could write both commands each time, or you could define a custom function:

function AddInvAndPlaySound(InventoryItem* item) {
  player.AddInventory(item);
  aInventorySound.Play();
}

AddInvAndPlaySound(iKey);

Generally, you place your functions in your global script. You then need to add an import line to your script header to allow the function to be called from room scripts.

Optional parameters

You can make int parameters optional if there is a default value that the user doesn't need to supply. To do this, change the script header import declaration like this:

import function TestFunction(int stuff, int things = 5);

NOTE: To use optional parameters, you need to have an "import" declaration for the function in the script header. The default values cannot be specified in the actual function declaration itself.

struct

Declares a custom struct type in your script.
Structs allow you to group together related variables in order to make your script more structured and readable. For example, suppose that wanted to store some information on weapons that the player could carry. You could declare the variables like this:

int swordDamage;
int swordPrice;
String swordName;

struct Weapon {
  int damage;
  int price;
  String name;
};

Weapon sword;
sword.damage = 10;
sword.price = 50;
sword.name = "Fine sword";

// at top of script
Weapon weapons[10];
// inside script function
weapons[0].damage = 10;
weapons[0].price = 50;
weapons[0].name = "Fine sword";
weapons[1].damage = 20;
weapons[1].price = 80;
weapons[1].name = "Poison dagger";

enum

enum name {
option1 [ = value1 ],
option2 [ = value2 ],
...
};

Declares an enumeration type. An enumeration allows you to group together a set of related options, where only one will be true at any one time -- a bit like the contents of a list box.

For example, if you have a script function, doStuff, that can perform 3 different operations, you could do this:

function doStuff(int param) {
  if (param == 1) {
    // do something
  }
  else if (param == 2) {
    // do something else
  }
  // etc
}

enum DoStuffOption {
  BakeCake,
  DoLaundry
};

function doStuff(DoStuffOption param) {
  if (param == BakeCake) {
    // do something
  }
  else if (param == DoLaundry) {
    // do something else
  }
  // etc
}

Normally, you would put the enum definition into the script header.

In summary, enums are not an essential part of scripting and you can get away perfectly well without using them, but in some specific situations they're very handy.

this

1. Accessing members of the current struct

When you are creating custom structs, you use the "this" keyword inside member functions to refer to the current struct. For example:

Suppose you had this in your script header:

struct MyStruct {
  int myValue;
  
  import function MyMethod();
};

function MyStruct::MyMethod()
{
  this.myValue = 5;
}

The code above will mean that when the MyMethod function is called, it sets the myValue variable to 5.

2. Declaring extender functions

Please see the Extender functions page for details.

import

Declares declaration as a variable or function which is external to the current script, but that the script needs access to it. You use this to provide your room scripts with access to parts of your global script.

For example:

import int counter;
import function add_numbers (int, int);

In order to import the variable, it must have been exported from the global script with the export keyword.

NOTE: You MUST import external variables with the correct type. If counter was declared as a short in the global script, you MUST import it as a short, otherwise your game may crash.

NOTE: You cannot import old-style string variables (this does not apply to new-style String variables).

export

Declares that variable can be exported and accessed by other scripts. You must place this at the end of your global script. You can export many variables with one export line.

For example:

export my_variable;
export counter, strength;

noloopcheck

The noloopcheck keyword disables the script loop checking for the current function.

Normally, if a while loop runs for more than 150,000 loops, AGS will assume that the script has hung and abort the game. This is to assist scripting since otherwise the game would lock up if you scripted a loop wrongly.

However, there are some rare situations in which you need a loop to run several thousand times (for example, when initialising a very large array). In this case, the noloopcheck keyword can be used to stop AGS aborting your script.

NOTE: The noloopcheck keyword must be placed between "function" and the function's name.
If you import the function into the script header, you do not include the "noloopcheck" keyword in the import declaration -- it is only included in the actual function body.

NOTE: If AGS gives you a script iterations error, DO NOT just automatically add this keyword as a way to fix the problem -- more often than not, it is a fault in your scripting and using this keyword will mean that the game will hang rather than abort.

For example:

function noloopcheck initialize_array() {
  char bigarray[200000];
  int a = 0;
  while (a < 200000) {
    bigarray[a] = 1;
    a++;
  }
}