社交服務 可以幫助在 Roblox 平台上建立的關係影響社交功能。其主要用途是向玩家顯示邀請提示和電話簿,讓他們通過PromptGameInvite()和PromptPhoneBook()分別向朋友發送邀請請求。當這些請求被提出時,您可以利用信號。
概要
方法
活動
當玩家的呼叫狀態變更時,發出火焰。
當玩家關閉邀請提示時發生火災。
當玩家關閉電話簿提示時發生火災。
回調
當從電話簿中呼叫時,呼叫回應。
屬性
方法
GetPlayersByPartyId
返回所有現在連接的 Player 對象的表,其 Player.PartyId 屬性與提供的 partyId 相匹配。這個方法與 Players:GetPlayers() 相似,但過濾結果只包含屬於指定派系的玩家。
請注意,此服務在 Roblox Studio 中無法在遊戲測試期間運作;若要使用它來測試您的體驗方面,您必須發布體驗並在 Roblox 應用程式中播放它。
參數
返回
一個包含 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.
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.
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() 來確定玩家是否可以發送邀請,因為此能力可能會根據平台或玩家而異。
請參閱玩家邀請提示了解更多關於實現邀請提示、自定義提示和通知以及使用發射數據的詳情。
參數
可選擇 ExperienceInviteOptions 對象來自定制提示。
返回
範例程式碼
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().
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 以獲得此方法的樣本實現。
參數
用於提示電話簿的玩家。
用於區分各種電話簿「入口點」或類似物之間的字串。例如,您可以傳送一個字串,定義呼叫玩家角色目前在哪個體驗區域。
返回
範例程式碼
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.
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
顯示呼叫玩家的自我視圖。如果這個方法在自我視圖已經可見時被呼叫,它不會做任何事情。
參數
放置自我視圖的位置。
返回
CanSendCallInviteAsync
如果指定的 Player 可以向朋友發送呼叫邀請,返回 true 。你應該總是在呼叫 PromptPhoneBook() 之前使用此方法的結果,因為開啟電話簿的能力可能會因玩家而異。
請參閱 Roblox Connect 以獲得此方法的樣本實現。
參數
返回
指定的玩家是否可以發送呼叫邀請。
範例程式碼
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.
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.UserId 潛在 接收人 ,用於檢查發送者是否可以邀請特定接收人。
返回
指定的玩家是否可以發送邀請。
範例程式碼
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().
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
GetEventRsvpStatusAsync
返回本地玩家的 RSVP 狀態,用於指定的事件。事件必須在當前體驗中,且不得已經開始。如果事件已經開始,這個方法將返回錯誤。
請注意,您可以使用 PromptRsvpToEventAsync() 來提示玩家更改他們對事件的 RSVP 狀態。
參數
事件的事件ID,可提示玩家更改其 RSVP 狀態。這必須是現有體驗中存在的有效事件 ID,以字串形式表示(不是數字)。
返回
返回 Enum.RsvpStatus 指示玩家目前對事件的 RSVP 狀態。如果玩家沒有對活動進行回應,這將返回 Enum.RsvpStatus.None。
範例程式碼
The following example checks if a player is RSVP'd to an event; if not, it gives them the option to RSVP. If the player is already RSVP'd, it gives them the option to cancel their RSVP.
The following Script assumes that RunContext is set to Enum.RunContext.Client and that two sibling ProximityPrompts are in place: one for following the event and one for unfollowing the event. The prompts are enabled or disabled based on the player's RSVP status.
local SocialService = game:GetService("SocialService")
local EVENT_ID = "YOUR_EVENT_ID"
local followPrompt : ProximityPrompt = script.Parent.FollowProximityPrompt
local unFollowPrompt : ProximityPrompt = script.Parent.UnfollowProximityPrompt
local function updatePrompt(rsvpStatus : Enum.RsvpStatus)
if rsvpStatus == Enum.RsvpStatus.Going then
unFollowPrompt.Enabled = true
followPrompt.Enabled = false
else
unFollowPrompt.Enabled = false
followPrompt.Enabled = true
end
end
local success, currentRsvpStatus = pcall(function()
return SocialService:GetEventRsvpStatusAsync(EVENT_ID)
end)
if not success then
-- Could not retrieve RSVP status; don't enable either proximity prompt
warn("Failed to get RSVP status:", currentRsvpStatus)
return
end
print("CurrentRsvpStatus:", currentRsvpStatus)
updatePrompt(currentRsvpStatus)
unFollowPrompt.Triggered:Connect(function(player)
local rsvpStatus = SocialService:PromptRsvpToEventAsync(EVENT_ID)
updatePrompt(rsvpStatus)
end)
followPrompt.Triggered:Connect(function(player)
local rsvpStatus = SocialService:PromptRsvpToEventAsync(EVENT_ID)
updatePrompt(rsvpStatus)
end)
GetPartyAsync
返回包含所有與給定 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 應用程式中播放它。
參數
返回
一個代表指定派對成員的字典陣列,目前正在體驗中。
範例程式碼
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.
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)
PromptRsvpToEventAsync
PromptRsvpToEventAsync() 顯示向本地玩家發出的提示,可以將他們的 RSVP 狀態變更為指定的事件。
事件必須在當前體驗中,且不得已經開始。如果事件已經開始,此方法將返回錯誤。
請注意,您可以使用 GetEventRsvpStatusAsync() 來檢查玩家的當前 RSVP 狀態,然後才能呼叫此方法。
參數
事件的事件ID,可提示玩家更改其 RSVP 狀態。這必須是現有體驗中存在的有效事件 ID,以字串形式表示(不是數字)。
返回
返回 Enum.RsvpStatus 指示玩家在提示關閉後的新 RSVP 狀態。如果玩家沒有更改他們的 RSVP 狀態而關閉提示,這會返回 Enum.RsvpStatus.None 或他們舊的 Enum.RsvpStatus 如果他們已經選擇了一個狀態。
範例程式碼
The following example checks if a player is RSVP'd to an event; if not, it gives them the option to RSVP. If the player is already RSVP'd, it gives them the option to cancel their RSVP.
The following Script assumes that RunContext is set to Enum.RunContext.Client and that two sibling ProximityPrompts are in place: one for following the event and one for unfollowing the event. The prompts are enabled or disabled based on the player's RSVP status.
local SocialService = game:GetService("SocialService")
local EVENT_ID = "YOUR_EVENT_ID"
local followPrompt : ProximityPrompt = script.Parent.FollowProximityPrompt
local unFollowPrompt : ProximityPrompt = script.Parent.UnfollowProximityPrompt
local function updatePrompt(rsvpStatus : Enum.RsvpStatus)
if rsvpStatus == Enum.RsvpStatus.Going then
unFollowPrompt.Enabled = true
followPrompt.Enabled = false
else
unFollowPrompt.Enabled = false
followPrompt.Enabled = true
end
end
local success, currentRsvpStatus = pcall(function()
return SocialService:GetEventRsvpStatusAsync(EVENT_ID)
end)
if not success then
-- Could not retrieve RSVP status; don't enable either proximity prompt
warn("Failed to get RSVP status:", currentRsvpStatus)
return
end
print("CurrentRsvpStatus:", currentRsvpStatus)
updatePrompt(currentRsvpStatus)
unFollowPrompt.Triggered:Connect(function(player)
local rsvpStatus = SocialService:PromptRsvpToEventAsync(EVENT_ID)
updatePrompt(rsvpStatus)
end)
followPrompt.Triggered:Connect(function(player)
local rsvpStatus = SocialService:PromptRsvpToEventAsync(EVENT_ID)
updatePrompt(rsvpStatus)
end)
活動
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
當玩家關閉邀請提示時,此事件會發生。
參數
回調
OnCallInviteInvoked
在電話簿中放置呼叫時處理的回呼。tag 參數可用於區分不同的「入口點」或類似物,如在 PromptPhoneBook() 中所述。只能設置一個回呼。
參數
返回
包括 PlaceId 和 ReservedServerAccessCode 鍵值為 DataModel.PlaceId 和由 TeleportService:ReserveServer() 返回的服務器存取代碼的表,分別為值。
範例程式碼
local SocialService = game:GetService("SocialService")
local TeleportService = game:GetService("TeleportService")
SocialService.OnCallInviteInvoked = function()
local placeId = 0123456789 -- This is the place ID of the desired place to drop call participants into
local accessCode = TeleportService:ReserveServer(placeId)
return { ReservedServerAccessCode = accessCode, PlaceId = placeId }
end