نظرة عامة على الدردشة النصية

تقدم Roblox رسائل نصية بين اللاعبين في الجلسات المباشرة من خلال TextChatService، وهي فئة مفردة مسؤولة عن إدارة نظام الدردشة بشكل عام، بما في ذلك تصفية رسائل الدردشة، والاعتدال، وأذونات المستخدم. تحتوي هذه الخدمة على وظائفها القياسية وتوفر أيضًا مجموعة من الطرق والأحداث لتوسيع وتخصيص الدردشة، مثل توصيل الرسائل بناءً على متطلبات مخصصة، وإضافة أذونات خاصة أو اعتدال للاعبين محددين، وإنشاء أوامر مخصصة لتنفيذ إجراءات محددة.

تكوين واجهة المستخدم

توفر TextChatService واجهة مستخدم افتراضية يمكن تخصيصها لتناسب احتياجات لعبتك. قم بتعطيل أي من هذه التكوينات لإخفاء عنصر واجهة المستخدم المرتبط بها. إذا رغبت، يمكنك أيضًا استبدال هذه العناصر بواجهات مخصصة:

• ChatWindowConfiguration
• ChatInputBarConfiguration
• ChannelTabsConfiguration
• BubbleChatConfiguration

لمزيد من المعلومات، راجع نافذة الدردشة و الدردشة الفقاعية.

القنوات والرسائل والأوامر

• TextChannel — تمر قنوات النصوص الرسائل المرسلة من المستخدم من العميل إلى الخادم، الذي يعرضها بعد ذلك للمستخدمين الآخرين بناءً على الأذونات. يجب أن تكون قنوات النصوص مرتبطة بـ TextChatService لتعمل.

  إذا تم تعيين TextChatService.CreateDefaultTextChannels إلى true، فإن الخدمة تنشئ تلقائيًا قناتين نصيتين، RBXGeneral و RBXSystem. يمكنك أيضًا إنشاء مثيلات إضافية من TextChannel يدويًا وربطها بـ TextChatService.

• TextSource — مستخدم في TextChannel. يتم ربط مصادر النصوص مباشرة بـ TextChannel عند استدعاء AddUserAsync(). تحتوي مصادر النصوص على أذونات مفصلة لمستخدم في القناة، مثل قدرته على إرسال الرسائل. إذا كان مستخدم واحد في عدة قنوات نصية، فإنه يرتبط بعدة مصادر نصوص.

• TextChatMessage — رسالة في قناة نصية. تحتوي رسائل الدردشة على معلومات أساسية مثل مرسل الرسالة، الرسالة الأصلية، الرسالة المصفاة، وطابع الزمن الخاص بإنشائها.

• TextChatCommand — يتيح للمستخدمين استدعاء إجراءات أو سلوكيات محددة عن طريق إرسال رسائل تتطابق مع خصائص PrimaryAlias أو SecondaryAlias. يجب أن تكون أوامر الدردشة مرتبطة بـ TextChatService لتعمل.

  إذا تم تعيين TextChatService.CreateDefaultCommands إلى true، سيتم إنشاء أوامر الدردشة الافتراضية تلقائيًا. يمكنك أيضًا إنشاء مثيلات إضافية من TextChatCommand يدويًا وربطها بـ TextChatService.

مخطط تدفق الدردشة

تستخدم الدردشة النصية نموذج العميل-الخادم، مع عميل الإرسال، والخادم، وعملاء الاستقبال.

1. يرسل لاعب رسالة من جهازه المحلي، مما يؤدي إلى استدعاء طريقة TextChannel:SendAsync(). تعالج هذه الطريقة الرسالة وتحدد ما إذا كانت أمر دردشة أو رسالة دردشة عادية.

   • إذا كانت الرسالة أمر دردشة، يتم تشغيل حدث TextChatCommand.Triggered لتنفيذ الإجراء المحدد. لا تتطلب خطوات إضافية.

   • إذا كانت الرسالة رسالة دردشة عادية، يتم تشغيل حدث TextChatService.SendingMessage لعرض الرسالة على المرسل على عميل الإرسال. في نفس الوقت، تمر TextChannel:SendAsync() الرسالة إلى الخادم.

