Visão geral do chat de texto

Roblox oferece mensagens baseadas em texto entre jogadores em sessões ao vivo através de TextChatService, uma classe singleton responsável por gerenciar o sistema de chat geral, incluindo filtragem de mensagens de chat, moderação e permissões de usuários. Este serviço possui sua funcionalidade padrão e também fornece um conjunto de métodos e eventos para estender e personalizar o chat, como entregar mensagens com base em requisitos personalizados, adicionar permissões especiais ou moderação a jogadores específicos e criar comandos personalizados para executar ações específicas.

Configuração da interface do usuário

TextChatService fornece uma interface padrão que pode ser personalizada para atender às necessidades do seu jogo. Desative qualquer uma dessas configurações para ocultar seu elemento de interface associado. Se desejar, você também pode substituir esses elementos da interface por interfaces personalizadas:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Para mais informações, consulte Janela de chat e Chat em bolha.

Canais, mensagens e comandos

• TextChannel — Canais de texto transmitem mensagens enviadas pelos usuários do cliente para o servidor, que as exibe para outros usuários com base nas permissões. Canais de texto devem ser parentados ao TextChatService para funcionar.

  Se TextChatService.CreateDefaultTextChannels estiver definido como true, o serviço criará automaticamente dois canais de texto, RBXGeneral e RBXSystem. Você pode criar manualmente instâncias adicionais de TextChannel e parentá-las ao TextChatService, também.

• TextSource — Um usuário em um TextChannel. Fontes de texto são diretamente parentadas ao TextChannel quando AddUserAsync() é chamado. Fontes de texto contêm permissões detalhadas de um usuário no canal, como sua capacidade de enviar mensagens. Se um único usuário estiver em vários canais de texto, eles estarão associados a várias fontes de texto.

• TextChatMessage — Uma mensagem em um canal de texto. Mensagens de chat contêm informações básicas, como o remetente da mensagem, a mensagem original, a mensagem filtrada e o timestamp de criação.

• TextChatCommand — Permite que os usuários invoquem ações ou comportamentos específicos enviando mensagens que correspondem às propriedades PrimaryAlias ou SecondaryAlias. Comandos de chat devem ser parentados ao TextChatService para funcionar.

  Se TextChatService.CreateDefaultCommands estiver definido como true, comandos de chat padrão serão criados automaticamente. Você pode criar manualmente instâncias adicionais de TextChatCommand e parentá-las ao TextChatService, também.

Fluxograma do chat

O chat de texto utiliza o modelo cliente-servidor, com um cliente de envio, o servidor e clientes de recebimento.

1. Um jogador envia uma mensagem de seu dispositivo local, chamando o método TextChannel:SendAsync(). Este método processa a mensagem e determina se é um comando de chat ou uma mensagem de chat regular.

   • Se a mensagem for um comando de chat, ela dispara o evento TextChatCommand.Triggered para realizar a ação definida. Nenhum passo adicional é necessário.

   • Se a mensagem for uma mensagem de chat regular, ela dispara o evento TextChatService.SendingMessage para exibir a mensagem no cliente de envio. Ao mesmo tempo, TextChannel:SendAsync() passa a mensagem para o servidor.

2. O servidor dispara TextChannel.ShouldDeliverCallback para determinar se a mensagem deve ser entregue a outros jogadores com base nas permissões e nos requisitos de filtragem da comunidade Roblox.

3. Se TextChannel.ShouldDeliverCallback determinar que a mensagem é elegível para ser entregue a outros jogadores, o servidor aplica quaisquer filtros e dispara TextChannel.OnIncomingMessage duas vezes:

   1. A primeira vez é no cliente de envio e sinaliza que o servidor está processando a mensagem através do evento TextChatService.MessageReceived. Este evento substitui a mensagem local no cliente de envio pela mensagem processada do servidor. A mensagem é idêntica se a original não exigiu filtragem.

   2. A segunda vez é nos clientes de recebimento, o que aciona o evento TextChatService.MessageReceived para exibir a mensagem para outros jogadores.

Ganchos e callbacks do chat de texto

A API TextChatService incentiva uma separação clara na aparência e entrega de mensagens de chat. Múltiplas instâncias do sistema de chat de texto fornecem ganchos e callbacks para formatar em locais centralizados e claros.

Entregar mensagens condicionalmente

O callback TextChannel.ShouldDeliverCallback deve ser definido apenas no servidor. O callback é disparado para cada filho TextSource do canal de texto quando uma mensagem é enviada para determinar se a mensagem deve ser entregue. Este callback pode ser usado para implementar lógica de entrega de mensagens personalizada que pode depender de contexto adicional de jogabilidade, como:

• Chat baseado em proximidade onde os usuários só podem enviar mensagens para aqueles que estão próximos a eles.
• Impedir que usuários com certos atributos enviem mensagens para outros.

Personalizar a exibição de mensagens

A interface padrão do TextChatService depende de texto enriquecido para formatar e personalizar como as mensagens são exibidas. Você pode usar os seguintes callbacks para formatar mensagens antes de serem exibidas aos usuários, por exemplo, para adicionar cores ou etiquetas de chat a nomes de usuários ou formatar o conteúdo das mensagens.

Os seguintes callbacks são chamados em cada TextChatMessage que está prestes a ser exibido, o que permite personalizar a aparência da janela de chat com base no conteúdo de TextChannel, TextSource ou TextChatMessage. Quando um cliente envia uma mensagem, esses callbacks são chamados uma vez quando a mensagem é enviada ao servidor e o valor TextChatMessage.Status será Enum.TextChatMessageStatus.Sending. Assim que a mensagem é recebida pelo servidor e está sendo entregue a outros usuários, o cliente remetente recebe a mensagem novamente com um valor atualizado de Enum.TextChatMessageStatus.

