Steamworks Documentation
ISteamUserStats Interface
Provides functions for accessing and submitting stats, achievements, and leaderboards.

Member Functions

Member functions for ISteamUserStats are called through the global accessor function SteamUserStats().

AttachLeaderboardUGC

SteamAPICall_t AttachLeaderboardUGC( SteamLeaderboard_t hSteamLeaderboard, UGCHandle_t hUGC );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.
hUGCUGCHandle_tHandle to a piece of user generated content that was shared using ISteamRemoteStorage::FileShare.

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 GetDownloadedLeaderboardEntry which contains LeaderboardEntry_t.m_hUGC. 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 SteamLeaderboard_t prior to calling this function.

Returns: SteamAPICall_t to be used with a LeaderboardUGCSet_t call result.

ClearAchievement

bool ClearAchievement( const char *pchName );
NameTypeDescription
pchNameconst char *The 'API Name' of the Achievement to reset.

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: bool
This function 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.

See Also: ResetAllStats, GetAchievementAndUnlockTime, GetAchievement, SetAchievement

DownloadLeaderboardEntries

SteamAPICall_t DownloadLeaderboardEntries( SteamLeaderboard_t hSteamLeaderboard, ELeaderboardDataRequest eLeaderboardDataRequest, int nRangeStart, int nRangeEnd );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.
eLeaderboardDataRequestELeaderboardDataRequestThe type of data request to make.
nRangeStartintThe index to start downloading entries relative to eLeaderboardDataRequest.
nRangeEndintThe last index to retrieve entries for relative to eLeaderboardDataRequest.

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 SteamLeaderboard_t prior to calling this function.

Returns: SteamAPICall_t to be used with a LeaderboardScoresDownloaded_t call result.


See Also: GetDownloadedLeaderboardEntry, UploadLeaderboardScore

DownloadLeaderboardEntriesForUsers

SteamAPICall_t DownloadLeaderboardEntriesForUsers( SteamLeaderboard_t hSteamLeaderboard, CSteamID *prgUsers, int cUsers );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.
prgUsersCSteamID *An array of Steam IDs to get the leaderboard entries for.
cUsersintThe number of elements in the prgUsers array.

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 SteamLeaderboard_t prior to calling this function.

Returns: SteamAPICall_t to be used with a LeaderboardScoresDownloaded_t call result.
Returns k_uAPICallInvalid indicating an error if the number of users is greater than 100 or if one of the Steam IDs is invalid.

See Also: GetDownloadedLeaderboardEntry, UploadLeaderboardScore

FindLeaderboard

SteamAPICall_t FindLeaderboard( const char *pchLeaderboardName );
NameTypeDescription
pchLeaderboardNameconst char *The name of the leaderboard to find. Must not be longer than k_cchLeaderboardNameMax.

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: SteamAPICall_t to be used with a LeaderboardFindResult_t call result.


See Also: GetLeaderboardEntryCount, DownloadLeaderboardEntries, UploadLeaderboardScore

FindOrCreateLeaderboard

SteamAPICall_t FindOrCreateLeaderboard( const char *pchLeaderboardName, ELeaderboardSortMethod eLeaderboardSortMethod, ELeaderboardDisplayType eLeaderboardDisplayType );
NameTypeDescription
pchLeaderboardNameconst char *The name of the leaderboard to find or create. Must not be longer than k_cchLeaderboardNameMax.
eLeaderboardSortMethodELeaderboardSortMethodThe sort order of the new leaderboard if it's created.
eLeaderboardDisplayTypeELeaderboardDisplayTypeThe 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 k_ELeaderboardSortMethodNone for eLeaderboardSortMethod or k_ELeaderboardDisplayTypeNone for eLeaderboardDisplayType as this is undefined behavior.

Returns: SteamAPICall_t to be used with a LeaderboardFindResult_t call result.


See Also: GetLeaderboardEntryCount, DownloadLeaderboardEntries, UploadLeaderboardScore

GetAchievement

bool GetAchievement( const char *pchName, bool *pbAchieved );
NameTypeDescription
pchNameconst char *The 'API Name' of the achievement.
pbAchievedbool *Returns the unlock status of the achievement.

