Bubble Chat

10 min

The built-in bubble chat system enables display of customizable chat bubbles above avatars and NPCs.

Key features include:

Animated transitions for improved engagement.
Numerous customization options including bubble duration, text/background color, distance at which bubbles are minimized or hidden, and much more.
Ability to define unique bubble styles per-user or NPC.

Enabling Bubble Chat

To enable bubble chat, toggle on BubbleChatEnabled in the Chat service, either directly or from a LocalScript within StarterPlayerScripts.

			
				LocalScript - Enable Bubble Chat
			
				Expected Output
			
				Expand
				
			local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true
		
				Copy Code
			
				Light Theme

Customization Options

The appearance and behavior of bubbles can be customized by calling Chat/SetBubbleChatSettings and passing in a table of key-value pairs, for example:

			
				LocalScript - Customize Bubble Appearance/Behavior
			
				Expected Output
			
				Expand
				
			local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true

local bubbleChatSettings = {
	BackgroundColor3 = Color3.fromRGB(180, 210, 220),
	TextSize = 20,
	Font = Enum.Font.FredokaOne,
	BubbleDuration = 10
}
-- Apply the settings
ChatService:SetBubbleChatSettings(bubbleChatSettings)
		
				Copy Code
			
				Light Theme

Appearance

Basic bubble appearance and style can be controlled through the following:

Key	Description	Type	Default
BackgroundColor3	Bubble background color	`Datatype/Color3`	[250, 250, 250]
TextColor3	Bubble text color	`Datatype/Color3`	[57, 59, 61]
TextSize	Bubble text size	number	16
Font	Bubble text font	`Enum/Font\|Enum.Font`	GothamSemibold
Transparency	Bubble transparency (0–1)	number	0.1
CornerEnabled	Whether bubbles have rounded corners	boolean	true
CornerRadius	Radius of bubble corners	`Datatype/UDim`	0, 12
TailVisible	Whether the pointed "tail" of the most recent bubble is visible	boolean	true
Padding	Space between the text and the edges of a bubble, in pixels	number	8
MaxWidth	Maximum width of a bubble, in pixels	number	300

Behavior

Bubble behavior on screen, such as duration and maximum visible distance from the camera, can be configured with the following:

Key	Description	Type	Default
AdorneeName	Name of the body part or `Attachment` that bubbles will attach to; if multiple instances of the same name exist, only the first instance found will be used	string	HumanoidRootPart
BubbleDuration	Time before a bubble fades out, in seconds	number	15
BubblesSpacing	Vertical space between stacked bubbles, in pixels	number	6
MaxBubbles	Maximum number of bubbles displayed before older bubbles immediately disappear	number	3
VerticalStudsOffset	Extra space between bubbles and their adornee, in studs	number	0
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, 2
MinimizeDistance	Distance from the camera when bubbles turn into a single bubble with an ellipsis (...) to indicate chatter	number	40
MaxDistance	Maximum distance from the camera that bubbles are shown	number	100

Background Image

The background image of bubbles can be customized by including a BackgroundImage sub-table within the main settings table:

			
				LocalScript - Bubble Background Image
			
				Expected Output
			
				Expand
				
			local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true

local bubbleChatSettings = {
	CornerEnabled = false,
	TailVisible = false,
	TextSize = 24,
	TextColor3 = Color3.fromRGB(220, 50, 50),
	Font = Enum.Font.LuckiestGuy,
	Padding = 30,
	BackgroundImage = {
		Image = "rbxassetid://6733332557",
		ScaleType = Enum.ScaleType.Slice,
		SliceCenter = Rect.new(40, 40, 360, 160),
		SliceScale = 0.5
	}
}
-- Apply the settings
ChatService:SetBubbleChatSettings(bubbleChatSettings)
		
				Copy Code
			
				Light Theme

Key	Description	Type	Default
Image	Asset ID of the background image	string
ImageColor3	`ImageLabel/ImageColor3\|ImageColor3` property for the image	`Datatype/Color3`	[255, 255, 255]
ImageRectOffset	`ImageLabel/ImageRectOffset\|ImageRectOffset` property for the image	`Datatype/Vector2`	0, 0
ImageRectSize	`ImageLabel/ImageRectSize\|ImageRectSize` property for the image	`Datatype/Vector2`	0, 0
ScaleType	`ImageLabel/ScaleType\|ScaleType` property for the image	`Enum/ScaleType\|Enum.ScaleType`	Stretch
SliceCenter	`ImageLabel/SliceCenter\|SliceCenter` property for the image; only applies if ScaleType is set to `Enum/ScaleType\|Enum.ScaleType.Slice`	`Datatype/Rect`	0, 0, 0, 0
SliceScale	`ImageLabel/SliceScale\|SliceScale` property for the image; only applies if ScaleType is set to `Enum/ScaleType\|Enum.ScaleType.Slice`	number	1
TileSize	`ImageLabel/TileSize\|TileSize` property for the image; only applies if ScaleType is set to `Enum/ScaleType\|Enum.ScaleType.Tile`	`Datatype/UDim2`	1, 0, 1, 0

Background Gradient

A gradient background can be applied to bubbles by including a BackgroundGradient sub-table within the main settings table:

			
				LocalScript - Bubble Background Gradient
			
				Expected Output
			
				Expand
				
			local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true

