Skip to content

in-experience-text-chat.md

Latest commit

 

History

History
296 lines (230 loc) · 17.5 KB

in-experience-text-chat.md

File metadata and controls

296 lines (230 loc) · 17.5 KB
title TextChatService overview
description The TextChatService system allows players to communicate with each other using text-based messages in live sessions.

Roblox offers text-based messaging between players in live sessions through Class.TextChatService. This service has its standard functionality, but also provides a set of methods and events for extending and customizing chat, such as delivering messages based on customized requirements, adding special permissions or moderation to specific players, and creating custom commands to execute specific actions.

This page includes a high-level overview of how messaging works and instructions on migrating from legacy chat, but the easiest way to get started with customizing your experience's chat system is to [see the examples](examples/simple-custom-frontend-ui.md).

Text chat instances

The following sections summarize the primary classes and instances that you can use to customize the chat system.

Top-level configuration

  • Class.TextChatService - This singleton class is responsible for managing the overall chat system, including handling chat message filtering, moderation, and user permissions. Use properties like Class.TextChatService.CreateDefaultTextChannels and Class.TextChatService.CreateDefaultCommands to enable or disable default chat channels and commands.

Default UI configuration

TextChatService provides a default UI that can be customized to fit your experience's needs. Each of these configurations can be disabled to hide the associated UI element and can be replaced with custom interfaces if desired.

  • Class.ChatWindowConfiguration - Represents the default chat window UI, including its appearance and behavior. Disable it to hide the chat window.
  • Class.ChatInputBarConfiguration - Represents the default chat input bar UI, including its appearance and behavior.
  • Class.BubbleChatConfiguration - Represents the default bubble chat UI, including its appearance and behavior.

Channels, messages, and commands

  • Class.TextChannel - Represents a text chat channel that passes user-sent chat messages from the client to the server, which then displays them to other users based on permissions. These instances must be parented to TextChatService in order to function. If Class.TextChatService.CreateDefaultTextChannels is set to true, the service automatically creates two text channels, RBXGeneral and RBXSystem. You can manually create additional TextChannel instances and parent them to Class.TextChatService, as well.

    • Class.TextSource - Represents a user in a Class.TextChannel. These instances are directly parented to the Class.TextChannel when Class.TextChannel:AddUserAsync is used. Text sources contains detailed permissions of a user in the channel, such as their ability to send messages. A single user can be associated with multiple text sources if they have been added to multiple text channels.

  • Class.TextChatMessage - Represents a single chat message in a text channel, with basic information such as the sender of the message, the original message, the filtered message, and the creation timestamp.

  • Class.TextChatCommand - Allows users to invoke specific actions or behaviors by sending messages that match Class.TextChatCommand.PrimaryAlias or Class.TextChatCommand.SecondaryAlias. These instances must be parented to TextChatService in order to function. Chat commands are helpful for adding additional functionality and interactivity to the chat experience. If Class.TextChatService.CreateDefaultCommands is set to true, default chat commands will be created automatically. You can manually create additional TextChatCommand instances and parent them to Class.TextChatService, as well.

Chat flowchart

Text chat uses the client‑server model, with a sending client, the server, and receiving clients.

A flowchart for in-experience text chat.

  1. A player sends a message from their local device, triggering the Class.TextChannel:SendAsync() method. This method processes the message and determines whether it's a chat command or a regular chat message.

    • If the message is a chat command, it fires the Class.TextChatCommand.Triggered event to perform the defined action. No further steps are required.

    • If the message is a regular chat message, it fires the Class.TextChatService.SendingMessage event to display the message to the sender on the sending client. At the same time, Class.TextChannel:SendAsync() passes the message to the server.

  2. The server fires Class.TextChannel.ShouldDeliverCallback to determine whether to deliver the message to other players based on permissions and Roblox community filtering requirements.

  3. If Class.TextChannel.ShouldDeliverCallback determines that message is eligible to deliver to other players, the server applies any filters and fires Class.TextChannel.OnIncomingMessage twice:

    1. The first time is on the sending client and signals that the server is processing the message through the Class.TextChatService.MessageReceived event. This event replaces the local message on the sending client with the processed message from the server. The message is identical if the original didn't require filtering.

    2. The second time is on the receiving clients, which triggers the Class.TextChatService.MessageReceived event to display the message to other players.

Text chat hooks and callbacks

The Class.TextChatService API encourages a clear separation on the appearance and delivery of chat messages. Multiple instances of the text chat system provide hooks and callbacks to format in centralized, clear locations.

All callbacks are expected to be non-yielding functions. Yielding or waiting for a response in a callback blocks the chat system and can cause unexpected behavior.

A flowchart of the TextChatService callbacks order

Callback Return Value
Class.TextChannel.ShouldDeliverCallback boolean
Class.TextChatService.OnIncomingMessage Class.TextChatMessageProperties
Class.TextChannel.OnIncomingMessage Class.TextChatMessageProperties
Class.TextChatService.OnBubbleAdded Class.BubbleChatMessageProperties
Class.TextChatService.OnChatWindowAdded Class.ChatWindowMessageProperties

Conditionally deliver messages

  • Class.TextChannel.ShouldDeliverCallback - This callback should be defined on the server only. The callback is fired for each Class.TextSource child of the text channel when a message is sent to determine whether the message should be delivered. This callback can be used to implement custom message delivery logic that may depend on additional gameplay context, such as:

    • Proximity-based chat where users can only send messages to those close to them.
    • Preventing users with certain attributes from sending messages to others.

Customize message display

