TSteamUserStats · BlitzMax

Provides methods for accessing and submitting stats, achievements, and leaderboards.

Methods

`Method SetListener(listener:ISteamUserStatsListener)`

Sets the user stats callback listener.

Once installed, the listener will receive stats events via the callback methods.

`Method RemoveListener()`

Removes the current user stats callback listener.

`Method ClearAchievement:Int(name:String)`

Resets the unlock status of an achievement.

This is primarily only ever used for testing.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this!

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

True upon success if all of the following conditions are met; otherwise, False.

`Method DownloadLeaderboardEntries(leaderboardHandle:ULong, leaderboardDataRequest:ELeaderboardDataRequest, rangeStart:Int, rangeEnd:Int)`

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 leaderboardHandle prior to calling this method.

`Method DownloadLeaderboardEntriesForUsers(leaderboardHandle:ULong, users:ULong[])`

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 leaderboardHandle prior to calling this method.

`Method FindLeaderboard(leaderboardName:String)`

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 methods.

`Method FindOrCreateLeaderboard(leaderboardName:String, sortMethod:ELeaderboardSortMethod , displayType:ELeaderboardDisplayType)`

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 methods.

Leaderboards created with this method 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 k_ELeaderboardSortMethodNone for sortMethod or k_ELeaderboardDisplayTypeNone for displayType as this is undefined behavior.

`Method GetAchievement:Int(name:String, achieved:Int Var)`

Gets the unlock status of the Achievement.

The equivalent method for other users is GetUserAchievement.

This method returns True upon success if all of the following conditions are met; otherwise, False.

RequestCurrentStats has completed and successfully returned its callback.
The 'API Name' of the specified achievement exists in App Admin on the Steamworks website, and the changes are published.

If the call is successful then the unlock status is returned via the achieved parameter.

`Method GetAchievementAchievedPercent:Int(name:String, percent:Float Var)`

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

True upon success; otherwise False if RequestGlobalAchievementPercentages has not been called or if the specified 'API Name' does not exist in the global achievement percentages.

`Method GetAchievementAndUnlockTime:Int(name:String, achieved:Int Var, unlockTime:UInt Var)`

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.

`Method GetAchievementDisplayAttribute:String(name:String, key:String)`

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.

`Method GetAchievementIcon:Int(name:String)`

Gets the icon for an achievement.

Triggers an OnUserAchievementIconFetched callback. The image is returned as a handle to be used with TSteamUtils.GetImageRGBA to get the actual image data.

An invalid handle of 0 will be returned under the following conditions:

RequestCurrentStats has not completed and successfully returned its callback.
The specified achievement does not exist in App Admin on the Steamworks website, or the changes are not published.
Steam is still fetching the image data from the server. This will trigger an OnUserAchievementIconFetched callback which will notify you when the image data is ready and provide you with a new handle. If the iconHandle in the callback is still 0, then there is no image set for the specified achievement.

`Method GetAchievementName:String(achievement:UInt)`

Gets the 'API name' for an achievement index between 0 and GetNumAchievements.

This method must be used in cojunction with GetNumAchievements to loop over the list of achievements. In general games should not need these methods as they should have the list of achievements compiled into them.

RequestCurrentStats must have been called and successfully returned its callback, and the current App ID must have achievements.

`Method GetGlobalStat:Int(statName:String, data:Long Var)`

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.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestGlobalStats has completed and successfully returned its callback.
The type does not match the type listed in the App Admin panel of the Steamworks website.

`Method GetGlobalStat:Int(statName:String, data:Double Var)`

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.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestGlobalStats has completed and successfully returned its callback.
The type does not match the type listed in the App Admin panel of the Steamworks website.

`Method GetGlobalStatHistory:Int(statName:String, data:Long[])`

Gets the daily history for an aggregated stat.

data will be filled with daily values, starting with today. So when called, data[0] will be today, data[1] will be yesterday, and data[2] will be two days ago, etc.

You must have called RequestGlobalStats and it needs to return successfully via its callback prior to calling this.

A return value of 0 indicates failure for one of the following reasons:

The specified stat does not exist in App Admin on the Steamworks website, or the changes aren't published.
RequestGlobalStats has not been called or returned its callback, with at least 1 day of history.
The type does not match the type listed in the App Admin panel of the Steamworks website.
There is no history available.

Returns

