Ikhtisar Obrolan Teks

Roblox menawarkan messaging berbasis teks antara pemain dalam sesi langsung melalui TextChatService, sebuah kelas singleton yang bertanggung jawab untuk mengelola sistem obrolan secara keseluruhan, termasuk penyaringan pesan obrolan, moderasi, dan izin pengguna. Layanan ini memiliki fungsionalitas standar dan juga menyediakan serangkaian metode dan acara untuk memperluas dan menyesuaikan obrolan, seperti mengirim pesan berdasarkan persyaratan yang disesuaikan, menambahkan izin atau moderasi khusus untuk pemain tertentu, dan membuat perintah kustom untuk mengeksekusi tindakan tertentu.

Konfigurasi UI

TextChatService menyediakan UI default yang dapat disesuaikan untuk memenuhi kebutuhan permainan Anda. Nonaktifkan konfigurasi ini untuk menyembunyikan elemen UI yang terkait. Jika diinginkan, Anda juga dapat mengganti elemen UI ini dengan antarmuka khusus:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Untuk informasi lebih lanjut, lihat Jendela Obrolan dan Obrolan Gelembung.

Saluran, pesan, dan perintah

• TextChannel — Saluran teks meneruskan pesan yang dikirim pengguna dari klien ke server, yang kemudian menampilkan pesan tersebut kepada pengguna lain berdasarkan izin. Saluran teks harus menjadi anak dari TextChatService agar dapat berfungsi.

  Jika TextChatService.CreateDefaultTextChannels diatur ke true, layanan secara otomatis membuat dua saluran teks, RBXGeneral dan RBXSystem. Anda juga dapat secara manual membuat instansi TextChannel tambahan dan menjadikannya anak di TextChatService.

• TextSource — Seorang pengguna di TextChannel. Sumber teks langsung menjadi anak dari TextChannel ketika AddUserAsync() dipanggil. Sumber teks berisi izin terperinci dari pengguna di saluran, seperti kemampuan mereka untuk mengirim pesan. Jika seorang pengguna berada di beberapa saluran teks, mereka terhubung dengan beberapa sumber teks.

• TextChatMessage — Sebuah pesan dalam saluran teks. Pesan obrolan berisi informasi dasar seperti pengirim pesan, pesan asli, pesan yang difilter, dan timestamp pembuatan.

• TextChatCommand — Memungkinkan pengguna untuk memanggil tindakan atau perilaku tertentu dengan mengirim pesan yang cocok dengan properti PrimaryAlias atau SecondaryAlias. Perintah obrolan harus menjadi anak dari TextChatService agar dapat berfungsi.

  Jika TextChatService.CreateDefaultCommands diatur ke true, perintah obrolan default akan dibuat secara otomatis. Anda juga dapat secara manual membuat instansi TextChatCommand tambahan dan menjadikannya anak di TextChatService.

Diagram Alur Obrolan

Obrolan teks menggunakan model klien-server, dengan klien pengirim, server, dan klien penerima.

1. Seorang pemain mengirim pesan dari perangkat lokal mereka, memicu metode TextChannel:SendAsync(). Metode ini memproses pesan dan menentukan apakah itu adalah perintah obrolan atau pesan obrolan biasa.

   • Jika pesan tersebut adalah perintah obrolan, itu memicu acara TextChatCommand.Triggered untuk melakukan tindakan yang ditentukan. Tidak ada langkah lebih lanjut yang diperlukan.

   • Jika pesan tersebut adalah pesan obrolan biasa, itu memicu acara TextChatService.SendingMessage untuk menampilkan pesan kepada pengirim di klien pengirim. Pada saat yang sama, TextChannel:SendAsync() meneruskan pesan ke server.

2. Server memicu TextChannel.ShouldDeliverCallback untuk menentukan apakah pesan harus disampaikan kepada pengguna lain berdasarkan izin dan persyaratan penyaringan komunitas Roblox.

3. Jika TextChannel.ShouldDeliverCallback menentukan bahwa pesan memenuhi syarat untuk disampaikan kepada pengguna lain, server menerapkan filter dan memicu TextChannel.OnIncomingMessage dua kali:

   1. Pertama kali di klien pengirim dan memberi sinyal bahwa server sedang memproses pesan melalui acara TextChatService.MessageReceived. Acara ini menggantikan pesan lokal di klien pengirim dengan pesan yang diproses dari server. Pesan tersebut identik jika yang asli tidak memerlukan penyaringan.

   2. Kali kedua adalah pada klien penerima, yang memicu acara TextChatService.MessageReceived untuk menampilkan pesan kepada pengguna lain.

Hook dan Callback Obrolan Teks

API TextChatService mendorong pemisahan yang jelas pada tampilan dan pengiriman pesan obrolan. Beberapa instance dari sistem obrolan teks menyediakan hook dan callback untuk memformat di lokasi yang terpusat dan jelas.

Mengirim Pesan Secara Bersyarat

Callback TextChannel.ShouldDeliverCallback harus didefinisikan hanya di server. Callback ini dipicu untuk setiap anak TextSource dari saluran teks ketika pesan dikirim untuk menentukan apakah pesan harus disampaikan. Callback ini dapat digunakan untuk menerapkan logika pengiriman pesan khusus yang mungkin bergantung pada konteks permainan tambahan, seperti:

