Tổng quan về trò chuyện văn bản

Roblox cung cấp khả năng nhắn tin dựa trên văn bản giữa các người chơi trong các phiên trực tiếp thông qua TextChatService, một lớp singleton chịu trách nhiệm quản lý toàn bộ hệ thống trò chuyện, bao gồm lọc tin nhắn trò chuyện, quản lý và quyền của người dùng. Dịch vụ này có chức năng tiêu chuẩn và cũng cung cấp một tập hợp các phương thức và sự kiện để mở rộng và tùy chỉnh trò chuyện, chẳng hạn như gửi tin nhắn dựa trên các yêu cầu tùy chỉnh, thêm quyền đặc biệt hoặc quản lý cho các người chơi cụ thể, và tạo các lệnh tùy chỉnh để thực hiện các hành động cụ thể.

Cấu hình UI

TextChatService cung cấp một UI mặc định có thể được tùy chỉnh để phù hợp với nhu cầu của trò chơi của bạn. Vô hiệu hóa bất kỳ cấu hình nào trong số này để ẩn phần tử UI liên quan. Nếu muốn, bạn cũng có thể thay thế các phần tử UI này bằng các giao diện tùy chỉnh:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Để biết thêm thông tin, xem Cửa sổ trò chuyện và Trò chuyện bong bóng.

Kênh, tin nhắn và lệnh

• TextChannel — Các kênh văn bản chuyển các tin nhắn do người dùng gửi từ máy khách đến máy chủ, sau đó hiển thị chúng cho các người dùng khác dựa trên quyền. Các kênh văn bản phải được gán cho TextChatService để hoạt động.

  Nếu TextChatService.CreateDefaultTextChannels được đặt thành true, dịch vụ sẽ tự động tạo hai kênh văn bản, RBXGeneral và RBXSystem. Bạn cũng có thể tạo thủ công các thể hiện TextChannel bổ sung và gán chúng cho TextChatService.

• TextSource — Một người dùng trong một TextChannel. Các nguồn văn bản được gán trực tiếp cho TextChannel khi AddUserAsync() được gọi. Các nguồn văn bản chứa thông tin chi tiết về quyền của một người dùng trong kênh, chẳng hạn như khả năng gửi tin nhắn. Nếu một người dùng duy nhất có mặt trong nhiều kênh văn bản, họ sẽ được liên kết với nhiều nguồn văn bản.

• TextChatMessage — Một tin nhắn trong một kênh văn bản. Các tin nhắn trò chuyện chứa thông tin cơ bản như người gửi tin nhắn, tin nhắn gốc, tin nhắn đã được lọc và dấu thời gian tạo.

• TextChatCommand — Cho phép người dùng thực hiện các hành động hoặc hành vi cụ thể bằng cách gửi các tin nhắn phù hợp với thuộc tính PrimaryAlias hoặc SecondaryAlias. Các lệnh trò chuyện phải được gán cho TextChatService để hoạt động.

  Nếu TextChatService.CreateDefaultCommands được đặt thành true, các lệnh trò chuyện mặc định sẽ được tạo tự động. Bạn cũng có thể tạo thủ công các thể hiện TextChatCommand bổ sung và gán chúng cho TextChatService.

Sơ đồ dòng trò chuyện

Trò chuyện văn bản sử dụng mô hình máy khách - máy chủ, với một máy khách gửi, máy chủ, và các máy khách nhận.

1. Một người chơi gửi một tin nhắn từ thiết bị cục bộ của họ, kích hoạt phương thức TextChannel:SendAsync(). Phương thức này xử lý tin nhắn và xác định xem đó có phải là một lệnh trò chuyện hay một tin nhắn trò chuyện thông thường.

   • Nếu tin nhắn là một lệnh trò chuyện, nó sẽ kích hoạt sự kiện TextChatCommand.Triggered để thực hiện hành động đã định nghĩa. Không cần thêm bước nào.

   • Nếu tin nhắn là một tin nhắn trò chuyện thông thường, nó sẽ kích hoạt sự kiện TextChatService.SendingMessage để hiển thị tin nhắn cho người gửi trên máy khách gửi. Đồng thời, TextChannel:SendAsync() sẽ chuyển tin nhắn đến máy chủ.

2. Máy chủ kích hoạt TextChannel.ShouldDeliverCallback để xác định xem có nên chuyển tin nhắn đến các người chơi khác dựa trên quyền và yêu cầu lọc cộng đồng Roblox hay không.

