Aperçu du chat textuel

Roblox propose un système de messagerie textuelle entre les joueurs lors de sessions en direct via TextChatService, une classe singleton responsable de la gestion de l'ensemble du système de chat, y compris le filtrage des messages, la modération et les autorisations des utilisateurs. Ce service dispose d'une fonctionnalité standard et offre également un ensemble de méthodes et d'événements pour étendre et personnaliser le chat, tels que la livraison de messages en fonction de conditions personnalisées, l'ajout d'autorisations ou de modérations spéciales pour des joueurs spécifiques, et la création de commandes personnalisées pour exécuter des actions spécifiques.

Configuration de l'UI

TextChatService fournit une interface utilisateur par défaut qui peut être personnalisée pour répondre aux besoins de votre jeu. Désactivez l'une de ces configurations pour masquer son élément UI associé. Si désiré, vous pouvez également remplacer ces éléments UI par des interfaces personnalisées :

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Pour plus d'informations, consultez Fenêtre de chat et Chat bubble.

Canaux, messages et commandes

• TextChannel — Les canaux de texte transmettent les messages envoyés par l'utilisateur du client au serveur, qui les affiche ensuite aux autres utilisateurs en fonction des autorisations. Les canaux de texte doivent être parentés à TextChatService pour fonctionner.

  Si TextChatService.CreateDefaultTextChannels est défini sur true, le service crée automatiquement deux canaux textuels, RBXGeneral et RBXSystem. Vous pouvez également créer manuellement d'autres instances de TextChannel et les parentées à TextChatService.

• TextSource — Un utilisateur dans un TextChannel. Les sources de texte sont directement parentées au TextChannel lorsque AddUserAsync() est appelé. Les sources de texte contiennent des autorisations détaillées d'un utilisateur dans le canal, telles que sa capacité à envoyer des messages. Si un utilisateur unique est dans plusieurs canaux de texte, il est associé à plusieurs sources de texte.

• TextChatMessage — Un message dans un canal textuel. Les messages de chat contiennent des informations de base telles que l'expéditeur du message, le message original, le message filtré et l'horodatage de création.

• TextChatCommand — Permet aux utilisateurs d'invoquer des actions ou des comportements spécifiques en envoyant des messages qui correspondent aux propriétés PrimaryAlias ou SecondaryAlias. Les commandes de chat doivent être parentées à TextChatService pour fonctionner.

  Si TextChatService.CreateDefaultCommands est défini sur true, des commandes de chat par défaut seront créées automatiquement. Vous pouvez également créer manuellement d'autres instances de TextChatCommand et les parentées à TextChatService.

Schéma du flux de chat

Le chat textuel utilise le modèle client-serveur, avec un client d'envoi, le serveur et des clients récepteurs.

1. Un joueur envoie un message depuis son appareil local, déclenchant la méthode TextChannel:SendAsync(). Cette méthode traite le message et détermine s'il s'agit d'une commande de chat ou d'un message de chat ordinaire.

   • Si le message est une commande de chat, elle déclenche l'événement TextChatCommand.Triggered pour réaliser l'action définie. Aucune étape supplémentaire n'est requise.

   • Si le message est un message de chat ordinaire, il déclenche l'événement TextChatService.SendingMessage pour afficher le message à l'expéditeur sur le client d'envoi. En même temps, TextChannel:SendAsync() transmet le message au serveur.

2. Le serveur déclenche TextChannel.ShouldDeliverCallback pour déterminer s'il faut livrer le message à d'autres joueurs en fonction des autorisations et des exigences de filtrage de la communauté Roblox.

3. Si TextChannel.ShouldDeliverCallback détermine que le message peut être livré à d'autres joueurs, le serveur applique tous les filtres et déclenche TextChannel.OnIncomingMessage deux fois :

   1. La première fois sur le client d'envoi et indique que le serveur traite le message via l'événement TextChatService.MessageReceived. Cet événement remplace le message local sur le client d'envoi par le message traité du serveur. Le message est identique si l'original ne nécessitait pas de filtrage.

   2. La deuxième fois sur les clients récepteurs, ce qui déclenche l'événement TextChatService.MessageReceived pour afficher le message aux autres joueurs.

Hooks et rappels du chat textuel

L'API TextChatService encourage une séparation claire sur l'apparence et la livraison des messages de chat. Plusieurs instances du système de chat textuel fournissent des hooks et des rappels pour formater dans des emplacements centralisés et clairs.

Livraison conditionnelle des messages

Le rappel TextChannel.ShouldDeliverCallback doit être défini uniquement sur le serveur. Le rappel est déclenché pour chaque enfant TextSource du canal texte lors de l'envoi d'un message afin de déterminer si le message doit être livré. Ce rappel peut être utilisé pour implémenter une logique de livraison de message personnalisée qui peut dépendre d'un contexte de jeu supplémentaire, tel que :

