| title | description |
|---|---|
Migrating from Legacy Chat to In-Experience Text Chat |
Explains how to migrate from the Legacy Chat System to the more modern and safe In-Experience Text Chat system. |
The in-experience text chat system offers simplified implementations and modern user interface (UI) of the same feature set as the legacy chat system, providing a more robust and flexible solution for supporting and extending chat in your experience. With this system, you no longer need to fork the chat system manually to add customization and chat commands. Instead, you can simply use engine API classes or the Studio settings to support your chat functionalities.
This guide assists you in migrating from the legacy chat system by providing alternative methods for implementing common chat functionalities and behaviors using the in-experience text chat system.
When creating a new experience, the in-experience text chat system is automatically enabled as the default chat system. To switch the chat system of an existing experience from the legacy chat system to the in-experience text chat system:
-
In the Explorer window, select TextChatService.
-
In the Properties window, find the ChatVersion dropdown and select TextChatService.
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.
| Functionality | Legacy Chat | In-Experience Text Chat | 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 the in-experience text chat system have more flexibilities and customization options. |
| Add custom chat commands | `ChatService/ChatCommand` module | `Class.TextChatCommand` | The in-experience text chat system has a dedicated class representing a text command for customization rather than using a legacy chat module. |
| Display a system message | Custom admin command library | `Class.TextChannel:DisplaySystemMessage()` | |
| Disable chat | Game Settings in Studio and `ChatWindow/ChatSettings` module for hiding the chat window | `Class.ChatWindowConfiguration.Enabled` |
The in-experience text chat system can automatically filter 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.
| Functionality | Legacy Chat | In-Experience Text Chat | Differences |
|---|---|---|---|
| Filter message for individual user | `Class.Chat:FilterStringAsync()` | `Class.TextChannel:SendAsync()` | No need to manually filter chat messages using the in-experience text chat system. |
| Filter broadcasting messages | `Class.Chat:FilterStringForBroadcast()` |
Both the chat window and bubble chat behavior and customization options of the in-experience text chat system 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, the in-experience text chat system provides dedicated classes, Class.ChatWindowConfiguration and Class.BubbleChatConfiguration, to manage all chat window and bubble chat properties respectively. 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 | In-Experience Text Chat |
|---|---|---|
| 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()` |