3. Nếu TextChannel.ShouldDeliverCallback xác định rằng tin nhắn đủ điều kiện để chuyển đến các người chơi khác, máy chủ sẽ áp dụng bất kỳ bộ lọc nào và kích hoạt TextChannel.OnIncomingMessage hai lần:

   1. Lần đầu tiên là trên máy khách gửi và báo hiệu rằng máy chủ đang xử lý tin nhắn thông qua sự kiện TextChatService.MessageReceived. Sự kiện này thay thế tin nhắn cục bộ trên máy khách gửi bằng tin nhắn đã được xử lý từ máy chủ. Tin nhắn là giống hệt nhau nếu bản gốc không yêu cầu lọc.

   2. Lần thứ hai là trên các máy khách nhận, kích hoạt sự kiện TextChatService.MessageReceived để hiển thị tin nhắn cho các người chơi khác.

Các hook và callback của trò chuyện văn bản

API TextChatService khuyến khích một sự phân tách rõ ràng về hình thức và việc chuyển giao các tin nhắn trò chuyện. Nhiều thể hiện của hệ thống trò chuyện văn bản cung cấp các hook và callback để định dạng ở các vị trí trung tâm, rõ ràng.

Giao hàng tin nhắn có điều kiện

Callback TextChannel.ShouldDeliverCallback chỉ nên được định nghĩa trên máy chủ. Callback này được kích hoạt cho mỗi TextSource con của kênh văn bản khi một tin nhắn được gửi để xác định xem tin nhắn có nên được chuyển giao hay không. Callback này có thể được sử dụng để triển khai logic giao hàng tin nhắn tùy chỉnh có thể phụ thuộc vào ngữ cảnh gameplay bổ sung, chẳng hạn như:

• Trò chuyện dựa trên khoảng cách nơi người dùng chỉ có thể gửi tin nhắn cho những người gần họ.
• Ngăn chặn người dùng có các thuộc tính nhất định gửi tin nhắn cho người khác.

Tùy chỉnh hiển thị tin nhắn

UI mặc định của TextChatService dựa vào văn bản phong phú để định dạng và tùy chỉnh cách các tin nhắn được hiển thị. Bạn có thể sử dụng các callback sau để định dạng các tin nhắn trước khi chúng được hiển thị cho người dùng, chẳng hạn như để thêm màu sắc hoặc thẻ trò chuyện vào tên người dùng hoặc định dạng nội dung tin nhắn.

Các callback sau được gọi trên mỗi TextChatMessage sắp được hiển thị, cho phép bạn tùy chỉnh diện mạo của cửa sổ trò chuyện dựa trên TextChannel, TextSource, hoặc nội dung của TextChatMessage. Khi một máy khách gửi một tin nhắn, các callback này được gọi một lần khi tin nhắn được gửi đến máy chủ và giá trị TextChatMessage.Status sẽ là Enum.TextChatMessageStatus.Sending. Khi tin nhắn được máy chủ nhận và đang được chuyển giao cho các người dùng khác, máy khách gửi sẽ nhận lại tin nhắn với giá trị Enum.TextChatMessageStatus đã được cập nhật.

• TextChatService.OnIncomingMessage — Callback này chỉ nên được định nghĩa trên máy khách. Callback này được kích hoạt khi một tin nhắn được nhận, hoặc từ máy chủ hoặc nếu máy khách cục bộ vừa gửi một tin nhắn. Callback này được gọi trên mỗi TextChatMessage nhận từ tất cả các thể hiện TextChannel và là cái đầu tiên xử lý tin nhắn trước khi nó được hiển thị cho người dùng.
• TextChannel.OnIncomingMessage — Callback này chỉ nên được định nghĩa trên máy khách. Callback này được kích hoạt khi một tin nhắn được nhận từ máy chủ. Callback này được gọi trên mỗi TextChatMessage nhận từ TextChannel. Các thể hiện TextChannel mặc định được tạo từ TextChatService.CreateDefaultTextChannels có callback này được định nghĩa và có thể bị ghi đè.
• TextChatService.OnBubbleAdded — Callback này chỉ nên được định nghĩa trên máy khách. Sử dụng nó để tùy chỉnh diện mạo của các bong bóng trò chuyện độc lập với diện mạo của tin nhắn trong UI cửa sổ trò chuyện.
• TextChatService.OnChatWindowAdded — Callback này chỉ nên được định nghĩa trên máy khách. Sử dụng nó để tùy chỉnh diện mạo của các tin nhắn trò chuyện trong UI cửa sổ trò chuyện độc lập với diện mạo của tin nhắn trong các bong bóng trò chuyện.

Di chuyển từ trò chuyện cũ

Phần này giúp bạn di chuyển từ hệ thống trò chuyện cũ bằng cách cung cấp các phương thức thay thế để triển khai các chức năng và hành vi trò chuyện phổ biến bằng cách sử dụng TextChatService.

1. Trong cửa sổ Explorer, chọn TextChatService.

2. Trong cửa sổ Properties, tìm dropdown ChatVersion và chọn TextChatService.

   