local bubbleChatSettings = {
	CornerRadius = UDim.new(1, 0),
	TailVisible = false,
	TextSize = 28,
	TextColor3 = Color3.fromRGB(0, 0, 0),
	Font = Enum.Font.DenkOne,
	Padding = 12,
	BackgroundGradient = {
		Enabled = true,
		Rotation = 90,
		Color = ColorSequence.new(Color3.fromRGB(150, 225, 255), Color3.fromRGB(50, 115, 255)),
		Transparency = NumberSequence.new({
			NumberSequenceKeypoint.new(0, 0.2),
			NumberSequenceKeypoint.new(1, 0.5)
		})
	}
}
-- Apply the settings
ChatService:SetBubbleChatSettings(bubbleChatSettings)
		
				Copy Code
			
				Light Theme

Key	Description	Type	Default
Enabled	Whether the defined gradient is enabled	boolean	false
Color	The `UIGradient/Color\|Color` property of the background gradient	`Datatype/ColorSequence`	[150, 150, 150] → [250, 250, 250]
Offset	The `UIGradient/Offset\|Offset` property of the background gradient	`Datatype/Vector2`	0, 0
Rotation	The `UIGradient/Rotation\|Rotation` property of the background gradient	number	0
Transparency	The `UIGradient/Transparency\|Transparency` property of the background gradient	`Datatype/NumberSequence`	0 → 0

Animation

Bubble animation can be customized by including a SizeAnimation and/or TransparencyAnimation sub-table within the main settings table:

			
				LocalScript - Bubble Animation
			
				Expected Output
			
				Expand
				
			local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true

local bubbleChatSettings = {
	BackgroundColor3 = Color3.fromRGB(210, 210, 255),
	TextSize = 22,
	Padding = 10,
	Font = Enum.Font.Cartoon,
	CornerRadius = UDim.new(1, 0),
	SizeAnimation = {
		SpringDampingRatio = 0.25
	},
	TransparencyAnimation = {
		SpringFrequency = 3
	}
}
-- Apply the settings
ChatService:SetBubbleChatSettings(bubbleChatSettings)
		
				Copy Code
			
				Light Theme

Key	Description	Type	Default
Enabled	Whether the defined size animation is enabled	boolean	true
SpringDampingRatio	Damping ratio of the size animation; a value above 1 will result in a slower, more rigid animation while a value between 0 and 1 will result in a bouncing effect	number	1
SpringFrequency	Frequency of the size animation; higher values will make the animation play faster	number	2

Key	Description	Type	Default
Enabled	Whether the defined transparency animation is enabled	boolean	true
SpringDampingRatio	Damping ratio of the transparency animation; a value above 1 will result in a slower, more rigid animation while a value between 0 and 1 will result in a bouncing effect	number	1
SpringFrequency	Frequency of the transparency animation; higher values will make the animation play faster	number	2

Per-User Customization

Bubbles can be customized per-user by including a UserSpecificSettings sub-table within the main settings table. Each key within the table should be a user’s Player/UserId|UserId and its value should be a table containing override settings for that user.

			
				LocalScript - Larger Bubbles for Local User
			
				Expected Output
			
				Expand
				
			local Players = game:GetService("Players")
local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true

local bubbleChatSettings = {
	UserSpecificSettings = {
		[Players.LocalPlayer.UserId] = {
			TextSize = 24,
			Padding = 12,
			BubblesSpacing = 8
		}
	}
}
-- Apply the settings
ChatService:SetBubbleChatSettings(bubbleChatSettings)
		
				Copy Code
			
				Light Theme

NPC Bubbles

Chat bubbles can be shown above NPCs by calling the Chat/Chat method. You can also customize such bubbles by including a UserSpecificSettings table as outlined in per-user customization, but instead of a Player/UserId|UserId, use the full name of the part/attachment (Instance/GetFullName).

Typically, Chat/Chat should be called from a server-side Script so that messages propagate correctly to other users. However, in the case of NPC conversations which only need to appear to the specific user interacting with the NPC, it should be called from a client-side LocalScript.

			
				LocalScript - NPC Bubbles
			
				Expected Output
			
				Expand
				
			local ChatService = game:GetService("Chat")
ChatService.BubbleChatEnabled = true

local npc = workspace:FindFirstChild("SpiderGirl")
local adornee = npc:FindFirstChild("HumanoidRootPart")

local bubbleChatSettings = {
	UserSpecificSettings = {
		[adornee:GetFullName()] = {
			CornerRadius = UDim.new(0, 6),
			TailVisible = false,
			TextSize = 25,
			TextColor3 = Color3.new(1, 1, 1),
			Font = Enum.Font.SpecialElite,
			Padding = 12,
			BubbleDuration = 8,
			BubblesSpacing = 4,
			BackgroundGradient = {
				Enabled = true,
				Rotation = 90,
				Color = ColorSequence.new(Color3.fromRGB(175, 0, 0), Color3.fromRGB(175, 0, 0)),
				Transparency = NumberSequence.new({
					NumberSequenceKeypoint.new(0, 0),
					NumberSequenceKeypoint.new(1, 0.25)
				})
			}
		}
	}
}
-- Apply the settings
ChatService:SetBubbleChatSettings(bubbleChatSettings)

-- Display chat bubbles above the NPC adornee
ChatService:Chat(adornee, "Welcome to our island, traveler!")
wait(3.5)
ChatService:Chat(adornee, "I have potions and other magical items for sale")
wait(4.75)
ChatService:Chat(adornee, "I also have some fresh gibblyboks in the chest...")
wait(5.25)
ChatService:Chat(adornee, "Would you like to buy some?")
		
				Copy Code
			
				Light Theme

Tags:

chat
bubble
dialog
npc

Bubble Chat

Bubble Chat

Enabling Bubble Chat

Customization Options

Appearance

Behavior

Background Image

Background Gradient

Animation

Per-User Customization

NPC Bubbles

Related Articles

Text and Chat Filtering

Lua Chat System