Visão geral do chat de texto

O Roblox oferece mensagens baseadas em texto entre os jogadores em sessões ao vivo através de TextChatService .Este serviço tem sua funcionalidade padrão, mas 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 ou moderação especiais a jogadores específicos e criar comandos personalizados para executar ações específicas.

As seções a seguir resumem as principais classes e instâncias que você pode usar para personalizar o sistema de chat.

Configuração de alto nível

A classe única TextChatService é responsável por gerenciar o sistema geral de chat, incluindo a filtragem, moderação e permissões de usuários de mensagens de chat.Use propriedades como CreateDefaultTextChannels e CreateDefaultCommands para habilitar ou desabilitar canais e comandos de chat padrão.

Configuração padrão da UI

TextChatService fornece uma interface padrão que pode ser personalizada para atender às necessidades da sua experiência.Cada uma dessas configurações pode ser desativada para ocultar o elemento de UI associado e pode ser substituída por interfaces personalizadas, se desejado.

• ChatWindowConfiguration — Representa a interface de janela de chat padrão, incluindo sua aparência e comportamento. Desabilite-a para ocultar a janela de chat.
• ChatInputBarConfiguration — Representa a interface de barra de entrada de chat padrão, incluindo sua aparência e comportamento.
• BubbleChatConfiguration — Representa a interface padrão de bate-papo de bolhas, incluindo sua aparência e comportamento.

Canais, mensagens e comandos

• TextChannel — Representa um canal de chat de texto que passa mensagens de chat enviadas pelo usuário do cliente para o servidor, que as exibe a outros usuários com base em permissões.Essas instâncias devem ser parentadas para TextChatService para funcionar.

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

• TextSource — Representa um usuário em um TextChannel .Essas instâncias são diretamente parentadas para o TextChannel quando AddUserAsync() for chamado.Fontes de texto contêm permissões detalhadas de um usuário no canal, como sua capacidade de enviar mensagens.Um único usuário pode ser associado a várias fontes de texto se elas foram adicionadas a vários canais de texto.

• TextChatMessage — Representa uma única mensagem de bate-papo em um canal de texto, com informações básicas, como o remetente da mensagem, a mensagem original, a mensagem filtrada e o tempo de criação.

• TextChatCommand — Permite que os usuários invoquem ações ou comportamentos específicos enviando mensagens que correspondam a PrimaryAlias ou SecondaryAlias.Essas instâncias devem ser parentadas para TextChatService para funcionar.

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

Fluxograma de bate-papo

O bate-papo de texto usa o modelo cliente-servidor, com um cliente de envio , o servidor e clientes de recepção .

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 ela é 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 executar a ação definida. Não são necessários mais passos.

   • Se a mensagem for uma mensagem de bate-papo regular, ela ativa 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 enviar a mensagem para outros jogadores com base em permissões e 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 o original não exigir filtragem.

   2. A segunda vez é nos clientes de recepção, que ativa o evento TextChatService.MessageReceived para exibir a mensagem a outros jogadores.

Ganchos de chat de texto e chamadas de retorno

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 retornos de chamada para formatar em locais centralizados e claros.

| Callback | Retorno de Valor | | ----------------------------------------- | ----------------------------------- | | | boolean | | | | | | | | | | | | | | |

Entregar mensagens condicionalmente

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

• Chat baseado em proximidade onde os usuários só podem enviar mensagens para aqueles próximos deles.
• Prevenindo usuários com certos atributos de enviar mensagens para outros.

Personalizar exibição de mensagem

A interface padrão TextChatService UI depende de texto rico para formatar e personalizar como as mensagens são exibidas.Você pode usar os seguintes retornos de chamada para formatar mensagens antes de serem exibidas aos usuários, por exemplo, para adicionar cores ou tags de bate-papo aos nomes de usuários ou formatar o conteúdo da mensagem.

Os seguintes retornos de chamada são chamados a 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 TextChannel, TextSource ou TextChatMessage.Quando um cliente envia uma mensagem, esses retornos de chamada são chamados uma vez quando a mensagem é enviada ao servidor e o valor TextChatMessage.Status será Enum.TextChatMessageStatus.Sending.Uma vez que a mensagem é recebida pelo servidor e está sendo entregue a outros usuários, o cliente de remetente recebe a mensagem novamente com um valor atualizado de Enum.TextChatMessageStatus.

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

Migre do chat legado

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

1. Na janela Explorer, selecione TextChatService.

2. Na janela Propriedades, encontre o menu suspenso ChatVersion e selecione TextChatService.

   

Funcionalidades básicas

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

Filtro de mensagens

TextChatService filtra automaticamente mensagens de bate-papo com base na informação da conta de cada jogador, então você não precisa implementar manualmente a filtragem de texto para todos os tipos de mensagens de bate-papo.

Chat de janela e bolha

O comportamento e as opções de personalização da janela de bate-papo e da bolha de bate-papo são idênticos às do sistema de bate-papo 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 e do bate-papo de bolhas.Além disso, você pode facilmente ajustar e pré-visualizar as propriedades de aparência e comportamento do bate-papo de bolhas usando as configurações do Studio em vez de ter que programá-las todas.

Migrar dados adicionais do orador "extra"

O sistema de chat Lua legado permitiu que os desenvolvedores usassem SetExtraData na classe Speaker.Esses dados foram usados para formatar a cor do nome, cor do chat ou aplicar tags de nome para um orador dado.

Sistema de Chat Legado SetExtraData
-- Um exemplo de definir dados extras em um orador 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)

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

O seguinte é um exemplo de emular o "dado extra" do chat Lua legado ao acessar atributos em Player objetos:

Serviço de Chat de Texto Defina Atributos
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 retorno de chamada OnChatWindowAdded para personalizar a aparência da janela de chat com base nos atributos definidos no jogador:

TextChatService Adicionado ao ChatWindow
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