• TextChatService.OnIncomingMessage — Este callback deve ser definido apenas no cliente. O callback é disparado quando uma mensagem é recebida, seja do servidor ou se o cliente local acabou de enviar uma mensagem. O callback é chamado em cada TextChatMessage recebida de todas as instâncias de TextChannel e é o primeiro a processar a mensagem antes que ela seja exibida ao usuário.
• TextChannel.OnIncomingMessage — Este callback deve ser definido apenas no cliente. O callback é disparado quando uma mensagem é recebida do servidor. O callback é chamado em cada TextChatMessage recebida do TextChannel. Instâncias padrão de TextChannel criadas a partir de TextChatService.CreateDefaultTextChannels têm esse callback definido e podem ser sobrescritos.
• TextChatService.OnBubbleAdded — Este callback deve ser definido apenas no cliente. Use-o para personalizar a aparência das bolhas de chat independentemente da aparência da mensagem na interface da janela de chat.
• TextChatService.OnChatWindowAdded — Este callback deve ser definido apenas no cliente. Use-o para personalizar a aparência das mensagens de chat na interface da janela de chat, independentemente da aparência da mensagem nas bolhas de chat.

Migrar do chat legado

Esta seção ajuda você a migrar do sistema de chat legado, fornecendo métodos alternativos para implementar funcionalidades e comportamentos comuns de chat usando TextChatService.

1. Na janela do Explorador, selecione TextChatService.

2. Na janela de Propriedades, encontre o dropdown ChatVersion e selecione TextChatService.

   

Funcionalidades básicas

Embora ambos os sistemas compartilhem as mesmas funcionalidades básicas de chat, as implementações do TextChatService são, em geral, mais sustentáveis e mais fáceis de iterar.

Filtragem de mensagens

O TextChatService filtra automaticamente as mensagens de chat com base nas informações da conta de cada jogador, para que você não precise implementar manualmente a filtragem de texto para todos os tipos de mensagens de chat.

Janela e chat em bolha

Comportamento de ambos, a janela de chat e as opções de personalização do chat em bolha do TextChatService são idênticos aos do sistema de chat legado. Como o sistema de chat legado só permite personalização usando módulos de chat ou o contêiner Players, o serviço fornece classes dedicadas (ChatWindowConfiguration e BubbleChatConfiguration) para gerenciar todas as propriedades da janela de chat e do chat em bolha. Além disso, você pode facilmente ajustar e visualizar as propriedades de aparência e comportamento do seu chat em bolha usando as configurações do Studio, em vez de ter que scriptar tudo.

Migrar "dados extras" do falante

O sistema de chat legado em Lua permitia que os desenvolvedores usassem SetExtraData na classe Speaker. Esses dados eram usados para formatar a cor do nome, a cor do chat ou para aplicar etiquetas de nome para um determinado falante.

Sistema de Chat Legado SetExtraData
-- Um exemplo de como definir dados extras em um falante no sistema de chat legado
ChatService.SpeakerAdded:Connect(function(playerName)
	local speaker = ChatService:GetSpeaker(playerName)
	speaker:SetExtraData("NameColor", Color3.fromRGB(255, 255, 55))
	speaker:SetExtraData("ChatColor", Color3.fromRGB(212, 175, 55))
	speaker:SetExtraData("Tags", {{TagText = "YourTagName", TagColor = Color3.fromRGB(0, 255, 0)}, {TagText = "OtherTagName", TagColor = Color3.fromRGB(255, 0, 0)}})
end)

O TextChatService não tem um equivalente direto para SetExtraData. Em vez disso, use callbacks como OnWindowAdded para personalizar a aparência das mensagens usando texto enriquecido com base na TextSource da mensagem.

O seguinte é um exemplo de emular os "dados extras" de chat legado em Lua acessando atributos nos objetos Player:

TextChatService SetAttributes
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	player:SetAttribute("NameColor", Color3.fromRGB(255, 255, 55))
	player:SetAttribute("ChatColor", Color3.fromRGB(212, 175, 55))
	player:SetAttribute("isYourTag", true)
	player:SetAttribute("isOtherTag", true)
end)

Em seguida, você pode usar o callback OnChatWindowAdded para personalizar a aparência da janela de chat com base nos atributos definidos no jogador:

TextChatService OnChatWindowAdded
local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

TextChatService.OnChatWindowAdded = function(textChatMessage)
	local textSource = textChatMessage.TextSource
	if textSource then
		local player = Players:GetPlayerByUserId(textSource.UserId)
		if player then
			local overrideProperties = TextChatService.ChatWindowConfiguration:DeriveNewMessageProperties()
			overrideProperties.PrefixText = textChatMessage.PrefixText
			overrideProperties.Text = textChatMessage.Text

			local nameColor = player:GetAttribute("NameColor")
			if nameColor and typeof(nameColor) == "Color3" then
				overrideProperties.PrefixTextProperties.TextColor3 = nameColor
			end

			local chatColor = player:GetAttribute("ChatColor")
			if chatColor and typeof(chatColor) == "Color3" then
				overrideProperties.TextColor3 = chatColor
			end

			local isYourTag = player:GetAttribute("isYourTag")
			if isYourTag == true then
				overrideProperties.PrefixText = `<font color='rgb(0, 255, 0)'>[YourTag]</font> {overrideProperties.PrefixText}`
			end

			local isOtherTag = player:GetAttribute("isOtherTag")
			if isOtherTag == true then
				overrideProperties.PrefixText = `<font color='rgb(255, 0, 0)'>[OtherTag]</font> {overrideProperties.PrefixText}`
			end

			return overrideProperties
		end
	end

	return nil
end