Bubble Chat

With the in-experience text chat system, you can support bubble chat to display customizable speech chat bubbles above user avatars and NPCs. Bubble chat can make your experience more visually immersive and help users easily identify messages and their speakers in a contextually relevant manner. This feature is especially useful for experiences where users need to focus on the content in the meantime communicating with others in a less obtrusive way.

Bubble Chat Configuration

To enable bubble chat in your experience:

1. In the Explorer window, select BubbleChatConfiguration under TextChatService.

   

2. In the Properties window, check the Enabled checkbox under the Behavior category.

   

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 window of BubbleChatConfiguration for basic changes like text color and spacing. For advanced customization, such as adding background images for bubbles, add UI objects as children of BubbleChatConfiguration and then modify these objects.

Alternatively, you can add a LocalScript in StarterPlayerScripts with all your customization settings. This allows the engine to apply your customizations during runtime, overriding the settings in Studio. It's useful for adding special effects to chat bubbles when users trigger certain events or conditions.

Basic Customization

The following table shows common bubble chat customization properties. For a full list of customization properties, see BubbleChatConfiguration.

Appearance

Behavior

Advanced Customization

For advanced customization of your bubble, add UI objects representing certain aspects of the bubble appearance as children under BubbleChatConfiguration, including:

• ImageLabel for background image settings.
• UIGradient for background gradient settings.
• UICorner for the corner shape of bubbles.
• UIPadding for the padding space between the text and bubble edges, relative to the parent's normal size.

To add these objects as children of BubbleChatConfiguration, you can either add a script or use the Studio user interface directly:

1. Hover over BubbleChatConfiguration and click the ⊕ button.
2. Select the object from list.

After adding these objects, you can modify properties of these objects applicable to chat bubbles for advanced bubble customization. The following example client-side LocalScript adds a background image and sharp corners to bubbles:

Advanced Bubble Customization
local BubbleChatConfiguration = game:GetService("TextChatService").BubbleChatConfiguration
BubbleChatConfiguration.TailVisible = false
BubbleChatConfiguration.TextSize = 24
BubbleChatConfiguration.TextColor3 = Color3.fromRGB(220, 50, 50)
BubbleChatConfiguration.FontFace = Font.fromEnum(Enum.Font.LuckiestGuy)

local UICorner = BubbleChatConfiguration:FindFirstChildOfClass("UICorner")
if not UICorner then
	UICorner = Instance.new("UICorner")
	UICorner.Parent = BubbleChatConfiguration
end
UICorner.CornerRadius = UDim.new(0, 0)

local ImageLabel = BubbleChatConfiguration:FindFirstChildOfClass("ImageLabel")
if not ImageLabel then
	ImageLabel = Instance.new("ImageLabel")
	ImageLabel.Parent = BubbleChatConfiguration
end
ImageLabel.Image = "rbxassetid://6733332557"
ImageLabel.ScaleType = Enum.ScaleType.Slice
ImageLabel.SliceCenter = Rect.new(40, 40, 360, 160)
ImageLabel.SliceScale = 0.5

The following tables include all available properties for customization:

ImageLabel

UIGradient

UICorner

UIGradient

Per-Bubble Customization

You can individually style and modify chat bubble behaviors based on specific conditions that overrides your general settings. For example, you can use chat bubbles to differentiate NPCs and users, highlight critical health status, and apply special effects to messages with pre-defined keywords.

To set per-bubble customization, add a client-side LocalScript using BubbleChatMessageProperties, which overrides matching properties of BubbleChatConfiguration, and the TextChatService.OnBubbleAdded callback to specify how to customize each bubble. The callback supplies you with the TextChatMessage property as well as the adornee, so you can apply the customization based on attributes associated with users, the chat text content, user character properties, and any special conditions you want to define.

The following example adds special appearance to VIP users' chat bubbles by checking if a chat message sender has the IsVIP attribute:

VIP Bubbles
local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

-- Event handler for when a new chat bubble is added to the experience
TextChatService.OnBubbleAdded = function(message: TextChatMessage, adornee: Instance)
	-- Check if the chat message has a TextSource (sender) associated with it
	if message.TextSource then
		-- Create a new BubbleChatMessageProperties instance to customize the chat bubble
		local bubbleProperties = Instance.new("BubbleChatMessageProperties")

		-- Get the user who sent the chat message based on their UserId
		local player = Players:GetPlayerByUserId(message.TextSource.UserId)

		if player:GetAttribute("IsVIP") then
			-- If the player is a VIP, customize the chat bubble properties
			bubbleProperties.TextColor3 = Color3.fromHex("#F5CD30")
			bubbleProperties.BackgroundColor3 = Color3.fromRGB(25, 27, 29)
			bubbleProperties.FontFace = Font.fromEnum(Enum.Font.PermanentMarker)
		end
		return bubbleProperties
	end
end

Available Options

The following basic customization properties are available for per-bubble customization:

All advanced customization options are available for per-bubble customization. Similar to advanced customization for general bubbles, add instances that you want to customize as children of BubbleChatMessageProperties. The following example adds a special gradient effect along with other properties to chat bubbles of users with low health status by checking the Humanoid.Health property of chat message senders' characters:

Low Health Bubbles
local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

-- Event handler for when a new chat bubble is added to the experience
TextChatService.OnBubbleAdded = function(message: TextChatMessage, adornee: Instance)
	-- Check if the chat message has a TextSource (sender) associated with it
	if message.TextSource then
		-- Get the user who sent the chat message by using their UserId
		local player = Players:GetPlayerByUserId(message.TextSource.UserId)

		-- Find the humanoid in the user's character
		local humanoid = player.Character:FindFirstChild("Humanoid")

		if humanoid and humanoid.Health < 25 then
			-- Create a new BubbleChatMessageProperties instance to customize the chat bubble
			local bubbleProperties :BubbleChatMessageProperties = Instance.new("BubbleChatMessageProperties")

			-- Customize the chat bubble properties for low health condition
			bubbleProperties.BackgroundColor3 = Color3.fromRGB(245, 245, 245)
			bubbleProperties.TextColor3 = Color3.fromRGB(234, 51, 96)
			bubbleProperties.TextSize = 20
			bubbleProperties.FontFace = Font.fromEnum(Enum.Font.DenkOne)

			-- Add a UIGradient as a child to customize the gradient
			local uiGradient : UIGradient = Instance.new("UIGradient")
			uiGradient.Color = ColorSequence.new(Color3.fromRGB(110, 4, 0), Color3.fromRGB(0, 0, 0))
			uiGradient.Parent = bubbleProperties
			uiGradient.Rotation = 90

			return bubbleProperties
		end
	end
end

NPC Bubbles

You can display chat bubbles for non-player characters (NPCs) by calling TextChatService:DisplayBubble(), with the NPC character and the message as parameters. These bubbles are customizable using the TextChatService.OnBubbleAdded callback just like any other chat bubble.

TextChatService:DisplayBubble() only works on client-side scripts, so be sure to use a LocalScript in an appropriate container, such as StarterPlayerScripts. If you attach a ProximityPrompt to an NPC, a script for displaying a chat bubble might look like this:

local TextChatService = game:GetService("TextChatService")

local prompt = workspace.SomeNPC.ProximityPrompt
local head = prompt.Parent:WaitForChild("Head")

prompt.Triggered:Connect(function()
	TextChatService:DisplayBubble(head, "Hello world!")
end)