حزمة بطاقات الموسم

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

الحصول على الحزمة

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

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

للحصول على الحزم من مخزونك إلى لعبتك:

1. أضف حزم النواة والمهام وبطاقات الموسم إلى مخزونك داخل الاستوديو من خلال النقر على رابط إضافة إلى المخزون في مجموعة المكونات التالية.

   حزمة الميزات الأساسية

   تقدم حزمة الميزات الأساسية منطق جدول تخزين البيانات المشتركة لجميع حزم الميزات.

   Add to inventory

   حزمة ميزات المهام

   تقدم حزمة ميزات المهام وظائف لإنشاء مهام يمكن للاعبين إكمالها لتحقيق المكافآت والتقدم في لعبتك.

   Add to inventory

   حزمة ميزات بطاقات الموسم

   تقدم حزمة ميزات بطاقات الموسم وظائف لإنشاء نظام تقدم قائم على المهام لفترة محدودة يمكن للاعبين إكماله لكسب المكافآت.

   Add to inventory

2. من قائمة نافذة في الاستوديو أو شريط أدوات علامة التبويب الرئيسية، افتح صندوق الأدوات.

3. في نافذة صندوق الأدوات، انقر على علامة التبويب المخزون. يتم عرض فرز نماذجي.

   

4. انقر على بلاطة حزمة الميزات الأساسية، ثم بلاطة حزمة ميزات المهام، ثم بلاطة حزمة ميزات بطاقات الموسم. يتم عرض جميع مجلدات الحزم الثلاثة في نافذة المستكشف.

5. اسحب مجلدات الحزم إلى ReplicatedStorage.

6. اسمح لاستدعاءات تخزين البيانات بتتبع مشتريات اللاعبين مع الحزم.

   1. افتح نافذة ملف ⟩ إعدادات التجربة في الاستوديو.
   2. انتقل إلى علامة التبويب الأمان، ثم قم بتمكين تمكين وصول الاستوديو إلى خدمات API.

تكوين تبعيات المهام

لكي تعمل المواسم بشكل صحيح، يجب عليك إضافة منطق حتى تتمكن حزمة ميزات بطاقات الموسم من تتبع تقدم اللاعبين وتحديث مكوناتها في واجهة المستخدم. لتبسيط الأمر، يستخدم المثال أدناه حزمة ميزات المهام ويستدعي SeasonPasses.addProgressToSeason() بعد أن يكمل اللاعبون المهام، ولكن يمكنك تتبع تقدم اللاعبين كما تريد. ومع ذلك، سواء قمت بتعريف المهام أم لا، يجب عليك إضافة حزمة ميزات المهام إلى لعبتك لكي تعمل شيفرة بطاقات الموسم.

تمتلك كل مهمة مجموعة من المهام التي يجب الانتهاء منها لإكمال المهمة، وخيارات تكوين، وبيانات عرض اختيارية. للحصول على دليل شامل حول كيفية تكوين المهام ومهامها، راجع تعريف المهام.

إضافة XP من المهام إلى المواسم

يستخدم هذا المثال حزمة ميزات المهام لتعريف المهام التي يمكن للاعبين إكمالها لكسب الخبرة (XP) والتقدم خلال الموسم. لمنح اللاعبين XP عند إكمالهم مهمة محددة، يجب عليك إضافة منطق إلى البرنامج النصي الخادم ReplicatedStorage.Missions.Server.Examples.MissionsExample بحيث يمكنه استيراد بيانات بطاقة الموسم ومكافأة اللاعبين وفقًا لتقدمهم.

local SeasonPasses = require(ReplicatedStorage.SeasonPasses.Server.SeasonPasses)

local function completeHandler(player: Player, missionId: Types.MissionId)
	print(`{player} أكمل المهمة {missionId}`)
	if missionId == "Walking" then
		SeasonPasses.addProgressToSeason(player, 100)
	end
	if missionId == "Walking2" then
		SeasonPasses.addProgressToSeason(player, 100)
	end
	if missionId == "Walking3" then
		SeasonPasses.addProgressToSeason(player, 100)
	end
	if missionId == "Availability" then
		SeasonPasses.addProgressToSeason(player, 100)
	end
	if missionId == "Manual" then
		SeasonPasses.addProgressToSeason(player, 100)
	end
	if missionId == "Minutely" then
		SeasonPasses.addProgressToSeason(player, 100)
	end