The number of elements returned in the data array.

`Method GetGlobalStatHistory:Int(statName:String, data:Double[])`

Gets the daily history for an aggregated stat.

data will be filled with daily values, starting with today. So when called, data[0] will be today, data[1] will be yesterday, and data[2] will be two days ago, etc.

You must have called RequestGlobalStats and it needs to return successfully via its callback prior to calling this.

A return value of 0 indicates failure for one of the following reasons:

The specified stat does not exist in App Admin on the Steamworks website, or the changes aren't published.
RequestGlobalStats has not been called or returned its callback, with at least 1 day of history.
The type does not match the type listed in the App Admin panel of the Steamworks website.
There is no history available.

Returns

The number of elements returned in the data array.

`Method GetLeaderboardDisplayType:ELeaderboardDisplayType(leaderboardHandle:ULong)`

Returns the display type of a leaderboard handle.

Returns

The display type of the leaderboard. Returns ELeaderboardDisplayType.k_ELeaderboardDisplayTypeNone if the leaderboard handle is invalid.

`Method GetLeaderboardEntryCount:Int(leaderboardHandle:ULong)`

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

The number of entries in the leaderboard. Returns 0 if the leaderboard handle is invalid.

`Method GetLeaderboardName:String(leadboarHandle:ULong)`

Returns the name of a leaderboard handle.

Returns

The name of the leaderboard. Returns Null if the leaderboard handle is invalid.

`Method GetLeaderboardSortMethod:ELeaderboardSortMethod(leaderboardHandle:ULong)`

Returns the sort order of a leaderboard handle.

Returns

The sort method of the leaderboard. Returns ELeaderboardSortMethod.k_ELeaderboardSortMethodNone if the leaderboard handle is invalid.

`Method GetMostAchievedAchievementInfo:Int(name:String Var, percent:Float Var, achieved:Int Var)`

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. If the call is successful it returns an iterator which should be used with GetNextMostAchievedAchievementInfo.

Returns

-1 if RequestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app Id.

`Method GetNextMostAchievedAchievementInfo:Int(previous:Int, name:String Var, percent:Float Var, achieved:Int Var)`

Gets the info on the next most achieved achievement for the game.

Returns

-1 if RequestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app Id.

`Method GetNumAchievements:UInt()`

Gets 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 methods because they should have a list of existing achievements compiled into them.

Returns

The number of achievements. Returns 0 if RequestCurrentStats has not been called and successfully returned its callback, or the current App ID has no achievements.

`Method GetNumberOfCurrentPlayers()`

Asynchronously retrieves the total number of players currently playing the current game.

Both online and in offline mode.

`Method GetUserAchievement:Int(steamID:ULong, name:String, achieved:Int Var)`

Gets the unlock status of the Achievement.

The equivalent function for the local user is GetAchievement.

This function returns True upon success if all of the following conditions are met; otherwise, False.

RequestUserStats has completed and successfully returned its callback.
The 'API Name' of the specified achievement exists in App Admin on the Steamworks website, and the changes are published.

If the call is successful then the unlock status is returned via the achieved parameter

`Method GetUserAchievementAndUnlockTime:Int(steamID:ULong, name:String, achieved:Int Var, unlockTime:UInt Var)`

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 method for the local user is GetAchievementAndUnlockTime.

This method returns True upon success if all of the following conditions are met; otherwise, False.

RequestUserStats has completed and successfully returned its callback.
The 'API Name' of the specified achievement exists in App Admin on the Steamworks website, and the changes are published.

If the call is successful then the achieved status and unlock time are provided via the arguments pbAchieved and punUnlockTime.

`Method GetUserStat:Int(steamID:ULong, name:String, data:Int Var)`

Gets the current value of the a stat for the specified user.

You must have called RequestUserStats and it needs to return successfully via its callback prior to calling this. The equivalent method for the local user is GetStat.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestUserStats has completed and successfully returned its callback.
The type does not match the type listed in the App Admin panel of the Steamworks website.

`Method GetUserStat:Int(steamID:ULong, name:String, data:Float Var)`

Gets the current value of the a stat for the specified user.

You must have called RequestUserStats and it needs to return successfully via its callback prior to calling this. The equivalent method for the local user is GetStat.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestUserStats has completed and successfully returned its callback.
The type does not match the type listed in the App Admin panel of the Steamworks website.

