Creating and Calling Custom Scripts

Code Modularization and Reusability in GameMaker

As a game grows in complexity, writing all logic directly inside object events (such as Create, Step, or Draw) quickly becomes unsustainable. If you need to calculate the distance between two entities, cap the player's maximum health, or apply a damage formula across ten different objects, duplicating the same block of code introduces hard-to-trace bugs, complicates maintenance, and drastically increases development time. In programming, this issue is solved by applying the fundamental DRY (Don't Repeat Yourself) principle.

In GameMaker, the primary tool for structuring and reusing code is scripts. A script is an Asset Browser resource that acts as a global container where we define one or more custom functions using GML Code. Once a function is declared inside a script, any object, alarm, or event in your game can call it just like a built-in engine function (such as instance_create_layer, place_meeting, or point_distance), passing specific arguments and receiving processed values.

Creating a Script Resource in the Asset Browser

To create a script in GameMaker, locate the Asset Browser panel (usually on the right side of the workspace). Right-click the Scripts group or any empty space in the panel, select Create, and click Script. A new code file will be created immediately, prompting you to name it.

It is good naming practice to use the prefix scr_ followed by the functional domain grouping the functions within that file. For example, scr_math, scr_combat, scr_movement, or scr_utilities. In modern versions of GameMaker (version 2.3 and later), a single script resource can contain multiple independent function declarations, allowing you to organize your project into thematic modules rather than having hundreds of individual single-line files.

💡 Important historical note: In older versions of GameMaker Studio (1.4 and pre-2.3), a script file was equivalent to a single function carrying the name of the file and receiving arguments via the built-in argument[0], argument[1], etc. array. In modern GameMaker, scripts are container files that declare formal functions using the function keyword with named parameters.

Anatomy and Syntax of a Custom Function

A function is a block of statements that performs a specific task, accepts input data (called parameters or arguments), executes internal processing, and optionally returns a result to the caller via the return statement. The basic structure of a function in GML Code is as follows:

// Basic function declaration inside a Script
function calcular_area_rectangulo(_ancho, _alto)
{
    var _area = _ancho * _alto;
    return _area;
}

Let's break down each component of this structure: first, the 'function' keyword tells the GameMaker compiler that we are declaring a new executable routine. Next, we define the function name (calcular_area_rectangulo), which should be descriptive, lowercase, and use snake_case per standard GML conventions. Inside parentheses, we place parameters separated by commas—in this case, _ancho and _alto. Inside the function body, enclosed in curly brackets {}, we perform the necessary operations and use the 'return' keyword to send the result back.

Using local variables declared with 'var' (such as _area) for intermediate calculations within a function is essential. Local variables only exist while the function is actively executing and are immediately cleared from memory upon completion, avoiding memory clutter in the calling object or accidentally overwriting instance variables with the same name.

Documentation with JSDoc Comments and Autocompletion

One of GameMaker's most powerful features is its code autocompletion (IntelliSense) system. When you type a built-in function like instance_destroy, the editor displays in the status bar what arguments it expects and what it does. You can achieve the exact same professional behavior in your custom functions by adding JSDoc-formatted comments immediately before the function declaration, using triple-slash (///) syntax.

/// @function                   calcular_dano_mitigado(_dano_base, _defensa)
/// @description                Calculates the final damage received after defense percentage reduction.
/// @param {Real} _dano_base    Base incoming damage before mitigation.
/// @param {Real} _defensa      Receiver's defense points (range 0 to 100).
function calcular_dano_mitigado(_dano_base, _defensa)
{
    // Ensure defense stays between 0 and 90 so it never blocks 100% of damage
    var _defensa_segura = clamp(_defensa, 0, 90);
    var _factor_reduccion = 1 - (_defensa_segura / 100);
    var _dano_final = _dano_base * _factor_reduccion;
    
    return _dano_final;
}

By including these four lines of JSDoc comments, whenever you begin typing 'calcular_dano_mitigado' in any event across any object, GameMaker will automatically suggest the function, highlight parameter names, and display the expected data types at the bottom of the code editor.

Calling Functions and Execution Scope

Calling or invoking a custom function is as simple as typing its name followed by the required arguments in parentheses inside an object event. However, to avoid logic errors, it is crucial to understand the execution context or 'scope' of the function when it runs.

When a function declared in a script is called from an object (for instance, from the Step event of obj_jugador), the context of the 'self' keyword belongs to that specific calling instance. This means the function can directly read and modify that object's instance variables, unless it is designed as a purely mathematical function.

Knowing when to design a pure function versus an action function is a fundamental skill. Pure functions are easier to debug and can be safely reused anywhere in your project. Action functions dramatically simplify bloated events, turning an overloaded Step event into a clean, readable sequence of function calls.

Default Parameter Values

In game development, we frequently want certain function arguments to have default fallback values if the caller omits them. GameMaker allows default values right in the parameter list using the assignment operator (=).

/// @function               aplicar_impulso(_fuerza_x, _fuerza_y = 0)
/// @param {Real} _fuerza_x Horizontal force to apply
/// @param {Real} _fuerza_y Optional vertical force (defaults to 0)
function aplicar_impulso(_fuerza_x, _fuerza_y = 0)
{
    // Modifies instance variables of the calling object
    velocidad_x += _fuerza_x;
    velocidad_y += _fuerza_y;
}

With this declaration, calling 'aplicar_impulso(5)' from the player sets _fuerza_x to 5 while _fuerza_y automatically defaults to 0 without throwing a missing argument error. If we call 'aplicar_impulso(5, -12)', both parameters take their explicitly supplied values.