end

إضافة أيقونات مكافآت مستوى الموسم

بالإضافة إلى منح اللاعبين XP عند إكمال المهام، تستخدم حزمة ميزات بطاقات الموسم حزمة ميزات المهام لتعريف مستويات مكافآت فريدة داخل الموسم. إذا كنت ترغب في إضافة أيقونة على الشاشة لمكافأة مستوى يمكن للاعبين كسبها إذا حصلوا على ما يكفي من XP، أضف معرف الأصل في تكوين المهام لكل مكافأة مستوى موسم.

Tier3Mission = {
		categoryId = "عام",
		metadata = {
			displayName = "مهمة المستوى 3",
			description = "اقفز 10 مرات",
			visibleAfterComplete = true,
			visibleBeforeUnlocked = true,
			rewards = {
				{
					icon = 16826775737,
					displayName = "عنصر",
				},
				{
					icon = 106912146245070,
					displayName = "XP الموسم",
				},
			},
		},
	}

تكوين المواسم

بعد إعداد كل مهمة تريد تضمينها في موسم، حان الوقت لتكوين بطاقة الموسم نفسها. في ReplicatedStorage.SeasonPasses.Configs.Season، يوجد مثال لتكوين موسم للرجوع إليه، والعينات البرمجية التالية مأخوذة من ذلك الملف.

تعريف البطاقات

تسمح البطاقات لك بفرض رسوم على اللاعبين مقابل رسوم Robux لمرة واحدة للوصول إلى مهام بطاقة الموسم والمكافآت المحتملة. بعد إنشاء بطاقة بمعرف أصل فريد، يمكنك تعيين تفاصيل البطاقة في حقل premiumTrack لموسمك. على سبيل المثال، يحدد المثال البرمجي التالي بطاقة بمعرف أصل مثال قدره 928192647 لتمثيل بطاقة موسم، ثم يمنح بطاقة الموسم اسم مسار "المسار المتميز".

premiumTrack = {
        pricing = {
            gamePassId = 928192647,
        },
        trackMetadata = {
            trackName = "المسار المتميز",
        },
    },

تكوين المستويات والمكافآت

تمثل مستويات الموسم المعالم التي يجب على اللاعبين تحقيقها لكسب المكافآت طوال الموسم. للتقدم عبر المستويات، يكمل اللاعبون المهام لكسب XP، وعندما يكسبون ما يكفي من XP، يتخرجون إلى المستوى التالي ويتلقون المكافآت للمستوى الذي أكملوه للتو. تمتلك المستويات خاصية upperBoundXP التي تحدد الحد الأدنى من XP اللازم للمطالبة بالمكافآت لمستوى معين. يمكن أن تقدم كل مستوى نوعين من المكافآت:

• مجاني - مكافأة يمكن للاعبين كسبها دون شراء بطاقة الموسم.
• متميز - مكافأة يمكن للاعبين كسبها فقط من خلال شراء بطاقة الموسم.

للتوضيح، راجع المثال البرمجي التالي لموسم يحتوي على مستوى واحد يتطلب 100 XP لكسب مكافأة رمح جليدي مجانية ومكافأة درع انفجاري متميز. icon هو معرف الأصل لصورة واجهة المستخدم التي سيتم عرضها لمكافأة، وdisplayName يعرض اسم المكافأة. لاحظ أن displayName يظهر في واجهة المستخدم، ولكن rewardId مخفي عن اللاعب ويستخدم بشكل أساسي لأغراض تخزين البيانات.

tiers = {
        [1] = {
            upperBoundXP = 100,
            freeReward = {
                icon = 128181721602852,
                displayName = "رمح جليدي",
                rewardId = "iceLance",
            },
            premiumReward = {
                icon = 95882371958115,
                displayName = "درع انفجاري",
                rewardId = "blastShield",
            },
        },
    }

بينما يكون هذا البرنامج النصي لأغراض التوضيح حول كيفية تكوين مستوى واحد في كل مرة، تتضمن معظم المواسم أكثر من مستوى واحد. أثناء تعريف مستويات متعددة ومكافآت لموسم، تأكد من أن كل rewardId رقمي وفي ترتيب متزايد حتى تظهر مستوياتك بالترتيب الذي تحدده في قائمة المستويات.

