FriendShipService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

好友服务用于在游戏内处理玩家之间的好友关系，既可以查询某个玩家与指定用户是否互为好友，也可以向指定用户发起加好友请求。查询能力以异步回调的形式返回结果，适合在玩法逻辑中实时判断好友状态。

适用场景

常用于需要依据好友关系改变玩法结果的场合，例如判断队友是否为好友并给予额外奖励，或在结算时引导玩家向对手发送加好友请求；也可以用于在开局前确认玩家之间的社交关系。

使用要点

先通过 game:GetService("FriendShipService") 获取服务实例，再调用 IsPlayerFriendsWithAsync，依次传入玩家对象、目标用户标识以及接收查询结果的回调函数，在回调中处理好友关系结果；需要建立好友关系时调用 AddFriendWith，传入玩家对象与目标用户标识即可发起请求。

注意事项

IsPlayerFriendsWithAsync 的结果通过回调异步返回；AddFriendWith 只发起好友请求，不提供完成回调，也不表示对方已同意。

代码示例

查询业务传入的目标用户

-- @runtime client
local FriendShipService = game:GetService('FriendShipService')
local Players = game:GetService('Players')

local function checkFriend(targetUserId)
    local player = Players.LocalPlayer
    if player == nil or targetUserId == nil or targetUserId == '' then return end
    FriendShipService:IsPlayerFriendsWithAsync(player, targetUserId, function(isFriend)
        print('是否为好友:', isFriend)
    end)
end

-- 调用方应把玩家列表或业务输入中的真实 UserId 传给 checkFriend

向业务传入的目标用户发起好友请求

-- @runtime client
local FriendShipService = game:GetService('FriendShipService')
local Players = game:GetService('Players')

local function addFriend(targetUserId)
    local player = Players.LocalPlayer
    if player == nil or targetUserId == nil or targetUserId == '' then return end
    FriendShipService:AddFriendWith(player, targetUserId)
end

-- 调用方应把玩家列表或业务输入中的真实 UserId 传给 addFriend

函数 (2)

IsPlayerFriendsWithAsync

签名：IsPlayerFriendsWithAsync(player: Player, userId: String, checkCallback: Function) -> void

异步查询指定玩家是否是指定UserId的好友

⚙ 参数 userId 是目标玩家的 UserId 字符串（不是 Player 对象）；第三个参数 checkCallback 是异步结果回调，回调签名为 function(isFriend: Bool)。结果不会通过返回值给出，必须在回调内处理。

参数	类型	说明
player	Player	指定玩家，必须在当前场景中
userId	String	目标玩家的UserId
checkCallback	Function	查询结果回调函数

返回值 void

示例代码

查询业务传入的目标用户

-- @runtime client
local FriendShipService = game:GetService('FriendShipService')
local Players = game:GetService('Players')

local function checkFriend(targetUserId)
    local player = Players.LocalPlayer
    if player == nil or targetUserId == nil or targetUserId == '' then return end
    FriendShipService:IsPlayerFriendsWithAsync(player, targetUserId, function(isFriend)
        print('是否为好友:', isFriend)
    end)
end

-- 调用方应把玩家列表或业务输入中的真实 UserId 传给 checkFriend

AddFriendWith

签名：AddFriendWith(player: Player, userId: String) -> void

向目标用户发起好友请求；调用成功不表示对方已经同意或双方已经成为好友。

参数	类型	说明
player	Player	指定玩家，必须在当前场景中
userId	String	目标玩家的UserId

返回值 void

示例代码

向业务传入的目标用户发起好友请求

-- @runtime client
local FriendShipService = game:GetService('FriendShipService')
local Players = game:GetService('Players')

local function addFriend(targetUserId)
    local player = Players.LocalPlayer
    if player == nil or targetUserId == nil or targetUserId == '' then return end
    FriendShipService:AddFriendWith(player, targetUserId)
end

-- 调用方应把玩家列表或业务输入中的真实 UserId 传给 addFriend