Customizing Bubble Chat

With TextChatService, you can use 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.

Enabling Bubble Chat

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.

   

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, or implement advanced customization for bubble background images and other visual adjustments.

Alternatively, 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.

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.

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

Advanced Bubble Customization
local TextChatService = game:GetService("TextChatService")

local bubbleChatConfiguration = TextChatService.BubbleChatConfiguration
bubbleChatConfiguration.TailVisible = false
bubbleChatConfiguration.TextColor3 = Color3.fromRGB(220, 50, 50)
bubbleChatConfiguration.FontFace = Font.fromEnum(Enum.Font.LuckiestGuy)

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

local bubbleUIPadding = bubbleChatConfiguration:FindFirstChildOfClass("UIPadding")
if not bubbleUIPadding then
	bubbleUIPadding = Instance.new("UIPadding")
	bubbleUIPadding.Parent = bubbleChatConfiguration
end
bubbleUIPadding.PaddingTop = UDim.new(0, 20)
bubbleUIPadding.PaddingRight = UDim.new(0, 10)
bubbleUIPadding.PaddingBottom = UDim.new(0, 15)
bubbleUIPadding.PaddingLeft = UDim.new(0, 10)

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

The following tables outline the available GuiObject and appearance modifier children along with their valid customization properties:

Per-Bubble Customization

You can individually style and modify chat bubble behaviors based on specific conditions in order to override 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 basic customization properties are available for per-bubble customization:

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

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:FindFirstChildWhichIsA("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.Rotation = 90
			uiGradient.Parent = bubbleProperties
			
			return bubbleProperties
		end
	end
end

Manually Displaying Bubbles

You might want to display a chat bubble when players haven't sent a message, such as with NPCs. Use the TextChatService:DisplayBubble() method to manually display a chat bubble.

Customization of these bubbles is the same as the customization of the bubbles that are automatically displayed when Players send messages through TextChannels using the TextChatService.OnBubbleAdded callback.

NPC Bubbles

Display chat bubbles for non-player characters (NPCs) by calling TextChatService:DisplayBubble(character, message), 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 Script with RunContext set to Enum.RunContext.Client, or 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)