Chức năng cơ bản

Mặc dù cả hai hệ thống đều chia sẻ các chức năng trò chuyện cơ bản giống nhau, nhưng các triển khai của TextChatService nói chung bền vững hơn và dễ dàng hơn để lặp lại.

Lọc tin nhắn

TextChatService tự động lọc các tin nhắn trò chuyện dựa trên thông tin tài khoản của từng người chơi, vì vậy bạn không cần phải triển khai thủ công việc lọc văn bản cho tất cả các loại tin nhắn trò chuyện.

Cửa sổ và trò chuyện bong bóng

Cả hành vi và tùy chọn tùy chỉnh của cửa sổ trò chuyện và trò chuyện bong bóng của TextChatService đều giống hệt như của hệ thống trò chuyện cũ. Vì hệ thống trò chuyện cũ chỉ cho phép tùy chỉnh bằng cách sử dụng các module trò chuyện hoặc container Players, dịch vụ cung cấp các lớp dành riêng (ChatWindowConfiguration và BubbleChatConfiguration) để quản lý tất cả các thuộc tính của cửa sổ trò chuyện và trò chuyện bong bóng. Thêm vào đó, bạn có thể dễ dàng điều chỉnh và xem trước diện mạo và hành vi của trò chuyện bong bóng của bạn bằng cách sử dụng các cài đặt Studio thay vì phải lập trình tất cả chúng.

Di chuyển "dữ liệu bổ sung" của người nói

Hệ thống trò chuyện Lua cũ cho phép các nhà phát triển sử dụng SetExtraData trên lớp Speaker. Dữ liệu này được sử dụng để định dạng màu sắc tên, màu sắc trò chuyện, hoặc để áp dụng thẻ tên cho một người nói nhất định.

-- Một ví dụ về việc thiết lập dữ liệu bổ sung trên một người nói trong hệ thống trò chuyện cũ
ChatService.SpeakerAdded:Connect(function(playerName)
	local speaker = ChatService:GetSpeaker(playerName)
	speaker:SetExtraData("NameColor", Color3.fromRGB(255, 255, 55))
	speaker:SetExtraData("ChatColor", Color3.fromRGB(212, 175, 55))
	speaker:SetExtraData("Tags", {{TagText = "YourTagName", TagColor = Color3.fromRGB(0, 255, 0)}, {TagText = "OtherTagName", TagColor = Color3.fromRGB(255, 0, 0)}})
end)

TextChatService không có một tương đương trực tiếp với SetExtraData. Thay vào đó, hãy sử dụng các callback như OnWindowAdded để tùy chỉnh diện mạo của các tin nhắn bằng cách sử dụng văn bản phong phú dựa trên TextSource của tin nhắn.

Dưới đây là một ví dụ về việc mô phỏng "dữ liệu bổ sung" của trò chuyện Lua cũ bằng cách truy cập các thuộc tính trên các đối tượng Player:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	player:SetAttribute("NameColor", Color3.fromRGB(255, 255, 55))
	player:SetAttribute("ChatColor", Color3.fromRGB(212, 175, 55))
	player:SetAttribute("isYourTag", true)
	player:SetAttribute("isOtherTag", true)
end)

Sau đó, bạn có thể sử dụng callback OnChatWindowAdded để tùy chỉnh diện mạo của cửa sổ trò chuyện dựa trên các thuộc tính được thiết lập trên người chơi:

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

TextChatService.OnChatWindowAdded = function(textChatMessage)
	local textSource = textChatMessage.TextSource
	if textSource then
		local player = Players:GetPlayerByUserId(textSource.UserId)
		if player then
			local overrideProperties = TextChatService.ChatWindowConfiguration:DeriveNewMessageProperties()
			overrideProperties.PrefixText = textChatMessage.PrefixText
			overrideProperties.Text = textChatMessage.Text

			local nameColor = player:GetAttribute("NameColor")
			if nameColor and typeof(nameColor) == "Color3" then
				overrideProperties.PrefixTextProperties.TextColor3 = nameColor
			end

			local chatColor = player:GetAttribute("ChatColor")
			if chatColor and typeof(chatColor) == "Color3" then
				overrideProperties.TextColor3 = chatColor
			end

			local isYourTag = player:GetAttribute("isYourTag")
			if isYourTag == true then
				overrideProperties.PrefixText = `<font color='rgb(0, 255, 0)'>[YourTag]</font> {overrideProperties.PrefixText}`
			end

			local isOtherTag = player:GetAttribute("isOtherTag")
			if isOtherTag == true then
				overrideProperties.PrefixText = `<font color='rgb(255, 0, 0)'>[OtherTag]</font> {overrideProperties.PrefixText}`
			end

			return overrideProperties
		end
	end

	return nil
end