• Obrolan berbasis kedekatan di mana pengguna hanya dapat mengirim pesan kepada mereka yang dekat dengan mereka.
• Mencegah pengguna dengan atribut tertentu dari mengirim pesan kepada yang lain.

Sesuaikan Tampilan Pesan

UI default TextChatService bergantung pada teks kaya untuk memformat dan menyesuaikan bagaimana pesan ditampilkan. Anda dapat menggunakan callback berikut untuk memformat pesan sebelum ditampilkan kepada pengguna, misalnya untuk menambahkan warna atau tag obrolan pada nama pengguna atau memformat konten pesan.

Callback berikut dipanggil pada setiap TextChatMessage yang akan ditampilkan, yang memungkinkan Anda menyesuaikan tampilan jendela obrolan berdasarkan konten TextChannel, TextSource, atau TextChatMessage. Ketika klien mengirim pesan, callback ini dipanggil sekali ketika pesan dikirim ke server dan nilai TextChatMessage.Status akan menjadi Enum.TextChatMessageStatus.Sending. Setelah pesan diterima oleh server dan sedang dikirimkan kepada pengguna lain, klien pengirim menerima pesan lagi dengan nilai Enum.TextChatMessageStatus yang diperbarui.

• TextChatService.OnIncomingMessage — Callback ini harus didefinisikan hanya di klien. Callback ini dipicu ketika pesan diterima, baik dari server atau jika klien lokal baru saja mengirim pesan. Callback ini dipanggil pada setiap TextChatMessage yang diterima dari semua instance TextChannel dan merupakan yang pertama memproses pesan sebelum ditampilkan kepada pengguna.
• TextChannel.OnIncomingMessage — Callback ini harus didefinisikan hanya di klien. Callback ini dipicu ketika pesan diterima dari server. Callback ini dipanggil pada setiap TextChatMessage yang diterima dari TextChannel. Instance TextChannel default yang dibuat dari TextChatService.CreateDefaultTextChannels memiliki callback ini didefinisikan dan dapat ditimpa.
• TextChatService.OnBubbleAdded — Callback ini harus didefinisikan hanya di klien. Gunakan untuk menyesuaikan tampilan gelembung obrolan terlepas dari tampilan pesan dalam UI jendela obrolan.
• TextChatService.OnChatWindowAdded — Callback ini harus didefinisikan hanya di klien. Gunakan untuk menyesuaikan tampilan pesan obrolan dalam UI jendela obrolan terlepas dari tampilan pesan dalam gelembung obrolan.

Migrasi dari Obrolan Legacy

Bagian ini membantu Anda dalam migrasi dari sistem obrolan legacy dengan menyediakan metode alternatif untuk menerapkan fungsionalitas dan perilaku obrolan umum menggunakan TextChatService.

1. Di jendela Explorer, pilih TextChatService.

2. Di jendela Properties, temukan dropdown ChatVersion dan pilih TextChatService.

   

Fungsionalitas Dasar

Meskipun kedua sistem berbagi fungsionalitas dasar yang sama, implementasi TextChatService umumnya lebih berkelanjutan dan lebih mudah untuk dieksplorasi.

Penyaringan Pesan

TextChatService secara otomatis menyaring pesan obrolan berdasarkan informasi akun masing-masing pemain, sehingga Anda tidak perlu menerapkan penyaringan teks secara manual untuk semua jenis pesan obrolan.

Jendela dan Obrolan Gelembung

Baik perilaku dan opsi kustomisasi jendela obrolan dan obrolan gelembung dari TextChatService identik dengan sistem obrolan legacy. Karena sistem obrolan legacy hanya memperbolehkan kustomisasi menggunakan modul obrolan atau kontainer Players, layanan ini menyediakan kelas khusus (ChatWindowConfiguration dan BubbleChatConfiguration) untuk mengelola semua properti jendela obrolan dan obrolan gelembung. Selain itu, Anda dapat dengan mudah menyesuaikan dan meninjau properti tampilan dan perilaku obrolan gelembung Anda menggunakan pengaturan Studio alih-alih harus memprogram semuanya.

Migrasi "data ekstra" Pembicara

Sistem obrolan Lua legacy memungkinkan pengembang menggunakan SetExtraData pada kelas Speaker. Data ini digunakan untuk memformat warna nama, warna obrolan, atau untuk menerapkan tag nama untuk pembicara tertentu.

Sistem Obrolan Legacy SetExtraData
-- Contoh menetapkan data ekstra pada seorang pembicara di sistem obrolan legacy
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 tidak memiliki padanan langsung untuk SetExtraData. Sebagai gantinya, gunakan callback seperti OnWindowAdded untuk menyesuaikan tampilan pesan menggunakan teks kaya berdasarkan TextSource dari pesan tersebut.

Berikut adalah contoh mensimulasikan "data ekstra" sistem obrolan Lua legacy dengan mengakses atribut pada objek 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)

Kemudian Anda dapat menggunakan callback OnChatWindowAdded untuk menyesuaikan tampilan jendela obrolan berdasarkan atribut yang ditetapkan pada pemain:

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