---

name: gamemaker-gml description: "Best practices for GameMaker Language (GML) development, covering scripts, object events, rooms, data structures, and performance-minded game code. Use when writing GML scripts or object event code in GameMaker Studio, structuring create/step/draw events, managing rooms and instances, building state machines for gameplay, or optimizing GML for performance." metadata: maintainer: Mindrally source: https://github.com/Mindrally/skills

GameMaker Language (GML) Development

This skill covers writing maintainable, performant game code in GameMaker Language (GML), including code organization, style conventions, gameplay architecture, and performance patterns specific to GameMaker Studio.

Workflow for Building GML Gameplay Features

1. Design the object — Decide what Create, Step, Draw, Collision, and Alarm events the object needs, and what data it owns.
2. Initialize in Create — Set default variable values, instantiate data structures (ds_map, ds_list, structs), and cache references (layer IDs, other instance IDs) in the Create event.
3. Simulate in Step — Put input handling, physics/movement, state machine transitions, and collision response in Step (or Step-adjacent events like Begin/End Step).
4. Render in Draw — Keep Draw events limited to rendering; never mutate gameplay state there.
5. Extract reusable logic into scripts — Move any behavior used by more than one object, or any event body that's grown complex, into a named script/function.
6. Clean up on Destroy/Room End — Destroy any manually created data structures (ds_list_destroy, etc.) and free surfaces to avoid memory leaks.
7. Profile before optimizing — Use GameMaker's built-in profiler or manual timing (get_timer()) to find actual hot paths before restructuring for performance.

Code Organization

