steamworks.getUserStatValue()

Type Function
Return value Number
Revision Release 2024.3703
Keywords steam, steamworks, getUserStatValue
See also steamworks.setUserStatValues()
steamworks.requestUserProgress()
steamworks.*

Overview

Fetches one numeric stat value from a user. Note that stats are defined on the Steamworks website under the Stats & Achievements section. Stats are used to store developer-defined user gameplay statistics such as games played, games won, games lost, etc.

When fetching a stat from another user, you must first call the steamworks.requestUserProgress() function with that user's ID and wait for a successful userProgressUpdate event.

Gotchas

This function will return nil in the following cases:

Syntax

steamworks.getUserStatValue( params )
params (required)

Table. Table containing stat parameters — see the next section for details.

Parameter Reference

The params table can contain the following:

statName (required)

String. On the Steamworks website, this is the unique name of the stat set under the API Name column.

type (required)

String. Indicates the type of stat value to fetch. Must be set to "int", "float", or "averageRate". On the Steamworks website, this must match the value type set under the Type column or else Steam will fail to fetch the stat value.

userSteamId (optional)

String. Unique string ID of the user. The ID will default to the current user if this argument is not provided.

Example

local steamworks = require( "plugin.steamworks" )

-- Called when user achievement/stat data has been received
local function onUserProgressUpdated( event )
    -- Do not continue if fetching user progression data failed
    if ( event.isError ) then
        return
    end

    -- We're only interested in the currently logged in user's stats (ignore info from other users)
    if ( event.userSteamId ~= steamworks.userSteamId ) then
        return
    end

    -- Fetch a stat from the currently logged in user
    local params =
    {
        statName = "Games Played",
        type = "int",
    }
    local statValue = steamworks.getUserStatValue( params )

    -- If the value is "nil", this stat has not yet been set for this user
    -- This is typically the case for new players
    if ( statValue == nil ) then
        statValue = 0
    end

    -- Print the stat value to the log
    print( "Games Played: " .. tostring(statValue) )
end

-- Set up a listener to be invoked when achievement and stat data has been updated
steamworks.addEventListener( "userProgressUpdate", onUserProgressUpdated )