gameNetwork.request()

类型函数

库 gameNetwork.*

返回值 无

修订版 发行 2024.3703

关键词 gameNetwork、游戏中心

另请参阅 gameNetwork.init()

gameNetwork.show()

概述

发送或请求信息，操作对象为游戏中心。

语法

gameNetwork.request( command [, params] )

command _^(必需)

字符串. Game Center 支持的字符串值 — 参见下方的命令参考。

params _^(可选)

表. Game Center 允许的参数表 — 参见下方的参数参考。

命令参考

对于 command 参数，Game Center 支持以下值

"setHighScore"
"loadScores"
"loadLocalPlayer"
"loadPlayers"
"loadFriends"
"loadAchievements"
"unlockAchievement"
"resetAchievements"
"loadAchievementDescriptions"
"loadFriendRequestMaxNumberOfRecipients"
"loadLeaderboardCategories"
"loadPlayerPhoto"
"loadAchievementImage"
"loadPlaceholderCompletedAchievementImage"
"loadIncompleteAchievementImage"
"loadCurrentPlayer"
"createMatch"
"quitMatch"
"endMatch"
"removeMatch"
"setEventListener"
"loadMatchData"
"endTurn"
"loadMatches"
"loadTurnBasedMatchMaxNumberOfParticipants"

参数参考

根据指定的 command 参数，params 表的内容会有所不同。

侦听器函数

对于所有对 gameNetwork.request() 的调用，params 表支持带有回调监听器函数（值）的 listener 键，以监视调用结果。在回调监听器中，event.type 表示已执行的请求，以及每个请求类型特有的其他数据，如下所示。

local function requestCallback( event )

    if ( event.type == "setHighScore" ) then
        -- High score has been set
    end
end

gameNetwork.request( "setHighScore",
    {
        localPlayerScore = { category="com.appledts.EasyTapList", value=25 },
        listener = requestCallback
    }
)

设定最高分

对于 command 为 "setHighScore" 的参数，此函数为当前已登录用户设置特定排行榜 (category) 的最高分。如果最高分不高于服务器上的现有最高分，服务器将保留最高值。

gameNetwork.request( "setHighScore",
    {
        localPlayerScore = { category="com.appledts.EasyTapList", value=25 },
        listener = requestCallback
    }
)

在 params 表中，localPlayerScore 是一个必需表，在其中应用以下键值对

category — 匹配您想要登记分数的排行榜 ID 的字符串，如在 iTunes Connect 中配置。
value — 表示分数的数字。请注意，Apple 允许64 位整数，但在 Lua 中所有数字的类型都是 double。这意味着您允许的最大值和最小值受 double 范围的限制，约为 2^51，而不是 2^64。

加载分数

对于 command 为 "loadScores" 的参数，此函数根据各种筛选条件检索分数。

gameNetwork.request( "loadScores",
    {
        leaderboard =
        {
            category = "com.appledts.EasyTapList",
            playerScope = "Global",  -- "Global" or "FriendsOnly"
            timeScope = "AllTime",   -- "AllTime", "Week", or "Today"
            range = { 1,5 }
        },
        listener = requestCallback
    }
)

在 params 表中，leaderboard 是一个必需表，其中包括以下内容键值对

category — 必需字符串，与要在 iTunes Connect 中配置的そこから要获取分数的排行榜的 ID 相符。
playerScope — 可选字符串，其中可以是 "Global" 或 "FriendsOnly"。后者设置会将获取的分数仅限制为好友。
timeScope — 可选字符串，其中可以是 "AllTime"、"Week" 或 "Today"，这会将获取的分数限制在指定的时间范围内。
range - 可选的两个整数值的数组。第一个值是开始索引，第二个值是要检索的玩家数（少于 100）。默认范围是 { 1,25 }。

在处理 "loadScores" 调用时，回调监听器中的 event.data 是一个项目（表）数组，其中的每一项都包含以下属性

playerID (string)
category (string)
value (number)
context (number)
date (string)
formattedValue (string)
rank (integer)
shouldSetDefaultLeaderboard (boolean)
unixTime (integer)

event.data[1].playerID  -- ID of the first player in the request
event.data[3].rank      -- Rank of the third player in the request

此外，event.localPlayerScore 表可供已登录玩家访问。这包含上面显示的所有属性。

event.localPlayerScore.playerID
event.localPlayerScore.rank

加载本地玩家

对于 "loadLocalPlayer" 的 command 参数，此函数请求当前的数据已登录玩家。

