工坊手册

主题

SocialService ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • [SocialService]（3 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

社交服务，集中提供队伍信息查询与地图点赞面板弹出两类能力。它既支持按队伍标识异步读取队伍详情，也能同步取回同一队伍的玩家列表，还可主动通知指定玩家客户端弹出地图点赞面板。

适用场景 ​

在服务端按真实队伍标识查询队伍信息与当前 Space 内的在线队友；也可调用 ShowMapLikePanel，在客户端显示点赞面板或由服务端请求目标玩家客户端显示。

使用要点 ​

队伍查询在服务端取得 SocialService。先从 Player:GetPartyId() 或可信业务流程取得 partyId；在协程中调用 GetPartyAsync 查询完整队伍信息，或同步调用 GetPlayersByPartyId 查询当前 Space 内的在线队友。查询前检查队伍标识，结果为空时作分支处理。ShowMapLikePanel 接收目标 Player：客户端调用时弹出点赞界面，服务端调用时下发给目标玩家客户端执行。

注意事项 ​

GetPartyAsync 是异步方法，必须在协程中调用；GetPlayersByPartyId 是同步方法。两者都依赖真实 Player:GetPartyId() 返回或由可信业务流程传入的 partyId（String），不要使用伪造的固定队伍 ID。GetPartyAsync 的成员信息可能含预留服务器访问凭据，只按业务需要使用，禁止写入日志或对客户端公开。ShowMapLikePanel 的界面显示在客户端；本页示例由服务端向目标玩家发出请求。

代码示例 ​

查询在线玩家所在队伍 ​

lua
-- @runtime server
local SocialService = game:GetService('SocialService')
local Players = game:GetService('Players')
local Task = game:GetService('Task')
local player = Players:GetPlayers()[1]
if player == nil then return end
local partyId = player:GetPartyId()
if partyId == nil or partyId == '' then
    print('当前玩家未加入队伍')
    return
end

local partyPlayers = SocialService:GetPlayersByPartyId(partyId)
if partyPlayers ~= nil then
    for _, partyPlayer in ipairs(partyPlayers) do
        print('当前 Space 内的队友:', partyPlayer:GetName())
    end
end
Task:Spawn(function()
    local partyInfo = SocialService:GetPartyAsync(partyId)
    if partyInfo == nil then return end
    print('队伍信息查询完成')  -- 不输出返回表中的访问凭据
end)

关联类型 ​

函数 (3) ​

GetPartyAsync ​

签名：GetPartyAsync(partyId: String) -> Table | nil (队伍成员信息字典 { [UserId] = { mmo_map_id, server_instance_id, reserved_server_access_code } })

异步获取指定队伍的成员传送信息，返回一个字典，键为玩家 UserId，值为包含地图 ID、服务器实例 ID 和预留服务器访问码的表格。

参数类型说明
partyIdString队伍 Id

返回值 Table | nil (队伍成员信息字典 { [UserId] = { mmo_map_id, server_instance_id, reserved_server_access_code } })

示例代码

协程中查询队伍信息

lua
-- @runtime server
local SocialService = game:GetService('SocialService')
local Players = game:GetService('Players')
local Task = game:GetService('Task')
Task:Spawn(function()
    local player = Players:GetPlayers()[1]
    if player == nil then return end
    local partyId = player:GetPartyId()
    if partyId == nil or partyId == '' then
        print('当前玩家未加入队伍')
        return
    end
    local partyInfo = SocialService:GetPartyAsync(partyId)
    if partyInfo == nil then return end
    print('队伍信息查询完成')  -- 不输出返回表中的访问凭据
end)

GetPlayersByPartyId ​

签名：GetPlayersByPartyId(partyId: String) -> Array<Player> | nil (同队伍的在线玩家列表)

按队伍 ID 查询当前 Space 内该队伍的在线玩家列表，返回元素类型为 Player 的数组；接收一个字符串类型的 partyId 参数。该函数标题标注为仅服务端可用。若查询不到对应队伍或没有在线队员，返回值为空（nullable）。

参数类型说明
partyIdString队伍 Id

返回值 Array<Player> | nil (同队伍的在线玩家列表)

示例代码

查询在线玩家的当前队友

lua
-- @runtime server
local SocialService = game:GetService('SocialService')
local player = game:GetService('Players'):GetPlayers()[1]
if player == nil then return end
local partyId = player:GetPartyId()
if partyId == nil or partyId == '' then return end
local partyPlayers = SocialService:GetPlayersByPartyId(partyId)
if partyPlayers == nil then return end
for _, partyPlayer in ipairs(partyPlayers) do
    print('当前 Space 内的队友:', partyPlayer:GetName())
end

ShowMapLikePanel ​

签名：ShowMapLikePanel(player: Player) -> void

客户端调用时弹出点赞界面；服务端调用时下发给目标玩家客户端执行。参数 player 为目标 Player，无返回值。

参数类型说明
playerPlayer目标玩家

返回值 void

示例代码

服务端请求目标玩家客户端显示点赞面板

lua
-- @runtime server
local SocialService = game:GetService('SocialService')
local Players = game:GetService('Players')
local targetPlayer = Players:GetPlayers()[1]
if targetPlayer == nil then return end
-- 服务端发起请求，点赞面板在目标玩家的客户端显示
SocialService:ShowMapLikePanel(targetPlayer)