SocialService

Mostrar obsoleto

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

Não criável
Serviço
Não replicado

Serviço Social facilita funções sociais que impactam relacionamentos feitos na plataforma Roblox.Seu uso principal é mostrar prompts de convite e o diretório telefônico aos jogadores, permitindo que eles enviem solicitações de convite a seus amigos através de PromptGameInvite() e PromptPhoneBook().Você pode aproveitar sinais quando tais solicitações forem feitas.

Resumo

Métodos

Eventos

Callbacks

Propriedades

Métodos

GetPlayersByPartyId

Instances

Retorna uma tabela de todos os objetos conectados atualmente Player que possuem a propriedade Player.PartyId que correspondem à fornecida partyId.Este método se comporta de forma semelhante a Players:GetPlayers() , mas filtra os resultados para incluir apenas os jogadores pertencentes à parte especificada.

Observe que este serviço não funciona durante o teste de jogo no Roblox Studio; para testar aspectos de sua experiência usando-o, você deve publicar a experiência e jogá-la no aplicativo Roblox.

Parâmetros

partyId: string
Valor Padrão: ""

Devolução

Instances

Uma tabela de Player objetos cuja propriedade Player.PartyId corresponda ao partyId passado.

Amostras de código

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

()

Esconde a visão do jogador chamado de si mesmo. Se este método for chamado enquanto a visão de si mesmo já está oculta, ele não faz nada.


Devolução

()

PromptGameInvite

()

PromptGameInvite() exibe um prompt de convite para o jogador local através do qual eles podem convidar seus amigos para a experiência atual.Antes de chamar este método, você deve usar CanSendGameInviteAsync() para determinar se o jogador pode enviar um convite, pois essa capacidade pode variar dependendo da plataforma ou do jogador.

Veja Convites de Jogador para mais detalhes sobre a implementação de convites, personalização de convites e notificações e uso de dados de lançamento.

Parâmetros

player: Instance

O Player para solicitar com a janela de convite.

Valor Padrão: ""
experienceInviteOptions: Instance

Objeto opcional ExperienceInviteOptions para personalizar o prompt.

Valor Padrão: "nil"

Devolução

()

Amostras de código

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

()

Solicita ao dado Player com o livro de telefones.Se o jogador escolher chamar alguém, o evento CallInviteStateChanged é acionado.Você deve usar CanSendCallInviteAsync() antes de chamar PromptPhoneBook() pois a capacidade de ver o diretório telefônico pode variar dependendo do jogador.

Se um jogador não for elegível para abrir o diretório telefônico, um diálogo de erro é exibido.

Veja Roblox Connect para uma implementação de amostra deste método.

Parâmetros

player: Instance

O jogador para solicitar com o diretório telefônico.

Valor Padrão: ""
tag: string

Texto para ajudar a diferenciar entre vários " pontos de entrada " do diretório telefônico ou similares.Por exemplo, você pode passar uma string que define em qual região de uma experiência o personagem do chamador está atualmente.

Valor Padrão: ""

Devolução

()

Amostras de código

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

()

Mostra a visão do jogador chamado de si mesmo. Se este método for chamado enquanto a visão de si mesmo já é visível, ele não faz nada.

Parâmetros

selfViewPosition: Enum.SelfViewPosition

A posição para colocar a visão de si mesmo.

Valor Padrão: "LastPosition"

Devolução

()

CanSendCallInviteAsync

Rendimentos

Retorna true se o dado Player puder enviar um convite de chamada a um amigo.Você deve sempre usar o resultado deste método antes de chamar PromptPhoneBook() pois a capacidade de abrir o diretório telefônico pode variar dependendo do jogador.

Veja Roblox Connect para uma implementação de amostra deste método.

Parâmetros

player: Instance

A instância Player do jogador potencialmente enviando um convite de chamada.

Valor Padrão: ""

Devolução

Se o jogador especificado pode enviar um convite de chamada.

Amostras de código

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

CanSendGameInviteAsync

Rendimentos

CanSendGameInviteAsync() retorna true se o dado Player puder convidar outros jogadores para a experiência atual.Você deve sempre usar o resultado deste método antes de chamar PromptGameInvite() pois a capacidade de convidar jogadores pode variar dependendo da plataforma ou do jogador.

Veja Convites de Jogador para mais detalhes sobre a implementação de convites de jogador, personalização de prompts e notificações e uso de dados de lançamento.

Parâmetros

player: Instance

A instância Player do jogador potencialmente enviando um convite.

Valor Padrão: ""
recipientId: number

Opcional Player.UserId do potencial receptor , usado para verificar se o remetente pode convidar esse receptor específico.

Valor Padrão: 0

Devolução

Se o jogador especificado pode enviar um convite.

Amostras de código

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

GetEventRsvpStatusAsync

Rendimentos

Retorna o status de RSVP do jogador local para o evento dado.Eventos devem estar na experiência atual e não devem ter já começado.Se o evento já tiver começado, este método retornará um erro.

Observe que você pode usar PromptRsvpToEventAsync() para solicitar ao jogador que altere seu status de RSVP para o evento.

Parâmetros

eventId: string

O ID do evento do evento para solicitar que o jogador mude seu status de RSVP.Este deve ser um ID de evento válido que existe na experiência atual, representado como uma string (não um número).