gameNetwork.request( "loadLocalPlayer", { listener=requestCallback } )

在处理 "loadLocalPlayer" 调用时，回调监听器中的 event.data 包含以下属性

playerID (string)
alias (string)
isFriend (boolean)
isAuthenticated (boolean)
isUnderage (boolean)
friends (array) — 表示本地玩家朋友的玩家 ID (strings) 数组。

event.data.playerID
event.data.alias

加载玩家

对于 "loadPlayers" 的 command 参数，此函数会根据玩家 ID 请求玩家列表的数据。

gameNetwork.request( "loadPlayers",
    {
        playerIDs =
        {
            "G:123456789",
            "G:1234567890",
            "G:0123456789"
        },
        listener = requestCallback
    }
)

在 params 表中，playerIDs 是一个必需表，包含一个逗号分隔的要获取数据的玩家 ID (strings) 列表。

在处理 "loadPlayers" 调用时，回调监听器中的 event.data 是一个项目（表）数组，与每个请求的玩家相对应。每个表包含以下属性

playerID (string)
alias (string)
isFriend (boolean)

event.data[1].playerID  -- ID of the first player in the request
event.data[3].alias     -- Alias of the third player in the request

加载好友

对于 "loadFriends" 的 command 参数，此函数请求当前玩家的好友已登录玩家。

gameNetwork.request( "loadFriends", { listener=requestCallback } )

在处理 "loadFriends" 调用时，回调监听器中的 event.data 是一个项目（表）数组，与每个好友相对应。

event.data[2].playerID

加载成就

对于 "loadAchievements" 的 command 参数，此函数会加载玩家完成的成就列表。

gameNetwork.request( "loadAchievements", { listener=requestCallback } )

在处理 "loadAchievements" 调用时，回调监听器中的 event.data 是一个项目（表）数组，表示每个成就。每个表包含以下属性

identifier (string)
percentComplete (number)
isCompleted (boolean)
isHidden (boolean)
lastReportedDate (string)
showsCompletionBanner (boolean)

event.data[4].identifier       -- Identifier for the fourth achievement
event.data[2].percentComplete  -- Completed percentage for the second achievement

解锁成就

对于 "unlockAchievement" 的 command 参数，此函数会解锁/设置指定的成就（identifier），完成度为指定百分比。showsCompletionBanner 仅在成就 100% 完成时才生效。

gameNetwork.request( "unlockAchievement",
    {
        achievement =
        {
            identifier = "com.appletest.one_tap",
            percentComplete = 100,
            showsCompletionBanner = true
        },
        listener = requestCallback
    }
)

在 params 表内，achievement 是必需表，在其内部：键值对

identifier — 匹配您要解锁或报告的结果的成就名称的必需字符串，如在 iTunes Connect 中输入的（这里所示不需要遵循完全限定的反向域样式）。
percentComplete — 表示成就完成百分比的可选数字。将此值设为 100 将完全解锁成就。如果省略此字段，则认为此值为 100。
showsCompletionBanner — 如果设为 true，则为可选的布尔值，将导致 Apple 在 percentComplete 达到 100 时自动显示完成横幅。

在处理 "unlockAchievement" 调用的结果时，event.data 是响应您刚刚解锁的成就的表。您可以使用此信息来帮助识别哪些成就已成功报告给游戏中心服务器，而哪些成就可能由于网络超时而失败。

重置成就

对于 "resetAchievements" 的 command 参数，此函数重置当前已登录玩家的所有成就。谨慎使用，因为无法撤消此请求 — 一旦调用，玩家的所有成就都将为该应用程序重置为 0%。

gameNetwork.request( "resetAchievements", { listener=requestCallback } )

加载成就说明

对于 "loadAchievementDescriptions" 的 command 参数，此函数请求与应用程序成就相关的所有描述的列表。

gameNetwork.request( "loadAchievementDescriptions", { listener=requestCallback } )

在处理 "loadAchievementDescriptions" 调用的结果时，event.data 是指示当前项（表）数组已登录玩家的成就。

identifier (string)
title (字符串)
achievedDescription (字符串)
unachievedDescription (字符串)
maximumPoints (整数)
isHidden (boolean)

加载添加好友请求的最大收件人数

对于 "loadFriendRequestMaxNumberOfRecipients" 的 command 参数，此函数检索单个好友邀请中可以邀请的最大人数。值通过回调侦听器通过 event.data 返回。

gameNetwork.request( "loadFriendRequestMaxNumberOfRecipients", { listener=requestCallback } )

