SocialService

方法

GetPlayersByPartyId(partyId : string):Instances
返回所有现在连接的 Player 对象的表，其 Player.PartyId 属性与传递的 partyId 匹配。
HideSelfView():()
隐藏调用玩家的自我视图。
PromptGameInvite(player : Instance,experienceInviteOptions : Instance):()
向给定的 Player 提示邀请屏幕。
PromptPhoneBook(player : Instance,tag : string):()
向给定的 Player 提示使用电话簿。
ShowSelfView(selfViewPosition : Enum.SelfViewPosition):()
显示调用玩家的自我视图。
CanSendCallInviteAsync(player : Instance):boolean
暂停
指示是否给出的 Player 可以邀请其他玩家进行调用。
CanSendGameInviteAsync(player : Instance,recipientId : number):boolean
暂停
指示是否给出的 Player 可以邀请其他玩家。
GetPartyAsync(partyId : string):Array
暂停
返回包含所有成员数据的一组词典的阵列，这些成员目前正在体验中。

活动

CallInviteStateChanged(player : Instance,inviteState : Enum.InviteState):RBXScriptSignal
当玩家的呼叫状态发生变化时，发出火焰。
GameInvitePromptClosed(player : Instance,recipientIds : Array):RBXScriptSignal
当玩家关闭邀请提示时发生火灾。
PhoneBookPromptClosed(player : Instance):RBXScriptSignal
当玩家关闭电话手册提示时发生火灾。

回调

OnCallInviteInvoked(tag : string,callParticipantIds : Array):Instance
当从电话列表中拨打电话时的回调。

属性

方法

GetPlayersByPartyId

Instances

返回所有现在连接的 Player 对象的表，其 Player.PartyId 属性与提供的 partyId 匹配。该方法与 Players:GetPlayers() 相似，但会将结果过滤以仅包含指定派对的玩家。

请注意，此服务在 Roblox Studio 中无法在游戏测试期间运行；要使用它测试体验的方面，您必须发布体验并在 Roblox 应用程序中播放它。

参数

partyId: string

默认值：""

Instances

一个包含 Player 对象的表，其 Player.PartyId 属性与传递的 partyId 匹配。

代码示例

The following example listens for when a player joins the experience. If the player is part of a party, it uses SocialService:GetPlayersByPartyId() to retrieve all players in the same party who are currently connected to the server. It then outputs the name of each party member.

SocialService:GetPlayersByPartyId()

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	local partyId = player.PartyId

	if partyId ~= "" then
		local partyPlayers: { Player } = SocialService:GetPlayersByPartyId(partyId)

		for _, partyMember in partyPlayers do
			print("Party Member: " .. partyMember.Name)
		end
	else
		warn("Player is not in a party")
	end
end)

This code sample demonstrates how to assign players to Teams based on their Player.PartyId using the SocialService:GetPlayersByPartyId() method. When a player joins the experience, the script checks whether they're part of a party. If so, it attempts to assign them to the same team as other party members. If no match is found or the player isn't in a party, they're placed on the team with fewer members to maintain balance.

Team Rebalance with Party Integration

local Teams = game:GetService("Teams")
local Players = game:GetService("Players")
local SocialService = game:GetService("SocialService")

local redTeam = Instance.new("Team")
redTeam.Name = "Red Team"
redTeam.TeamColor = BrickColor.Red()
redTeam.AutoAssignable = false
redTeam.Parent = Teams

local blueTeam = Instance.new("Team")
blueTeam.Name = "Blue Team"
blueTeam.TeamColor = BrickColor.Blue()
blueTeam.AutoAssignable = false
blueTeam.Parent = Teams

local function assignPlayerToTeam(player)
	local partyId = player.PartyId

	if partyId == "" then
		assignBalancedTeam(player)
		return
	end

	local teams = { redTeam, blueTeam }
	local matchingTeam = nil
	local partyPlayers = SocialService:GetPlayersByPartyId(partyId)

	for _, partyPlayer in partyPlayers do
		if partyPlayer ~= player and table.find(teams, partyPlayer.Team) then
			matchingTeam = partyPlayer.Team
			break
		end
	end

	if matchingTeam then
		player.Team = matchingTeam
		player.TeamColor = matchingTeam.TeamColor
	else
		assignBalancedTeam(player)
	end
end

function assignBalancedTeam(player)
	local redCount = #redTeam:GetPlayers()
	local blueCount = #blueTeam:GetPlayers()
	local chosenTeam = redCount <= blueCount and redTeam or blueTeam

	player.Team = chosenTeam
	player.TeamColor = chosenTeam.TeamColor
end

local function groupPlayersByParty()
	local seenPartyIds = {}
	local groupedPlayers = {}

	for _, player in Players:GetPlayers() do
		if player.PartyId == "" then
			table.insert(groupedPlayers, { player })
		elseif not table.find(seenPartyIds, player.PartyId) then
			table.insert(seenPartyIds, player.PartyId)

			local partyPlayers = SocialService:GetPlayersByPartyId(player.PartyId)
			table.insert(groupedPlayers, partyPlayers)
		end
	end

	return groupedPlayers
