Engine

Customizing In-Experience Text Chat

The in-experience text chat system powered by TextChatService allows users to easily communicate and socialize with each other in live experiences. In addition to supporting the default text chat, you can customize the front-end user interface (UI) to improve your user engagement and immersion.

Chat Window Configuration

You can toggle appearance of the chat window and input bar in one of two ways:

  • Directly in Studio by toggling the Enabled property of the service's ChatWindowConfiguration and ChatInputBarConfiguration children.


  • Through scripting, from a LocalScript within StarterPlayerScripts.

    LocalScript

    local TextChatService = game:GetService("TextChatService")
    local chatWindowConfiguration = TextChatService:FindFirstChildOfClass("ChatWindowConfiguration")
    local chatInputBarConfiguration = TextChatService:FindFirstChildOfClass("ChatInputBarConfiguration")
    if chatWindowConfiguration then
    chatWindowConfiguration.Enabled = true
    end
    if chatInputBarConfiguration then
    chatInputBarConfiguration.Enabled = true
    end

By default, when enabling both the chat window and the chat bar, the chat bar attaches to the chat window on the UI. You can obtain their read-only properties on their positions and sizes and use them to calculate the total size of the combination:

Chat Window Customization

You can customize the default chat window to match your experience's UI layout, design, and style by using the following properties in Studio:

PropertyDescriptionDefault
Appearance
BackgroundColor3Background color of the chat window in Color3.[25, 27, 29]
BackgroundTransparencyTransparency of the chat window.0.3
FontFaceFont of chat text displayed on the chat window.Enum.Font.GothamMedium
TextColor3Color of chat text displayed on the chat window in Color3.[255, 255, 255]
TextSizeSize of chat text displayed on the chat window.14
TextStrokeColor3Chat text stroke color displayed on the chat window in Color3.[0, 0, 0]
TextStrokeTransparencyTransparency of chat text stroke displayed on the chat window.0.5
Behavior
HeightScaleHeight scale of the chat window relative to the screen size.1
WidthScaleWidth scale of the chat window relative to the screen size.1

Emoji and Command Autocomplete

By default, the text chat system shows autocomplete options for emojis and commands:

  • Emojis are autocompleted by typing : followed by non-whitespace characters.
  • Commands are autocompleted by typing /.

If you want to disable the autocomplete behavior, set the AutocompleteEnabled property to false through Studio UI or scripting.

Customizing Message Appearance

You can customize the appearance of chat message bodies and prefixes using rich text tags and TextChatService.OnIncomingMessage callbacks without overriding the existing UI. The customization options let you modify the appearance of chat messages to match your experience's theme, and you can also sort or highlight messages from different user groups by adding chat tags and coloring usernames.

Adding Chat Tags

If your experience has users with special attributes like VIP status, you can attach chat tags wrapped in brackets to the front of user messages to highlight their chat messages. The following LocalScript in StarterPlayerScripts examines all Player instances representing users in your experience and appends VIP chat tags for those with the IsVIP attribute.

LocalScript

local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")
TextChatService.OnIncomingMessage = function(message: TextChatMessage)
local properties = Instance.new("TextChatMessageProperties")
if message.TextSource then
local player = Players:GetPlayerByUserId(message.TextSource.UserId)
if player:GetAttribute("IsVIP") then
properties.PrefixText = "<font color='#F5CD30'>[VIP]</font> " .. message.PrefixText
end
end
return properties
end
VIP users' chat tags

Coloring Usernames

When a user sends a chat message, their username displays as the prefix portion of the message. By default, each user's name is colored according to their TeamColor but you can change the colors of chat usernames using TextChatService.OnIncomingMessage and font color tags. The following LocalScript in StarterPlayerScripts assigns a predetermined color to each user, picking randomly from a table of RGB colors.

LocalScript

local TextChatService = game:GetService("TextChatService")
local nameColors = {
Color3.fromRGB(255, 0, 0),
Color3.fromRGB(0, 255, 0),
Color3.fromRGB(0, 0, 255),
Color3.fromRGB(255, 255, 0),
}
TextChatService.OnIncomingMessage = function(textChatMessage: TextChatMessage)
local properties = Instance.new("TextChatMessageProperties")
local textSource = textChatMessage.TextSource
if textSource then
local index: number = (textSource.UserId % #nameColors) + 1
local randomColor: Color3 = nameColors[index]
properties.PrefixText = string.format("<font color='#%s'>%s</font>", randomColor:ToHex(), textChatMessage.PrefixText)
end
return properties
end

Customizing Translated Messages

By default, Roblox automatically translates text chat messages based on users' language settings. To apply message customizations to translated messages, use the TextChatMessage.Translation property. The following example, a Script in ReplicatedStorage with its Enum.RunContext property as Client, sets the font color of translated messages to the same color as untranslated messages.

Script

local TextChatService = game:GetService("TextChatService")
local FONT_COLOR = "#FF007F"
local FORMAT_STRING = `<font color='{FONT_COLOR}'>%s</font>`
local function onIncomingChatMessage(textChatMessage: TextChatMessage)
local properties = Instance.new("TextChatMessageProperties")
properties.Text = string.format(FORMAT_STRING, textChatMessage.Text)
if textChatMessage.Translation then
properties.Translation = string.format(FORMAT_STRING, textChatMessage.Translation)
end
return properties
end
TextChatService.OnIncomingMessage = onIncomingChatMessage

Adding Chat Bubbles

In addition to displaying messages on the chat window, you can add and customize chat bubbles above user avatars and NPC characters for immersive engagement. For more information, see Bubble Chat.