Script Functions And Variables

Script assets are essentially a collection of one or more user defined functions or variables that you write yourself as short snippets of code in the Script Editor. The functions you define in a script can resolve expressions, return values or do anything else that the GameMaker Language permits, just like the built in runtime functions.

Script functions should generally be used if you have a block of code that you use in more than one place or object, or when you want a block of code to be used across multiple objects in a modular fashion. Using scripts to define functions means that you can change the function just once when required and the change will be "picked up" by every object that has a call to the function.

Scripts can also be very handy from an organizational point of view, as they permit you to create groups of functions that all work within the same namespace - for example, you might have several functions all related to collisions between instances in your game, so you would create a "Collision_Functions" script and store all these functions together in it.

When creating a script with functions in it, the functions must be created using the following formats:

function <name>( <parameter1>, <parameter2>, etc... )
    {
    <statement1>;
    <statement1>;
    ...
    }

or:

<name> = function( <parameter1>, <parameter2>, etc... )
    {
    <statement1>;
    <statement1>;
    ...
    }

In general, however, you would use the first form for script functions as it will define the function as specifically being a script function, meaning that it will be global in scope, be assigned a script index, and not require the global prefix to identify it since the compiler will recognise it as a script function. Using the second form will instead be generating a global scope method variable, and as such it will not be recognised as a script function by the IDE and will require the use of the global prefix when being referenced in your code.

NOTE: You can check this by using both forms in a script and then calling the runtime function typeof() on each of them. One will be classed as a "number" - since it returns a script index ID - and the other will be classed as a "method".

We also recommend that you add comments to define the properties of the function (see the section on JSDoc Comments for more details), such that a simple script would look like this:

/// @function                 log(message);
/// @param {string}  message  The message to show
/// @description              Show a message whenever the function is called.

function log(message)
    {
    show_debug_message(message);
    }

Additional functions for the script can be added using the same format as shown above, one after the other within the script asset.

Functions in scripts can also return a value, just as runtime functions can, and as such 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 function 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 function from a script called "sqr_calc" which calculates the square of whatever value is passed to it, and it includes error catching in case the parameter that it is passed is not a real number:

/// @function           sqr_calc(val);
/// @param {real}  val  The value to calculate the square of
/// @description        Calculate the square of the given value

function sqr_calc(value)
    {
    if !is_real(value)
        {
        return 0;
        }
    else
        {
        return (value * value);
        }
    }

Note that if you create a script function with no return value then in your code check for one, you will get the value undefined by default.

To call a script function from within a piece of code, just use it the same way as when calling any runtime function - that is, write the function name with the parameter values in parentheses. So, the above script would be called like this:

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

NOTE: When using your own functions from scripts in the code editor, you can press  or click the middle mouse button  on the function name to open the script that contains it for editing directly.

It is important to understand that script names are independent of the functions that they contain, so you can name your scripts in a more "common sense" way, ie: all your AI functions could go in a script "Enemy_AI" (following the standard asset naming conventions of alpha-numeric characters and the underbar "_" only). However, you can still call scripts in your game - and you can name scripts the same as a function that you define in them - which can give rise to a issues due to the way that GameMaker Studio 2 stores asset references. To give an example consider this code, called from an instance:

function indirectCall(func, arg)
    {
    func(arg);
    }
indirectCall(myscript, arg);

The above code is attempting to call a script called "myscript" within a method, which in this case will fail. This is because the in-line function is actually using the index for the script asset and not actually calling the script - eg: if the script index resolves to "4", essentially the function is calling 4(arg);, which makes no sense. The code should instead be structured in one of the following two ways:

function indirectCall(func, arg)
    {
    func(arg);
    }
indirectCall(method(undefined, myscript), arg);

// OR

function indirectCall(func, arg)
    {
    script_execute( func, arg);
    }
indirectCall(myscript, arg);

This is important to note, especially when working with legacy projects where scripts contain one single function, and the function is named the same as the scrpt. However, you really should never do this, and your scripts should be named independatly of the functions they contain.

This leads us to the final and most important thing to know about scripts and the functions they contain: scripts are parsed on a global level and will be compiled at the very start of the game. This means that technically all functions in a script are "unbound" method variables, and any variables declared outside of a function in the script will be considered global variables. For example, consider this script:

function Foo()
    {
    // Do something
    }
blah = 10;
function Bar()
    {
    // Do something else
    }

In the above case, not only have we defined the functions Foo and Bar but also the variable blah and all of them are considered to have been created in the global scope. The functions don't need the global keyword to be recognized as the compiler understands that these functions are part of the script, but if you wanted to access blah then you would need to do:

val = global.blah;

That said, we recommend that you always explicitly type global variables when creating them in scripts to prevent any issues later. Scripts are also an ideal place to define any Macros or Enums (constants), as adding them to a script outside of a function also means that they will be created for use before the game code actually starts running. Below is an example of a script that is creating different global scope values for a game:

/// Initialise All Global Scope Values And Constants
global.player_score = 0;
global.player_hp = 100;
global.pause = false;
global.music = true;
global.sound = true;

enum rainbowcolors {
    red,
    orange,
    yellow,
    green,
    blue,
    indigo,
    violet
    }

#macro weapon_num 3
#macro weapon_gun 0
#macro weapon_bomb 1
#macro weapon_knife 2

Note how all these constants are set up outside of any function call, meaning they will be initialised before everything else and at a global scope. This means that if you want to use a script to initialise variables on an instance scope then you must wrap them in a function, for example:

/// @function                init_enemy();
/// @description             Initialise enemy instance vars

function init_enemy()
    {
    hp = 100;
    dmg = 5;
    mana = 50;
    }

So, scripts can be used to generate macros, enums and global variables before the game starts so they are ready for use at any time, and they can also be used to create "unbound" methods (user-defined functions) that can be used in your game like GML runtime functions.

One final thing to note about script functions is that if you are developing for Web (ie: targeting HTML5), then there is an additional function protocol that you can use when adding functions to scripts, which is to prefix a function name with gmcallback_, for example:

gmcallback_create_button

Using the above function name would mean that the function gmcallback_create_button() will not be obfuscated and so can be used in JavaScript extensions and other areas of your game, for example, when using the clickable_* functions.