GameMaker Studio · GML · Achievements

gmda_unlockAchievement

Unlocks an achievement for the current player (idempotent).

Asynchronous (result via event)

Signature

gmda_unlockAchievement(key) -> real

What it does

POSTs /achievements/unlock (session-auth). Returns 1 when fired, 0 with no active session. Unlocking an already-unlocked achievement is safe: the achievement_unlocked event still reports response.success true and response.already_unlocked true instead of failing. Unknown or inactive keys fail (event success is false).

Parameters

Name	Type	Default	Description
key	string	required	The achievement's key from the panel.

How to call it

Fire gmda_unlockAchievement(), then read achievement_unlocked from gmda_pollEvent(). Safe to re-call on load thanks to already_unlocked.

Result event: achievement_unlocked { success, response }

Example

gmda_unlockAchievement("first_win");

// In the Step event:
var _e = gmda_pollEvent();
while (!is_undefined(_e)) {
    if (_e.event == "achievement_unlocked" && _e.success) {
        if (!_e.response.already_unlocked) show_debug_message("unlocked first_win");
    }
    _e = gmda_pollEvent();
}

Use cases

Grant an achievement when the player hits a milestone.
Safely re-call on load without double-granting (already_unlocked guards it).