gamemaker-gml — Claude Code skill: what it does, how to install
gamemaker-gml — a skill for Claude Code that guides GameMaker Language (GML) development. Triggers when writing object event logic, scripts, room transitions, and state machines in GameMaker Studio.
Apache-2.0 109 installs ★ 312 updated 2026-10-08
npx skills add Mindrally/skills --skill gamemaker-gml -a claude-codeWhat gamemaker-gml does
This skill guides the agent to structure GameMaker Studio code cleanly across Create, Step, and Draw events. State mutation stays out of Draw events, while shared behaviors move into separate script functions using project naming conventions like scr_ and obj_.
It enforces finite state machines using enums and switch blocks, decouples raw input polling from physics updates, and advises caching layer IDs and asset pointers in Create. Instance lookups rely on instance_exists guards to prevent crashes against destroyed objects.
Dynamic structures like ds_list, ds_map, and surfaces require explicit destruction during Destroy or Room End events, because missing those calls leads to memory leaks.
What it helps with
- Organize object logic across Create, Step, and Draw without state mutations during rendering
- Build finite state machines for player and enemy actions using enums and functions
- Eliminate broad Step event scans and full-room instance searches
- Prevent memory leaks by freeing ds data structures and surfaces on room exit
Example prompts for the agent
- Write a finite state machine script for player movement and jump states in GML
- Refactor my obj_player Step event to decouple keyboard inputs from collision math
- Audit this object to ensure all ds_list and ds_map structures are destroyed cleanly
How to install gamemaker-gml
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill gamemaker-gml -a claude-code2Manually: put the files in place
~/.claude/skills/gamemaker-gml/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gamemaker-gml/
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill gamemaker-gml -a codex2Manually: put the files in place
.agents/skills/gamemaker-gml/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill gamemaker-gml -a cursor2Manually: put the files in place
.cursor/skills/gamemaker-gml/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Mindrally/skills gamemaker-gml2Manually: put the files in place
.github/skills/gamemaker-gml/SKILL.md1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill gamemaker-gml -a gemini-cli2Platform CLI
gemini skills install https://github.com/Mindrally/skills --path gamemaker-gmlManually: put the files in place
.devin/skills/gamemaker-gml/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Mindrally/skills --skill gamemaker-gml -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gamemaker-gml
How to install gamemaker-gml in Claude Code?
Run npx skills add Mindrally/skills --skill gamemaker-gml -a claude-code. The skill file will be saved to ~/.claude/skills/gamemaker-gml/SKILL.md.
What does gamemaker-gml do?
It provides architecture standards for GML: clean event separation, safe instance reference guards, decoupled player input, and performance profiling guidelines.
What cleanup is required for dynamic structures under this skill?
Manually allocated structures such as ds_map or ds_list must be explicitly freed with ds_*_destroy in Destroy or Room End events to avoid memory leaks.
Source text
SKILL.md · Apache-2.0
---
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
```gml
// 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;
}
}
```
```gml
// 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);
```
```gml
// 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.
© Mindrally · Apache-2.0 · Mindrally/skills