Resumen del chat de texto

Roblox ofrece mensajería basada en texto entre jugadores en sesiones en vivo a través de TextChatService, una clase singleton responsable de gestionar el sistema de chat en general, incluyendo el filtrado de mensajes de chat, moderación y permisos de usuario. Este servicio tiene su funcionalidad estándar y también proporciona un conjunto de métodos y eventos para extender y personalizar el chat, como entregar mensajes según requisitos personalizados, agregar permisos especiales o moderación a jugadores específicos, y crear comandos personalizados para ejecutar acciones específicas.

Configuración de la interfaz de usuario

TextChatService proporciona una interfaz de usuario predeterminada que se puede personalizar para adaptarse a las necesidades de tu juego. Desactiva cualquiera de estas configuraciones para ocultar su elemento de interfaz de usuario asociado. Si lo deseas, también puedes reemplazar estos elementos de interfaz de usuario con interfaces personalizadas:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Para obtener más información, consulta Ventana de chat y Chat burbuja.

Canales, mensajes y comandos

• TextChannel — Los canales de texto envían mensajes enviados por el usuario del cliente al servidor, que luego los muestra a otros usuarios según los permisos. Los canales de texto deben estar subordinados a TextChatService para funcionar.

  Si TextChatService.CreateDefaultTextChannels está configurado en true, el servicio crea automáticamente dos canales de texto, RBXGeneral y RBXSystem. También puedes crear manualmente instancias adicionales de TextChannel y subordinarlas a TextChatService.

• TextSource — Un usuario en un TextChannel. Las fuentes de texto están directamente subordinadas a TextChannel cuando se llama a AddUserAsync(). Las fuentes de texto contienen permisos detallados de un usuario en el canal, como su capacidad para enviar mensajes. Si un solo usuario está en múltiples canales de texto, se asocia a múltiples fuentes de texto.

• TextChatMessage — Un mensaje en un canal de texto. Los mensajes de chat contienen información básica como el remitente del mensaje, el mensaje original, el mensaje filtrado y la marca de tiempo de creación.

• TextChatCommand — Permite a los usuarios invocar acciones o comportamientos específicos enviando mensajes que coincidan con las propiedades PrimaryAlias o SecondaryAlias. Los comandos de chat deben estar subordinados a TextChatService para funcionar.

  Si TextChatService.CreateDefaultCommands está configurado en true, los comandos de chat predeterminados se crearán automáticamente. También puedes crear manualmente instancias adicionales de TextChatCommand y subordinarlas a TextChatService.

Diagrama de flujo del chat

El chat de texto utiliza el modelo cliente-servidor, con un cliente de envío, el servidor y clientes de recepción.

1. Un jugador envía un mensaje desde su dispositivo local, activando el método TextChannel:SendAsync(). Este método procesa el mensaje y determina si es un comando de chat o un mensaje de chat regular.

   • Si el mensaje es un comando de chat, dispara el evento TextChatCommand.Triggered para realizar la acción definida. No se requieren más pasos.

   • Si el mensaje es un mensaje de chat regular, dispara el evento TextChatService.SendingMessage para mostrar el mensaje al remitente en el cliente de envío. Al mismo tiempo, TextChannel:SendAsync() pasa el mensaje al servidor.

2. El servidor dispara TextChannel.ShouldDeliverCallback para determinar si debe entregar el mensaje a otros jugadores según los permisos y los requisitos de filtrado de la comunidad de Roblox.

3. Si TextChannel.ShouldDeliverCallback determina que el mensaje es elegible para ser entregado a otros jugadores, el servidor aplica cualquier filtro y dispara TextChannel.OnIncomingMessage dos veces:

   1. La primera vez es en el cliente de envío y señala que el servidor está procesando el mensaje a través del evento TextChatService.MessageReceived. Este evento reemplaza el mensaje local en el cliente de envío con el mensaje procesado del servidor. El mensaje es idéntico si el original no requería filtrado.

   2. La segunda vez es en los clientes de recepción, lo que activa el evento TextChatService.MessageReceived para mostrar el mensaje a otros jugadores.

Hooks y callbacks del chat de texto

La API de TextChatService fomenta una clara separación en la apariencia y entrega de mensajes de chat. Múltiples instancias del sistema de chat de texto proporcionan hooks y callbacks para formatear en ubicaciones centralizadas y claras.

Entrega condicional de mensajes

El callback TextChannel.ShouldDeliverCallback debe definirse solo en el servidor. El callback se dispara para cada hijo TextSource del canal de texto cuando se envía un mensaje para determinar si el mensaje debe ser entregado. Este callback se puede usar para implementar una lógica de entrega de mensajes personalizada que puede depender de contexto adicional del juego, como:

• Chat basado en proximidad donde los usuarios solo pueden enviar mensajes a aquellos cercanos a ellos.
• Prevención de que los usuarios con ciertos atributos envíen mensajes a otros.