Gets the unlock status of the Achievement.

The equivalent function for other users is GetUserAchievement.

Returns: bool
This function 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 pbAchieved parameter.

See Also: GetAchievementDisplayAttribute, GetAchievementName, GetAchievementIcon, GetAchievementAndUnlockTime, GetAchievementAchievedPercent

GetAchievementAchievedPercent

bool GetAchievementAchievedPercent( const char *pchName, float *pflPercent );
NameTypeDescription
pchNameconst char *The 'API Name' of the achievement.
pflPercentfloat *Variable to return the percentage of people that have unlocked this achievement from 0 to 100.

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: bool
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.

See Also: GetMostAchievedAchievementInfo, GetNextMostAchievedAchievementInfo

GetAchievementAndUnlockTime

bool GetAchievementAndUnlockTime( const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );
NameTypeDescription
pchNameconst char *The 'API Name' of the achievement.
pbAchievedbool *Returns whether the current user has unlocked the achievement.
punUnlockTimeuint32 *Returns the time that the achievement was unlocked; if pbAchieved is true.

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: bool
This function 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 achieved status and unlock time are provided via the arguments pbAchieved and punUnlockTime.

See Also: GetAchievement, GetAchievementDisplayAttribute, GetAchievementName, GetAchievementIcon

GetAchievementDisplayAttribute

const char * GetAchievementDisplayAttribute( const char *pchName, const char *pchKey );
NameTypeDescription
pchNameconst char *The 'API Name' of the achievement.
pchKeyconst char *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: const char *
This function returns the value as a string upon success if all of the following conditions are met; otherwise, an empty string: "".
  • 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 pchKey is valid.

See Also: GetAchievement, GetAchievementName, GetAchievementIcon, GetAchievementAndUnlockTime

GetAchievementIcon

int GetAchievementIcon( const char *pchName );
NameTypeDescription
pchNameconst char *The 'API Name' of the achievement.

Gets the icon for an achievement.

Returns: int
Triggers a UserAchievementIconFetched_t callback.
The image is returned as a handle to be used with ISteamUtils::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 a UserAchievementIconFetched_t callback which will notify you when the image data is ready and provide you with a new handle. If the m_nIconHandle in the callback is still 0, then there is no image set for the specified achievement.

See Also: GetAchievement, GetAchievementName, GetAchievementAndUnlockTime, GetAchievementAchievedPercent, GetAchievementDisplayAttribute

GetAchievementName

const char * GetAchievementName( uint32 iAchievement );
NameTypeDescription
iAchievementuint32Index of the achievement.

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

This function must be used in cojunction 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: const char *
The 'API Name' of the achievement, returns an empty string if iAchievement is not a valid index. RequestCurrentStats must have been called and successfully returned its callback, and the current App ID must have achievements.

Example:
int numAchievements = SteamUserStats()->GetNumAchievements(); for ( int i = 0; i < numAchievements; ++i ) { const char *achName = SteamUserStats()->GetAchievementName( i ); if ( achName ) { printf( "%s", achName ); } }

GetDownloadedLeaderboardEntry

bool GetDownloadedLeaderboardEntry( SteamLeaderboardEntries_t hSteamLeaderboardEntries, int index, LeaderboardEntry_t *pLeaderboardEntry, int32 *pDetails, int cDetailsMax );
NameTypeDescription
hSteamLeaderboardEntriesSteamLeaderboardEntries_tA leaderboard entries handle obtained from the most recently received LeaderboardScoresDownloaded_t call result.
indexintThe index of the leaderboard entry to receive, must be between 0 and LeaderboardScoresDownloaded_t.m_cEntryCount.
pLeaderboardEntryLeaderboardEntry_t *Variable where the entry will be returned to.
pDetailsint32 *A preallocated array where the details of this entry get returned into.
cDetailsMaxintThe length of the pDetails array.

Retrieves the data for a single leaderboard entry.

