Creación y llamada de scripts personalizados

Modularización y reutilización de código en GameMaker

A medida que un videojuego crece en complejidad, escribir toda la lógica directamente en los eventos de los objetos (como Create, Step o Draw) se vuelve insostenible. Si necesitas calcular la distancia entre dos entidades, limitar la vida máxima del personaje o aplicar una fórmula de daño en diez objetos distintos, duplicar el mismo bloque de código genera errores difíciles de rastrear, dificulta el mantenimiento e incrementa drásticamente el tiempo de desarrollo. En programación, este problema se resuelve aplicando el principio fundamental DRY (Don't Repeat Yourself, o No te repitas).

En GameMaker, la herramienta principal para estructurar y reutilizar código son los scripts. Un script es un recurso del Asset Browser que actúa como contenedor global donde definimos una o varias funciones personalizadas mediante GML Code. Una vez declarada una función en un script, cualquier objeto, alarma o evento de tu juego puede invocarla de la misma forma en que invoca las funciones nativas del motor (como instance_create_layer, place_meeting o point_distance), pasando argumentos específicos y recibiendo valores procesados.

Creación de un recurso Script en el Asset Browser

Para crear un script en GameMaker, localiza el panel del Asset Browser (generalmente ubicado en el lateral derecho de la interfaz de trabajo). Haz clic derecho sobre la carpeta Scripts o en cualquier espacio vacío del panel, selecciona Create y haz clic en Script. Inmediatamente se creará un nuevo archivo de texto de código y GameMaker te solicitará que le asignes un nombre identificador.

Es una buena práctica de nomenclatura utilizar el prefijo scr_ seguido del área temática que agrupará las funciones contenidas en ese archivo. Por ejemplo, scr_matematicas, scr_combate, scr_movimiento o scr_utilidades. En las versiones modernas de GameMaker (a partir de la versión 2.3), un único recurso de script puede contener múltiples declaraciones de funciones independientes, lo que te permite organizar tu proyecto por módulos temáticos en lugar de tener cientos de archivos individuales con una sola línea cada uno.

💡 Nota histórica importante: En versiones antiguas de GameMaker Studio (1.4 y anteriores a la 2.3), el archivo de script equivalía a una sola función que llevaba el mismo nombre del archivo y recibía parámetros mediante el arreglo interno argument[0], argument[1], etc. En el GameMaker moderno, los scripts son archivos contenedores que declaran funciones formales mediante la palabra clave function con parámetros nombrados.

Anatomía y sintaxis de una función personalizada

Una función es un bloque de instrucciones que realiza una tarea específica, recibe datos de entrada (llamados parámetros o argumentos), ejecuta un procesamiento interno y, opcionalmente, devuelve un resultado al punto del programa donde fue invocada mediante la sentencia return. La estructura básica de una función en GML Code es la siguiente:

// Declaración de una función básica dentro de un Script
function calcular_area_rectangulo(_ancho, _alto)
{
    var _area = _ancho * _alto;
    return _area;
}

Analicemos cada componente de esta estructura: primero, la palabra reservada 'function' indica al compilador de GameMaker que estamos declarando una nueva rutina ejecutable. A continuación, definimos el nombre de la función (calcular_area_rectangulo), el cual debe ser descriptivo, estar en minúsculas y usar guiones bajos según las convenciones estándar de GML. Entre paréntesis colocamos los parámetros separados por comas; en este caso, _ancho y _alto. Dentro del cuerpo de la función, delimitado por llaves {}, realizamos las operaciones necesarias y utilizamos la palabra reservada 'return' para enviar el resultado de vuelta.

Es fundamental utilizar variables locales declaradas con 'var' (como _area) para los cálculos intermedios dentro de una función. Las variables locales solo existen mientras la función se está ejecutando y se liberan de la memoria de inmediato al terminar, evitando contaminar la memoria del objeto que invocó la función o sobrescribir variables de instancia con el mismo nombre accidentalmente.

Documentación con comentarios JSDoc y autocompletado

Uno de los aspectos más potentes de GameMaker es su sistema de autocompletado de código (IntelliSense). Cuando escribes una función nativa como instance_destroy, el editor te muestra en la barra inferior qué argumentos espera y qué hace. Puedes lograr exactamente el mismo comportamiento profesional en tus funciones personalizadas añadiendo comentarios con formato JSDoc inmediatamente antes de la declaración de la función, utilizando la sintaxis de triple barra (///).

/// @function                   calcular_dano_mitigado(_dano_base, _defensa)
/// @description                Calcula el daño final recibido restando el porcentaje de defensa.
/// @param {Real} _dano_base    Cantidad de daño inicial antes de mitigación.
/// @param {Real} _defensa      Puntos de defensa del receptor (rango de 0 a 100).
function calcular_dano_mitigado(_dano_base, _defensa)
{
    // Aseguramos que la defensa se mantenga entre 0 y 90 para no bloquear el 100% del daño
    var _defensa_segura = clamp(_defensa, 0, 90);
    var _factor_reduccion = 1 - (_defensa_segura / 100);
    var _dano_final = _dano_base * _factor_reduccion;
    
    return _dano_final;
}

Al incluir estas cuatro líneas de comentarios JSDoc, cada vez que comiences a escribir 'calcular_dano_mitigado' en cualquier evento de cualquier objeto, GameMaker sugerirá automáticamente la función, resaltará los nombres de los parámetros y te indicará el tipo de dato requerido en la parte inferior de la ventana de código.

Llamada de funciones y ámbito de ejecución (Scope)

Llamar o invocar a una función personalizada es tan simple como escribir su nombre seguido de los argumentos requeridos entre paréntesis dentro de un evento de un objeto. Sin embargo, para evitar errores de lógica, es crucial entender qué ámbito o 'scope' tiene la función en el instante en que se ejecuta.

Cuando una función declarada en un script es invocada desde un objeto (por ejemplo, desde el evento Step de obj_jugador), el contexto de la palabra clave 'self' corresponde a esa instancia específica del jugador. Esto significa que la función puede leer y modificar directamente las variables de instancia de dicho objeto, a menos que esté diseñada como una función puramente matemática.

Distinguir cuándo diseñar una función pura y cuándo una función de acción es una habilidad fundamental. Las funciones puras son más fáciles de depurar y pueden reutilizarse sin riesgo en cualquier parte del proyecto. Las funciones de acción simplifican drásticamente los eventos extensos, convirtiendo un evento Step sobrecargado en una secuencia limpia y legible de llamadas a funciones.

Valores por defecto en parámetros

En el desarrollo de videojuegos, con frecuencia deseamos que ciertos argumentos de nuestras funciones tengan valores predeterminados en caso de que quien las invoque decida no especificarlos. GameMaker permite asignar valores por defecto en la propia lista de parámetros utilizando el operador de asignación (=).

/// @function               aplicar_impulso(_fuerza_x, _fuerza_y = 0)
/// @param {Real} _fuerza_x Fuerza horizontal a aplicar
/// @param {Real} _fuerza_y Fuerza vertical opcional (por defecto 0)
function aplicar_impulso(_fuerza_x, _fuerza_y = 0)
{
    // Modifica las variables de instancia del objeto que llama a la función
    velocidad_x += _fuerza_x;
    velocidad_y += _fuerza_y;
}

Con esta declaración, si llamamos a 'aplicar_impulso(5)' desde el jugador, _fuerza_x tomará el valor 5 y _fuerza_y asumirá automáticamente el valor 0 sin lanzar un error por falta de argumentos. Si llamamos a 'aplicar_impulso(5, -12)', ambos valores serán tomados de los parámetros suministrados explícitamente.