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 todo o sistema de chat, incluindo filtragem de mensagens de chat, moderação e permissões de usuário. 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 UI

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

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Para mais informações, veja Janela de chat e Chat em bolhas.

Canais, mensagens e comandos

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

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

• 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, ele estará associado 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ê também pode criar manualmente instâncias adicionais de TextChatCommand e parentá-las ao TextChatService.

Fluxograma do chat

O chat de texto usa 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, acionando 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, ele 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, ele dispara o evento TextChatService.SendingMessage para exibir a mensagem ao remetente no cliente de envio. Ao mesmo tempo, TextChannel:SendAsync() passa a mensagem para o servidor.

2. O servidor dispara TextChannel.ShouldDeliverCallback para determinar se deve entregar a mensagem 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 entrega 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, que aciona o evento TextChatService.MessageReceived para exibir a mensagem a outros jogadores.

Ganchos e callbacks do chat de texto

A API TextChatService incentiva uma clara separação na aparência e entrega das 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 é acionado 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 jogo, 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 UI padrão do TextChatService depende de texto rico 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 tags de chat aos nomes dos usuários ou formatar o conteúdo da mensagem.

Os seguintes callbacks são chamados em cada TextChatMessage que está prestes a ser exibido, o que permite que você personalize 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 para o servidor e o valor de TextChatMessage.Status será Enum.TextChatMessageStatus.Sending. Uma vez 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 é acionado 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 de ser exibida ao usuário.
• TextChannel.OnIncomingMessage — Este callback deve ser definido apenas no cliente. O callback é acionado quando uma mensagem é recebida do servidor. O callback é chamado em cada TextChatMessage recebida do TextChannel. As instâncias padrão de TextChannel criadas a partir de TextChatService.CreateDefaultTextChannels têm este callback definido e podem ser sobrescritas.
• 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 UI 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 UI 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 Explorer, selecione TextChatService.

2. Na janela Properties, 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 de TextChatService são, em geral, mais sustentáveis e mais fáceis de iterar.

Filtragem de mensagens

TextChatService filtra automaticamente 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 bolhas

Tanto a janela de chat quanto o comportamento e as opções de personalização do chat em bolhas 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 bolhas. Além disso, você pode facilmente ajustar e visualizar suas propriedades de aparência e comportamento do chat em bolhas usando as configurações do Studio em vez de ter que scriptar tudo.

Migrar "dados extras" do falante

O sistema de chat Lua legado 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 tags de nome para um determinado falante.

-- Um exemplo de configuração de 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 = "SeuNomeTag", TagColor = Color3.fromRGB(0, 255, 0)}, {TagText = "OutroNomeTag", TagColor = Color3.fromRGB(255, 0, 0)}})
end)

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

O seguinte é um exemplo de emulação dos "dados extras" do chat Lua legado acessando atributos em objetos Player:

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)

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

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)'>[SeuTag]</font> {overrideProperties.PrefixText}`
			end

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

			return overrideProperties
		end
	end

	return nil
end