The default TextChatService UI relies on rich text to format and customize how messages are displayed. You can use the following callbacks to format messages before they are displayed to users. You might want to add colors or chat tags to user's names or format message content.

The following callbacks are called on every TextChatMessage that is about to be displayed, which lets you customize chat window appearance based on the TextChannel, TextSource, or TextChatMessage content.

When a client sends a message, these callbacks are called once when the message is sent to the server and the Class.TextChatMessage.Status value will be Enum.TextChatMessageStatus.Sending. Once the message is received by the server and is being delivered to other users, the sender client receives the message again with an updated Enum.TextChatMessageStatus value.

  • Class.TextChatService.OnIncomingMessage - This callback should be defined on the client only. The callback is fired when a message is received, either from the server or if the local client has just sent a message. The callback is called on every TextChatMessage received from all TextChannel instances and is the first to process the message before it is displayed to the user.
  • Class.TextChannel.OnIncomingMessage - This callback should be defined on the client only. The callback is fired when a message is received from the server. The callback is called on every TextChatMessage received from the TextChannel. Default TextChannel instances created from Class.TextChatService.CreateDefaultTextChannels have this callback defined and can be overwritten.
  • Class.TextChatService.OnBubbleAdded - This callback should be defined on the client only. Use it to customize the appearance of chat bubbles independent of the appearance of the message in the chat window UI.
  • Class.TextChatService.OnChatWindowAdded - This callback should be defined on the client only. Use it to customize the appearance of chat messages in the chat window UI independent of the appearance of the message in chat bubbles.

Migrate from legacy chat

This section assists you in migrating from the legacy chat system by providing alternative methods for implementing common chat functionalities and behaviors using TextChatService.

To switch the chat system of an existing experience from the legacy chat system to TextChatService:

  1. In the Explorer window, select TextChatService.

  2. In the Properties window, find the ChatVersion dropdown and select TextChatService.

Basic functionalities

Though both systems share the same basic chat functionalities, TextChatService implementations are in general more sustainable and easier to iterate on.

Functionality Legacy chat TextChatService Differences
Send a chat message `Class.Players:Chat()` `Class.TextChannel:SendAsync()` The `Class.TextChatService:SendAsync()` method supports more advanced chat features, such as rich text formatting and message priority. It also includes built-in filtering to help prevent inappropriate messages from being sent.
Implement messaging callbacks `Class.Chat:InvokeChatCallback()`
`Class.Chat:RegisterChatCallback()`		 `Class.TextChatService.SendingMessage`
`Class.TextChatService.OnIncomingMessage`		 The legacy chat system binds a function to chat system events for delivering messages. The two methods of `TextChatService` offer better flexibility and customization.
Add custom chat commands `ChatService/ChatCommand` module `Class.TextChatCommand` `TextChatService` has a dedicated class for text commands rather than using a legacy chat module.
Display a system message `Class.StarterGui:SetCore()` using `ChatMakeSystemMessage` `Class.TextChannel:DisplaySystemMessage()` The `Class.TextChannel.OnIncomingMessage` callback can return a `Class.TextChatMessageProperties` instance to customize the message appearance.
Disable chat [Game Settings](../studio/game-settings.md) in Studio and `ChatWindow/ChatSettings` module for hiding the chat window `Class.ChatWindowConfiguration.Enabled`

Message filtering

TextChatService automatically filters chat messages based on each player's account information, so you don't need to manually implement text filtering for all kinds of chat messages.

Functionality Legacy chat TextChatService
Filter chat message for individual player `Class.Chat:FilterStringAsync()` Automatic
Filter broadcasting messages `Class.Chat:FilterStringForBroadcast()` Automatic

Window and bubble chat

Both the chat window and bubble chat behavior and customization options of TextChatService are identical to those of the legacy chat system. As the legacy chat system only allows customization using chat modules or the Class.Players container, TextChatService provides dedicated classes (Class.ChatWindowConfiguration and Class.BubbleChatConfiguration) to manage all chat window and bubble chat properties. Additionally, you can easily adjust and preview your bubble chat appearance and behavior properties using Studio settings instead of having to script them all.

Functionality Legacy chat TextChatService
Enable Chat Window `Class.Chat.LoadDefaultChat`
`Class.Players.ClassicChat`		 `Class.ChatWindowConfiguration.Enabled`
Enable Bubble Chat `Class.Chat.BubbleChatEnabled`
`Class.Players.BubbleChat`		 `Class.BubbleChatConfiguration.Enabled`
Set Chat Window Properties `Class.Players:SetChatStyle()` `Class.ChatWindowConfiguration`
Set Bubble Chat Properties `Class.Chat:SetBubbleChatSettings()`
`Class.Chat.BubbleChatSettingsChanged()`
`Class.Players.BubbleChat`
`Class.Players:SetChatStyle()`		 `Class.BubbleChatConfiguration`
Enable NPC Bubbles `Class.Chat:Chat()` `Class.TextChatService:DisplayBubble()`

Migrate speaker "extra data"

The legacy Lua chat system allowed devleopers to use SetExtraData on the Speaker class. This data was used to format the name color, chat color, or to apply name tags for a given speaker.

-- An example of setting extra data on a speaker in the legacy chat system
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 does not have a direct equivalent to SetExtraData. Instead, use TextChatService callbacks such as Class.TextChatService.OnWindowAdded to customize the appearance of messages using rich text based on the TextSource of the message.

The following is an example of emulating legacy Lua chat's "extra data" by access attributes on the TextSource's Class.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)

Then you can use the OnChatWindowAdded callback to customize the appearance of the chat window based on the attributes set on the player:

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