赛季通行证包

赛季通行证功能包提供开箱即用的功能，以创建限时的基于任务的进度系统，玩家可以完成任务目标以获得仅在预定义时间段内可用的奖励。通过使用该包的自定义选项，您可以个性化所有赛季通行证，以向您的受众提供新内容，促进玩家留存并产生收入。

获取包

创作者商店是工具箱的一个选项卡，您可以使用它查找所有由Roblox和Roblox社区制作的可在您的项目中使用的资产，包括模型、图像、网格、音频、插件、视频和字体资产。您可以使用创作者商店将一个或多个资产直接添加到打开的游戏中，包括功能包！

每个功能包都需要核心功能包才能正常运行，而赛季通行证包需要任务功能包来定义赛季的任务。一旦这三个包的资产都在您的库存中，您可以在平台上的任何项目中重复使用它们。

要将包从您的库存添加到游戏中：

1. 通过单击以下组件集中的添加到库存链接，将核心、任务和赛季通行证包添加到Studio中的库存中。

   核心功能包

   核心功能包为所有功能包提供共享数据存储表逻辑。

   添加至道具库

   任务功能包

   任务功能包提供创建任务的功能，玩家可以完成这些任务以获得奖励并在游戏中进展。

   添加至道具库

   赛季通行证功能包

   赛季通行证功能包提供创建限时的基于任务的进度系统的功能，玩家可以完成这些任务以获得奖励。

   添加至道具库

2. 从Studio的窗口菜单或主页选项卡工具栏中，打开工具箱。

3. 在工具箱窗口中，单击库存选项卡。我的模型排序显示。

   

4. 单击功能包核心图块、任务功能包图块，然后单击赛季通行证功能包图块。所有三个包文件夹将在资源管理器窗口中显示。

5. 将包文件夹拖入ReplicatedStorage。

6. 允许数据存储调用跟踪玩家使用包的购买情况。

   1. 打开Studio的文件 ⟩ 体验设置窗口。
   2. 导航到安全选项卡，然后启用启用Studio访问API服务。

配置任务依赖关系

为了使赛季正常运行，您必须添加逻辑，以便赛季通行证功能包可以跟踪玩家进度并更新其UI组件。为了简单起见，下面的示例使用任务功能包，并在玩家完成任务后调用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外，赛季通行证功能包还使用任务功能包在赛季中定义独特的奖励等级。如果您想为玩家可以获得的等级奖励添加屏幕图标，请在每个赛季等级奖励的Missions配置中添加资产ID。

Tier3Mission = {
		categoryId = "General",
		metadata = {
			displayName = "第3等级任务",
			description = "跳跃10次",
			visibleAfterComplete = true,
			visibleBeforeUnlocked = true,
			rewards = {
				{
					icon = 16826775737,
					displayName = "物品",
				},
				{
					icon = 106912146245070,
					displayName = "赛季XP",
				},
			},
		},
	}

配置赛季

在您设置好要包含在赛季中的每个任务后，是时候配置赛季通行证本身。在ReplicatedStorage.SeasonPasses.Configs.Season中，有一个赛季配置的示例供您参考，以下代码示例来自该文件。

定义通行证

通行证允许您向玩家收取一次性Robux费用，以便访问赛季通行证的任务和潜在奖励。在您创建一个具有唯一资产ID的通行证后，您可以在赛季的premiumTrack字段中设置通行证的详细信息。 例如，以下代码示例定义了一个通行证，示例资产ID为928192647，表示一个赛季通行证，然后将赛季通行证的轨道名称设置为“高级轨道”。

premiumTrack = {
        pricing = {
            gamePassId = 928192647,
        },
        trackMetadata = {
            trackName = "高级轨道",
        },
    },

配置等级和奖励

赛季等级代表玩家必须达到的里程碑，以便在整个赛季中获得奖励。为了提升等级，玩家完成任务以获得XP，当他们获得足够的XP时，他们将晋级到下一个等级，并获得他们刚刚完成的等级的奖励。 等级具有upperBoundXP属性，该属性设置了领取等级奖励所需的XP阈值。每个等级可以提供两种类型的奖励：

• 免费 - 玩家可以在不购买赛季通行证的情况下获得的奖励。
• 高级 - 玩家只能通过购买赛季通行证获得的奖励。

为了演示，请查看以下代码示例，该示例为一个等级需要100 XP以获得免费冰矛奖励和高级爆炸护盾奖励。icon是要显示的奖励的UI图像的资产ID，displayName显示奖励的名称。请注意，displayName在UI中显示，但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。 您可能想要调整以满足游戏设计要求的主要内容：
• 声音资产ID
• 购买效果持续时间和粒子颜色 此外，您可以在一个位置找到用于翻译的字符串：ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings。

自定义UI组件

通过修改包对象，例如颜色、字体和透明度，您可以调整赛季通行证提示的视觉呈现。然而，请记住，如果您在层次结构中移动任何对象，代码将无法找到它们，您需要对代码进行调整。

一个赛季由以下高层组件组成，这些组件以编程方式添加到任务功能包的UI组件中：

• SeasonBottomFrame – 包含有关每个轨道的信息、等级奖励的滚动框架和等级数据的框架。
• SeasonDescriptionFrame - 在标题中显示赛季标题、描述和倒计时的框架。
• TierRewardFrame - 显示特定等级奖励的框架。
• TierProgressFrame - 显示玩家在当前等级上所取得进展的框架。
• PurchaseFrame - 提示玩家购买高级通行证的框架。
• SeasonProgressFrame - 显示玩家在整个赛季中的进度条的框架。
• RewardsButtonFrame - 添加一个按钮的框架，允许通过SeasonBottomFrame显示赛季的信息。