Scripting hints

• Keys not listed in the ASCII Code Table have no guarantees about their keycode numbers and may well overlap keys that are listed. [1]

• There is no point in using a short rather than an int as a local variable. In fact, ints are faster because the CPU is better at reading/writing 32-bit chunks of memory than it is at 16-bit chunks. [2]

• There is no fixed limit on the size of global arrays, but as scotch says they use up memory so don't go silly with creating massive ones unless you really need to. [3]

• The workaround for displaying player-entered strings, in case anyone wants to know, is simply to do the following, since that way, the player string will not be parsed for special tokens: [4]

Display("%s", playerString);

• You have to place the export after the variable's declaration, so you don't necessarily have to put the exports at the end of scripts. [5]

• Parameters to functions can be made optional by adding a default value in the import of the function. This even works if you are not actually exporting the function.

import function myfun (int a, int b=5);  // optional int b

• Optional parameters only work with int and enum parameters, you can't do it with strings or floats.

You can make a String parameter optional by setting it to 0 (which is the equivalent of setting it to null). You can also do this with other pointer types, such as Character*. You just have to remember that if you make it optional this way then you shouldn't crash (abort) the game if it's null.

• Basically, to be consistent with Java/C#, the protection level always goes first when using protected functions: [6]

protected import static function get_slots();

• It's not until a room is loaded that the current viewport size is known. So better not rely on system.viewport_width or system.viewport_height in game_start. [7] (Tracker)

• You can use return; to abort the rest of the script.

• Local room scripts have their data segment saved when the room is destroyed, so all variables retain their values (for rooms 1-300 only). This is useful for storing the condition of light switches, for example.

• RunInventoryInteraction doesn't get run immediately - instead, it gets run when the calling script finishes. Applies only if the interaction runs a script. Interaction editor commands are executed immediately.

• The number of game loops speech text stays for is: [8]

int gameloops = ((StrLen(text) / game.text_speed) + 1) * GetGameSpeed();

• Functions cannot return structs or arrays - they can only return primitive types. This includes Strings in AGS v2.71. They can also as of v2.7 return any pointer type (pointers are currently only supported for the built-in types such as GUI and Character).

• The character's global inventory variables are integers and can be used to keep track of how many items the character has.

AGS do-while loop

One of the "missing" loop structures in AGS is the "do-while" structure which in other languages looks like this:

 int i = 5;
 do {
   blah();
   i++;
 } while (i < 4);

The point being to ensure that the loop is run at least one time, regardless of the condition. This can however be simulated in AGS using the Game.DoOnceOnly function:

 int i = 5;
 DateTime *now = DateTime.Now;
 while ((i < 4) || (Game.DoOnceOnly(String.Format("%d", now.RawTime)))) {
   blah();
   i++;
 }

In both cases (AGS and the pseudo-C-style programming) i would have a resulting value of 6 and the loop would run exactly one time. This bit of trickery is possible thanks to Game.DoOnceOnly accepting unique ID strings. If you needed to perform more than one do-while within a single second you would have to do something else, perhaps just appending a variable to the end of that, but you should get the idea now.