• Chat basé sur la proximité Proximity-based chat où les utilisateurs ne peuvent envoyer des messages qu'à ceux qui leur sont proches.
• Empêcher les utilisateurs avec certains attributs d'envoyer des messages à d'autres.

Personnaliser l'affichage des messages

L'interface utilisateur par défaut de TextChatService dépend du texte enrichi pour formater et personnaliser la façon dont les messages sont affichés. Vous pouvez utiliser les rappels suivants pour formater les messages avant qu'ils ne soient affichés aux utilisateurs, par exemple pour ajouter des couleurs ou des tags de chat aux noms d'utilisateur ou formater le contenu des messages.

Les rappels suivants sont appelés sur chaque TextChatMessage qui est sur le point d'être affiché, ce qui vous permet de personnaliser l'apparence de la fenêtre de chat en fonction du contenu de TextChannel, TextSource ou TextChatMessage. Lorsqu'un client envoie un message, ces rappels sont appelés une fois lorsque le message est envoyé au serveur et la valeur TextChatMessage.Status sera Enum.TextChatMessageStatus.Sending. Une fois que le message est reçu par le serveur et est en cours de livraison à d'autres utilisateurs, le client expéditeur reçoit à nouveau le message avec une valeur mise à jour de Enum.TextChatMessageStatus.

• TextChatService.OnIncomingMessage — Ce rappel doit être défini uniquement sur le client. Le rappel est déclenché lorsqu'un message est reçu, soit du serveur, soit si le client local vient d'envoyer un message. Le rappel est appelé sur chaque TextChatMessage reçu de toutes les instances de TextChannel et est le premier à traiter le message avant qu'il ne soit affiché à l'utilisateur.
• TextChannel.OnIncomingMessage — Ce rappel doit être défini uniquement sur le client. Le rappel est déclenché lorsqu'un message est reçu du serveur. Le rappel est appelé sur chaque TextChatMessage reçu du TextChannel. Les instances par défaut de TextChannel créées depuis TextChatService.CreateDefaultTextChannels ont ce rappel défini et peuvent être remplacées.
• TextChatService.OnBubbleAdded — Ce rappel doit être défini uniquement sur le client. Utilisez-le pour personnaliser l'apparence des bulles de chat indépendamment de l'apparence du message dans l'interface utilisateur de la fenêtre de chat.
• TextChatService.OnChatWindowAdded — Ce rappel doit être défini uniquement sur le client. Utilisez-le pour personnaliser l'apparence des messages de chat dans l'interface utilisateur de la fenêtre de chat indépendamment de l'apparence du message dans les bulles de chat.

Migrer depuis le chat hérité

Cette section vous aide à migrer depuis le système de chat hérité en fournissant des méthodes alternatives pour implémenter des fonctionnalités et comportements de chat courants en utilisant TextChatService.

1. Dans la fenêtre Explorer, sélectionnez TextChatService.

2. Dans la fenêtre Propriétés, trouvez le menu déroulant ChatVersion et sélectionnez TextChatService.

   

Fonctionnalités de base

Bien que les deux systèmes partagent les mêmes fonctionnalités de chat de base, les implémentations de TextChatService sont généralement plus durables et plus faciles à itérer.

Filtrage des messages

TextChatService filtre automatiquement les messages de chat en fonction des informations de compte de chaque joueur, donc vous n'avez pas besoin d'implémenter manuellement le filtrage du texte pour tous les types de messages de chat.

Fenêtre et chat bubble

Le comportement et les options de personnalisation de la fenêtre de chat et du chat bubble de TextChatService sont identiques à ceux du système de chat hérité. Comme le système de chat hérité ne permet la personnalisation qu'à l'aide de modules de chat ou du conteneur Players, le service fournit des classes dédiées (ChatWindowConfiguration et BubbleChatConfiguration) pour gérer toutes les propriétés de la fenêtre de chat et du chat bubble. De plus, vous pouvez facilement ajuster et prévisualiser les propriétés de votre apparence et comportement de chat bubble à l'aide des paramètres de Studio plutôt que de devoir tous les scriptser.

Migrer les "données supplémentaires" du locuteur

Le système de chat Lua hérité permettait aux développeurs d'utiliser SetExtraData sur la classe Speaker. Ces données étaient utilisées pour formater la couleur du nom, la couleur du chat, ou pour appliquer des tags de nom pour un locuteur donné.

SetExtraData du système de chat hérité
-- Un exemple de définition de données supplémentaires sur un locuteur dans le système de chat hérité
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'a pas d'équivalent direct à SetExtraData. Utilisez plutôt des rappels tels que OnWindowAdded pour personnaliser l'apparence des messages en utilisant du texte enrichi basé sur la TextSource du message.

Ce qui suit est un exemple pour émuler les "données supplémentaires" du chat Lua hérité en accédant aux attributs sur les objets 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)

Vous pouvez ensuite utiliser le rappel OnChatWindowAdded pour personnaliser l'apparence de la fenêtre de chat en fonction des attributs définis sur le joueur :

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