`Method IndicateAchievementProgress:Int(name:String, curProgress:UInt, maxProgress:UInt)`

Shows the user a pop-up notification with the current progress of an achievement.

Calling this method will NOT set the progress or unlock the achievement, the game must do that manually by calling SetStat!

Triggers an OnUserStatsStored callback. Triggers an OnUserAchievementStored callback.

This method returns true upon success if all of the following conditions are met; otherwise, false.

RequestCurrentStats has completed and successfully returned its callback.
The specified achievement exists in App Admin on the Steamworks website, and the changes are published.
The specified achievement is not already unlocked.
curProgress is less than maxProgress.

`Method RequestCurrentStats:Int()`

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.

See Also: GetStat, SetStat, SetAchievement, StoreStats

`Method RequestGlobalAchievementPercentages()`

Asynchronously fetch the data for the percentage of players who have received each achievement for the current game globally.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this.

Triggers an OnGlobalAchievementPercentagesReady callback.

`Method RequestGlobalStats(historyDays:Int)`

Asynchronously fetches global stats data, which is available for stats marked as "aggregated" in the App Admin panel of the Steamworks website.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this.

Triggers an OnGlobalStatsReceived callback.

`Method RequestUserStats(steamID:ULong)`

Asynchronously downloads stats and achievements for the specified user from the server.

These stats are not automatically updated; you'll need to call this method again to refresh any data that may have changed. To keep from using too much memory, a least recently used cache (LRU) is maintained and other user's stats will occasionally be unloaded. When this happens an OnUserStatsUnloaded callback is sent. After receiving this callback the user's stats will be unavailable until this method is called again.

The equivalent method for the local user is RequestCurrentStats.

Triggers an OnUserStatsReceived callback.

`Method ResetAllStats:Int(achievementsToo:Int)`

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. Ensure that you sync up your stats with the new default values provided by Steam after calling this by calling RequestCurrentStats.

Returns

True indicating success if RequestCurrentStats has been called and successfully returned its callback; otherwise False.

`Method SetAchievement:Int(name:String)`

Unlocks an achievement.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this! 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.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified achievement "API Name" exists in App Admin on the Steamworks website, and the changes are published.
RequestCurrentStats has completed and successfully returned its callback.

`Method SetStat:Int(name:String, data:Int)`

Sets / updates the value of a given stat for the current user.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this!

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.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestCurrentStats has completed and successfully returned its callback.
The type passed to this function must match the type listed in the App Admin panel of the Steamworks website.

See Also: GetStat, UpdateAvgRateStat, ResetAllStats

`Method SetStat:Int(name:String, data:Float)`

Sets / updates the value of a given stat for the current user.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this!

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.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestCurrentStats has completed and successfully returned its callback.
The type passed to this function must match the type listed in the App Admin panel of the Steamworks website.

See Also: GetStat, UpdateAvgRateStat, ResetAllStats

`Method StoreStats:Int()`

Sends 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 method 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.

Triggers an OnUserStatsStored callback. Triggers an OnUserAchievementStored callback.

This method returns True upon success if all of the following conditions are met; otherwise, False.

RequestCurrentStats has completed and successfully returned its callback.
The current game has stats associated with it in the Steamworks Partner backend, and those stats are published.

If the call is successful you will receive an OnUserStatsStored callback.

If esult has a result of k_EResultInvalidParam, then one or more stats uploaded has been rejected, either because they broke constraints or were out of date. In this case the server sends back updated values and the stats should be updated locally to keep in sync.

If one or more achievements has been unlocked then this will also trigger an OnUserAchievementStored callback.

`Method UpdateAvgRateStat:Int(name:String, countThisSession:Float, sessionLength:Double)`

Updates an AVGRATE stat with new values.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this!

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.

This method returns True upon success if all of the following conditions are met; otherwise, False.

The specified stat exists in App Admin on the Steamworks website, and the changes are published.
RequestCurrentStats has completed and successfully returned its callback.
The type must be AVGRATE in the Steamworks Partner backend.

`Method UploadLeaderboardScore(leaderboardHandle:ULong, uploadScoreMethod:ELeaderboardUploadScoreMethod, score:Int, scoreDetails:Int[])`

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.

Triggers an OnLeaderboardScoreUploaded callback.

See Also: DownloadLeaderboardEntries, AttachLeaderboardUGC