steamworks.requestLeaderboardEntries()

类型 函数
返回值 布尔值
修订版 发布 2024.3703
关键字 steam、steamworks、排行榜、requestLeaderboardEntries
另请参见 steamworks.requestLeaderboardInfo()
steamworks.requestSetHighScore()
排行榜条目
steamworks.*

概述

异步方式从一个排行榜中获取条目。

如果已成功向 Steam 发送请求，将返回 true。请注意这并不一定意味着请求的操作将取得成功。例如，如果没有网络连接，此函数将返回 true。因此，侦听器必须检查已收到的 event.isError 属性以确定请求的操作是否成功。

如果提供的参数无效，或 steamworks.isLoggedOn 属性为 false，将返回 false。

语法

steamworks.requestLeaderboardEntries( params )
参数 (必需)

表. 包含排行榜参数的表 — 有关详细信息，请参见下一部分。

参数参考

params 表可以包含以下内容

leaderboardName (必需)

字符串. 要从中获取条目的排行榜的唯一名称。在 Steamworks 网站上，这是在名称列下设置的排行榜字符串。

侦听器 (必需)

函数. 通过 leaderboardEntries 事件接收请求结果的函数。

startIndex (可选)

数字. 指定要从排行榜中获取的首个条目的可选整数值。如果设置该参数，还必须设置一个 endIndex 参数，否则此函数将失败并返回 false。请参见以下 playerScope 详细信息了解如何设置此索引。

endIndex (可选)

数字. 指定要从排行榜中获取的最后一个条目的可选整数值。如果设置该参数，则还必须设置一个 startIndex 参数，否则此函数将失败并返回 false。请参见以下 playerScope 详细信息了解如何设置此索引。

playerScope (必需)

字符串. 提供一种基于好友或附近玩家来筛选条目的可选参数

范围 描述
"Global" 如果不是另行指定，则为默认范围。startIndex 和 endIndex 参数是绝对1-based其中索引 1 引用排行榜上的人员（例如排名 1 上得分最高的玩家）。如果您未设置 startIndex 和 endIndex 参数，此函数将默认获取排行榜上前 25 分。
"GlobalAroundUser" startIndex 和 endIndex 参数是相对索引，其中索引 0 引用当前登录用户在排行榜上的条目。负索引引用排名/分数更高的条目，而正索引引用排名/分数低于该用户的条目。如果您未设置 startIndex 和 endIndex 参数，此函数将分别默认为 -12 和 12，它将获取用户排名更高的 12 个条目和排名更低的 12 个条目，当考虑用户的索引 0 时，则总共为 25 个条目。
"FriendsOnly" 将获取当前所有已登录用户的排行榜条目。将忽略 startIndex 和 endIndex 参数。

示例

local steamworks = require( "plugin.steamworks" )

local function onReceivedLeaderboradEntries( event )
    -- Do not continue if fetching of leaderboard entries failed
    if ( event.isError ) then
        print( "Failed to fetch leaderboard entries." )
        return
    end

    -- Print information about each leaderborad entry to the log
    for index = 1, #event.entries do
        -- Concatenate the player's rank
        local message = "Rank: " .. tostring(event.entries[index].globalRank)

        -- Concatenate the player's name
        message = message .. ", User: "
        local userInfo = steamworks.getUserInfo( event.entries[index].userSteamId )
        if ( userInfo ) then
            message = message .. userInfo.name
            if ( string.len( userInfo.nickname ) > 0 ) then
                message = message .. " (" .. userInfo.nickname .. ")"
            end
        else
            message = message .. event.entries[index].userSteamId
        end

        -- Concatenate the player's score
        message = message .. ", Score: " .. tostring(event.entries[index].score)

        -- Output the above concatenated message to the log
        print( message )
    end
end

-- Fetch leaderboard entries around the currently logged in user's entry
local requestParams =
{
    leaderboardName = "My Leaderboard",
    listener = onReceivedLeaderboradEntries,
    playerScope = "GlobalAroundUser",
    startIndex = -4,  -- Get 4 entries with higher score than user
    endIndex = 5      -- Get 5 entries with lower score than user
}
steamworks.requestLeaderboardEntries( requestParams )