Migrating from Legacy Chat to In-Experience Text Chat

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.

Enabling Text Chat

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:

  1. In the Explorer window, select TextChatService.

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

Basic Chat 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.

FunctionalityLegacy ChatIn-Experience Text ChatDifferences
Send a chat messagePlayers:Chat()TextChannel:SendAsync()The 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 callbacksChat:InvokeChatCallback(), Chat:RegisterChatCallback()TextChatService.SendingMessage, TextChatService.OnIncomingMessageThe 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 commandsChatService/ChatCommand moduleTextChatCommandThe 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 messageCustom admin command libraryTextChannel:DisplaySystemMessage()
Disable chatGame Settings in Studio and ChatWindow/ChatSettings module for hiding the chat windowChatWindowConfiguration.Enabled

Chat Message Filtering

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.

FunctionalityLegacy ChatIn-Experience Text ChatDifferences
Filter message for individual userChat:FilterStringAsync()TextChannel:SendAsync()No need to manually filter chat messages using the in-experience text chat system.
Filter broadcasting messagesChat:FilterStringForBroadcast()

Chat Window and Bubble Chat

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 Players container, the in-experience text chat system provides dedicated classes, ChatWindowConfiguration and 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.