- 
- 
-2. In the [Properties](../studio/properties.md) window, check the **Enabled** checkbox under the **Behavior** category.
+2. In the [Properties](../studio/properties.md) window, check the `Class.BubbleChatConfiguration.Enabled|Enabled` checkbox.
## Bubble Customization
-After enabling bubble chat, you can customize the appearance and behavior of your chat bubbles to match your experience theme. Use the [Properties](../studio/properties.md) window of **BubbleChatConfiguration** for [basic](#basic-customization) changes like text color and spacing. For [advanced](#advanced-customization) customization, such as adding background images for bubbles, add UI objects as children of **BubbleChatConfiguration** and then modify these objects.
+After enabling bubble chat, you can customize the appearance and behavior of your chat bubbles to match your experience theme. Use the [Properties](../studio/properties.md) window of `Class.BubbleChatConfiguration` for [basic](#basic-customization) changes like text color and spacing, or implement [advanced](#advanced-customization) customization for bubble background images and other visual adjustments.
@@ -31,8 +31,8 @@ Alternatively, you can add a `Class.LocalScript` in `Class.StarterPlayerScripts`
The following table shows common bubble chat customization properties. For a full list of customization properties, see `Class.BubbleChatConfiguration`.
-#### Appearance
-
+| `Class.BubbleChatConfiguration.BackgroundColor3|BackgroundColor3` | Background color of bubbles in `Datatype.Color3`. | -[250, 250, 250] | +|
| `Class.BubbleChatConfiguration.FontFace|FontFace` | `Datatype.Font` of the bubble text. | -`Enum.Font|GothamMedium` | +`Enum.Font.BuilderSansMedium|BuilderSansMedium` |
| `Class.BubbleChatConfiguration.TextColor3|TextColor3` | Color of bubble text in `Datatype.Color3`. | -[57, 59, 61] | +`[57, 59, 61]` |
| `Class.BubbleChatConfiguration.TextSize|TextSize` | Size of bubble text. | -16 | +`16` |
| `Class.BubbleChatConfiguration.AdorneeName|AdorneeName` | String name of the body part or `Class.Attachment` that bubbles attach to; if multiple instances of the same name exist, the system attaches to the first instance found. | -HumanoidRootPart | +`HumanoidRootPart` |
| `Class.BubbleChatConfiguration.BubbleDuration|BubbleDuration` | Time before a bubble fades out, in seconds. | -30 | +`30` |
| `Class.BubbleChatConfiguration.BubblesSpacing|BubblesSpacing` | Vertical space between stacked bubbles, in pixels. | -6 | +`6` |
| `Class.BubbleChatConfiguration.LocalPlayerStudsOffset|LocalPlayerStudsOffset` | If adorned to the local player, the offset of bubbles in studs from their adornee, relative to the camera orientation (`Datatype.Vector3`). | -(0, 0, 0) | +`(0, 0, 0)` |
| `Class.BubbleChatConfiguration.MaxDistance|MaxDistance` | Maximum distance from the camera that bubbles are shown. | -100 | +`100` |
| `Class.BubbleChatConfiguration.MinimizeDistance|MinimizeDistance` | Distance from the camera when bubbles turn into a single bubble with an ellipsis (**⋯**) to indicate chatter. | -40 | +`40` |
| `Class.BubbleChatConfiguration.VerticalStudsOffset|VerticalStudsOffset` | Extra space between bubbles and their adornee, in studs. | -0 | +`0` |
| `Class.BubbleChatConfiguration.MaxBubbles|MaxBubbles` | Maximum number of bubbles displayed before older bubbles disappear. | -3 | +`3` |
-
-The following tables include all available properties for customization:
+
-| `Class.ImageLabel.ImageColor3|ImageColor3` | Color tint of the bubble background image in `Datatype.Color3`. | -[255, 255, 255] | +||
| `Class.ImageLabel.ImageRectOffset|ImageRectOffset` | Offset of the image area to be displayed from the top-left in pixels. | -(0, 0) | +`(0, 0)` | |
| `Class.ImageLabel.ImageRectSize|ImageRectSize` | -Size of the image area to be displayed in pixels. To display the entire image, set either dimension to 0. | -(0, 0) | +Size of the image area to be displayed in pixels. To display the entire image, set either dimension to `0`. | +`(0, 0)` |
| `Class.ImageLabel.ScaleType|ScaleType` | @@ -208,23 +215,22 @@ The following tables include all available properties for customization:||||
| `Class.ImageLabel.SliceCenter|SliceCenter` | Slice boundaries of the image if the image is a 9-sliced image. Only applicable when you set `Class.ImageLabel.ScaleType|ScaleType` as `Enum.ScaleType|Slice`. | -(0, 0, 0, 0) | +`(0, 0, 0, 0)` | |
| `Class.ImageLabel.SliceScale|SliceScale` | Scale ratio of slice edges if the image is a 9-sliced image. Only applicable when you set `Class.ImageLabel.ScaleType|ScaleType` as `Enum.ScaleType|Slice`. | -1 | +`1` | |
| `Class.ImageLabel.TileSize|TileSize` | Tiling size of the image. Only applicable when you set `Class.ImageLabel.ScaleType|ScaleType` as `Enum.ScaleType|Tile`. | -(1, 0, 1, 0) | +`(1, 0, 1, 0)` |
| `Class.UIGradient.Color|Color` | Color of the background gradient. | -[250, 250, 250] | +|
| `Class.UIGradient.Offset|Offset` | Scalar translation of the gradient from the center of the bubble. | -(0, 0) | +`(0, 0)` |
| `Class.UIGradient.Rotation|Rotation` | Clockwise rotation, in degrees, of the gradient starts from left to right. | -0 | +`0` |
| `Class.UIGradient.Transparency|Transparency` | Transparency of the background gradient. | -(1, 0) | +`(1, 0)` |
| `Class.UICorner.CornerRadius|CornerRadius` | Radius of the bubble corner shape in pixels. | -(0, 12) | +
| `Class.UIPadding.PaddingBottom|PaddingBottom` | Padding on the bottom. | -`UDim.new(0,8)` | +`Datatype.UDim.new(0,8)` | |
| `Class.UIPadding.PaddingLeft|PaddingLeft` | ->Padding on the left. | -`UDim.new(0,8)` | +Padding on the left. | +`Datatype.UDim.new(0,8)` |
| `Class.UIPadding.PaddingRight|PaddingRight` | Padding on the right. | -`UDim.new(0,8)` | +`Datatype.UDim.new(0,8)` | |
| `Class.UIPadding.PaddingTop|PaddingTop` | Padding on the top. | -`UDim.new(0,8)` | +`Datatype.UDim.new(0,8)` |
| `Class.BubbleChatConfiguration.BackgroundColor3|BackgroundColor3` | Background color of bubbles in `Datatype.Color3`. | -(250, 250, 250) | +`(250, 250, 250)` |
| `Class.BubbleChatConfiguration.BackgroundTransparency|BackgroundTransparency` | Background transparency of bubbles. | -0.1 | +`0.1` |
| `Class.BubbleChatConfiguration.FontFace|FontFace` | `Datatype.Font` of the bubble text. | -`Enum.Font|GothamMedium` | +`Enum.Font.BuilderSansMedium|BuilderSansMedium` |
| `Class.BubbleChatConfiguration.TextColor3|TextColor3` | Color of bubble text in `Datatype.Color3`. | -[57, 59, 61] | +`[57, 59, 61]` |
| `Class.BubbleChatConfiguration.TextSize|TextSize` | Size of bubble text. | -16 | +`16` |
-
-
-
+| Default Channel | +Tab Name | +
|---|---|
| **RBXGeneral** | +**General** | +
| **RBXSystem** | +**General** (combined into a single tab with **RBXGeneral**) | +
| **RBXTeam** | +**Team** | +
| **RBXWhisper** | +User name 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` | +|
| `Class.ChatWindowConfiguration.HorizontalAlignment|HorizontalAlignment` | +Horizontal alignment of the chat window. | +`Enum.HorizontalAlignment.Left|Left` | |||
| **Behavior** | +`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` | ||
-You can customize the appearance of chat message bodies and prefixes using [rich text](../ui/rich-text.md) tags and `Class.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](#adding-chat-tags) and [coloring usernames](#coloring-usernames).
+| 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` | +
-```lua title='LocalScript' highlight='4,5,9-11'
-local TextChatService = game:GetService("TextChatService")
-local Players = game:GetService("Players")
+| 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 User Names
-### Coloring Usernames
+When a user sends a chat message, their `Class.Player.DisplayName|DisplayName` displays as the **prefix** portion of the message. By default, each user's name is colored according to their `Class.Player.TeamColor` but you can change the colors of chat names using `Class.ChatWindowMessageProperties|ChatWindowMessageProperties` and `Class.TextChatService.OnChatWindowAdded|OnChatWindowAdded`. The following `Class.LocalScript` in `Class.StarterPlayerScripts` assigns a predetermined color to each user, picking randomly from a table of RGB 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.
+
-```lua title='LocalScript' hightlight='10,11,17'
+```lua title="LocalScript - Random User Name Colors"
local TextChatService = game:GetService("TextChatService")
+local chatWindowConfiguration = TextChatService.ChatWindowConfiguration
+
local nameColors = {
Color3.fromRGB(255, 0, 0),
Color3.fromRGB(0, 255, 0),
@@ -168,58 +305,165 @@ local nameColors = {
Color3.fromRGB(255, 255, 0),
}
-TextChatService.OnIncomingMessage = function(textChatMessage: TextChatMessage)
- local properties = Instance.new("TextChatMessageProperties")
+TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
+ local properties = chatWindowConfiguration:DeriveNewMessageProperties()
- local textSource = textChatMessage.TextSource
+ local textSource = message.TextSource
if textSource then
local index: number = (textSource.UserId % #nameColors) + 1
local randomColor: Color3 = nameColors[index]
- properties.PrefixText = string.format("%s", randomColor:ToHex(), textChatMessage.PrefixText)
+
+ properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
+ properties.PrefixTextProperties.TextColor3 = randomColor
end
return properties
end
```
-### Customizing Translated Messages
+You can also apply color and transparency gradients to color message prefixes using `Class.UIGradient`.
-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="Gradient User Name Colors"
local TextChatService = game:GetService("TextChatService")
-local FONT_COLOR = "#FF007F"
-local FORMAT_STRING = `%s`
+local chatWindowConfiguration = TextChatService.ChatWindowConfiguration
-local function onIncomingChatMessage(textChatMessage: TextChatMessage)
- local properties = Instance.new("TextChatMessageProperties")
+local gradient = Instance.new("UIGradient")
+gradient.Color = ColorSequence.new{
+ ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 0, 0)),
+ ColorSequenceKeypoint.new(0.5, Color3.fromRGB(255, 255, 0)),
+ ColorSequenceKeypoint.new(1, Color3.fromRGB(255, 0, 255))
+}
- properties.Text = string.format(FORMAT_STRING, textChatMessage.Text)
-
- if textChatMessage.Translation ~= nil and textChatMessage.Translation ~= "" then
- properties.Translation = string.format(FORMAT_STRING, textChatMessage.Translation)
+TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
+ local properties = chatWindowConfiguration:DeriveNewMessageProperties()
+
+ local textSource = message.TextSource
+ if textSource then
+ properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
+ gradient:Clone().Parent = properties.PrefixTextProperties
end
return properties
end
+```
+
+### Adding Chat Tags
+
+If your experience has users with special [attributes](../studio/properties.md#instance-attributes) like VIP status, you can attach **chat tags** wrapped in brackets to the front of user messages to highlight their messages. The following `Class.LocalScript` in `Class.StarterPlayerScripts` examines all `Class.Player` instances representing users in your experience and appends VIP chat tags to those with the `IsVIP` attribute.
+
+
+
+```lua title="Appending Chat Tags"
+local TextChatService = game:GetService("TextChatService")
+local Players = game:GetService("Players")
-TextChatService.OnIncomingMessage = onIncomingChatMessage
+local chatWindowConfiguration = TextChatService.ChatWindowConfiguration
+
+TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
+ local properties = chatWindowConfiguration:DeriveNewMessageProperties()
+
+ if message.TextSource then
+ local player = Players:GetPlayerByUserId(message.TextSource.UserId)
+ if player:GetAttribute("IsVIP") then
+ properties.PrefixText = "[VIP] " .. message.PrefixText
+
+ properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
+ properties.PrefixTextProperties.TextColor3 = Color3.fromRGB(255, 125, 50)
+ end
+ end
+
+ return properties
+end
```
-## Displaying System Messages
+### Rich Text Customization
+
+Rich text [font color tags](../ui/rich-text.md#supported-tags) can be used to format chat messages, helpful if you want to apply formatting to very specific parts of the message. Note that rich text does not support gradients, but the following code sample shows how you can move the user name (stored in `Class.TextChatMessage.PrefixText`) into the message body and then apply rich text tagging to only the name portion.
-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.
+
-```lua title='LocalScript'
+```lua title="Rich Text Customization"
+local TextChatService = game:GetService("TextChatService")
+local Players = game:GetService("Players")
+
+local chatWindowConfiguration = TextChatService.ChatWindowConfiguration
+
+local gradient = Instance.new("UIGradient")
+gradient.Color = ColorSequence.new{
+ ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 0, 0)),
+ ColorSequenceKeypoint.new(0.5, Color3.fromRGB(255, 255, 0)),
+ ColorSequenceKeypoint.new(1, Color3.fromRGB(255, 0, 255))
+}
+
+TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
+ local properties = chatWindowConfiguration:DeriveNewMessageProperties()
+
+ if message.TextSource then
+ properties.PrefixText = "[VIP]"
+ properties.Text = string.format("%s", message.PrefixText) .. " " .. message.Text
+
+ properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
+ gradient:Clone().Parent = properties.PrefixTextProperties
+ end
+
+ return properties
+end
+```
+
+## Sending Messages from Non‑Player Sources
+
+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.
+
+### 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 |