Steamworks Documentation
ISteamGameServerStats Interface
Functions to allow game servers to set stats and achievements on players.

Member Functions

Member functions for ISteamGameServerStats are called through the global accessor function SteamGameServerStats().

ClearUserAchievement

bool ClearUserAchievement( CSteamID steamIDUser, const char *pchName );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to clear the achievement for.
pchNameconst char *The 'API Name' of the Achievement to reset.

Resets the unlock status of an achievement for the specified user.

This is primarily only ever used for testing.

You must have called RequestUserStats 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. To submit the stats to the server you must call StoreUserStats.

NOTE: This will work only on achievements that game servers are allowed to set. If the "Set By" field for this achievement is "Official GS" then only game servers that have been declared as officially controlled by you will be able to set it. To do this you must set the IP range of your official servers in the Dedicated Servers section of App Admin.

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.
  • RequestUserStats has completed and successfully returned its callback for the specified user.
  • The stat must be allowed to be set by game server.

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.

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.

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.

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 passed to this function must match the type listed in the App Admin panel of the Steamworks website.

RequestUserStats

SteamAPICall_t RequestUserStats( CSteamID steamIDUser );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to request the stats for.

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

These stats will only be auto-updated for clients currently playing on the server. For other users you'll need to call this function again to refresh any data.

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

SetUserAchievement

bool SetUserAchievement( CSteamID steamIDUser, const char *pchName );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to unlock the achievement for.
pchNameconst char *The 'API Name' of the Achievement to unlock.

Unlocks an achievement for the specified user.

You must have called RequestUserStats 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. To submit the stats to the server you must call StoreUserStats.

NOTE: This will work only on achievements that game servers are allowed to set. If the "Set By" field for this achievement is "Official GS" then only game servers that have been declared as officially controlled by you will be able to set it. To do this you must set the IP range of your official servers in the Dedicated Servers section of App Admin.

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.
  • RequestUserStats has completed and successfully returned its callback for the specified user.
  • The stat must be allowed to be set by game server.

SetUserStat

bool SetUserStat( CSteamID steamIDUser, const char *pchName, int32 nData ); bool SetUserStat( CSteamID steamIDUser, const char *pchName, float fData );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to set the stat on.
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 specified user.

You must have called RequestUserStats 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. To submit the stats to the server you must call StoreUserStats.

NOTE: These updates will work only on stats that game servers are allowed to edit. If the "Set By" field for this stat is "Official GS" then only game servers that have been declared as officially controlled by you will be able to set it. To do this you must set the IP range of your official servers in the Dedicated Servers section of App Admin.

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 for the specified user.
  • The type passed to this function must match the type listed in the App Admin panel of the Steamworks website.
  • The stat must be allowed to be set by game server.

StoreUserStats

SteamAPICall_t StoreUserStats( CSteamID steamIDUser );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to store the stats of.

Send the changed stats and achievements data to the server for permanent storage for the specified user.

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.

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

UpdateUserAvgRateStat

bool UpdateUserAvgRateStat( CSteamID steamIDUser, const char *pchName, float flCountThisSession, double dSessionLength );
NameTypeDescription
steamIDUserCSteamIDThe Steam ID of the user to update the AVGRATE stat for.
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 for the specified user.

You must have called RequestUserStats 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. To submit the stats to the server you must call StoreUserStats.

NOTE: These updates will work only on stats that game servers are allowed to edit. If the "Set By" field for this stat is "Official GS" then only game servers that have been declared as officially controlled by you will be able to set it. To do this you must set the IP range of your official servers in the Dedicated Servers section of App Admin.

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 for the specified user.
  • The type must be AVGRATE in the Steamworks Partner backend.
  • The stat must be allowed to be set by game server.

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

GSStatsReceived_t

Result when getting the latests stats and achievements for a user from the server.

NameTypeDescription
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: RequestUserStats

GSStatsStored_t

Result of a request to store the user stats.

NameTypeDescription
m_eResultEResultReturns whether the call was successful or not.
m_steamIDUserCSteamIDThe user for whom the stats were stored

Associated Functions: StoreUserStats

GSStatsUnloaded_t

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

Call RequestUserStats again to access stats for this user.

NameTypeDescription
m_steamIDUserCSteamIDUser whose stats have been unloaded.

Constants

These are constants which are defined for use with ISteamGameServerStats.

NameTypeValueDescription
STEAMGAMESERVERSTATS_INTERFACE_VERSIONconst char *"SteamGameServerStats001"