You should use a for loop from 0 to LeaderboardScoresDownloaded_t.m_cEntryCount to get all the downloaded entries. Once you've accessed all the entries, the data will be freed, and the SteamLeaderboardEntries_t handle will become invalid.

Optionally details may be returned for the entry via the pDetails. If this is NULL then cDetailsMax MUST be 0.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
  • hSteamLeaderboardEntries must be a valid handle from the last received LeaderboardScoresDownloaded_t call result.
  • index must be between 0 and LeaderboardScoresDownloaded_t.m_cEntryCount

If the call is successful then the entry is returned via the parameter pLeaderboardEntry and if cDetailsMax is not 0 then pDetails is filled with the unlock details.

See Also: DownloadLeaderboardEntries, UploadLeaderboardScore

Example:
void OnLeaderboardScoresDownloaded( LeaderboardScoresDownloaded_t *pCallback ) { for ( int i = 0; i < pCallback->m_cEntryCount; i++ ) { LeaderboardEntry_t leaderboardEntry; int32 details[3]; // We know that we store this many initially. SteamUserStats()->GetDownloadedLeaderboardEntry( pCallback->m_hSteamLeaderboardEntries, i, &leaderboardEntry, details, 3 ); assert( leaderboardEntry.m_cDetails == 3 ); //... } }

GetGlobalStat

bool GetGlobalStat( const char *pchStatName, int64 *pData ); bool GetGlobalStat( const char *pchStatName, double *pData );
NameTypeDescription
pchStatNameconst char *The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pDataint64 * / double *The variable to return the stat value into.

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: bool
This function 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 matches the type listed in the App Admin panel of the Steamworks website.

See Also: GetGlobalStatHistory

GetGlobalStatHistory

int32 GetGlobalStatHistory( const char *pchStatName, int64 *pData, uint32 cubData ); int32 GetGlobalStatHistory( const char *pchStatName, double *pData, uint32 cubData );
NameTypeDescription
pchStatNameconst char *The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pDatadouble *Array that the daily history will be returned into.
cubDatauint32The total size in bytes of the pData array.

Gets the daily history for an aggregated stat.

pData will be filled with daily values, starting with today.
So when called, pData[0] will be today, pData[1] will be yesterday, and pData[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.

Returns: int32
The number of elements returned in the pData array.

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

See Also: GetGlobalStat

GetLeaderboardDisplayType

ELeaderboardDisplayType GetLeaderboardDisplayType( SteamLeaderboard_t hSteamLeaderboard );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.

Returns the display type of a leaderboard handle.

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

See Also: GetLeaderboardName, GetLeaderboardSortMethod, GetLeaderboardEntryCount

GetLeaderboardEntryCount

int GetLeaderboardEntryCount( SteamLeaderboard_t hSteamLeaderboard );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.

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
The number of entries in the leaderboard. Returns 0 if the leaderboard handle is invalid.

See Also: GetLeaderboardName, GetLeaderboardSortMethod, GetLeaderboardDisplayType

GetLeaderboardName

const char * GetLeaderboardName( SteamLeaderboard_t hSteamLeaderboard );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.

Returns the name of a leaderboard handle.

Returns: const char *
The name of the leaderboard. Returns an empty string if the leaderboard handle is invalid.

See Also: GetLeaderboardEntryCount, GetLeaderboardSortMethod, GetLeaderboardDisplayType

GetLeaderboardSortMethod

ELeaderboardSortMethod GetLeaderboardSortMethod( SteamLeaderboard_t hSteamLeaderboard );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.

Returns the sort order of a leaderboard handle.

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

See Also: GetLeaderboardName, GetLeaderboardDisplayType, GetLeaderboardEntryCount

GetMostAchievedAchievementInfo

int GetMostAchievedAchievementInfo( char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );
NameTypeDescription
pchNamechar *String buffer to return the 'API Name' of the achievement into.
unNameBufLenuint32The size in bytes of pchName, should be at least as long as your longest achievement 'API Name'.
pflPercentfloat *Variable to return the percentage of people that have unlocked this achievement from 0 to 100.
pbAchievedbool *Variable to return whether the current user has unlocked this achievement.

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: int
Returns -1 if RequestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app Id.

If the call is successful it returns an iterator which should be used with GetNextMostAchievedAchievementInfo.

See Also: RequestCurrentStats, RequestGlobalAchievementPercentages, GetNextMostAchievedAchievementInfo, GetAchievementAchievedPercent

Example:
const int ACH_NAME_MAX_LENGTH = 64; char[ACH_NAME_MAX_LENGTH] achName; float achPercent; float achUnlocked; int i = SteamUserStats()->GetMostAchievedAchievementInfo( achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); while ( i != -1 ) { printf( "AchievementInfo - name: %s, percent: %f, unlocked: %d", achName, achPercent, achUnlocked ); // Do something like add/update this info in your local achievement object or display it to the user. i = SteamUserStats()->GetNextMostAchievedAchievementInfo( i, achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); }

GetNextMostAchievedAchievementInfo

int GetNextMostAchievedAchievementInfo( int iIteratorPrevious, char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );
NameTypeDescription
iIteratorPreviousintIterator returned from the previous call to this function or from GetMostAchievedAchievementInfo
pchNamechar *String buffer to return the 'API Name' of the achievement into.
unNameBufLenuint32The size in bytes of pchName, should be at least as long as your longest achievement 'API Name'.
pflPercentfloat *Variable to return the percentage of people that have unlocked this achievement from 0 to 100.
pbAchievedbool *Variable to return whether the current user has unlocked this achievement.

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: int
Returns -1 if RequestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app Id.

If the call is successful it returns an iterator which should be used with subsequent calls to this function.

Example:
const int ACH_NAME_MAX_LENGTH = 64; char[ACH_NAME_MAX_LENGTH] achName; float achPercent; float achUnlocked; int i = SteamUserStats()->GetMostAchievedAchievementInfo( achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); while ( i != -1 ) { printf( "AchievementInfo - name: %s, percent: %f, unlocked: %d", achName, achPercent, achUnlocked ); // Do something like add/update this info in your local achievement object or display it to the user. i = SteamUserStats()->GetNextMostAchievedAchievementInfo( i, achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); }

GetNumAchievements

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

See Also: RequestCurrentStats, GetAchievementName

Example:
int numAchievements = SteamUserStats()->GetNumAchievements(); for ( int i = 0; i < numAchievements; ++i ) { const char *achName = SteamUserStats()->GetAchievementName( i ); if ( achName ) { printf( "%s", achName ); } }

GetNumberOfCurrentPlayers

SteamAPICall_t GetNumberOfCurrentPlayers();
Asynchronously retrieves the total number of players currently playing the current game. Both online and in offline mode.

Returns: SteamAPICall_t to be used with a NumberOfCurrentPlayers_t call result.

GetStat

bool GetStat( const char *pchName, int32 *pData ); bool GetStat( const char *pchName, float *pData );
NameTypeDescription
pchNameconst char *The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pDataint32 * / float *The variable to return the stat value into.

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

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

To receive stats for other users use GetUserStat.

Returns: bool
This function 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: RequestCurrentStats, SetStat, UpdateAvgRateStat, StoreStats, ResetAllStats

GetTrophySpaceRequiredBeforeInstall

uint64 GetTrophySpaceRequiredBeforeInstall();
DEPRECATE ME.

Returns: uint64

GetUserAchievement

bool GetUserAchievement( CSteamID steamIDUser, const char *pchName, bool *pbAchieved );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to get the achievement for.
pchNameconst char *The 'API Name' of the achievement.
pbAchievedbool *Returns the unlock status of the achievement.

Gets the unlock status of the Achievement.

The equivalent function for the local user is GetAchievement, the equivalent function for game servers is ISteamGameServerStats::GetUserAchievement.

Returns: bool
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 pbAchieved parameter.

See Also: RequestUserStats, GetUserStat, GetUserAchievementAndUnlockTime

GetUserAchievementAndUnlockTime

bool GetUserAchievementAndUnlockTime( CSteamID steamIDUser, const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to get the achievement for.
pchNameconst char *The 'API Name' of the achievement.
pbAchievedbool *Returns whether the current user has unlocked the achievement.
punUnlockTimeuint32 *Returns the time that the achievement was unlocked; if pbAchieved is true.

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: bool
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 achieved status and unlock time are provided via the arguments pbAchieved and punUnlockTime.

See Also: RequestUserStats, GetUserAchievement, GetUserStat

GetUserStat

bool GetUserStat( CSteamID steamIDUser, const char *pchName, int32 *pData ); bool GetUserStat( CSteamID steamIDUser, const char *pchName, float *pData );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to get the stat for.
pchNameconst char *The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pDataint32 * / float *The variable to return the stat value into.

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 function for the local user is GetStat, the equivalent function for game servers is ISteamGameServerStats::GetUserStat.

Returns: bool
This function 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.

See Also: GetUserAchievement, GetUserAchievementAndUnlockTime

GetUserStatsData

bool GetUserStatsData( void *pvData, uint32 cubData, uint32 *pcubWritten );
NameTypeDescription
pvDatavoid *
cubDatauint32
pcubWrittenuint32 *

DEPRECATE ME.

Returns: bool

IndicateAchievementProgress

bool IndicateAchievementProgress( const char *pchName, uint32 nCurProgress, uint32 nMaxProgress );
NameTypeDescription
pchNameconst char *The 'API Name' of the achievement.
nCurProgressuint32The current progress.
nMaxProgressuint32The 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 SetStat!

The notification looks like this:
achievement_progress.png

Returns: bool
Triggers a UserStatsStored_t callback.
Triggers a UserAchievementStored_t callback.
This function 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.
  • nCurProgress is less than nMaxProgress.

See Also: RequestCurrentStats, SetAchievement, SetStat, StoreStats, ISteamUtils::SetOverlayNotificationPosition, ISteamUtils::SetOverlayNotificationInset

InstallPS3Trophies

bool InstallPS3Trophies();
DEPRECATE ME!!

Returns: bool

RequestCurrentStats

bool 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
Triggers a UserStatsReceived_t callback.
Only returns false if there is no user logged in; otherwise, true.

See Also: GetStat, SetStat, SetAchievement, StoreStats

RequestGlobalAchievementPercentages

SteamAPICall_t 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!

Returns: SteamAPICall_t to be used with a GlobalAchievementPercentagesReady_t call result.


See Also: GetMostAchievedAchievementInfo, GetNextMostAchievedAchievementInfo, GetAchievementAchievedPercent

RequestGlobalStats

SteamAPICall_t RequestGlobalStats( int nHistoryDays );
NameTypeDescription
nHistoryDaysintHow 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.

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

Returns: SteamAPICall_t to be used with a GlobalStatsReceived_t call result.


See Also: GetGlobalStat, GetGlobalStatHistory

RequestUserStats

SteamAPICall_t RequestUserStats( CSteamID steamIDUser );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to request stats 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 UserStatsUnloaded_t 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, the equivalent function for game servers is ISteamGameServerStats::RequestUserStats.

Returns: SteamAPICall_t to be used with a UserStatsReceived_t call result.


See Also: GetUserAchievement, GetUserAchievementAndUnlockTime, GetUserStat

ResetAllStats

bool ResetAllStats( bool bAchievementsToo );
NameTypeDescription
bAchievementsTooboolAlso reset the user's achievements?

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: bool
true indicating success if RequestCurrentStats has been called and successfully returned its callback; otherwise false.

SetAchievement

bool SetAchievement( const char *pchName );
NameTypeDescription
pchNameconst char *The 'API Name' of the Achievement to unlock.

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.

Returns: bool
This function 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.

See Also: RequestCurrentStats, StoreStats, ResetAllStats, GetAchievementAndUnlockTime, GetAchievement

SetStat

bool SetStat( const char *pchName, int32 nData ); bool SetStat( const char *pchName, float fData );
NameTypeDescription
pchNameconst char *The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
nDataint32 / floatThe new value of the stat. This must be an absolute value, it will not increment or decrement for you.

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.

Returns: bool
This function 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

SetUserStatsData

bool SetUserStatsData( const void *pvData, uint32 cubData );
NameTypeDescription
pvDataconst void *
cubDatauint32

DEPRECATE ME.

Returns: bool

StoreStats

bool 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
Triggers a UserStatsStored_t callback.
Triggers a UserAchievementStored_t callback.
This function 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 a UserStatsStored_t callback.

If m_eResult 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. You do not need to call RequestCurrentStats again in this case.

If one or more achievements has been unlocked then this will also trigger a UserAchievementStored_t callback.

See Also: SetStat, SetAchievement

UpdateAvgRateStat

bool UpdateAvgRateStat( const char *pchName, float flCountThisSession, double dSessionLength );
NameTypeDescription
pchNameconst char *The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
flCountThisSessionfloatThe value accumulation since the last call to this function.
dSessionLengthdoubleThe amount of time in seconds since the last call to this function.

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!

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
This function 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.

UploadLeaderboardScore

SteamAPICall_t UploadLeaderboardScore( SteamLeaderboard_t hSteamLeaderboard, ELeaderboardUploadScoreMethod eLeaderboardUploadScoreMethod, int32 nScore, const int32 *pScoreDetails, int cScoreDetailsCount );
NameTypeDescription
hSteamLeaderboardSteamLeaderboard_tA leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.
eLeaderboardUploadScoreMethodELeaderboardUploadScoreMethodDo you want to force the score to change, or keep the previous score if it was better?
nScoreint32The score to upload.
pScoreDetailsconst int32 *Optional: Array containing the details surrounding the unlocking of this score.
cScoreDetailsCountintThe number of elements in pScoreDetails. Must not exceed k_cLeaderboardDetailsMax

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: SteamAPICall_t to be used with a LeaderboardScoreUploaded_t call result.


See Also: DownloadLeaderboardEntries, AttachLeaderboardUGC

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamUserStats.

GlobalAchievementPercentagesReady_t

Called when the global achievement percentages have been received from the server.

NameTypeDescription
m_nGameIDuint64Game ID which these achievement percentages are for.
m_eResultEResultResult of the request. Returns:
k_EResultOK indicating success.
k_EResultInvalidState Stats haven't been loaded yet, Call RequestCurrentStats.
k_EResultFail if the remote call fails or there are no global achievement percentages for the current AppId.

Associated Functions: RequestGlobalAchievementPercentages

GlobalStatsReceived_t

Called when the global stats have been received from the server.

NameTypeDescription
m_nGameIDuint64Game ID which these global stats are for.
m_eResultEResultThe result of the request. Returns:

Associated Functions: RequestGlobalStats

LeaderboardFindResult_t

Result when finding a leaderboard.

NameTypeDescription
m_hSteamLeaderboardSteamLeaderboard_tHandle to the leaderboard that was searched for. 0 if no leaderboard was found.
m_bLeaderboardFounduint8Was the leaderboard found? 1 if it was, 0 if it wasn't.

Associated Functions: FindOrCreateLeaderboard, FindLeaderboard

LeaderboardScoresDownloaded_t

Called when scores for a leaderboard have been downloaded and are ready to be retrieved.
After calling you must use GetDownloadedLeaderboardEntry to retrieve the info for each downloaded entry.

NameTypeDescription
m_hSteamLeaderboardSteamLeaderboard_tHandle to the leaderboard that these entries belong to.
m_hSteamLeaderboardEntriesSteamLeaderboardEntries_tThe handle to pass into GetDownloadedLeaderboardEntry to retrieve the info for each downloaded entry.
m_cEntryCountintThe number of entries downloaded.

Associated Functions: DownloadLeaderboardEntries, DownloadLeaderboardEntriesForUsers

LeaderboardScoreUploaded_t

Result indicating that a leaderboard score has been uploaded.

NameTypeDescription
m_bSuccessuint8Was the call successful? Returns 1 if the call was successful, 0 on failure.
The amount of details sent exceeds k_cLeaderboardDetailsMax.
The leaderboard is set to "Trusted" in App Admin on Steamworks website, and will only accept scores sent from the Steam Web API.
m_hSteamLeaderboardSteamLeaderboard_tHandle to the leaderboard that this score was uploaded to.
m_nScoreint32The score that was attempted to set.
m_bScoreChangeduint8true if the score on the leaderboard changed otherwise false if the existing score was better.
m_nGlobalRankNewintThe new global rank of the user on this leaderboard.
m_nGlobalRankPreviousintThe previous global rank of the user on this leaderboard; 0 if the user had no existing entry in the leaderboard.

Associated Functions: UploadLeaderboardScore

LeaderboardUGCSet_t

Result indicating that user generated content has been attached to one of the current user's leaderboard entries.

NameTypeDescription
m_eResultEResultThe result of the operation.Possible Values:
m_hSteamLeaderboardSteamLeaderboard_tHandle to the leaderboard that the UGC was attached to.

Associated Functions: AttachLeaderboardUGC

NumberOfCurrentPlayers_t

Gets the current number of players for the current AppId.

NameTypeDescription
m_bSuccessuint8Was the call successful? Returns 1 if it was; otherwise, 0 on failure.
m_cPlayersint32Number of players currently playing.

Associated Functions: GetNumberOfCurrentPlayers

PS3TrophiesInstalled_t

Called when PS3 trophies are available.

NameTypeDescription
m_nGameIDuint64Game that these stats are for.
m_eResultEResultThe result of the operation.
m_ulRequiredDiskSpaceuint64If m_eResult is k_EResultDiskFull, then this will contain the amount of space needed to install trophies.

UserAchievementIconFetched_t

Result of an achievement icon that has been fetched

NameTypeDescription
m_nGameIDCGameIDThe Game ID this achievement is for.
m_rgchAchievementNamechar[k_cchStatNameMaxThe name of the achievement that this callback is for.
m_bAchievedboolReturns whether the icon for the achieved (true) or unachieved (false) version.
m_nIconHandleintHandle to the image, which can be used with ISteamUtils::GetImageRGBA to get the image data. 0 means no image is set for the achievement.

Associated Functions: GetAchievementIcon

UserAchievementStored_t

Result of a request to store the achievements on the server, or an "indicate progress" call. If both m_nCurProgress and m_nMaxProgress are zero, that means the achievement has been fully unlocked.

NameTypeDescription
m_nGameIDuint64Game ID that this achievement is for.
m_bGroupAchievementboolUnused.
m_rgchAchievementNamechar[k_cchStatNameMaxName of the achievement.
m_nCurProgressuint32Current progress towards the achievement.
m_nMaxProgressuint32The total amount of progress required to unlock.

Associated Functions: StoreStats, IndicateAchievementProgress

UserStatsReceived_t

Called when the latest stats and achievements for a specific user (including the local user) have been received from the server.

NameTypeDescription
m_nGameIDuint64Game ID that these stats are for.
m_eResultEResultReturns whether the call was successful or not. If the user has no stats, this will be set to k_EResultFail.
m_steamIDUserCSteamIDThe user whose stats were retrieved.

Associated Functions: RequestCurrentStats, RequestUserStats

UserStatsStored_t

Result of a request to store the user stats.

NameTypeDescription
m_nGameIDuint64Game ID that these stats are for.
m_eResultEResultReturns whether the call was successful or not.

Associated Functions: StoreStats, IndicateAchievementProgress

UserStatsUnloaded_t

Callback indicating that a user's stats have been unloaded.

Call RequestUserStats again before accessing stats for this user.

NameTypeDescription
m_steamIDUserCSteamIDUser whose stats have been unloaded.

Structs

These are structs which functions in ISteamUserStats may return and/or interact with.

LeaderboardEntry_t

A single entry in a leaderboard, as returned by GetDownloadedLeaderboardEntry.

NameTypeDescription
m_steamIDUserCSteamIDUser who this entry belongs to. You can use ISteamFriends::GetFriendPersonaName and ISteamFriends::GetSmallFriendAvatar to get more info.
m_nGlobalRankint32The global rank of this entry ranging from [1..N], where N is the number of users with an entry in the leaderboard.
m_nScoreint32The raw score as set in the leaderboard.
m_cDetailsint32The number of details available for this entry.
m_hUGCUGCHandle_tHandle for the UGC attached to the entry. k_UGCHandleInvalid if there is none.

Enums

These are enums which are defined for use with ISteamUserStats.

ELeaderboardDataRequest

Type of data request, used when downloading leaderboard entries with DownloadLeaderboardEntries.

NameValueDescription
k_ELeaderboardDataRequestGlobal0Used to query for a sequential range of leaderboard entries by leaderboard rank. The start and end parameters control the requested range. For example, you can display the top 10 on a leaderboard for your game by setting start to 1 and end to 10.
k_ELeaderboardDataRequestGlobalAroundUser1Used to retrieve leaderboard entries relative a user's entry. The start parameter is the number of entries to retrieve before the current user's entry, and the end parameter is the number of entries after the current user's entry. The current user's entry is always included. For example, if the current user is #5 on the leaderboard, setting start to -2 and end to 2 will return 5 entries: ranks #3 through #7. If there are not enough entries in the leaderboard before or after the user's entry, Steam will adjust the range to try to return the number of entries requested. For example, if the user is #1 on the leaderboard and start is set to -2, end is set to 2, Steam will return the first 5 entries in the leaderboard.
k_ELeaderboardDataRequestFriends2Used to retrieve all leaderboard entries for friends of the current user. The start and end parameters are ignored.
k_ELeaderboardDataRequestUsers3Used internally, do not use with DownloadLeaderboardEntries! Doing so is undefined behavior.

ELeaderboardDisplayType

The display type used by the Steam Community web site to know how to format the leaderboard scores when displayed. You can set the display type when creating a leaderboard with FindOrCreateLeaderboard or in the Steamworks partner backend. You can retrieve the display type for a given leaderboard with GetLeaderboardDisplayType.

NameValueDescription
k_ELeaderboardDisplayTypeNone0This is only ever used when a leaderboard is invalid, you should never set this yourself.
k_ELeaderboardDisplayTypeNumeric1The score is just a simple numerical value.
k_ELeaderboardDisplayTypeTimeSeconds2The score represents a time, in seconds.
k_ELeaderboardDisplayTypeTimeMilliSeconds3The score represents a time, in milliseconds.

ELeaderboardSortMethod

The sort method used to set whether a higher or lower score is better. You can set the sort method when creating a leaderboard with FindOrCreateLeaderboard or in App Admin on the Steamworks website. You can retrieve the sort method for a given leaderboard with GetLeaderboardSortMethod.

NameValueDescription
k_ELeaderboardSortMethodNone0Only ever used when a leaderboard is invalid, you should never set this yourself.
k_ELeaderboardSortMethodAscending1The top-score is the lowest number.
k_ELeaderboardSortMethodDescending2The top-score is the highest number.

ELeaderboardUploadScoreMethod



NameValueDescription
k_ELeaderboardUploadScoreMethodNone0
k_ELeaderboardUploadScoreMethodKeepBest1Leaderboard will keep user's best score
k_ELeaderboardUploadScoreMethodForceUpdate2Leaderboard will always replace score with specified

Typedefs

These are typedefs which are defined for use with ISteamUserStats.

NameBase typeDescription
SteamLeaderboardEntries_tuint64Handle to a list of downloaded entries in a leaderboard. This is returned by LeaderboardScoresDownloaded_t and can be used to iterate through all of the entries with GetDownloadedLeaderboardEntry
SteamLeaderboard_tuint64Handle to a single leaderboard.

Constants

These are constants which are defined for use with ISteamUserStats.

NameTypeValueDescription
k_cchLeaderboardNameMaxint128Maximum number of bytes for a leaderboard name (UTF-8 encoded).
k_cchStatNameMaxint128Maximum number of bytes for stat and achievement names (UTF-8 encoded).
k_cLeaderboardDetailsMaxint64Maximum number of details that you can store for a single leaderboard entry.
STEAMUSERSTATS_INTERFACE_VERSIONconst char *"STEAMUSERSTATS_INTERFACE_VERSION011"