2. يقوم الخادم بتشغيل TextChannel.ShouldDeliverCallback لتحديد ما إذا كان يجب توصيل الرسالة للاعبين الآخرين بناءً على الأذونات ومتطلبات تصفية مجتمع Roblox.

3. إذا حددت TextChannel.ShouldDeliverCallback أن الرسالة مؤهلة للتوصيل للاعبين الآخرين، يقوم الخادم بتطبيق أي فلاتر ويشغل TextChannel.OnIncomingMessage مرتين:

   1. المرة الأولى تكون على عميل الإرسال وتدل على أن الخادم يعالج الرسالة من خلال حدث TextChatService.MessageReceived. يستبدل هذا الحدث الرسالة المحلية على عميل الإرسال بالرسالة المعالجة من الخادم. تكون الرسالة متطابقة إذا لم تتطلب الأصل تصفية.

   2. المرة الثانية تكون على عملاء الاستقبال، مما يؤدي إلى تشغيل حدث TextChatService.MessageReceived لعرض الرسالة على اللاعبين الآخرين.

روابط الدردشة النصية واستدعاءات العودة

تشجع واجهة برمجة تطبيقات TextChatService على فصل واضح بين مظهر الرسائل النصية وتوصيلها. توفر عدة مثيلات من نظام الدردشة النصية روابط واستدعاءات للعودة لتنسيق في مواقع مركزية وواضحة.

توصيل الرسائل بشكل مشروط

يجب تعريف استدعاء العودة TextChannel.ShouldDeliverCallback على الخادم فقط. يتم تشغيل الاستدعاء لكل طفل من TextSource لقناة النصوص عند إرسال رسالة لتحديد ما إذا كان يجب توصيل الرسالة. يمكن استخدام هذا الاستدعاء لتنفيذ منطق توصيل رسائل مخصص قد يعتمد على سياق اللعب الإضافي، مثل:

• الدردشة المعتمدة على القرب حيث يمكن للمستخدمين إرسال رسائل فقط لأولئك القريبين منهم.
• منع المستخدمين الذين لديهم سمات معينة من إرسال رسائل للآخرين.

تخصيص عرض الرسائل

تعتمد واجهة المستخدم الافتراضية لـ TextChatService على النص الغني لتنسيق وتخصيص كيفية عرض الرسائل. يمكنك استخدام استدعاءات العودة التالية لتنسيق الرسائل قبل عرضها على المستخدمين، على سبيل المثال لإضافة ألوان أو علامات دردشة لأسماء المستخدمين أو تنسيق محتوى الرسالة.

يتم استدعاء الاستدعاءات التالية على كل TextChatMessage على وشك أن يتم عرضها، مما يتيح لك تخصيص مظهر نافذة الدردشة بناءً على محتوى TextChannel و TextSource أو TextChatMessage. عندما يرسل عميل رسالة، يتم استدعاء هذه الاستدعاءات مرة واحدة عند إرسال الرسالة إلى الخادم وستكون قيمة TextChatMessage.Status هي Enum.TextChatMessageStatus.Sending. بمجرد استلام الرسالة من قبل الخادم ويتم توصيلها إلى مستخدمين آخرين، يتلقى عميل المرسل الرسالة مرة أخرى مع قيمة محدثة لـ Enum.TextChatMessageStatus.

