- 
- 
-
-
-
- if chatWindowConfiguration then
- chatWindowConfiguration.Enabled = true
- end
- if chatInputBarConfiguration then
- chatInputBarConfiguration.Enabled = true
- end
- ```
+### Scripting
-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:
+In a client script within `Class.StarterPlayerScripts`, enable each component as desired:
-- `Class.ChatWindowConfiguration.AbsolutePosition`
-- `Class.ChatWindowConfiguration.AbsoluteSize`
-- `Class.ChatInputBarConfiguration.AbsolutePosition`
-- `Class.ChatInputBarConfiguration.AbsoluteSize`
+```lua title='Client Script'
+local TextChatService = game:GetService("TextChatService")
+
+local ChatWindowConfiguration = TextChatService:FindFirstChildOfClass("ChatWindowConfiguration")
+local ChatInputBarConfiguration = TextChatService:FindFirstChildOfClass("ChatInputBarConfiguration")
+local ChannelTabsConfiguration = TextChatService:FindFirstChildOfClass("ChannelTabsConfiguration")
+
+-- Enable chat window
+if ChatWindowConfiguration then
+ ChatWindowConfiguration.Enabled = true
+end
+-- Enable input bar
+if ChatInputBarConfiguration then
+ ChatInputBarConfiguration.Enabled = true
+end
+-- Enable channel tabs
+if ChannelTabsConfiguration then
+ ChannelTabsConfiguration.Enabled = true
+end
+```
-### Chat Window Customization
+When `Class.ChannelTabsConfiguration` is enabled, each **default** `Class.TextChannel` will appear in a tab as outlined in the following table. In addition, each **custom** `Class.TextChannel` will create a tab corresponding to the channel's `Class.Instance.Name|Name` property.
+
+| Default Channel | +Tab Name | +
|---|---|
| **RBXGeneral** | +**General** | +
| **RBXSystem** | +**General** (combined into a single tab with **RBXGeneral**) | +
| **RBXTeam** | +**Team** | +
| **RBXWhisper** | +Username of other player | +
| **Appearance** | -|||||
| `Class.ChatWindowConfiguration.BackgroundColor3|BackgroundColor3` | -Background color of the chat window in `Datatype.Color3`. | +`Datatype.Color3` background color of the chat window. | `[25, 27, 29]` | ||
| `Class.ChatWindowConfiguration.BackgroundTransparency|BackgroundTransparency` | -Transparency of the chat window. | -0.3 | +Transparency of the chat window's background. | +`0.3` | |
| `Class.ChatWindowConfiguration.FontFace|FontFace` | -`Datatype.Font` of chat text displayed on the chat window. | -`Enum.Font.GothamMedium` | +`Datatype.Font` of chat window text. | +`Enum.Font.BuilderSansMedium|BuilderSansMedium` | |
| `Class.ChatWindowConfiguration.TextColor3|TextColor3` | -Color of chat text displayed on the chat window in `Datatype.Color3`. | +`Datatype.Color3` of chat window text. | `[255, 255, 255]` | ||
| `Class.ChatWindowConfiguration.TextSize|TextSize` | -Size of chat text displayed on the chat window. | +Size of chat window text. | `14` | ||
| `Class.ChatWindowConfiguration.TextStrokeColor3|TextStrokeColor3` | -Chat text stroke color displayed on the chat window in `Datatype.Color3`. | +`Datatype.Color3` of the stroke for chat window text. | `[0, 0, 0]` | ||
| `Class.ChatWindowConfiguration.TextStrokeTransparency|TextStrokeTransparency` | -Transparency of chat text stroke displayed on the chat window. | -0.5 | +Transparency of the stroke for chat window text. | +`0.5` | |
| **Behavior** | +`Class.ChatWindowConfiguration.HorizontalAlignment|HorizontalAlignment` | +Horizontal alignment of the chat window. | +`Enum.HorizontalAlignment.Left|Left` | +||
| `Class.ChatWindowConfiguration.VerticalAlignment|VerticalAlignment` | +Vertical alignment of the chat window. | +`Enum.VerticalAlignment.Top|Top` | |||
| `Class.ChatWindowConfiguration.HeightScale|HeightScale` | Height scale of the chat window relative to the screen size. | -1 | +`1` | ||
| `Class.ChatWindowConfiguration.WidthScale|WidthScale` | Width scale of the chat window relative to the screen size. | -1 | +`1` | +||
+
+| Property | +Description | +Default | +
|---|---|---|
| `Class.ChatInputBarConfiguration.BackgroundColor3|BackgroundColor3` | +`Datatype.Color3` background color of the chat input bar. | +`[25, 27, 29]` | +
| `Class.ChatInputBarConfiguration.BackgroundTransparency|BackgroundTransparency` | +Transparency of the chat input bar's background. | +`0.2` | +
| `Class.ChatInputBarConfiguration.FontFace|FontFace` | +`Datatype.Font` of chat input text. | +`Enum.Font.BuilderSansMedium|BuilderSansMedium` | +
| `Class.ChatInputBarConfiguration.PlaceholderColor3|PlaceholderColor3` | +`Datatype.Color3` of placeholder chat input text. | +`[178, 178, 178]` | +
| `Class.ChatInputBarConfiguration.TextColor3|TextColor3` | +`Datatype.Color3` of player-entered chat input text. | +`[255, 255, 255]` | +
| `Class.ChatInputBarConfiguration.TextSize|TextSize` | +Size of chat input text. | +`14` | +
| `Class.ChatInputBarConfiguration.TextStrokeColor3|TextStrokeColor3` | +`Datatype.Color3` stroke color of chat input text. | +`[0, 0, 0]` | +
| `Class.ChatInputBarConfiguration.TextStrokeTransparency|TextStrokeTransparency` | +Transparency of the stroke for chat input text. | +`0.5` | +
| `Class.ChatInputBarConfiguration.AutocompleteEnabled|AutocompleteEnabled` | +Whether the text chat system shows autocomplete options for emojis and [commands](../chat/in-experience-text-chat.md#creating-custom-commands). Emojis are autocompleted by typing `:` followed by non-whitespace characters, while commands are autocompleted by typing `/`. | +`true` | +
| `Class.ChatInputBarConfiguration.KeyboardKeyCode|KeyboardKeyCode` | +Additional key players can press to trigger focusing on the default chat input bar. | +`Enum.KeyCode.Slash|Slash` |
-If you want to disable the autocomplete behavior, set the **AutocompleteEnabled** property to false through Studio UI or scripting.
+| Property | +Description | +Default | +
|---|---|---|
| `Class.ChannelTabsConfiguration.BackgroundColor3|BackgroundColor3` | +`Datatype.Color3` background color of the channel tabs. | +`[25, 27, 29]` | +
| `Class.ChannelTabsConfiguration.BackgroundTransparency|BackgroundTransparency` | +Transparency of the channel tabs' background. | +`0` | +
| `Class.ChannelTabsConfiguration.HoverBackgroundColor3|HoverBackgroundColor3` | +`Datatype.Color3` background color of tabs when hovering over them. | +`[125, 125, 125]` | +
| `Class.ChannelTabsConfiguration.FontFace|FontFace` | +`Datatype.Font` for the text in channel tabs. | +`Enum.Font.BuilderSansBold|BuilderSansBold` | +
| `Class.ChannelTabsConfiguration.TextColor3|TextColor3` | +`Datatype.Color3` of text in an unselected tab. | +`[175, 175, 175]` | +
| `Class.ChannelTabsConfiguration.SelectedTabTextColor3|SelectedTabTextColor3` | +`Datatype.Color3` of text in a selected tab. | +`[255, 255, 255]` | +
| `Class.ChannelTabsConfiguration.TextSize|TextSize` | +Size of the text in channel tabs. | +`18` | +
| `Class.ChannelTabsConfiguration.TextStrokeColor3|TextStrokeColor3` | +`Datatype.Color3` stroke color of the text in channel tabs. | +`[0, 0, 0]` | +
| `Class.ChannelTabsConfiguration.TextStrokeTransparency|TextStrokeTransparency` | +Transparency of the stroke for text in channel tabs. | +`1` | +
+
-### Coloring Usernames
+### Username Colors
-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 `Class.Team.TeamColor|TeamColor` but you can change the colors of chat usernames using `Class.TextChatService.OnIncomingMessage` and [font color tags](../ui/rich-text.md#supported-tags). The following `Class.LocalScript` in `Class.StarterPlayerScripts` assigns a predetermined color to each user, picking randomly from a table of RGB colors.
+When a player sends a chat message, their username displays as the prefix portion of the message. By default, each player's name is colored according to their `Class.Team.TeamColor|TeamColor` but you can change the colors of chat usernames using `Class.TextChatService.OnIncomingMessage` and [font color tags](../ui/rich-text.md#supported-tags). The following client script in `Class.StarterPlayerScripts` assigns a predetermined color to each player, picking randomly from a table of RGB colors.
-```lua title='LocalScript' hightlight='10,11,17'
+```lua title='Client Script' hightlight='10,11,17'
local TextChatService = game:GetService("TextChatService")
local nameColors = {
@@ -182,11 +341,11 @@ TextChatService.OnIncomingMessage = function(textChatMessage: TextChatMessage)
end
```
-### Customizing Translated Messages
+### Chat Translations
By default, Roblox [automatically translates](../production/localization/automatic-translations.md) text chat messages based on users' language settings. To apply message customizations to translated messages, use the `Class.TextChatMessage.Translation` property. The following example, a `Class.Script` in `Class.ReplicatedStorage` with its `Enum.RunContext` property as `Enum.RunContext|Client`, sets the font color of translated messages to the same color as untranslated messages.
-```lua title='Script'
+```lua title='Client Script'
local TextChatService = game:GetService("TextChatService")
local FONT_COLOR = "#FF007F"
@@ -207,19 +366,57 @@ end
TextChatService.OnIncomingMessage = onIncomingChatMessage
```
-## Displaying System Messages
+## Sending Messages from Non‑Player Sources
-Through `Class.TextChannel:DisplaySystemMessage()`, you can display a system-like message, useful for greeting users or alerting them when an in-experience event is happening.
+In certain design scenarios, you may want to show non‑player dialogue in the chat window, such as "speech" from a public address system or a non‑player character.
-```lua title='LocalScript'
+### System
+
+To deliver an unstyled system message to the local player, simply call `Class.TextChannel:DisplaySystemMessage()|DisplaySystemMessage()` from the default **RBXGeneral** channel with a prefix before the player's display name.
+
+```lua title='Client Script'
local Players = game:GetService("Players")
local TextChatService = game:GetService("TextChatService")
-local generalChannel = TextChatService.TextChannels.RBXGeneral
+local player = Players.LocalPlayer
+local generalChannel: TextChannel = TextChatService:WaitForChild("TextChannels").RBXGeneral
+
+local PREFIX = "[Guide] Welcome "
-generalChannel:DisplaySystemMessage("[Server] Hello " .. Players.LocalPlayer.Name)
+-- Send "system message" to player with their display name appended
+generalChannel:DisplaySystemMessage(PREFIX .. player.DisplayName)
```
-## Adding Chat Bubbles
+
+
+### NPC/Object
+
+You can also stylize non-player dialogue and add [chat bubbles](../chat/bubble-chat.md) to make it appear like messages are coming from an NPC or object within the 3D world.
+
+```lua title='Client Script'
+local TextChatService = game:GetService("TextChatService")
+
+local generalChannel: TextChannel = TextChatService:WaitForChild("TextChannels").RBXGeneral
+
+TextChatService.OnIncomingMessage = function(textChatMessage: TextChatMessage)
+ local properties = Instance.new("TextChatMessageProperties")
+
+ -- Check for system messages that contain metadata
+ if not textChatMessage.TextSource and textChatMessage.Metadata ~= "" then
+
+ -- Add prefix to make message look like it was sent by a player
+ properties.PrefixText = string.format("%s: ", "#50C999", textChatMessage.Metadata)
+
+ -- Add bubble chat
+ TextChatService:DisplayBubble(workspace.Statue, textChatMessage.Text)
+ end
+
+ return properties
+end
+
+local message = "Welcome! I will be your guide."
+local speakerName = "Ancient Knight"
+generalChannel:DisplaySystemMessage(message, speakerName)
+```
-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](../chat/bubble-chat.md).
+
diff --git a/content/en-us/chat/in-experience-text-chat.md b/content/en-us/chat/in-experience-text-chat.md
index 15a8389d6..4b415017c 100644
--- a/content/en-us/chat/in-experience-text-chat.md
+++ b/content/en-us/chat/in-experience-text-chat.md
@@ -1,37 +1,37 @@
---
-title: In-Experience Text Chat System
-description: The in-experience text chat system allows users to communicate with each other using text-based messages in live sessions.
+title: In-Experience Text Chat
+description: The in-experience text chat system allows players to communicate with each other using text-based messages in live sessions.
---
-With the **in-experience text chat** system on Roblox, you can allow users to communicate with each other using text-based messages in live sessions. The system provides a set of methods and events for extending and customizing chat functionalities for enhanced user immersion and engagement, such as delivering messages based on customized requirements, adding special permissions or moderation to specific users, and creating custom commands to execute specific actions.
+With the **in-experience text chat** system on Roblox, players can communicate with each other using text-based messages in live sessions. The system provides a set of methods and events for extending and customizing chat functionalities, such as delivering messages based on [customized requirements](#customizing-message-delivery-behaviors), adding special permissions or moderation to specific players, and creating [custom commands](#creating-custom-commands) to execute specific actions.
-This guide covers the chat workflow and the usage of APIs for extending the functionalities of the in-experience text chat system. For more information on customizing the chat User Interface (UI), see [Customizing In-Experience Text Chat](../chat/customizing-in-experience-text-chat.md).
+This guide covers the chat workflow and approaches for extending the functionalities of the chat system. For more information on customizing the chat user interface (UI), see [Customizing Text Chat](../chat/customizing-in-experience-text-chat.md).
-## Chat APIs and Workflow
+## Chat Workflow
-The in-experience text chat system consists of both mutable APIs that you can extend for customized chat delivery behaviors and immutable data objects representing certain chat elements returned by mutable APIs.
+The in-experience text chat system consists of both [mutable classes](#mutable-chat-classes) that you can extend for customized chat delivery behaviors and [immutable data objects](#immutable-chat-objects) representing certain chat elements returned by mutable classes.
-### Mutable Chat APIs
+### Mutable Chat Classes
-The in-experience text chat system provides the following mutable APIs:
+The in-experience text chat system provides the following mutable classes:
-- `Class.TextChatService` — This singleton class is responsible for managing the overall chat system, including handling chat message filtering, moderation, and user permissions. Accessible from the server, it provides a set of methods and events that other text chat APIs or user actions can invoke through the chat delivery workflow.
-- `Class.TextChannel` — This class represents a text chat channel that passes user-sent chat messages from the client to the server and displays them to other users based on permissions. You can use it to create, modify, and manage text channels in your experience. Additionally, you can create multiple text channels to group users together for chat purposes, such as allowing users to chat with their group members that are not visible to others.
-- `Class.TextChatCommand` — This class enables you to create custom chat commands that allow users to invoke specific actions or behaviors by typing special characters followed by a command name. Chat commands are helpful for adding additional functionality and interactivity to the chat experience. You can also use them to create admin commands to manage and moderate your experience with shortcuts.
+- `Class.TextChatService` — This singleton class is responsible for managing the overall chat system, including handling chat message filtering, moderation, and user permissions. Accessible from the server, it provides a set of methods and events that other text chat APIs or player actions can invoke through the chat delivery workflow.
+- `Class.TextChannel` — This class represents a text chat channel that passes player-sent chat messages from the client to the server and displays them to other players based on permissions. You can use it to create, modify, and manage text channels in your experience. Additionally, you can create multiple text channels to group players together for chat purposes, such as allowing players to chat with their group members that are not visible to others.
+- `Class.TextChatCommand` — This class enables you to create custom chat commands that allow players to invoke specific actions or behaviors by typing special characters followed by a command name. Chat commands are helpful for adding additional functionality and interactivity to the chat experience. You can also use them to create admin commands to manage and moderate your experience with shortcuts.
### Immutable Chat Objects
The in-experience text chat system includes the following immutable objects with read-only properties that you can't modify:
- `Class.TextChatMessage`: This object represents a single chat message in a text chat channel with basic information such as the sender of the message, the original message, the filtered message, and the creation timestamp.
-- `Class.TextSource`: This object represents a message sender in a text chat channel with detailed permissions of a user in the channel. If a user is in multiple text chat channels, they can have multiple text sources as well.
+- `Class.TextSource`: This object represents a message sender in a text chat channel with detailed permissions of a player in the channel. If a player is in multiple text chat channels, they can have multiple text sources as well.
-### Text Chat Workflow
+### Chat Flowchart
-Through the chat message sending and delivering process, methods, callbacks, and events of mutable chat classes carrying immutable chat objects take place on three sides of the client-server model:
+Through the chat message sending and delivery process, methods, callbacks, and events of mutable chat classes work alongside immutable chat objects on three sides of the [client‑server](../projects/client-server.md) model:
-- The sending client, which is the local device of a user sending a message.
-- Receiving clients, which are other users' local devices.
+- The sending client, which is the local device of a player sending a message.
+- Receiving clients, which are other players' local devices.
- The server, which is the central processor for receiving the message from the sending client and handles the delivery to receiving clients.
+ 
1. Set its **PrimaryAlias** property to `/super` and its **SecondaryAlias** to `/mini`.
@@ -163,7 +159,7 @@ To switch the chat system of an existing experience from the legacy chat system
-### Basic Chat Functionalities
+### Basic Functionalities
Though both systems share the same basic chat functionalities, the in-experience text chat system implementations are in general more sustainable and easier to iterate on.
@@ -209,9 +205,9 @@ Though both systems share the same basic chat functionalities, the in-experience
-### Chat Message Filtering
+### Message Filtering
-The in-experience text chat system automatically filters chat messages based on each user's account information, so you don't need to manually implement text filtering for all kinds of chat messages.
+The in-experience text chat system 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.
| Filter Message for Individual User | +Filter Message for Individual Player | `Class.Chat:FilterStringAsync()` | n/a |
| Property | +Description | +
|---|---|
| `Class.UIDragDetector.SelectionModeDragSpeed|SelectionModeDragSpeed` | +Defines the maximum drag speed for translation as a combination of `Datatype.UDim.Scale|Scale` and `Datatype.UDim.Offset|Offset` of the first ancestor `Class.ScreenGui` or `Class.SurfaceGui` the `Class.UIDragDetector` belongs to. | +
| `Class.UIDragDetector.SelectionModeRotateSpeed|SelectionModeRotateSpeed` | +Defines the maximum angle per second at which the `Class.UIDragDetector` can rotate. | +
| `Class.UIDragDetector.UIDragSpeedAxisMapping|UIDragSpeedAxisMapping` | +Determines the **X**/**Y** dimension dragging speeds, based on the detector's `Class.UIDragDetector.SelectionModeDragSpeed|SelectionModeDragSpeed`. The default is `Enum.UIDragSpeedAxisMapping.XY|XY`, meaning the **X** and **Y** axis speeds are based off the **X** and **Y** `Datatype.UDim.Scale|Scale`/`Datatype.UDim.Offset|Offset` values respectively. Alternatives are `Enum.UIDragSpeedAxisMapping|XX` and `Enum.UIDragSpeedAxisMapping|YY`, meaning both the **X** and **Y** axis speeds are based off the **X** (`Enum.UIDragSpeedAxisMapping|XX`) or **Y** (`Enum.UIDragSpeedAxisMapping|YY`) axis for `Datatype.UDim.Scale|Scale`, while the `Datatype.UDim.Offset|Offset` values still apply to their respective axis. For example, if the first ancestor `Class.ScreenGui` is sized 800×600 and `Class.UIDragDetector.SelectionModeDragSpeed|SelectionModeDragSpeed` is |
+