Skip to content

Game Server Stats

Functions to allow game servers to set stats and achievements on players.

Only available in the GodotSteam Server branches

Functions

clearUserAchievement

clearUserAchievement( uint64_t steam_id, string name )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to clear the achievement for.
name string 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.

Returns: bool

Notes

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.


Read more in the official Steamworks SDK documentation

getUserAchievement

getUserAchievement( uint64_t steam_id, string name )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to get the achievement for.
name string The API name of the achievement.

Gets the unlock status of the Achievement.

Returns: dictionary

Contains the following keys:

Key Type Notes
result 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.
user uint64_t The Steam ID of the user we got the achievement for.
name string The API name of the achievement.
unlocked bool Whether or not the achievement was unlocked.

Read more in the official Steamworks SDK documentation

getUserStatFloat

getUserStatFloat( uint64_t steam_id, string name )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to get the stat for.
name string The API name of the stat.

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

Returns: float


Read more in the official Steamworks SDK documentation

getUserStatInt

getUserStatInt( uint64_t steam_id, string name )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to get the stat for.
name string The API name of the stat.

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

Returns: uint32_t


Read more in the official Steamworks SDK documentation

requestUserStats

requestUserStats( uint64_t steam_id )

Parameter Type Notes
steam_id uint64_t The 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: void

Triggers

stats_received call result.


Read more in the official Steamworks SDK documentation

setUserAchievement

setUserAchievement( uint64_t steam_id, string name )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to unlock the achievement for.
name string 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.

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.

Notes

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.


Read more in the official Steamworks SDK documentation

setUserStatFloat

setUserStatFloat( uint64_t steam_id, string name, float stat )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to set the stat on.
name string The API name of the stat.
stat float The 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.

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.

Notes

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.


Read more in the official Steamworks SDK documentation

setUserStatInt

setUserStatInt( uint64_t steam_id, string name, int stat )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to set the stat on.
name string The API name of the stat.
stat int The 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.

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.

Notes

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.


Read more in the official Steamworks SDK documentation

storeUserStats

storeUserStats( uint64_t steam_id )

Parameter Type Notes
steam_id uint64_t The 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: void

Triggers

stats_stored callback.


Read more in the official Steamworks SDK documentation

updateUserAvgRateStat

updateUserAvgRateStat( uint64_t steam_id, string name, float this_session, double session_length )

Parameter Type Notes
steam_id uint64_t The Steam ID of the user to update the AVGRATE stat for.
name string The API name of the stat.
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 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.

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.

Read more in the official Steamworks SDK documentation

Signals

These callbacks require you to setup one of the three callback methods to receive them.

stats_received

stats_received

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

Emits signal in response to function requestUserStats.

Returns

Key Type Notes
result Result enum Success / error fetching the stats.
steam_id uint64_t The user for whom the stats are retrieved for.

Read more in the official Steamworks SDK documentation

stats_stored

stats_stored

Result of a request to store the user stats.

Emits signal in response to function storeUserStats.

Returns

Key Type Notes
result Result enum Returns whether the call was successful or not.
steam_id uint64_t The user for whom the stats were stored.

Read more in the official Steamworks SDK documentation

stats_unloaded

stats_unloaded

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

Returns

Key Type Notes
steam_id uint64_t User whose stats have been unloaded.

Read more in the official Steamworks SDK documentation