Variable Scope and Best Practices

Best Coding Practices and Clean Code in GameMaker

Writing code is not just about getting the game to run on screen; it's about making it understandable, scalable, and maintainable. When you return to your project weeks after taking a break, disorganized code will be confusing even to you. Below, we review essential guidelines for maintaining professional standards in GameMaker.

1. Clear and Consistent Naming Conventions

In GameMaker, it is strongly recommended to use three-letter prefixes for project assets, preventing confusion between visual assets, objects, or audio files:

• Sprites: `spr_personaje_caminar`, `spr_bloque_piso`, `spr_moneda`. • Objects: `obj_jugador`, `obj_enemigo_patrulla`, `obj_bloque_solido`. • Sounds: `snd_salto`, `snd_moneda`, `mus_nivel_1`. • Rooms: `rm_menu_inicio`, `rm_nivel_1`, `rm_pantalla_victoria`. • Scripts: `scr_calcular_danio`, `scr_guardar_partida`.

For variables, 'snake_case' (lowercase words separated by underscores) is recommended, using descriptive names that explain their purpose without guesswork. Avoid single-letter generic names like `a = 10;` or `temp = true;`. Instead, use `velocidad_maxima = 10;` or `esta_invencible = true;`.

2. Avoiding Magic Numbers with Variables and Macros

A 'magic number' is a hardcoded numeric value placed directly in game logic without clear context. For example, writing `if (y > 720) { instance_destroy(); }` in a Step event. If you later decide to change screen resolution or level height, you will have to manually hunt down every instance of '720' scattered across dozens of objects.

Instead, declare a descriptively named variable or define a global macro using the `#macro` directive. Macros replace an identifier with a constant value before compilation and cannot be altered at runtime:

// Macro declarations in a global script (for example: scr_configuracion)
#macro LIMITE_INFERIOR_PANTALLA 720
#macro GRAVEDAD_BASE 0.4
#macro MAX_VIDAS 3

// Clean usage in the Step event of obj_jugador:
if (y > LIMITE_INFERIOR_PANTALLA) {
    scr_reiniciar_posicion_jugador();
}

3. Meaningful Comments and Visual Formatting

Code comments should explain the 'why' behind a design decision, rather than merely repeating what the syntax already makes obvious. GML supports single-line comments with `//` and multi-line comment blocks with `/* ... */`.

// Redundant comment (provides no real value):
// Add 5 to x
x = x + 5;

// Clean, descriptive comment (explains design intent):
// Add constant velocity to simulate conveyor belt movement
x = x + velocidad_cinta;

Practical Example: Clean Refactoring of Player and Controller

Let's apply everything we've learned to the architecture of our retro platformer. We will coordinate two clean elements: the general management object `obj_controlador_juego` and a refactored version of basic movement for our `obj_jugador` using instance, local, and global variables.

Step 1: Create the object `obj_controlador_juego`. In the GameMaker Inspector, check the 'Persistent' box. In its Create event, initialize the global state:

// Asset: Objects -> obj_controlador_juego
// Event: Create

// Initialize global game variables
global.puntuacion = 0;
global.vidas = 3;
global.nivel_completado = false;

// Confirmation message in the GameMaker debug console
show_debug_message("Game system initialized successfully.");

Step 2: Now open `obj_jugador`. In its Create event, declare only its instance variables, avoiding temporary variables that are only needed for momentary calculations:

// Asset: Objects -> obj_jugador
// Event: Create

// Instance variables: velocity and physical state
velocidad_movimiento = 3.5;
velocidad_vertical = 0;
velocidad_horizontal = 0;
fuerza_salto = -8;
gravedad_personaje = 0.35;
estrellado_contra_suelo = true;

Step 3: In the Step event of `obj_jugador`, use local variables (`var`) to capture keyboard inputs and compute frame velocities. Notice how none of these intermediate variables clutter the instance's persistent memory:

// Asset: Objects -> obj_jugador
// Event: Step

// 1. Read input using local variables
var presiona_izquierda = keyboard_check(vk_left) || keyboard_check(ord("A"));
var presiona_derecha = keyboard_check(vk_right) || keyboard_check(ord("D"));
var presiona_salto = keyboard_check_pressed(vk_space) || keyboard_check_pressed(ord("W"));

// 2. Vector calculation of horizontal axis using a local variable
var direccion_horizontal = presiona_derecha - presiona_izquierda;

// 3. Assign movement to instance variables
velocidad_horizontal = direccion_horizontal * velocidad_movimiento;

// Apply gravity to instance vertical velocity
velocidad_vertical += gravedad_personaje;

// 4. Provisional basic jump when pressed
if (presiona_salto && estrellado_contra_suelo) {
    velocidad_vertical = fuerza_salto;
    estrellado_contra_suelo = false;
}

// 5. Apply physics to the instance's built-in coordinates
x += velocidad_horizontal;
y += velocidad_vertical;

// Provisional floor clamp for testing (actual collision will be covered in Module 5)
if (y >= 400) {
    y = 400;
    velocidad_vertical = 0;
    estrellado_contra_suelo = true;
}

By clearly separating transient variables (`presiona_izquierda`, `direccion_horizontal`) from sustained entity states (`velocidad_vertical`, `estrellado_contra_suelo`) and global values (`global.vidas`), we build a robust, readable technical foundation ready for complex systems without scope collisions or memory waste.

Hands-on Exercises

Test your understanding of the three variable scopes and GML best practices by completing the following three guided exercises:

Exercise 1: Refactoring Code with Leaked Scope Analyze the following problematic snippet written in the Step event of a projectile fired by the player (`obj_proyectil`). A beginner developer forgot to use `var` on variables only needed for an immediate trigonometric calculation: ```gml // Problematic snippet: angulo_rad = degtorad(image_angle); componente_x = cos(angulo_rad) * 6; componente_y = -sin(angulo_rad) * 6; x += componente_x; y += componente_y; ``` Rewrite the snippet correcting the scope so that these three intermediate variables (`angulo_rad`, `componente_x`, `componente_y`) become strictly temporary local variables. Verification check: Verify that by prepending the `var` keyword to these variables, the projectile continues moving smoothly across the screen while no longer appearing as persistent instance properties in the debugger's 'Variables' tab.

Exercise 2: Creating a Collectible Coin Object with a Global Variable Create a new object in your project named `obj_moneda`. Assign it a simple square or circular gold sprite (you can draw it in GameMaker's sprite editor at 16x16 pixels). In the Collision event between `obj_moneda` and `obj_jugador`, implement the following actions: 1. Add 25 points to the global variable `global.puntuacion`. 2. Display a console message using `show_debug_message()` showing the new point total. 3. Destroy the collected coin instance with `instance_destroy()`. Verification check: Place three coins in your room `rm_nivel_1`. Run the game, collect them, and watch GameMaker's Output window; the counter should sequentially increase to 25, 50, and 75 as the coins disappear from the room.

Exercise 3: Spotting and Resolving Variable Shadowing Imagine a developer wrote in the player's Create event: `velocidad = 5;`. Then, in the Step event, they accidentally wrote: `var velocidad = 10; x += velocidad;`. Explain in writing what happens to the original instance variable during that frame and what visual effect it produces on the player. Modify the code so the variables have clear, distinct names and do not shadow each other. Verification check: Verify that the player moves at the intended instance speed setting without a temporary variable shadowing the object's instance variable.