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

Roblox cung cấp 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 đơn có 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 hạn của người dùng. Dịch vụ này có chức năng tiêu chuẩn của 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ư chuyển phát các tin nhắn dựa trên các yêu cầu tùy chỉnh, thêm quyền hạ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 giao diện người dùng

TextChatService cung cấp một giao diện người dùng 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ử giao diện người dùng liên quan. Nếu muốn, bạn cũng có thể thay thế các phần tử giao diện người dùng 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 tiếp các tin nhắn do người dùng gửi từ client đến server, sau đó hiển thị chúng cho những người dùng khác dựa trên quyền truy cập. Các kênh văn bản phải được cha mẹ hóa với TextChatService để hoạt động.

  Nếu TextChatService.CreateDefaultTextChannels được thiết lập là true, dịch vụ 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ực thể TextChannel bổ sung và cha mẹ hóa chúng với TextChatService.

• TextSource — Một người dùng trong một TextChannel. Các nguồn văn bản được cha mẹ hóa trực tiếp với TextChannel khi AddUserAsync() được gọi. Các nguồn văn bản chứa quyền hạn chi tiết 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 đơn lẻ có mặt trong nhiều kênh văn bản, họ sẽ 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 đã bị lọc, và dấu thời gian tạo.

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

  Nếu TextChatService.CreateDefaultCommands được thiết lập là 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ực thể TextChatCommand bổ sung và cha mẹ hóa chúng với TextChatService.

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

Trò chuyện văn bản sử dụng mô hình client‑server, với một client gửi, server, và client nhận.

1. Một người chơi gửi một tin nhắn từ thiết bị địa phương 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ó kích hoạt sự kiện TextChatCommand.Triggered để thực hiện hành động đã xác định. Không có bước nào khác cần thực hiện.

   • Nếu tin nhắn là một tin nhắn trò chuyện thông thường, nó kích hoạt sự kiện TextChatService.SendingMessage để hiển thị tin nhắn cho người gửi trên client gửi đi. Cùng lúc đó, TextChannel:SendAsync() truyền tin nhắn tới server.

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

3. Nếu TextChannel.ShouldDeliverCallback xác định rằng tin nhắn đủ điều kiện để gửi đến những người chơi khác, server á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 client gửi đi và báo hiệu rằng server đang xử lý tin nhắn thông qua sự kiện TextChatService.MessageReceived. Sự kiện này thay thế tin nhắn địa phương trên client gửi đi bằng tin nhắn đã được xử lý từ server. Tin nhắn là giống nhau nếu nguyên bản không cần được lọc.

   2. Lần thứ hai là trên các client nhận, kích hoạt sự kiện TextChatService.MessageReceived để hiển thị tin nhắn cho những 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 gửi các tin nhắn trò chuyện. Nhiều thực thể 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.

Điều kiện gửi tin nhắn

Callback TextChannel.ShouldDeliverCallback chỉ nên được định nghĩa trên server. 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 gửi hay không. Callback này có thể được sử dụng để triển khai logic gửi tin nhắn tùy chỉnh có thể phụ thuộc vào ngữ cảnh trò chơi 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 với 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

Giao diện người dùng 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 thứ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, ví dụ 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 cho 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 nội dung TextChannel, TextSource hoặc TextChatMessage. Khi một client gửi một tin nhắn, các callback này sẽ được gọi một lần khi tin nhắn được gửi đến server và giá trị TextChatMessage.Status sẽ là Enum.TextChatMessageStatus.Sending. Khi tin nhắn được server nhận và đang được gửi cho các người dùng khác, client gửi sẽ nhận được tin nhắn lại 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 client. Callback này được kích hoạt khi một tin nhắn được nhận, từ server hoặc nếu client địa phương vừa mới gửi một tin nhắn. Callback này được gọi cho mỗi TextChatMessage được nhận từ tất cả các thực thể TextChannel và là lần đầ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 client. Callback này được kích hoạt khi một tin nhắn được nhận từ server. Callback này được gọi cho mỗi TextChatMessage được nhận từ TextChannel. Các thực thể 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 client. 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 giao diện người dùng cửa sổ trò chuyện.
• TextChatService.OnChatWindowAdded — Callback này chỉ nên được định nghĩa trên client. Sử dụng nó để tùy chỉnh diện mạo của các tin nhắn trò chuyện trong giao diện người dùng 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 kế thừa

Mục này giúp bạn di chuyển từ hệ thống trò chuyện kế thừa 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.

   

Các chức năng cơ bản

Mặc dù cả hai hệ thống 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 nhìn chung bền vững hơn và dễ dàng để lặp đi 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 kế thừa. Bởi vì hệ thống trò chuyện kế thừa 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 chuyên dụ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 sử dụng các cài đặt trong Studio thay vì phải lập trình tất cả.

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

Hệ thống trò chuyện Lua kế thừa 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 tên, màu trò chuyện, hoặc để áp dụng thẻ tên cho một người nói nhất định.

Đặt dữ liệu bổ sung trong Hệ thống Trò chuyện Kế thừa
-- 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 kế thừa
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ó 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 giả lập "dữ liệu bổ sung" của trò chuyện Lua kế thừa bằng cách truy cập các thuộc tính trên các đối tượng Player:

TextChatService SetAttributes
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:

TextChatService OnChatWindowAdded
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