加载排行榜类别

对于 "loadLeaderboardCategories" 的 command 参数，此函数请求应用程序的排行榜类别的列表。

gameNetwork.request( "loadLeaderboardCategories", { listener=requestCallback } )

在处理 "loadLeaderboardCategories" 调用的结果时，event.data 是项（表）数组。每个都包含以下排行榜属性

category (string)
title (字符串)

event.data[1].category  --> "com.appledts.EasyTapList"
event.data[1].title     --> "Easy"

加载玩家照片

对于 "loadPlayerPhoto" 的 command 参数，此函数检索请求的玩家的图像并为此创建一个显示对象。

gameNetwork.request( "loadPlayerPhoto",
    {
        playerID = "G:0123456789",
        size = "Small",  -- "Small" or "Normal"
        listener = requestCallback
    }
)

在 params 表中，以下键值对

playerID — 要获取图像的 Game Center 玩家 ID (字符串)。
size — 表示要获取的图像大小的可选值。支持的值是 "Small"（默认）或 "Normal"。

在处理 "loadPlayerPhoto" 调用的结果时，event.data 是包含下面列出的属性的表。请注意，额外的 photo 属性是由成功请求创建的显示对象。

playerID (string)
alias (string)
isFriend (boolean)
isAuthenticated (boolean)
isUnderage (boolean)
friends (数组)
photo (显示对象)

加载成就图片

对于 "loadAchievementImage" 的 command 参数，此函数检索请求的成就的图像并为此创建一个显示对象。

gameNetwork.request( "loadAchievementImage",
    {
        achievementDescription =
        {
            identifier = "com.appledts.twenty_taps"
        },
        listener = requestCallback
    }
)

在 params 表中，achievementDescription 是必需表，在其内部：键值对

identifier — 与要检索其图像的成就名称相匹配的必需字符串（这里所示不需要遵循完全限定的反向域样式）。

在处理“loadAchievementImage”调用的结果时，“event.data”是一个包含下面列出的属性的表。请注意，成功的请求创建的显示对象就是附加的“image”属性。

identifier (string)
title (字符串)
achievedDescription (字符串)
unachievedDescription (字符串)
maximumPoints (整数)
isHidden (boolean)
image（显示对象）

注意

上传到 iTunes Connect 的成就图像应与 Corona 完全兼容（参见对于 display.newImage() 的图像指南）。

加载已完成成就占位符图片

对于“loadPlaceholderCompletedAchievementImage”的“command”参数，此函数检索完成成就的 Apple 占位符图像，并创建一个显示对象用于该图像，可通过回调侦听器中的“event.data”访问。

gameNetwork.request( "loadPlaceholderCompletedAchievementImage", { listener=requestCallback } )

加载未完成成就图片

对于“loadIncompleteAchievementImage”的“command”参数，此函数检索未完成成就的 Apple 占位符图像，并创建一个显示对象用于该图像，可通过回调侦听器中的“event.data”访问。

gameNetwork.request( "loadIncompleteAchievementImage", { listener=requestCallback } )

加载当前玩家

对于“loadCurrentPlayer”的“command”参数，此函数检索在竞赛中预定进行其/她的轮次的当前玩家。

gameNetwork.request( "loadCurrentPlayer",
    {
        matchID = "w4o98y3498hg349h",
        listener = requestCallback
    }
)

在 params 表中，以下键值对

matchID — 要从中提取当前参与者的竞赛的竞赛 ID（字符串）。

在处理“loadCurrentPlayer”调用的结果时，回调侦听器中的“event.data”包括参与者对象。

创建比赛

对于“createMatch”的“command”参数，此函数创建具有指定玩家的回合制竞赛，与gameNetwork.show( "createMatch", ... )（参考）不同，这仅仅创建一个match对象并允许您展示自定义用户界面。

注意此调用得假定当前已登录玩家将在竞赛中。因此，不应该在“playerIDs”表中包含当前玩家的 ID。另外，确保“maxPlayers”已设置为同时兼顾请求的玩家数和当前玩家的值。例如，如果您在“playerIDs”表中使用两名玩家请求竞赛，“maxPlayers”则应设置为“3”或更高。

gameNetwork.request( "createMatch",
    {
        playerIDs = { "w4o98y3498hg349h", "wrighfq547hg543" },
        minPlayers = 2,
        maxPlayers = 3,
        playerGroup = 1,
        playerAttributes = { 1, 4, 6 },
        inviteMessage = "Hi, please join our match!",
        listener = requestCallback
    }
)

