Ikhtisar obrolan teks

Roblox menawarkan pengiriman pesan 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 peristiwa untuk memperluas dan menyesuaikan obrolan, seperti mengirim pesan berdasarkan persyaratan yang disesuaikan, menambahkan izin khusus atau moderasi untuk pemain tertentu, dan membuat perintah khusus untuk mengeksekusi tindakan tertentu.

Konfigurasi UI

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

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

Untuk informasi lebih lanjut, lihat Jendela obrolan dan Obrolan gelembung.

Saluran, pesan, dan perintah

• TextChannel — Saluran teks mengirimkan pesan yang dikirim pengguna dari klien ke server, yang kemudian menampilkannya kepada pengguna lain berdasarkan izin. Saluran teks harus diparent ke 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 instance TextChannel tambahan dan memparent-nya ke TextChatService.

• TextSource — Seorang pengguna dalam TextChannel. Sumber teks diparent langsung ke TextChannel ketika AddUserAsync() dipanggil. Sumber teks berisi izin terperinci dari seorang pengguna di saluran, seperti kemampuannya untuk mengirim pesan. Jika seorang pengguna berada di beberapa saluran teks, mereka terkait dengan beberapa sumber teks.

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

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

  Jika TextChatService.CreateDefaultCommands diatur ke true, perintah obrolan default akan dibuat secara otomatis. Anda juga dapat secara manual membuat instance TextChatCommand tambahan dan memparent-nya ke 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 adalah perintah obrolan, itu memicu peristiwa TextChatCommand.Triggered untuk melakukan tindakan yang ditentukan. Tidak ada langkah lebih lanjut yang diperlukan.

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

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

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

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

   2. Kedua kali di klien penerima, yang memicu peristiwa TextChatService.MessageReceived untuk menampilkan pesan kepada pemain lain.

Hook dan callback obrolan teks

API TextChatService mendorong pemisahan yang jelas pada penampilan 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 sebuah pesan dikirim untuk menentukan apakah pesan tersebut harus disampaikan. Callback ini dapat digunakan untuk menerapkan logika pengiriman pesan kustom 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 mengirim pesan kepada orang lain.

Kustomisasi 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 ke nama pengguna atau memformat konten pesan.

Callback berikut dipanggil pada setiap TextChatMessage yang akan ditampilkan, yang memungkinkan Anda menyesuaikan penampilan jendela obrolan berdasarkan TextChannel, TextSource, atau konten 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 disampaikan 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 sebuah 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 sebuah 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 ini untuk menyesuaikan penampilan gelembung obrolan terlepas dari penampilan pesan di UI jendela obrolan.
• TextChatService.OnChatWindowAdded — Callback ini harus didefinisikan hanya di klien. Gunakan ini untuk menyesuaikan penampilan pesan obrolan di UI jendela obrolan terlepas dari penampilan pesan di gelembung obrolan.

Migrasi dari obrolan lama

Bagian ini membantu Anda dalam migrasi dari sistem obrolan lama 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 memiliki fungsionalitas obrolan dasar yang sama, implementasi TextChatService umumnya lebih berkelanjutan dan lebih mudah untuk diiterasi.

Penyaringan pesan

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

Jendela dan obrolan gelembung

Baik jendela obrolan maupun perilaku dan opsi kustomisasi obrolan gelembung dari TextChatService identik dengan sistem obrolan lama. Karena sistem obrolan lama hanya memungkinkan kustomisasi menggunakan modul obrolan atau wadah 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 melihat properti penampilan dan perilaku obrolan gelembung Anda menggunakan pengaturan Studio alih-alih harus menyusunnya semua.

Migrasi "data tambahan" pembicara

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

-- Contoh pengaturan data tambahan pada pembicara dalam sistem obrolan lama
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 penampilan pesan menggunakan teks kaya berdasarkan TextSource dari pesan tersebut.

Berikut adalah contoh meniru "data tambahan" obrolan Lua lama dengan mengakses atribut pada objek 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)

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

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