• Keep object event code short; move any reusable behavior into scripts or named functions instead of duplicating logic across events or objects.
• Use clear, consistent prefixes or naming conventions for scripts (scr_), objects (obj_), sprites (spr_), rooms (rm_), and global variables/macros, matching whatever convention the project has already established.
• Prefer functions over copy-pasted event blocks — if the same five lines appear in two objects' Step events, it belongs in a script.
• Keep Create/Step/Draw responsibilities separate: initialization goes in Create, simulation and logic in Step, and rendering-only work in Draw (and Draw GUI for HUD/UI elements that shouldn't scale/move with the room camera).

GML Style

• Use descriptive variable names (player_speed, enemy_target) and avoid single-letter names outside small, obviously-scoped loops (for (var i = 0; i < count; i++)).
• Prefer local variables declared with var (function/event-scoped) over unnecessary instance variables — instance variables should hold state that genuinely needs to persist or be accessed elsewhere.
• Use constants, enums (enum PlayerState { IDLE, RUN, JUMP }), and macros (#macro) for repeated identifiers, layer names, state IDs, and collision groups — never scatter raw numeric or string literals for meaningful values.
• Guard optional or possibly-stale instance references with instance_exists(other_id) before accessing their variables, since instance IDs can become invalid after the referenced instance is destroyed.
• Keep global state (global.*) minimal and documented; excessive globals make an object's actual dependencies invisible.

Example: A State Machine with a Script and an Object

// scr_player_states.gml
function player_state_enter(_inst, _state) {
    _inst.state = _state;
    switch (_state) {
        case PlayerState.IDLE:
            _inst.sprite_index = spr_player_idle;
            break;
        case PlayerState.RUN:
            _inst.sprite_index = spr_player_run;
            break;
        case PlayerState.JUMP:
            _inst.sprite_index = spr_player_jump;
            _inst.vspeed = -_inst.jump_force;
            break;
    }
}

function player_state_step(_inst) {
    switch (_inst.state) {
        case PlayerState.IDLE:
            if (_inst.input_x != 0) {
                player_state_enter(_inst, PlayerState.RUN);
            } else if (!_inst.on_ground) {
                player_state_enter(_inst, PlayerState.JUMP);
            }
            break;

        case PlayerState.RUN:
            _inst.hspeed = _inst.input_x * _inst.move_speed;
            if (_inst.input_x == 0) {
                player_state_enter(_inst, PlayerState.IDLE);
            } else if (!_inst.on_ground) {
                player_state_enter(_inst, PlayerState.JUMP);
            }
            break;

        case PlayerState.JUMP:
            _inst.hspeed = _inst.input_x * _inst.move_speed;
            if (_inst.on_ground && _inst.vspeed >= 0) {
                player_state_enter(_inst, PlayerState.IDLE);
            }
            break;
    }
}

// obj_player - Create event
enum PlayerState { IDLE, RUN, JUMP }

move_speed   = 4;
jump_force   = 8;
input_x      = 0;
on_ground    = false;
state        = PlayerState.IDLE;

player_state_enter(id, PlayerState.IDLE);

// obj_player - Step event
input_x = (keyboard_check(vk_right) - keyboard_check(vk_left));
on_ground = place_meeting(x, y + 1, obj_ground);

player_state_step(id);

move_and_collide(hspeed, vspeed, obj_ground);

Gameplay Architecture

• Use finite state machines (enums + switch, or a struct-based FSM) for player, enemy, UI, and game-flow states instead of a tangle of boolean flags.
• Keep collision logic explicit and deterministic — use place_meeting, instance_place, and collision events consistently rather than mixing multiple ad hoc distance checks for the same interaction.
• Separate input collection (reading keyboard_check/gamepad_* into intent variables like input_x) from action execution (applying that intent to movement/attacks), so input remapping or AI-driven control doesn't require touching gameplay logic.
• Use alarms, timelines, or explicit timer variables consistently within a project; mixing multiple timing patterns for the same kind of behavior makes debugging harder.
• Store save data through structured maps/structs ({ level: 3, hp: 80, inventory: [...] }) and version the save format (a save_version field) so future format changes can migrate old saves instead of breaking them.

Performance

• Avoid expensive searches such as broad instance_find/instance_number loops or repeated full-room collision scans inside every Step event; scope searches with object type filters and spatial partitioning (grids, layers) where possible.
• Cache frequently used asset IDs, layer IDs, and instance references in Create rather than re-resolving them (e.g., layer_get_id("Instances")) every Step.
• Destroy data structures (ds_list_destroy, ds_map_destroy, ds_grid_destroy) when no longer needed — GML data structures are not garbage collected and leak until manually freed or the game restarts.
• Use object pooling (deactivate/reuse instances via instance_deactivate_object/reactivate, or a custom pool) for frequently spawned projectiles, particles, or short-lived effects once instance_create_layer/instance_destroy churn becomes a measurable cost.
• Profile before optimizing (GameMaker's built-in profiler, or get_timer() deltas around suspect code) and keep hot-path code simple — premature micro-optimization usually costs more in the code review than it saves in frame time.

Debugging and Testing

• Add debug overlays (drawn conditionally behind a debug flag) for collision boxes, current state, velocity vectors, and AI decisions when tracking down gameplay bugs.
• Use assertions or explicit guard clauses (if (!instance_exists(target)) return;) for states that should be impossible, so bugs fail loudly during development instead of silently misbehaving.
• Test room transitions, pause/resume, save/load, and controller/keyboard input as separate concerns — each has its own failure modes (state not reset on room change, input still processed while paused, etc.).
• Keep reproducible test rooms for complex mechanics (a "test_boss_fight" room, a "test_platforming" room) so a specific interaction can be re-verified quickly after a change.

Common Mistakes

• Putting game logic (state changes, physics, spawning) inside a Draw event, which can run at a different rate than Step and shouldn't mutate gameplay state.
• Creating data structures (ds_list_create, ds_map_create, surfaces) without ever destroying them, leaking memory over a play session.
• Relying on room-editor instance creation order for critical behavior — order isn't guaranteed to match visual/editor order at runtime; use explicit Create-event initialization or a controller object instead.
• Hardcoding magic numeric state IDs (state = 2) instead of named enum values (state = PlayerState.JUMP), which makes the code unreadable and error-prone to change.