Scripts are essentially functions that you write yourself as short snippets of code that can resolve expressions, return values or anything else that the language permits. Basically if you have a block of code that you use in more than one place or object, then it's probably better off in a script, as it means that you can change it once when required and the change will be "picked up" by every object that has a call to the script. They can also be very handy from an organisational point of view, even if the code they hold is called only once by a single object, since it permits you to break large code blocks into more easily managed "chunks" at logical points.

When you create a script the values that you choose to pass into it are called arguments and you'll want to access these arguments - either when using the script action, or when calling the script as a function from a program or from another script. These arguments are stored in the built in variables:

argument0, argument1, ..., etc... up to argument15

So there can be at most 16 arguments passed through to a script when called from code using the argument variables, and when using the argument0...15 variables for a script, you must ensure that the script uses all the supplied arguments. For example if you have a script that takes two arguments and you only supply one then you will get an error for that script. The same goes if you supply more arguments than you require.

However you can supply a variable number of arguments to a script using the built in argument array, and you are not limited to a maximum of 16 arguments either when using this array, but instead can have as many as you require (although, again, you must ensure that all arguments are referenced within the script):

argument[0 ... max_num]

When passing in a variable number of arguments as an array of values you can use the following function:

• argument_count

This can be used to find out how many arguments have been passed and adapt the script to use only those arguments supplied.

Scripts can also return a value, so that they can be used in expressions. For this you would use the return statement:

return <expression>

It should be noted that the execution of the script ends at the return statement, meaning that any code which comes after the return has been called will not be run. Here is a short example script called "scr_sqr" which calculates the square of whatever value is passed to it, and it includes error catching in case the argument that it is passed is not a real number:

{
if !is_real(argument0)
   {
   return 0;
   }
else
   {
   return (argument0 * argument0);
   }
}

To call a script from within a piece of code, just act the same way as when calling functions - that is, write the script name with the argument values in parentheses. So, the above script would be called like this:

if keyboard_check_pressed(vk_enter)
   {
   val = scr_sqr(amount);
   }

It is worth noting that when writing your own scripts they can also have certain JSDoc style comments added so that when you use them in your code they show up in auto-complete along with their arguments and other details. you can find out more about this from the section JSDoc Script Comments for more information. Further note that when you are typing out your scripts in the code editor, you can click or use the middle mouse button on the script name to open it for editing directly.