Valor Padrão: ""

Devolução

Retorna um Enum.RsvpStatus indicando o status atual de RSVP do jogador para o evento.Se o jogador não tiver respondido ao evento, isso retornará Enum.RsvpStatus.None .

Amostras de código

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.

SocialService:PromptRsvpToEventAsync()

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

Rendimentos

Retorna um conjunto de dicionários que contêm dados para todos os membros associados ao dado partyId.O array retornado reflete o estado atual da equipe em todas as instâncias ativas do servidor dentro da experiência e é ordenado pela hora em que cada membro da equipe aceitou o convite da equipe.Isso significa que o primeiro elemento no array é o mais antigo a aceitar e o último é o mais recente.

Este método é útil para recuperar informações atualizadas sobre todos os membros de uma equipe atualmente na experiência e em diferentes servidores, possibilitando um comportamento de grupo coordenado, como teletransporte, matchmaking ou lógica de jogos baseada em grupos.

Cada dicionário no array retornado contém os seguintes campos:


<th>Tipo de valor</th>
<th>Descrição</th>
</tr>
</thead>
<tbody>
<tr>
<th><code>Id do usuário</code></th>
<td>número</td>
<td>A propriedade <code>Class.Player.UserId</code> do jogador.</td>
</tr>
<tr>
<th><code>Id do Lugar</code></th>
<td>número</td>
<td>O <code>Class.DataModel.PlaceId</code> do local em que o membro do grupo está atualmente.</td>
</tr>
<tr>
<th><code>Id do Trabalho</code></th>
<td>corda</td>
<td>O <code>Class.DataModel.JobId</code> da instância do servidor em que o usuário atualmente reside.</td>
</tr>
<tr>
<th><code>Id do Servidor Privado</code></th>
<td>corda</td>
<td>Se aplicável, o <code>Class.DataModel.PrivateServerId</code> quando o membro da equipe está em um servidor privado ou reservado.</td>
</tr>
<tr>
<th><code>Código de Acesso Reservado ao Servidor</code></th>
<td>corda</td>
<td>Se aplicável, o código de acesso para o servidor reservado em que o usuário atualmente reside.Útil para teletransportar membros do grupo um ao outro usando <code>Class.TeleportService:TeleportAsync()</code>.</td>
</tr>
</tbody>
Chave

Observe que este serviço não funciona durante o teste de jogo no Roblox Studio; para testar aspectos de sua experiência usando-o, você deve publicar a experiência e jogá-la no aplicativo Roblox.

Parâmetros

partyId: string
Valor Padrão: ""

Devolução

Um conjunto de dicionários que representam os membros do grupo especificado que estão atualmente na experiência.

Amostras de código

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)

PromptRsvpToEventAsync

Rendimentos

PromptRsvpToEventAsync() exibe um prompt para o jogador local através do qual eles podem alterar o status de RSVP para o evento dado.

Os eventos devem estar na experiência atual e não devem ter já começado. Se o evento já tiver começado, este método retornará um erro.

Observe que você pode usar GetEventRsvpStatusAsync() para verificar o status atual de RSVP do jogador antes de chamar este método.

Parâmetros

eventId: string

O ID do evento do evento para solicitar que o jogador mude seu status de RSVP.Este deve ser um ID de evento válido que existe na experiência atual, representado como uma string (não um número).

Valor Padrão: ""

Devolução

Retorna um Enum.RsvpStatus indicando o novo status de RSVP do jogador após o prompt ser fechado.Se o jogador fechar o prompt sem alterar seu status RSVP, isso retornará Enum.RsvpStatus.None ou seu antigo Enum.RsvpStatus se eles já tivessem selecionado um status.

Amostras de código

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.

SocialService:PromptRsvpToEventAsync()

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)

Eventos

CallInviteStateChanged

Este evento dispara quando o estado de convite de chamada de um jogador muda.

Parâmetros

player: Instance

A instância Player do jogador que teve uma mudança de estado de convocação de chamada.

inviteState: Enum.InviteState

O novo estado de convite de chamada.


Amostras de código

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

Este evento é disparado quando um jogador fecha um prompt de convite.

Parâmetros

player: Instance

A instância Player do jogador que fechou o prompt.

recipientIds: Array

Não mais populada; um array vazio.


PhoneBookPromptClosed

Dispara quando um jogador fecha o prompt do diretório telefônico.

Parâmetros

player: Instance

A instância Player do jogador que fechou o livro de telefones.


Callbacks

OnCallInviteInvoked

Um retorno de chamada para processar quando uma chamada é feita do diretório telefônico.O parâmetro tag pode ser usado para diferenciar entre diferentes "pontos de entrada" ou similares, como descrito em PromptPhoneBook() .Apenas um retorno de chamada pode ser definido.

Parâmetros

tag: string

Texto para ajudar a diferenciar entre vários pontos de entrada do diretório telefônico.

callParticipantIds: Array

Array que contém todos os jogadores envolvidos na chamada. O chamador sempre será o primeiro jogador no array.


Devolução

Tabela que inclui as chaves PlaceId e ReservedServerAccessCode cujos valores são os DataModel.PlaceId e o código de acesso ao servidor retornado por TeleportService:ReserveServer(), respectivamente.

Amostras de código

SocialService.OnCallInviteInvoked

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