• TextChatService.OnIncomingMessage — يجب تعريف هذا الاستدعاء على العميل فقط. يتم تشغيل الاستدعاء عندما يتم استلام رسالة، إما من الخادم أو إذا كان العميل المحلي قد أرسل للتو رسالة. يتم استدعاء الاستدعاء على كل TextChatMessage تم استلامه من جميع مثيلات TextChannel وهو الأول في معالجة الرسالة قبل عرضها على المستخدم.
• TextChannel.OnIncomingMessage — يجب تعريف هذا الاستدعاء على العميل فقط. يتم تشغيل الاستدعاء عندما يتم استلام رسالة من الخادم. يتم استدعاء الاستدعاء على كل TextChatMessage تم استلامه من TextChannel. تحتوي مثيلات TextChannel الافتراضية التي تم إنشاؤها من TextChatService.CreateDefaultTextChannels على هذا الاستدعاء ويمكن الكتابة فوقه.
• TextChatService.OnBubbleAdded — يجب تعريف هذا الاستدعاء على العميل فقط. استخدمه لتخصيص مظهر فقاعات الدردشة بشكل مستقل عن مظهر الرسالة في واجهة مستخدم نافذة الدردشة.
• TextChatService.OnChatWindowAdded — يجب تعريف هذا الاستدعاء على العميل فقط. استخدمه لتخصيص مظهر رسائل الدردشة في واجهة مستخدم نافذة الدردشة بشكل مستقل عن مظهر الرسالة في فقاعات الدردشة.

الانتقال من الدردشة القديمة

تساعدك هذه القسم في الانتقال من نظام الدردشة القديم من خلال توفير طرق بديلة لتنفيذ وظائف وسلوكيات دردشة شائعة باستخدام TextChatService.

1. في نافذة Explorer، حدد TextChatService.

2. في نافذة Properties، ابحث عن قائمة ChatVersion المنسدلة واختر TextChatService.

   

الوظائف الأساسية

على الرغم من أن كلا النظامين يشتركان في نفس الوظائف الأساسية للدردشة، إلا أن تنفيذات TextChatService بشكل عام أكثر استدامة وأسهل في التكرار.

تصفية الرسائل

تقوم TextChatService تلقائيًا بتصفية رسائل الدردشة بناءً على معلومات حساب كل لاعب، لذا لا تحتاج إلى تنفيذ تصفية نصية يدويًا لجميع أنواع رسائل الدردشة.

نافذة الدردشة والدردشة الفقاعية

تكون سلوكيات وخيارات تخصيص كل من نافذة الدردشة و الدردشة الفقاعية لـ TextChatService متطابقة مع تلك الخاصة بنظام الدردشة القديم. حيث أن نظام الدردشة القديم يسمح فقط بالتخصيص باستخدام وحدات الدردشة أو حاوية Players، توفر الخدمة فئات مخصصة (ChatWindowConfiguration و BubbleChatConfiguration) لإدارة جميع خصائص نافذة الدردشة وخصائص الدردشة الفقاعية. بالإضافة إلى ذلك، يمكنك بسهولة ضبط ومعاينة مظهر وسلوك فقاعات الدردشة الخاصة بك باستخدام إعدادات الاستوديو بدلاً من الاضطرار إلى برمجتها جميعًا.

نقل "بيانات إضافية" المتحدث

سمح نظام الدردشة القديم بلغة Lua للمطورين باستخدام SetExtraData على فئة Speaker. تم استخدام هذه البيانات لتنسيق لون الاسم، لون الدردشة، أو لتطبيق علامات الاسم لمتحدث معين.

-- مثال على تعيين بيانات إضافية على متحدث في نظام الدردشة القديم
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 على ما يعادل مباشر لـ SetExtraData. بدلاً من ذلك، استخدم استدعاءات العودة مثل OnWindowAdded لتخصيص مظهر الرسائل باستخدام النص الغني بناءً على TextSource للرسالة.

فيما يلي مثال على محاكاة "البيانات الإضافية" لنظام الدردشة القديم بلغة Lua من خلال الوصول إلى السمات على كائنات 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)

ثم يمكنك استخدام استدعاء العودة 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