end

-- Call this function to rebalance teams
local function rebalanceTeams()
	local groups = groupPlayersByParty()

	table.sort(groups, function(a, b)
		return #a > #b
	end)

	for _, player in Players:GetPlayers() do
		player.Team = nil
	end

	for _, group in groups do
		local redCount = #redTeam:GetPlayers()
		local blueCount = #blueTeam:GetPlayers()

		local bestTeam
		if redCount <= blueCount then
			bestTeam = redTeam
		else
			bestTeam = blueTeam
		end

		for _, player in group do
			player.Team = bestTeam
			player.TeamColor = bestTeam.TeamColor
		end
	end

	for _, player in Players:GetPlayers() do
		player:LoadCharacter()
	end
end

Players.PlayerAdded:Connect(function(player)
	assignPlayerToTeam(player)

	player:LoadCharacter()

	player:GetPropertyChangedSignal("PartyId"):Connect(function()
		if player.PartyId ~= "" then
			assignPlayerToTeam(player)
		end
	end)
end)

HideSelfView

()

隐藏调用玩家的自我视图。如果此方法在自我视图已隐藏时调用，则不做任何操作。

()

PromptGameInvite

()

PromptGameInvite() 向本地玩家显示一个邀请提示，通过该提示他们可以邀请朋友加入当前体验。在调用此方法之前，您应该使用 CanSendGameInviteAsync() 来确定玩家是否可以发送邀请，因为此能力可能会根据平台或玩家而异。

请参阅玩家邀请提示了解更多关于实现邀请提示、自定义提示和通知以及使用发射数据的详细信息。

参数

player: Instance

The Player 以提示与邀请弹出窗口。

默认值：""

experienceInviteOptions: Instance

可选 ExperienceInviteOptions 对象用于自定义提示。

默认值："nil"

()

代码示例

The following code sample uses CanSendGameInviteAsync() to confirm whether the local Player can send an invite. If true, it then prompts the invite using PromptGameInvite().

Sending an Invite

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

local player = Players.LocalPlayer

-- Function to check whether the player can send an invite
local function canSendGameInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendGameInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canInvite = canSendGameInvite(player)
if canInvite then
	SocialService:PromptGameInvite(player)
end

PromptPhoneBook

()

向给定的 Player 提示使用电话簿。如果玩家选择呼叫某人，那么 CallInviteStateChanged 事件将触发。你应该在调用 PromptPhoneBook() 之前使用 CanSendCallInviteAsync() ，因为能够查看电话列表的能力可能会根据玩家而异。

如果玩家不符合打开电话列表的条件，将显示错误对话框。

请参阅Roblox Connect以获取此方法的示例实现。

参数

player: Instance

用于提示手机书的玩家。

默认值：""

tag: string

用于区分各种电话书“入口点”或类似内容的字符串。例如，您可以传递一个字符串，定义调用玩家角色当前所在的体验区域。

默认值：""

()

代码示例

The following code sample, placed within a child LocalScript of a GuiButton, uses CanSendCallInviteAsync() to confirm that the player can make a call. If so, it connects PromptPhoneBook() to the button's Activated event.

SocialService:PromptPhoneBook()

local Players = game:GetService("Players")
local SocialService = game:GetService("SocialService")

local player = Players.LocalPlayer
local button = script.Parent
button.Visible = false

-- Function to check whether the player can send a call invite
local function canSendCallingInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendCallInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canCall = canSendCallingInvite(player)
if canCall then
	button.Visible = true
	button.Activated:Connect(function()
		SocialService:PromptPhoneBook(player, "")
	end)
end

ShowSelfView

()

显示调用玩家的自我视图。如果此方法在自我视图已可见时调用，则不做任何操作。

参数

selfViewPosition: Enum.SelfViewPosition

放置自我视图的位置。

默认值："LastPosition"

()

CanSendCallInviteAsync

暂停

返回 true 如果给定的 Player 可以向朋友发送通话邀请。你总是应该在调用 PromptPhoneBook() 之前使用此方法的结果，因为打开电话手册的能力可能会根据玩家而异。

请参阅Roblox Connect以获取此方法的示例实现。

参数

player: Instance

玩家的 Player 实例可能发送呼叫邀请。

默认值：""

是否指定的玩家可以发送呼叫邀请。

代码示例

SocialService:PromptPhoneBook()

local Players = game:GetService("Players")
local SocialService = game:GetService("SocialService")

local player = Players.LocalPlayer
local button = script.Parent
button.Visible = false

-- Function to check whether the player can send a call invite
local function canSendCallingInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendCallInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canCall = canSendCallingInvite(player)
if canCall then
	button.Visible = true
	button.Activated:Connect(function()
		SocialService:PromptPhoneBook(player, "")
	end)