playerIDs — 邀请参加竞赛的人员的玩家 ID 表示的字符串的可选数组。
minPlayers — 竞赛中所需最少玩家数的可选值。
maxPlayers — 竞赛中允许的最大玩家数的可选值。
playerGroup — 将要创建的游戏类型，例如快速游戏或长时间游戏。只有其请求共享相同“playerGroup”值的玩家自动匹配到 Game Center 中。
playerAttributes — 指定本地玩家希望在游戏中扮演什么角色的面具。
inviteMessage — 竞赛的自定义邀请消息。

在处理“createMatch”调用的结果时，回调侦听器中的“event.data”包括match对象。

退出比赛

对于“quitMatch”的“command”参数，此函数从指定竞赛中移除当前已登录玩家，并对其/她的竞赛结果进行设置。

gameNetwork.request( "quitMatch",
    {
        matchID = "adsfawerg4",
        outcome = "lost",
        data = "dsfa4wt4t",
        nextParticipant = { "34tgergae5rtg5" },
        listener = requestCallback
    }
)

matchID — 识别玩家将要退出的竞赛的字符串。
outcome — 退出玩家的竞赛结果。
data — 下一名玩家的竞赛数据。这仅在是本地玩家轮次时才需要。
nextParticipant — 预订进行轮次的下一名玩家，包含在数组中。这可以是玩家 ID，也可以是参与者的索引值。这仅在是本地玩家轮次时才需要。

结束比赛

对于“endMatch”的“command”参数，此函数结束竞赛并将结果设置为所有玩家。

gameNetwork.request( "endMatch",
    {
        matchID = "adsfawerg4",
        outcome =
        {
            ["G:0123456789"] = "first",
            ["G:1234567890"] = "second",
            ["G:9876543210"] = "third"
        },
        data = "dsfa4wt4t",
        listener = requestCallback
    }
)

在 params 表中，以下内容键值对

matchID — 字符串，用于识别要结束的匹配。
outcome — 必填数组，其中包含玩家 ID 及每个玩家的匹配结果。
data — 匹配的最终数据。

移除比赛

对于 "removeMatch" 的 command 参数，此函数从游戏中心匹配列表中移除匹配。这只能在执行gameNetwork.request( "endMatch", ... )之后调用。在 params 表中，matchID 是一个用于识别要移除匹配的字符串。

gameNetwork.request( "removeMatch",
    {
        matchID = "adsfawerg4",
        listener = requestCallback
    }
)

设置比赛事件侦听器

对于 "setEventListener" 的 command 参数，此函数为所有匹配设置事件侦听器。

gameNetwork.request( "setEventListener", { listener=requestCallback } )

注意

设置此侦听器非常重要，以便应用可以相应地对参与匹配的其他玩家做出响应。例如，如果针对当前玩家调用 "endTurn" 请求，"playerTurn" 事件将被分发到队列中的下一位玩家。

在处理 "setEventListener" 调用的结果时，回调侦听器中的 event.type 将是以下内容之一

"invitationReceived" — 当玩家收到加入匹配的邀请时的值。
"matchEnded" — 当另一玩家调用gameNetwork.request( "endMatch", ... )，对所有玩家结束匹配时的值。
"playerTurn" — 当当前玩家在匹配中轮到时，紧随针对前一位玩家的 gameNetwork.request( "endTurn", ... )调用的值。

反过来，回调侦听器中的 event.data 将根据 event.type 的值而有所不同

当 event.type 为 "invitationReceived" 时，event.data 是一个字符串数组，表示被邀请参加匹配的所有玩家的 ID。
当 event.type 为 "matchEnded" 或 "playerTurn" 时，event.data 包含 match 对象。

加载比赛数据

对于 "loadMatchData" 的 command 参数，此函数会检索匹配的数据。在 params 表中，matchID 是一个字符串，用于识别要检索数据的匹配。

gameNetwork.request( "loadMatchData",
    {
        matchID = "adsfawerg4",
        listener = requestCallback
    }
)

在处理 "loadMatchData" 调用的结果时，回调侦听器中的 event.data 包括 match 对象，前提是该匹配已建立。

结束回合

对于 "endTurn" 的 command 参数，此函数会结束当前玩家的回合，然后让下一位玩家开始他们自己的回合。

gameNetwork.request( "endTurn",
    {
        matchID = "adsfawerg4",
        data = "dsfa4wt4t",
        nextParticipant = { "34tgergae5rtg5" },
        listener = requestCallback
    }
)