Godot 4 · GDScript
Referência de funções
Every function in the Gamdato Godot client, grouped by area. Pick a function for its parameters, how to call it, and a practical example.
Setup & session
| Function | What it does | Parameters |
|---|---|---|
| set_controller | Initializes the client and starts the session lifecycle. Call once at startup. | game_id, api_key |
| set_leaderboard | Declares the leaderboard tables this game uses; array order defines each table's number (1-based). | table_keys |
| set_save_secret | Optional: folds your own secret into the local save's encryption key. | secret |
| is_ready | True once the session is active and all tables have loaded at least once. | none |
| is_session_active | True while the session is alive, even during a table reload. | none |
| has_connectivity | True if the last connectivity probe to the server succeeded. | none |
| get_player_name | Returns the current player's display name (read from the local cache). | none |
| get_player_id | Returns the current player's unique id. | none |
| refresh_date | Returns the local device date and time as a formatted string. | none |
Leaderboards & scores
| Function | What it does | Parameters |
|---|---|---|
| submit | Sends a score to a table by index; refreshes that table afterwards. | table_index, score, custom_data |
| submit_with_retry | Submits a score with automatic offline retry; the queue survives app closes and crashes. | table_index, score, meta |
| get_pending | Returns the queued (not-yet-sent) score for a table, or {} if none. | table_index |
| clear_pending | Drops the queued (not-yet-sent) score for a table. | table_index |
| get_best_score | Returns the player's cached best score on a table (0 if unknown). | table_index |
| get_player_pos | Returns the player's cached global rank on a table (0 if unknown). | table_index |
| get_extra_info | Returns the player's own custom_data dict on a table. | table_index |
| get_table_data | Returns the cached top entries for a table as an Array of Dictionaries. | table_index |
| get_table_config | Returns a table's dashboard config: sort order and whether period scores are enabled. | table_index |
| get_view_cached | Returns the cached entries for a leaderboard view (period + optional friends-only). | table_index, period, friends_only |
| load_leaderboard_view | Loads a periodic / filtered leaderboard view; result arrives via view_loaded. | table_index, period, options |
| search_players | Searches players by name within a table; results arrive via players_search_completed. | table_index, query |
| reload_info | Forces a reload of all leaderboard tables; finishes with the tables_loaded signal. | none |
Players
| Function | What it does | Parameters |
|---|---|---|
| load_player_info | Loads another player's public profile and their best scores by their player_key. | player_key |
| set_newname | Changes the player's display name (server validates uniqueness + charset). | new_name |
| get_invitability | Reads whether other players are currently allowed to send this player friend invites. | none |
| set_invitability | Sets whether other players are allowed to send this player friend invites. | is_invitable |
Friends
| Function | What it does | Parameters |
|---|---|---|
| send_friend_invite | Sends a friend invitation to a player by key, with an optional message. | player_key, message |
| list_pending_invitations | Lists all pending friend invitations; incoming and outgoing; in one combined result. | none |
| respond_invitation | Accepts or declines an incoming friend invitation by id. | invitation_id, accept |
| cancel_invitation | Cancels an outgoing friend invitation you previously sent. | invitation_id |
| list_friends | Lists the player's accepted friends, newest friendship first, with optional name search. | limit, search |
| remove_friend | Removes an existing friendship by player key. | player_key |
Achievements
| Function | What it does | Parameters |
|---|---|---|
| list_achievements | Lists every active achievement with this player's unlock state, ordered by sort_order. | none |
| get_achievement_info | Fetches one achievement's full details plus this player's unlock state. | achievement_key |
| check_achievement | Checks whether this player has unlocked a given achievement. | achievement_key |
| unlock_achievement | Unlocks an achievement for the current player (idempotent). | achievement_key |
Cloud saves
| Function | What it does | Parameters |
|---|---|---|
| save_game | Writes (upserts) a cloud save slot with a free-form data object. | slot, data |
| load_game | Loads the full data object stored in a single cloud save slot. | slot |
| list_saves | Lists this player's cloud save slots (metadata only, no data). | none |
| delete_save | Deletes a single cloud save slot. | slot |
Currency & store
| Function | What it does | Parameters |
|---|---|---|
| get_balances | Fetches the player's currency balances plus the game's currency catalog. | none |
| get_inventory | Fetches the player's permanent inventory (items owned in this game). | none |
| purchase | Spends in-game currency to buy a shop item (server validates the balance). | sku, idempotency_key |
| buy_pack | Starts a real-money top-up: opens Stripe Checkout in the browser to credit currency. | pack_sku, success_url, cancel_url, idempotency_key |
| get_ledger | Fetches recent currency ledger entries for this player, newest first. | limit, offset |
| get_currency_leaderboard | Fetches the balance leaderboard for a currency (top balances ranked). | code, limit |
| grant_currency | Applies a server-configured currency grant by reason key (quest payout, level-up bonus). | reason_key, idempotency_key |
Rewards
| Function | What it does | Parameters |
|---|---|---|
| get_rewards_status | Fetches this player's reward status (what's claimable now and when each unlocks next). | none |
| claim_reward | Claims a reward by key (safe against double-claims). | key, idempotency_key |
Downloadable content
| Function | What it does | Parameters |
|---|---|---|
| list_game_content | Lists every content item configured for this game, with per-item metadata. | none |
| get_game_content | Requests one on-demand content item by key. | key |
| get_bootstrap | Fetches all auto-download content in a single flat response. | none |
| get_cached_content | Reads the locally cached copy of a content item, with no network call. | key |
| sync_always_download | Delta-syncs all always_download content, re-fetching only changed keys. | none |
| sync_content_keys | Delta-syncs an explicit set of content keys (any category, e.g. on-demand). | keys |
Groups & clans
| Function | What it does | Parameters |
|---|---|---|
| create_group | Creates a group; the caller becomes its leader. | group_name, opts |
| list_groups | Browses or searches public groups, ordered by member count (descending). | search, limit |
| get_group_info | Loads a group's details and its member list. | group_id |
| update_group | Edits the caller's group settings (requires the can_edit_group permission). | fields |
| leave_group | Leaves the caller's current group. | none |
| disband_group | Disbands the caller's group entirely (leader only). | none |
| join_group | Directly joins an OPEN group. | group_id |
| send_group_invite | Invites a player to the caller's group (requires the can_invite permission). | player_key, message |
| list_group_invitations | Lists group invitations, incoming or outgoing. | direction, status, limit |
| respond_group_invitation | Accepts or declines a group invitation addressed to the caller. | invitation_id, accept |
| cancel_group_invitation | Withdraws a pending invitation the group sent (requires the can_invite permission). | invitation_id |
| create_group_request | Requests to join a group whose join policy is "request". | group_id, message |
| list_group_requests | Lists join requests, incoming (to review) or outgoing (your own). | direction, status, limit |
| respond_group_request | Approves or rejects a pending join request (requires the can_review_requests permission). | request_id, approve |
| cancel_group_request | Withdraws the caller's own pending join request. | request_id |
| kick_group_member | Removes a member from the caller's group. | player_key |
| assign_group_role | Changes a member's role within the group. | player_key, role |
| transfer_group_leadership | Transfers leadership from the caller to another member (leader only). | player_key |