Type Function Return value Boolean Revision Release 2024.3703 Keywords steam, steamworks, leaderboard, requestSetHighScore See also steamworks.requestLeaderboardInfo() steamworks.requestLeaderboardEntries() setHighScore steamworks.*
Asynchronously sends a given score value to the specified leaderboard. The given score will only be accepted by the leaderboard if it is higher than the user’s previous score.
Returns true
if the request was successfully sent to Steam. Note that this does not necessarily mean that the requested operation will succeed. For example, this function will return true
if there is no Internet connection. So, the listener must check the received event.isError property to determine if the requested operation succeeded.
Returns false
if given invalid arguments or if the steamworks.isLoggedOn property is false
.
Internet access is required to set a high score on a leaderboard. Unlike achievements and stats, Steam will not cache high score updates while offline and resync the changes with the Steam server once Internet access becomes available again.
steamworks.requestSetHighScore( params )
Table. Table containing parameters — see the next section for details.
The params
table can contain the following:
String. The unique name of the leaderboard to send the high score to. On the Steamworks website, this is the leaderboard string set under the Name column.
Function. Function which will receive the result of the request via a setHighScore event.
Number. Integer value to be uploaded to the leaderboard as the new high score.
local steamworks = require( "plugin.steamworks" ) local function onReceivedSetHighScoreResult( event ) if ( event.isError ) then -- The request has failed -- Note that an error will not occur if the given score is less than the highest print( "Failed to access the leaderboard." ) else -- Print the result of this request to the log print( "Leaderboard Name: " .. event.leaderboardName ) print( "Was Score Changed: " .. tostring(event.scoreChanged) ) if ( event.scoreChanged ) then print( "Current Rank: " .. tostring(event.currentGlobalRank) ) print( "Previous Rank: " .. tostring(event.previousGlobalRank) ) end end end -- Attempt to set a new high score for the current user -- Requires an active Internet connection to succeed -- Provides the requested result to the given "listener" function local requestSettings = { leaderboardName = "My Leaderboard Name", value = 9000, listener = onReceivedSetHighScoreResult, } steamworks.requestSetHighScore( requestSettings )