Moeda e compras

Configuração do Painel

No painel você define três coisas: as moedas do seu jogo (ex.: "gemas"), pacotes de recarga (um SKU com preço em USD que concede X de moeda via Stripe) e itens compráveis (um SKU com seu custo em moeda e regras de concessão).

Ler Saldos

Solicite os saldos do jogador e o catálogo de moedas. O resultado chega pelo sinal balances_loaded.

Gamdato.balances_loaded.connect(_on_balances)
Gamdato.get_balances()

func _on_balances(balances: Array, currencies: Array) -> void:
    for b in balances:
        print("%s: %d" % [b.currency_id, b.balance])

# balances: Array, each:
{
  "currency_id": String,
  "balance": int
}
# currencies: Array, the catalog you defined in the panel:
{
  "id": String,
  "code": String,
  "display_name": String,
  "icon_url": String,
  "is_active": bool
}
# "code" is the currency code you pass to get_currency_leaderboard().

Comprar Moeda (Stripe)

Inicie a compra de um pacote de recarga. O addon abre o Stripe Checkout no navegador do sistema; no retorno, os saldos são atualizados no lado do servidor. O sinal topup_started confirma que a URL foi aberta.

Gamdato.topup_started.connect(_on_topup)
Gamdato.buy_pack("premium_pack")

func _on_topup(ok: bool, url: String, error_code: String) -> void:
    if ok: print("Checkout opened: %s" % url)
    else: print("Error: %s" % error_code)

Gastar Moeda

Gaste a moeda do jogador em um item. O servidor valida o saldo e aplica as regras de concessão de forma atômica. O resultado chega por purchase_completed.

Gamdato.purchase_completed.connect(_on_purchase)
Gamdato.purchase("sword_skin")

func _on_purchase(ok: bool, sku: String, result: Dictionary, error_code: String) -> void:
    if ok: print("Bought %s. Balances: %s" % [sku, result.balances])
    else: print("Failed: %s" % error_code)

Inventário do Jogador

Liste os itens que o jogador possui. Útil para desbloquear conteúdo quando o jogo inicia. Chega por inventory_loaded.

Gamdato.inventory_loaded.connect(_on_inventory)
Gamdato.get_inventory()

func _on_inventory(items: Array) -> void:
    for it in items:
        print("Owns: %s (%s)" % [it.item_id, it.source])

# items: Array, each owned item:
{
  "item_id": String,
  "source": String,
  "acquired_at": String,
  "metadata": Dictionary
}
# Rows also include internal ids (id, player_id, game_id).

Histórico de Transações

Liste as movimentações de moeda mais recentes do jogador (concessões, compras, recargas), das mais novas para as mais antigas. Chega pelo sinal ledger_loaded.

Gamdato.ledger_loaded.connect(_on_ledger)
Gamdato.get_ledger()                       # ou get_ledger(50, 0)

func _on_ledger(entries: Array) -> void:
    for e in entries:
        print("%s  %+d -> %d" % [e.op_type, e.delta, e.balance_after])

# entries: Array, newest first:
{
  "id": String,
  "currency_id": String,
  "delta": int,
  "balance_after": int,
  "op_type": String,
  "created_at": String
}
# Rows also include internal ids/metadata (player_id, game_id, ref_kind, ref_value, idempotency_key, metadata).

Ranking de Moeda

Um ranking de jogadores pelo saldo de moeda (deve estar habilitado para essa moeda no painel). Passe o código da moeda. Chega pelo sinal currency_leaderboard_loaded.

Gamdato.currency_leaderboard_loaded.connect(_on_currency_lb)
Gamdato.get_currency_leaderboard("gems")

func _on_currency_lb(code: String, entries: Array) -> void:
    for row in entries:
        print("#%d  %s  %d" % [row.rank, row.player_name, row.balance])

# entries: Array, ordered by balance, highest first:
{
  "rank": int,
  "player_id": String,
  "player_name": String,
  "balance": int
}

Conceder Moeda (Recompensas via Código)

Dê moeda ao jogador a partir de um motivo que você definiu no painel (o pagamento de uma missão, um bônus de subir de nível...). Passe a chave do motivo. Chega pelo sinal grant_completed.

Gamdato.grant_completed.connect(_on_grant)
Gamdato.grant_currency("quest_reward")

func _on_grant(ok: bool, reason_key: String, result: Dictionary, error_code: String) -> void:
    if ok: print("Concedido! Saldos: %s" % result.get("balances"))
    else: print("Falhou: %s" % error_code)