GameMaker Studio · GML · Rewards

gmda_claimReward

Claims a reward by key (safe against double-claims).

Asynchronous (result via event)

Signature

gmda_claimReward(key, [idempotency_key])

What it does

POSTs /rewards/claim (session-auth). Idempotent: the auto-generated idempotency_key means a retried claim never grants twice (a replay still reports success). On success the queued reward_claimed event carries response = the full server payload { ok, reward_key, payload_keys, period_key, currency_grant }, where currency_grant.balances holds the updated wallet when the reward is linked to a currency grant. On failure the event carries success=false and an error string such as "cooldown", "already_claimed_period", "expired", or "reward_not_found".

Parameters

Name	Type	Default	Description
key	string	required	The reward key from gmda_getRewardsStatus().
idempotency_key	string	auto-generated	Optional. A 24-char key is generated for you when omitted, so a retried claim never grants twice. Pass your own (e.g. persisted to disk) for retry-safety across app restarts.

How to call it

Fire gmda_claimReward(), then read the result in a Step event with gmda_pollEvent() when e.event == "reward_claimed".

Result event: reward_claimed { success, response }

Example

gmda_claimReward("daily_login");

// later, in a Step event:
var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "reward_claimed") {
        if (e.success) show_debug_message("claimed " + string(e.response.reward_key));
        else show_debug_message("no: " + string(e.error));
    }
    e = gmda_pollEvent();
}

Use cases

Claim the daily login bonus.
Hand out a periodic reward from the game UI.

What it does

Name

Type

Default

Description

key

string

required

The reward key from gmda_getRewardsStatus().

idempotency_key

string

auto-generated

Optional. A 24-char key is generated for you when omitted, so a retried claim never grants twice. Pass your own (e.g. persisted to disk) for retry-safety across app restarts.

Example

gmda_claimReward("daily_login"); // later, in a Step event: var e = gmda_pollEvent(); while (!is_undefined(e)) { if (e.event == "reward_claimed") { if (e.success) show_debug_message("claimed " + string(e.response.reward_key)); else show_debug_message("no: " + string(e.error)); } e = gmda_pollEvent(); }