تعريف تفاصيل الموسم

الآن بعد أن لديك بطاقة موسم مع مستويات ومكافآت، حان الوقت لتعريف تفاصيل موسمك:

• title - اسم موسمك.
• description - وصف موسمك.
• startUtc - بداية الموسم في الوقت العالمي المنسق.
• endUtc - نهاية الموسم في الوقت العالمي المنسق.
• seasonId - يتيح لك تتبع XP الذي يكسبه اللاعب طوال الموسم المعطى.

تستخدم الحزمة startUtc وendUtc لعرض العد التنازلي للموسم.

startUtc = DateTime.fromUniversalTime(2024, 10, 01, 17, 0, 0),
endUtc = DateTime.fromUniversalTime(2025, 2, 28, 17, 0, 0),
title = "الموسم 1",
description = "إلى مدينة الفضاء",
seasonId = "season1",

دمج منطق الخادم

ألقِ نظرة على ReplicatedStorage.SeasonPasses.Server.Examples.SeasonPassesExample، الذي يوضح كيف سيتفاعل خادمك مع حزمة ميزات بطاقات الموسم. المقتطف أدناه مأخوذ من ذلك البرنامج النصي.

تحتاج بشكل أساسي إلى إنشاء دالة معالج لمنح المكافآت المزعومة للاعبين. على سبيل المثال، ينشئ المثال البرمجي التالي دالة rewardClaimedHandlerFunction() تتعقب متى يتقدم اللاعبون إلى المستوى التالي، ثم يكافئهم إما بالمكافأة المجانية فقط، أو بالمكافأتين المجانية والمتميزة إذا قاموا بشراء بطاقة الموسم.

لأغراضك، استبدل استدعاء task.wait() بمنطق يسمح للاعبين بالحصول على المكافآت التي قاموا بالمطالبة بها في الموسم. يجب أن تعيد هذه الدالة قيمة منطقية: true إذا منح الخادم المكافأة، false إذا لم يفعل.

local function rewardClaimedHandlerFunction(_player: Player, _rewardId: Types.RewardId): boolean
	task.wait(2)
	return true
end

local function initializeRewardClaimedHandlers()
	for tierId, tier in pairs(Season.tiers) do
		if tier then
			if tier.freeReward then
				SeasonPasses.setRewardClaimedHandler(tier.freeReward.rewardId, rewardClaimedHandlerFunction)
			end
			if tier.premiumReward then
				SeasonPasses.setRewardClaimedHandler(tier.premiumReward.rewardId, rewardClaimedHandlerFunction)
			end
		end
	end
end

تكوين الثوابت

تعيش الثوابت الخاصة بحزمة النواة في مكانين:

• تعيش الثوابت المشتركة في ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.
• الثوابت الخاصة بالحزمة، وفي هذه الحالة حزمة ميزات بطاقات الموسم، تعيش في ReplicatedStorage.SeasonPasses.Configs.Constants. الأشياء الرئيسية التي قد ترغب في ضبطها لتلبية متطلبات تصميم لعبتك:
• معرفات أصول الصوت
• مدة تأثير الشراء وألوان الجسيمات بالإضافة إلى ذلك، يمكنك العثور على سلاسل للترجمة مقسمة إلى موقع واحد: ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

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

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

يتكون الموسم من المكونات عالية المستوى التالية التي تتم إضافتها برمجيًا إلى مكونات واجهة مستخدم حزمة ميزات المهام:

• SeasonBottomFrame – الإطار الذي يتضمن معلومات حول كل مسار، وإطار تمرير للمكافآت للمستويات، وبيانات المستوى.
• SeasonDescriptionFrame - الإطار في الرأس الذي يعرض عنوان الموسم، والوصف والعد التنازلي.
• TierRewardFrame - الإطار الذي يعرض مكافأة معينة لمستوى.
• TierProgressFrame - الإطار الذي يعرض التقدم الذي أحرزه اللاعب نحو المستوى الحالي الذي يعمل عليه.
• PurchaseFrame - الإطار الذي يطلب من اللاعب شراء بطاقة مميزة.
• SeasonProgressFrame - الإطار الذي يعرض شريط تقدم اللاعب طوال الموسم بأكمله.
• RewardsButtonFrame - الإطار الذي يضيف زرًا يسمح بعرض معلومات الموسم من خلال SeasonBottomFrame.