end

CanSendGameInviteAsync

暂停

CanSendGameInviteAsync() 返回 true 如果给定的 Player 可以邀请其他玩家进入当前体验。你总是应该在调用 PromptGameInvite() 之前使用此方法的结果，因为邀请玩家的能力可能会根据平台或玩家而异。

请参阅玩家邀请提示获取更多关于实现玩家邀请提示、自定义提示和通知以及使用发射数据的详细信息。

参数

player: Instance

玩家的 Player 实例可能发送邀请。

默认值：""

recipientId: number

可选的潜在接收人 ,用于检查发送者是否可以邀请该特定接收人。

默认值：0

指定的玩家是否可以发送邀请。

代码示例

The following code sample uses CanSendGameInviteAsync() to confirm whether the local Player can send an invite. If true, it then prompts the invite using PromptGameInvite().

Sending an Invite

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

local player = Players.LocalPlayer

-- Function to check whether the player can send an invite
local function canSendGameInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendGameInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canInvite = canSendGameInvite(player)
if canInvite then
	SocialService:PromptGameInvite(player)
end

GetPartyAsync

Array

暂停

返回包含所有与给定 partyId 相关的成员的数据的词典阵列。返回的阵列反映了体验中所有活跃服务器实例内的派对状态，并按派对成员接受派对邀请的时间排序。这意味着阵列中的第一个元素是最早接受的，最后一个是最新的。

该方法对于获取目前体验中和不同服务器上所有派对成员的最新信息有用，可启用协调的群组行为，例如传送、匹配或派对基于游戏逻辑的游戏。

返回的阵列中的每个词典包含以下字段：


<th>价值类型</th>

    <th>描述</th>
  </tr>
</thead>

<tbody>
  <tr>
    <th><code>用户ID</code></th>

    <td>数字</td>

    <td>玩家的 <code>Class.Player.UserId</code> 属性。</td>
  </tr>

  <tr>
    <th><code>地点ID</code></th>

    <td>数字</td>

    <td>派对成员目前所在的地方的 <code>Class.DataModel.PlaceId</code>。</td>
  </tr>

  <tr>
    <th><code>工作ID</code></th>

    <td>字符串</td>

    <td>服务器实例中用户目前居住的 <code>Class.DataModel.JobId</code>。</td>
  </tr>

  <tr>
    <th><code>私有服务器ID</code></th>

    <td>字符串</td>

    <td>如果适用，当派对成员在私人或保留服务器上时，<code>Class.DataModel.PrivateServerId</code>。</td>
  </tr>

  <tr>
    <th><code>保留服务器访问代码</code></th>

    <td>字符串</td>

    <td>如果适用，用户当前所在的保留服务器的访问代码。有用于将派对成员传送到对方使用 <code>Class.TeleportService:TeleportAsync()</code> 。</td>
  </tr>
</tbody>

关键

请注意，此服务在 Roblox Studio 中无法在游戏测试期间运行；要使用它测试体验的方面，您必须发布体验并在 Roblox 应用程序中播放它。

参数

partyId: string

默认值：""

Array

一个集合典词，代表指定派对的成员，目前正在体验中。

代码示例

The following example checks if a player is in a party when they join. If so, it retrieves the latest party data using SocialService:GetPartyAsync() and outputs the details of each party member.

SocialService:GetPartyAsync()

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	local partyId = player.PartyId

	if partyId == "" then
		warn("Player is not in a party")
		return
	end

	local success, partyData = pcall(function()
		return SocialService:GetPartyAsync(partyId)
	end)

	if success and partyData then
		for _, partyMemberData in partyData do
			print(
				partyMemberData.UserId,
				partyMemberData.PlaceId,
				partyMemberData.JobId,
				partyMemberData.PrivateServerId,
				partyMemberData.ReservedServerAccessCode
			)
		end
	else
		warn("Failed to retrieve party data")
	end
end)

活动

CallInviteStateChanged

当玩家的呼叫邀请状态发生变化时，此事件发生。

参数

player: Instance

具有调用邀请状态变更的玩家的 Player 实例。

inviteState: Enum.InviteState

新的呼叫邀请状态。

代码示例

SocialService.CallInviteStateChanged

local SocialService = game:GetService("SocialService")

local button = script.Parent
local isPhonebookOpen = false

SocialService.CallInviteStateChanged:Connect(function(_, inviteState)
	local isCalling = inviteState == Enum.InviteState.Placed

	if isCalling or isPhonebookOpen then
		button.Visible = false
	else
		button.Visible = true
	end
end)

GameInvitePromptClosed

当玩家关闭邀请提示时，此事件发生。

参数

player: Instance

关闭提示的玩家的 Player 实例。

recipientIds: Array

不再填充；一个空阵列。

PhoneBookPromptClosed

当玩家关闭电话手册提示时发生火灾。

参数

player: Instance

关闭电话手册的玩家的 Player 实例。