User Stats
Provides functions for accessing and submitting stats, achievements, and leaderboards.
Only available in the main GodotSteam branches
Functions
attachLeaderboardUGC
attachLeaderboardUGC( uint64_t
ugc_handle, uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
ugc_handle | uint64_t | Handle to a piece of user generated content that was shared using fileShare. |
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no this_leaderboard is passed, then the function will use the last internally-stored handle.
Attaches a piece of user generated content the current user's entry on a leaderboard.
This content could be a replay of the user achieving the score or a ghost to race against. The attached handle will be available when the entry is retrieved and can be accessed by other users using the leaderboard_scores_downloaded callback. To create and download user generated content see the documentation for the Steam Workshop.
Once attached, the content will be available even if the underlying Cloud file is changed or deleted by the user.
You must call findLeaderboard or findOrCreateLeaderboard to get a leaderboard handle prior to calling this function.
Returns: void
Triggers
leaderboard_ugc_set callback
clearAchievement
clearAchievement( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to reset; uses the name set in the Steamworks back-end. |
Resets the unlock status of an achievement.
This is primarily only ever used for testing.
This call only modifies Steam's in-memory state so it is quite cheap. To send the unlock status to the server and to trigger the Steam overlay notification you must call storeStats.
!!! returns "Returns: bool"
Returns true upon success if the specific achievement API name exists in the App Admin on the Steamworks website and changes are published; otherwise, false.
!!! info "Notes"
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called [requestCurrentStats](#requestcurrentstats) and it needs to return successfully via its callback prior to calling this!
---
[:fontawesome-brands-steam: Read more in the official Steamworks SDK documentation](https://partner.steamgames.com/doc/api/ISteamUserStats#ClearAchievement){ .md-button .md-button--doc_classes target="_blank" }
downloadLeaderboardEntries
downloadLeaderboardEntries( int
start, int
end, LeaderboardDataRequest
type = LEADERBOARD_DATA_REQUEST_GLOBAL, uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
start | int | The index to start downloading entries relative to LeaderboardDataRequest. |
end | int | The last index to retrieve entries for relative to LeaderboardDataRequest. |
type | LeaderboardDataRequest enum | The type of data request to make. Defaults to LEADERBOARD_DATA_REQUEST_GLOBAL. |
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no leaderboard_handle is passed, then the function will use the last internally-stored handle.
Fetches a series of leaderboard entries for a specified leaderboard.
You can ask for more entries than exist, then this will return as many as do exist.
If you want to download entries for an arbitrary set of users, such as all of the users on a server then you can use downloadLeaderboardEntriesForUsers which takes an array of Steam IDs.
You must call findLeaderboard or findOrCreateLeaderboard to get a leaderboard handle prior to calling this function.
Returns: void
Triggers
leaderboard_scores_downloaded call result
downloadLeaderboardEntriesForUsers
downloadLeaderboardEntriesForUsers( array
users_id, uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
users_id | array | An array of Steam IDs to get the leaderboard entries for. |
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no leaderboard_handle is passed, then the function will use the last internally-stored handle.
Fetches leaderboard entries for an arbitrary set of users on a specified leaderboard.
A maximum of 100 users can be downloaded at a time, with only one outstanding call at a time. If a user doesn't have an entry on the specified leaderboard, they won't be included in the result.
If you want to download entries based on their ranking or friends of the current user then you should use downloadLeaderboardEntries.
You must call findLeaderboard or findOrCreateLeaderboard to get a leaderboard handle prior to calling this function.
Returns: void
Triggers
leaderboard_scores_downloaded callback
findLeaderboard
findLeaderboard( string
leaderboard_name )
Argument | Type | Notes |
---|---|---|
leaderboard_name | string | The name of the leaderboard to find. Must not be longer than LEADERBOARD_NAME_MAX / 128. |
Gets a leaderboard by name.
You must call either this or findOrCreateLeaderboard to obtain the leaderboard handle which is valid for the game session for each leaderboard you wish to access prior to calling any other Leaderboard functions.
Returns: void
Triggers
leaderboard_find_result call result
findOrCreateLeaderboard
findOrCreateLeaderboard( string
leaderboard_name, LeaderboardSortMethod
sort_method, LeaderboardDisplayType
display_type )
Argument | Type | Notes |
---|---|---|
leaderboard_name | string | The name of the leaderboard to find or create. Must not be longer than LEADERBOARD_NAME_MAX / 128. |
sort_method | LeaderboardSortMethod enum | The sort order of the new leaderboard if it's created. |
display_type | LeaderboardDisplayType enum | The display type (used by the Steam Community web site) of the new leaderboard if it's created. |
Gets a leaderboard by name, it will create it if it's not yet created.
You must call either this or findLeaderboard to obtain the leaderboard handle which is valid for the game session for each leaderboard you wish to access prior to calling any other Leaderboard functions.
Leaderboards created with this function will not automatically show up in the Steam Community. You must manually set the Community Name field in the App Admin panel of the Steamworks website. As such it's generally recommended to prefer creating the leaderboards in the App Admin panel on the Steamworks website and using findLeaderboard unless you're expected to have a large amount of dynamically created leaderboards.
You should never pass 0 for sort_method or 0 for display_type as this is undefined behavior.
Returns: void
Triggers
leaderboard_find_result callback
getAchievement
getAchievement( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the status of; uses the name set in the Steamworks back-end. |
Gets the unlock status of the Achievement.
The equivalent function for other users is getUserAchievement.
Returns: dictionary
Contains the following keys:
- ret (bool) - Returns true if the API name of the specified achievement exists in the App Admin on the Steamworks site and the changes are published; otherwise, false.
- achieved (bool)
getAchievementAchievedPercent
getAchievementAchievedPercent( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the status of; uses the name set in the Steamworks back-end. |
Returns the percentage of users who have unlocked the specified achievement.
You must have called requestGlobalAchievementPercentages and it needs to return successfully via its callback prior to calling this.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
ret | bool | Returns true upon success; otherwise, false if requestGlobalAchievementPercentages has not been called or if the specified API names does not exist in the global achievement percentages. |
percent | float | The percentage of people that have unlocked this achievement from 0 to 100. |
getAchievementAndUnlockTime
getAchievementAndUnlockTime( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the status of; uses the name set in the Steamworks back-end. |
Gets the achievement status, and the time it was unlocked if unlocked.
If the return value is true, but the unlock time is zero, that means it was unlocked before Steam began tracking achievement unlock times (December 2009). The time is provided in Unix epoch format, seconds since January 1, 1970 UTC.
The equivalent function for other users is getUserAchievementAndUnlockTime.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
retrieve | bool | Returns true if the API name of the specified achievement exists in the App Admin on the Steamworks site and the changes are published; otherwise, false. |
achieved | bool | Returns whether the current user has unlocked the achievement. |
unlocked | uint32_t | Returns the time that the achievement was unlocked; if achieved is true. |
getAchievementDisplayAttribute
getAchievementDisplayAttribute( string
achievement_name, string
key )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the attribute of; uses the name set in the Steamworks back-end. |
key | string | The key to get a value for. |
Get general attributes for an achievement. Currently provides: Name, Description, and Hidden status.
This receives the value from a dictionary/map keyvalue store, so you must provide one of the following keys:
- name - to retrive the localized achievement name in UTF8
- desc - to retrive the localized achievement description in UTF8
- hidden - for retrieving if an achievement is hidden. Returns "0" when not hidden, "1" when hidden
This localization is provided based on the games language if it's set, otherwise it checks if a localization is avilable for the users Steam UI Language. If that fails too, then it falls back to english.
Returns: string
Returns a value as a string upon success if all the following conditions are met; otherwise, it returns an empty string:
- The specified achievement exists in the App Admin on the Steamworks site and the changes are published.
- The specified key is valid.
getAchievementIcon
getAchievementIcon( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the icon of; uses the name set in the Steamworks back-end. |
Gets the icon for an achievement.
The image is returned as a handle to be used with getImageRGBA to get the actual image data.
Returns: int
Returns a handle to be used with getImageRGBA. It will return an invalid handle of 0 under the following conditions:
- The specified achievement does not exists in the App Admin on the Steamworks site or the changes are not published.
- Steam is still fetching image data from the server. This will trigger a user_achievement_icon_fetched callback which will notify you when the image data is ready and provide you with a new handle. If the icon_handle in the callback is still 0, then there is no image set for the specified achievement.
Notes
See the Achievement Icons tutorial for an example.
getAchievementName
getAchievementName( uint32_t
achievement_index )
Argument | Type | Notes |
---|---|---|
achievement_index | uint32_t | Index of the achievement. |
Gets the 'API name' for an achievement index between 0 and getNumAchievements.
This function must be used in conjunction with getNumAchievements to loop over the list of achievements.
In general games should not need these functions as they should have the list of achievements compiled into them.
!!! returns "Returns: string
getAchievementProgressLimitsFloat
getAchievementProgressLimitsFloat( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the progress limits of; uses the name set in the Steamworks back-end. |
For achievements that have related progress stats, use this to query what the bounds of that progress are. You may want this info to selectively call indicateAchievementProgress when appropriate milestones of progress have been made, to show a progress notification to the user.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
min | float | The minimum value for the achievement progress. |
max | float | The maximum value for the achievement progress; when the achievement should trigger. |
getAchievementProgressLimitsInt
getAchievementProgressLimitsInt( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to obtain the progress limits of; uses the name set in the Steamworks back-end. |
For achievements that have related progress stats, use this to query what the bounds of that progress are. You may want this info to selectively call indicateAchievementProgress when appropriate milestones of progress have been made, to show a progress notification to the user.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
min | int32 | The minimum value for the achievement progress. |
max | int32 | The maximum value for the achievement progress; when the achievement should trigger. |
getGlobalStatFloat
getGlobalStatFloat( string
stat_name )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to obtain the global value of; uses the name set in the Steamworks back-end. |
Gets the lifetime totals for an aggregated stat.
You must have called requestGlobalStats and it needs to return successfully via its callback prior to calling this.
Returns: float
getGlobalStatInt
getGlobalStatInt( string
stat_name )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to obtain the global value of; uses the name set in the Steamworks back-end. |
Gets the lifetime totals for an aggregated stat.
You must have called requestGlobalStats and it needs to return successfully via its callback prior to calling this.
Returns: uint64_t
getGlobalStatFloatHistory
getGlobalStatFloatHistory( string
stat_name )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to obtain the global history of; uses the name set in the Steamworks back-end. |
Gets the daily history for an aggregated stat.
Returns: PackedFloat64Array
getGlobalStatIntHistory
getGlobalStatIntHistory( string
stat_name )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to obtain the global history of; uses the name set in the Steamworks back-end. |
Gets the daily history for an aggregated stat.
Returns: PackedInt64Array
getLeaderboardDisplayType
getLeaderboardDisplayType( uint64_t
leaderboard_handle = 0 )
Argument | Type | Notes |
---|---|---|
leaderboard_handle | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no leaderboard_handle is passed, then the function will use the last internally-stored handle.
Get the display type of a leaderboard handle.
Returns: LeaderboardDisplayType enum
This will return LEADERBOARD_DISPLAY_TYPE_NONE / 0 if the leaderboard handle is invalid.
getLeaderboardEntries
getLeaderboardEntries( )
Get the currently used leaderboard entries.
Returns: array
Notes
This is a GodotSteam specific function. Was replaced with get_leaderboard_entries() in Main class as a set-get.
getLeaderboardEntryCount
getLeaderboardEntryCount( uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no leaderboard_handle is passed, then the function will use the last internally-stored handle.
Returns the total number of entries in a leaderboard.
This is cached on a per leaderboard basis upon the first call to findLeaderboard or findOrCreateLeaderboard and is refreshed on each successful call to downloadLeaderboardEntries, downloadLeaderboardEntriesForUsers, and uploadLeaderboardScore.
Returns: int
getLeaderboardName
getLeaderboardName( uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no leaderboard_handle is passed, then the function will use the last internally-stored handle.
Returns: string
Returns the API name of a leaderboard handle.
getLeaderboardSortMethod
getLeaderboardSortMethod( uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If no leaderboard_handle is passed, then the function will use the last internally-stored handle.
Get the sort order of a leaderboard handle. If no thisLeaderboard handle is passed, then the function will use the last stored internal handle.
Returns: LeaderboardSortMethod enum
getMostAchievedAchievementInfo
getMostAchievedAchievementInfo( )
Gets the info on the most achieved achievement for the game.
You must have called requestGlobalAchievementPercentages and it needs to return successfully via its callback prior to calling this.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
iterator | int | Returns -1 if requestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app ID. If the call lis successful, it is an iterator which should be used with getNextMostAchievedAchievementInfo. |
name | string | The API name of the achievement. |
percent | float | The percentage of people that have unlocked this achievement from 0 to 100. |
achieved | bool | Whether the current user has unlocked this achievement. |
getNextMostAchievedAchievementInfo
getNextMostAchievedAchievementInfo( int
iterator )
Argument | Type | Notes |
---|---|---|
iterator | int | The index for getting achievement information. |
Gets the info on the next most achieved achievement for the game.
You must have called requestGlobalAchievementPercentages and it needs to return successfully via its callback prior to calling this.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
iterator | int | Returns -1 if requestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app ID. If the call lis successful, it is an iterator which should be used with subsequent calls to this function. |
name | string | The API name of the achievement. |
percent | float | The percentage of people that have unlocked this achievement from 0 to 100. |
achieved | bool | Whether the current user has unlocked this achievement. |
getNumAchievements
getNumAchievements( )
Get the number of achievements defined in the App Admin panel of the Steamworks website.
This is used for iterating through all of the achievements with getAchievementName.
In general games should not need these functions because they should have a list of existing achievements compiled into them.
Returns: uint32_t
getNumberOfCurrentPlayers
getNumberOfCurrentPlayers( )
Asynchronously retrieves the total number of players currently playing the current game. Both online and in offline mode.
Returns: void
Triggers
number_of_current_players callback
getStatFloat
getStatFloat( string
stat_name )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to obtain the value of; uses the name set in the Steamworks back-end. |
Gets the current value of the a stat for the current user.
To receive stats for other users use getUserStatFloat.
Returns: float
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
getStatInt
getStatInt( string
stat_name )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to obtain the value of; uses the name set in the Steamworks back-end. |
Gets the current value of the a stat for the current user.
To receive stats for other users use getUserStatInt.
Returns: int
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
getUserAchievement
getUserAchievement( uint64_t
steam_id, string
achievement_name )
Argument | Type | Notes |
---|---|---|
steam_id | uint64_t | The Steam ID of the user you want to get the achievement for. |
achievement_name | string | The achievement you want to get the status of; uses the name set in the Steamworks back-end. |
Gets the unlock status of the Achievement.
The equivalent function for the local user is getAchievement.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
steam_id | uint64_t | The Steam ID of the user this was called for. |
retrieved | bool | Returns true if successfully retrieved the status; otherwise, false if the API name does not exist in the App Admin on the Steamworks site or the changes aren't published. |
name | string | The API name of the achievement. |
achieved | bool | Returns the unlock status of the achievement. |
getUserAchievementAndUnlockTime
getUserAchievementAndUnlockTime( uint64_t
steam_id, string
achievement_name )
Argument | Type | Notes |
---|---|---|
steam_id | uint64_t | The Steam ID of the user you want to get the achievement for. |
achievement_name | string | The achievement you want to get the status of; uses the name set in the Steamworks back-end. |
Gets the achievement status, and the time it was unlocked if unlocked.
If the return value is true, but the unlock time is zero, that means it was unlocked before Steam began tracking achievement unlock times (December 2009). The time is provided in Unix epoch format, seconds since January 1, 1970 UTC.
The equivalent function for the local user is getAchievementAndUnlockTime.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
retrieved | bool | Returns true upon success; otherwise, false if the API name of the specified achievement does not exist in the App Admin on the Steamworks site or the changes are not published. |
name | string | The API name of the achievement. |
achieved | bool | Returns whether the current user has unlocked the achievement. |
unlocked | uint32_t | Returns the time that the achievement was unlocked; if achieved is true. |
getUserStatFloat
getUserStatFloat( uint64_t
steam_id, string
stat_name )
Argument | Type | Notes |
---|---|---|
steam_id | uint64_t | The Steam ID of the user you want to get the statistic for. |
stat_name | string | The statistic you want to obtain the value of; uses the name set in the Steamworks back-end. |
Gets the current value of the a stat for the specified user.
The equivalent function for the local user is getStatFloat.
Returns: float
Returns the float value upon success; otherwise, it may return 0.0 if the specified stat does not exist in the App Admin on the Steamworks site or the changes are not published.
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
getUserStatInt
getUserStatInt( uint64_t
steam_id, string
stat_name )
Argument | Type | Notes |
---|---|---|
steam_id | uint64_t | The Steam ID of the user you want to get the statistic for. |
stat_name | string | The statistic you want to obtain the value of; uses the name set in the Steamworks back-end. |
Gets the current value of the a stat for the specified user.
The equivalent function for the local user is getStatInt.
Returns: int
Returns the integer value upon success; otherwise, it may return 0 if the specified stat does not exist in the App Admin on the Steamworks site or the changes are not published.
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
indicateAchievementProgress
indicateAchievementProgress( string
achievement_name, int
current_progress, int
max_progress )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to show the progress of; uses the name set in the Steamworks back-end. |
current_progress | int | The current progress. |
max_progress | int | The progress required to unlock the achievement. |
Shows the user a pop-up notification with the current progress of an achievement.
Calling this function will not set the progress or unlock the achievement, the game must do that manually by calling setStatInt or setStatFloat.
Returns: bool
Returns true upon success; otherwise, false if:
- The specified achievement does not exist in the App Admin on the Steamworks site or the changes are not published.
- The specified achievement is already unlocked.
- The current_progress equals max_progress.
Triggers
- user_stats_stored callback
- user_achievement_stored callback
requestCurrentStats
requestCurrentStats( )
Asynchronously request the user's current stats and achievements from the server.
You must always call this first to get the initial status of stats and achievements. Only after the resulting callback comes back can you start calling the rest of the stats and achievement functions for the current user.
The equivalent function for other users is requestUserStats.
Returns: bool
Only returns false if there is no user logged in.
Triggers
current_stats_received callback
Read more in the official Steamworks SDK documentation Removed GodotSteam 4.12 Removed GodotSteam 3.28
requestGlobalAchievementPercentages
requestGlobalAchievementPercentages( )
Asynchronously fetches global stats data, which is available for stats marked as "aggregated" in the App Admin panel of the Steamworks website.
Returns: void
Triggers
global_achievement_percentages_ready callback
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
This function may not respond with actual data until the game is released on Steam.
requestGlobalStats
requestGlobalStats( int
history_days )
Argument | Type | Notes |
---|---|---|
history_days | int | How many days of day-by-day history to retrieve in addition to the overall totals. The limit is 60. |
Asynchronously fetches global stats data, which is available for stats marked as "aggregated" in the App Admin panel of the Steamworks website.
The limit is 60.
Returns: void
Triggers
global_stats_received callback
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
requestUserStats
requestUserStats( uint64_t
steam_id )
Argument | Type | Notes |
---|---|---|
steam_id | uint64_t | The Steam ID of the user you want to get statistics and achievements for. |
Asynchronously downloads stats and achievements for the specified user from the server.
These stats are not automatically updated; you'll need to call this function again to refresh any data that may have change.
To keep from using too much memory, an least recently used cache (LRU) is maintained and other user's stats will occasionally be unloaded. When this happens a user_stats_unloaded callback is sent. After receiving this callback the user's stats will be unavailable until this function is called again.
The equivalent function for the local user is requestCurrentStats; however, that has been removed since GodotSteam 4.12 / 3.28.
Returns: void
Triggers
user_stats_received callback
resetAllStats
resetAllStats( bool
achievements_too = true )
Argument | Type | Notes |
---|---|---|
achievements_too | bool | Whether this will reset the user's achievements also. Defaults to true. |
Resets the current users stats and, optionally achievements.
This automatically calls storeStats to persist the changes to the server. This should typically only be used for testing purposes during development.
Returns: bool
setAchievement
setAchievement( string
achievement_name )
Argument | Type | Notes |
---|---|---|
achievement_name | string | The achievement you want to unlock; uses the name set in the Steamworks back-end. |
Unlocks an achievement.
You can unlock an achievement multiple times so you don't need to worry about only setting achievements that aren't already set. This call only modifies Steam's in-memory state so it is quite cheap. To send the unlock status to the server and to trigger the Steam overlay notification you must call storeStats.
Returns: bool
Returns true upon success; otherwise, false if the specified achievement API name does not exist in the App Admin on the Steamworks site or the changes are not published.
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
setLeaderboardDetailsMax
setLeaderboardDetailsMax( int
max )
Argument | Type | Notes |
---|---|---|
max | int | The maximum number of details to return. |
Set the maximum number of details to return for leaderboard entries.
The current leaderboard details max value. This can only go as high as LEADERBOARD_DETAILS_MAX / 256.
Returns: int
Notes
This is a GodotSteam specific function. Was replaced with set_leaderboard_details_max() in Main class as a set-get.
setStatFloat
setStatFloat( string
stat_name, float
value )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to set the value for; uses the name set in the Steamworks back-end. |
value | float | The new value of the stat. This must be an absolute value, it will not increment or decrement for you. |
Sets / updates the float value of a given stat for the current user.
This call only modifies Steam's in-memory state and is very cheap. Doing so allows Steam to persist the changes even in the event of a game crash or unexpected shutdown. To submit the stats to the server you must call storeStats.
If this is returning false and everything appears correct, then check to ensure that your changes in the App Admin panel of the Steamworks website are published.
Returns: bool
Returns true upon success; otherwise, false if the specified stat does not exist in the App Admin on the Steamworks site or the changes are not published.
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
setStatInt
setStatInt( string
name, int32
value )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to set the value for; uses the name set in the Steamworks back-end. |
value | float | The new value of the stat. This must be an absolute value, it will not increment or decrement for you. |
Sets / updates the integer value of a given stat for the current user.
This call only modifies Steam's in-memory state and is very cheap. Doing so allows Steam to persist the changes even in the event of a game crash or unexpected shutdown. To submit the stats to the server you must call storeStats.
If this is returning false and everything appears correct, then check to ensure that your changes in the App Admin panel of the Steamworks website are published.
Returns: bool
Returns true upon success; otherwise, false if the specified stat does not exist in the App Admin on the Steamworks site or the changes are not published.
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
storeStats
storeStats( )
Send the changed stats and achievements data to the server for permanent storage.
If this fails then nothing is sent to the server. It's advisable to keep trying until the call is successful.
This call can be rate limited. Call frequency should be on the order of minutes, rather than seconds. You should only be calling this during major state changes such as the end of a round, the map changing, or the user leaving a server. This call is required to display the achievement unlock notification dialog though, so if you have called setAchievement then it's advisable to call this soon after that.
If you have stats or achievements that you have saved locally but haven't uploaded with this function when your application process ends then this function will automatically be called.
You can find additional debug information written to the %steam_install%\logs\stats_log.txt
file.
Returns: bool
Returns true upon success; otherwise, false if the current game does not have stats associated with it in the Steamworks partner backend or those stats are not published.
Triggers
- user_stats_stored callback
- user_achievement_stored callback
updateAvgRateStat
updateAvgRateStat( string
stat_name, float
this_session, double
session_length )
Argument | Type | Notes |
---|---|---|
stat_name | string | The statistic you want to set the value for; uses the name set in the Steamworks back-end. |
this_session | float | The value accumulation since the last call to this function. |
session_length | double | The amount of time in seconds since the last call to this function. |
Updates an AVGRATE stat with new values.
This call only modifies Steam's in-memory state and is very cheap. Doing so allows Steam to persist the changes even in the event of a game crash or unexpected shutdown. To submit the stats to the server you must call storeStats.
If this is returning false and everything appears correct, then check to ensure that your changes in the App Admin panel of the Steamworks website are published.
Returns: bool
Returns true upon success; otherwise, false if:
- The specified stat does not exist in the App Addmin on the Steamworks site.
- The changes are not published.
- The stat is not set as AVGRATE in the Setamworks partner backend.
Notes
If using earlier than SDK 1.60 (GodotSteam 3.26 / 4.9), you must have called requestCurrentStats and it needs to return successfully via its callback prior to calling this!
uploadLeaderboardScore
uploadLeaderboardScore( int32
score, bool
keep_best = false, PackedInt32Array
details = [], uint64_t
this_leaderboard = 0 )
Argument | Type | Notes |
---|---|---|
score | int32 | Do you want to force the score to change or keep the previous score if it was better? |
keep_best | bool | The score to upload. Defaults to false. |
details | PackedInt32Array | Optional: Array containing the details surrounding the unlocking of this score. Defaults to empty array. |
this_leaderboard | uint64_t | A leaderboard handle obtained from findLeaderboard or findOrCreateLeaderboard. Defaults to 0. |
If this_leaderboard is not passed, then the function will use the last internally-stored handle.
Uploads a user score to a specified leaderboard.
Details are optional game-defined information which outlines how the user got that score. For example if it's a racing style time based leaderboard you could store the timestamps when the player hits each checkpoint. If you have collectibles along the way you could use bit fields as booleans to store the items the player picked up in the playthrough.
Uploading scores to Steam is rate limited to 10 uploads per 10 minutes and you may only have one outstanding call to this function at a time.
Returns: void
Triggers
leaderboard_score_uploaded callback
Signals
These callbacks require you to run Steam.run_callbacks()
in your _process()
function or enabled them in Project Settings
to receive them.
current_stats_received
current_stats_received
Called when the latest stats and achievements for the local user have been received from the server; in response to function requestCurrentStats.
As of SDK 1.61, this no longer exists as everything is synced at game boot.
!!! returns "Returns"
| Key | Type | Notes |
| --- | ---- | ----- |
| game | uint64_t | The game ID that these stats are for; should match the app ID.
| result | uint32_t | Returns whether the call was successful or not; if the user has no stats, this will be set to [RESULT_FAIL](main.md#result).
| user | uint64_t | The user whose stats were retrieved.
---
[:fontawesome-brands-steam: Read more in the official Steamworks SDK documentation](https://partner.steamgames.com/doc/api/ISteamUserStats#UserStatsReceived_t){ .md-button .md-button--doc_classes target="_blank" }
Removed GodotSteam 4.12 Removed GodotSteam 3.28
global_achievement_percentages_ready
global_achievement_percentages_ready
Called when the global achievement percentages have been received from the server.
Returns
Key | Type | Notes |
---|---|---|
game | uint64_t | Game ID which these achievement percentages are for. |
result | Result enum | Result of the request. May get RESULT_FAIL if the remote call fails or there are no global achievement percentages for the current app ID. |
global_stats_received
global_stats_received
Called when the global stats have been received from the server.
Returns
Key | Type | Notes |
---|---|---|
game_id | uint64_t | Game ID which these global stats are for. |
result | Result enum | The result of the request. May be RESULT_FAIL if the remote call fails. |
leaderboard_find_result
leaderboard_find_result
Result when finding a leaderboard.
Returns
Key | Type | Notes |
---|---|---|
leaderboard_handle | uint64_t | Handle to the leaderboard that was searched for. 0 if no leaderboard was found. |
found | uint8_t | Was the leaderboard found? 1 if it was, 0 if it wasn't. |
leaderboard_scores_downloaded
leaderboard_scores_downloaded
Called when scores for a leaderboard have been downloaded and are ready to be retrieved.
Returns
Key | Type | Notes |
---|---|---|
message | string | The message about the successful call or not. |
this_handle | uint64_t | Handle to the leaderboard that these entries belong to. |
leaderboard_entries_array | array | An array of downloaded leaderboard entries as dictionaries. |
The leaderboard_entries_array contains a list of:
Key | Type | Notes |
---|---|---|
entry_dict | dictionary | The leaderboard entry for this call. |
Contains the following keys:
Key | Type | Notes |
---|---|---|
score | int | The raw score as set in the leaderboard. |
steam_id | uint64_t | The Steam ID of the user who this entry belongs to. |
global_rank | int | The global rank of this entry ranging from [1..N], where N is the number of users with an entry in the leaderboard. |
ugc_handle | uint64_t | The handle for the UGC attached to this entry. Will be UGC_HANDLE_INVALID if there is none. |
details | PackedInt32Array | An array of details for this entry. |
leaderboard_score_uploaded
leaderboard_score_uploaded
Result indicating that a leaderboard score has been uploaded.
Returns
Key | Type | Notes |
---|---|---|
success | uint8 | Was the call successful? Returns 1 if so, 0 on failure. Failure may happen if the details sent exceeds LEADERBOARD_DETAILS_MAX or the leaderboard is set to "Trusted" so it can only accepts scores frmo the Web API. |
this_handle | uint64_t | Handle to the leaderboard that this score was uploaded to. |
this_score | dictionary | The dictionary of score data for the entry uploaded. |
The this_score dictionary contains the following keys:
Key | Type | Notes |
---|---|---|
score | int32 | The score that was attempted to set. |
score_changed | uint8 | True if the score on the leaderboard changed otherwise false if the existing score was better. |
global_rank_new | int | The new global rank of the user on this leaderboard. |
global_rank_prev | int | The previous global rank of the user on this leaderboard; 0 if the user had no existing entry in the leaderboard. |
leaderboard_ugc_set
leaderboard_ugc_set
Result indicating that user generated content has been attached to one of the current user's leaderboard entries.
Returns
Key | Type | Notes |
---|---|---|
leaderboard_handle | uint64_t | Handle to the leaderboard that the UGC was attached to. |
result | Result enum | The result of the operation. RESULT_TIMEOUT if the upload took too long; the UGC was not submitted. RESULT_INVALID_PARAM if the handle passed was invalid; the UGC was not submitted. |
number_of_current_players
number_of_current_players
Gets the current number of players for the current app ID.
Returns
Key | Type | Notes |
---|---|---|
success | uint8 | Was the call successful? Returns 1 if it was; otherwise, 0 on failure. |
players | int32 | Number of players currently playing. |
user_achievement_icon_fetched
user_achievement_icon_fetched
Result of an achievement icon that has been fetched.
Returns
Key | Type | Notes |
---|---|---|
game_id | int | The game ID this achievement is for. |
achievement_name | string | The name of the achievement that this callback is for. |
achieved | bool | Returns whether the icon for the achieved (true) or unachieved (false) version. |
icon_handle | int | Handle to the image, which can be used with getImageRGBA to get the image data. 0 means no image is set for the achievement. |
user_achievement_stored
user_achievement_stored
Result of a request to store the achievements on the server, or an "indicate progress" call. If both current progress and max progress are zero, that means the achievement has been fully unlocked.
Returns
Key | Type | Notes |
---|---|---|
game_id | uint64_t | Game ID that this achievement is for. |
group_achieve | bool | Unused. |
name | string | Name of the achievement. |
current_progress | uint32_t | Current progress towards the achievement. |
max_progress | uint32_t | The total amount of progress required to unlock. |
user_stats_received
user_stats_received
Called when the latest stats and achievements for a specific user (including the local user) have been received from the server.
Returns
Key | Type | Notes |
---|---|---|
game_id | uint64_t | Game ID that these stats are for. |
result | uint32_t | Returns whether the call was successful or not. If the user has no stats, this will be set to RESULT_FAIL |
user | uint64_t | The user whose stats were retrieved. |
user_stats_stored
user_stats_stored
Result of a request to store the user stats.
Returns
Key | Type | Notes |
---|---|---|
game_id | uint64_t | Game ID that these stats are for. |
result | Result enum | Returns whether the call was successful or not. |
user_stats_unloaded
user_stats_unloaded
Callback indicating that a user's stats have been unloaded. Call requestUserStats again before accessing stats for this user.
Returns
Key | Type | Notes |
---|---|---|
user | uint64_t | User whose stats have been unloaded. |
Constants
Name | SDK Name | Value | Notes |
---|---|---|---|
LEADERBOARD_DETAILS_MAX | k_cLeaderboardDetailsMax | 64 | Maximum number of bytes for a leaderboard name (UTF-8 encoded). |
LEADERBOARD_NAME_MAX | k_cchLeaderboardNameMax | 128 | Maximum number of bytes for stat and achievement names (UTF-8 encoded). |
STAT_NAME_MAX | k_cchStatNameMax | 128 | Maximum number of details that you can store for a single leaderboard entry. |
Enums
LeaderboardDataRequest
Type of data request when downloading leaderboard entries.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
LEADERBOARD_DATA_REQUEST_GLOBAL | k_ELeaderboardDataRequestGlobal | 0 | - |
LEADERBOARD_DATA_REQUEST_GLOBAL_AROUND_USER | k_ELeaderboardDataRequestGlobalAroundUser | 1 | - |
LEADERBOARD_DATA_REQUEST_FRIENDS | k_ELeaderboardDataRequestFriends | 2 | - |
LEADERBOARD_DATA_REQUEST_USERS | k_ELeaderboardDataRequestUsers | 3 | - |
LeaderboardDisplayType
The display type (used by the Steam Community web site) for a leaderboard.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
LEADERBOARD_DISPLAY_TYPE_NONE | k_ELeaderboardDisplayTypeNone | 0 | - |
LEADERBOARD_DISPLAY_TYPE_NUMERIC | k_ELeaderboardDisplayTypeNumeric | 1 | Simple numerical score. |
LEADERBOARD_DISPLAY_TYPE_TIME_SECONDS | k_ELeaderboardDisplayTypeTimeSeconds | 2 | The score represents a time, in seconds. |
LEADERBOARD_DISPLAY_TYPE_TIME_MILLISECONDS | k_ELeaderboardDisplayTypeTimeMilliSeconds | 3 | The score represents a time, in milliseconds, |
LeaderboardSortMethod
The sort order of a leaderboard.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
LEADERBOARD_SORT_METHOD_NONE | k_ELeaderboardSortMethodNone | 0 | - |
LEADERBOARD_SORT_METHOD_ASCENDING | k_ELeaderboardSortMethodAscending | 1 | - |
LEADERBOARD_SORT_METHOD_DESCENDING | k_ELeaderboardSortMethodDescending | 2 | - |
LeaderboardUploadScoreMethod
How to handle uploaded scores.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
LEADERBOARD_UPLOAD_SCORE_METHOD | k_ELeaderboardUploadScoreMethodNone | 0 | - |
LEADERBOARD_UPLOAD_SCORE_METHOD_KEEP_BEST | k_ELeaderboardUploadScoreMethodKeepBest | 1 | Leaderboard will keep user's best score. |
LEADERBOARD_UPLOAD_SCORE_METHOD_FORCE_UPDATE | k_ELeaderboardUploadScoreMethodForceUpdate | 2 | Leaderboard will always replace score with specified. |