Personalizar la visualización de mensajes

La interfaz de usuario predeterminada de TextChatService se basa en texto enriquecido para formatear y personalizar cómo se muestran los mensajes. Puedes usar los siguientes callbacks para formatear los mensajes antes de que se muestren a los usuarios, por ejemplo, para agregar colores o etiquetas de chat a los nombres de usuario o formatear el contenido del mensaje.

Los siguientes callbacks se llaman en cada TextChatMessage que está a punto de ser mostrado, lo que te permite personalizar la apariencia de la ventana de chat según el contenido de TextChannel, TextSource o TextChatMessage. Cuando un cliente envía un mensaje, estos callbacks se llaman una vez cuando el mensaje se envía al servidor y el valor de TextChatMessage.Status será Enum.TextChatMessageStatus.Sending. Una vez que el mensaje es recibido por el servidor y se está entregando a otros usuarios, el cliente remitente recibe el mensaje nuevamente con un valor actualizado de Enum.TextChatMessageStatus.

• TextChatService.OnIncomingMessage — Este callback debe definirse solo en el cliente. El callback se dispara cuando se recibe un mensaje, ya sea del servidor o si el cliente local acaba de enviar un mensaje. El callback se llama en cada TextChatMessage recibido de todas las instancias de TextChannel y es el primero en procesar el mensaje antes de que se muestre al usuario.
• TextChannel.OnIncomingMessage — Este callback debe definirse solo en el cliente. El callback se dispara cuando se recibe un mensaje del servidor. El callback se llama en cada TextChatMessage recibido del TextChannel. Las instancias predeterminadas de TextChannel creadas a partir de TextChatService.CreateDefaultTextChannels tienen este callback definido y se pueden sobrescribir.
• TextChatService.OnBubbleAdded — Este callback debe definirse solo en el cliente. Úsalo para personalizar la apariencia de las burbujas de chat independientemente de la apariencia del mensaje en la interfaz de usuario de la ventana de chat.
• TextChatService.OnChatWindowAdded — Este callback debe definirse solo en el cliente. Úsalo para personalizar la apariencia de los mensajes de chat en la interfaz de usuario de la ventana de chat independientemente de la apariencia del mensaje en las burbujas de chat.

Migrar desde el chat heredado

Esta sección te ayuda a migrar desde el sistema de chat heredado proporcionando métodos alternativos para implementar funcionalidades y comportamientos comunes de chat usando TextChatService.

1. En la ventana de Explorer, selecciona TextChatService.

2. En la ventana de Properties, encuentra el menú desplegable ChatVersion y selecciona TextChatService.

   

Funcionalidades básicas

Aunque ambos sistemas comparten las mismas funcionalidades básicas de chat, las implementaciones de TextChatService son en general más sostenibles y más fáciles de iterar.

Filtrado de mensajes

TextChatService filtra automáticamente los mensajes de chat según la información de la cuenta de cada jugador, por lo que no es necesario implementar manualmente el filtrado de texto para todos los tipos de mensajes de chat.

Ventana y chat burbuja

El comportamiento y las opciones de personalización de la ventana de chat y el chat burbuja de TextChatService son idénticos a los del sistema de chat heredado. Como el sistema de chat heredado solo permite la personalización utilizando módulos de chat o el contenedor Players, el servicio proporciona clases dedicadas (ChatWindowConfiguration y BubbleChatConfiguration) para gestionar todas las propiedades de ventana de chat y chat burbuja. Además, puedes ajustar y previsualizar fácilmente tus propiedades de apariencia y comportamiento del chat burbuja utilizando la configuración de Studio en lugar de tener que programarlas todas.

Migrar "datos extra" del hablante

El sistema de chat Lua heredado permitía a los desarrolladores usar SetExtraData en la clase Speaker. Estos datos se usaban para formatear el color del nombre, el color del chat o para aplicar etiquetas de nombre para un hablante dado.

Sistema de chat heredado SetExtraData
-- Un ejemplo de establecer datos extra en un hablante en el sistema de chat heredado
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 = "TuNombreEtiqueta", TagColor = Color3.fromRGB(0, 255, 0)}, {TagText = "OtroNombreEtiqueta", TagColor = Color3.fromRGB(255, 0, 0)}})
end)

TextChatService no tiene un equivalente directo a SetExtraData. En su lugar, utiliza callbacks como OnWindowAdded para personalizar la apariencia de los mensajes utilizando texto enriquecido basado en la TextSource del mensaje.

El siguiente es un ejemplo de emulación de los "datos extra" del chat Lua heredado accediendo a atributos en los 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)

Luego puedes usar el callback OnChatWindowAdded para personalizar la apariencia de la ventana de chat según los atributos establecidos en el jugador:

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

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

			return overrideProperties
		end
	end

	return nil
end