任务包 | 文档 - Roblox 创作者中心

此功能包处于测试阶段。

任务功能包提供了开箱即用的功能，以创建玩家可以完成以获得奖励并在您的体验中取得进展的任务。所有任务必须有一个 ID、类别和任务列表，玩家必须完成这些任务才能完成该任务。然而，任务列表可以是空的，这允许即刻领取任务的奖励。

通过使用包的自定义选项，您可以个性化所有任务，以满足您的独特游戏需求，例如：

创建能够为新玩家提供指导的任务，并提高D1 保留率。
通过添加中长期目标和一种进展感来针对D7 和 D30 保留率。
通过展示您游戏中的各种系统，并奖励玩家与其互动，来提高参与度。

有关如何为玩家提供新目标和激励措施，以便他们能更长时间地获得游戏动机和增加参与度的信息，请参见任务设计简介。

获取包

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

每个功能包需要核心功能包才能正常工作。一旦核心和任务功能包资源进入您的库存，您可以在平台上的任何项目中重复使用它们。

要从您的库存中获取包到您的体验中：

在 Studio 中通过点击以下组件集中的添加到库存链接将核心和任务添加到您的库存。

核心功能包
核心功能包为所有功能包提供共享数据存储逻辑。
任务功能包
任务功能包提供创建任务的功能，玩家可以完成这些任务以获得奖励并在您的体验中取得进展。
从 Studio 的窗口菜单或主页标签工具栏中，打开工具箱。
在工具箱窗口中，点击库存标签。我的模型排序将显示。
点击功能包核心瓷砖，然后点击任务功能包瓷砖。两个包文件夹将显示在浏览器窗口中。
将包文件夹拖入 ReplicatedStorage。

定义任务

每个可完成的任务包括一组必须完成的任务、配置选项和可选的显示元数据，所有这些都可以在 ReplicatedStorage.Missions.Configs.Missions 中定义，类型由同一文件夹中的 Types 脚本导出。

必填字段

每个任务的以下字段是必需的。

名称	类型	描述
missionId	string	主要任务表的键。所有任务均通过其独特字符串进行标识。
categoryId	string	任务必须属于某个类别，并在用户界面中按类别分组。
tasks	table	玩家必须完成的任务列表，以完成该任务。

解锁条件

默认情况下，任务会自动为玩家解锁，并且只能完成一次。但是，您可以使用以下可选配置选项来改变此行为。

名称	类型	描述
prerequisites	table	必须在任务解锁之前完成的其他 missionIds 列表。
manualOnly	bool	禁用任务的自动解锁。相反，必须调用一个函数来解锁任务。任何其他解锁条件也必须得到满足。
availableAfterUtc	bool	在指定的 UTC 时间之前，任务无法解锁。
availableBeforeUtc	bool	在指定的 UTC 时间之后，任务无法解锁。如果在此时间之前已解锁但未完成，则任务将失败。
repeatable	bool	任务在完成后再次解锁。
repeatLimit	number	如果任务是可重复的，则不能重复超过此次数。
repeatCooldownSeconds	number	如果任务是可重复的，解锁之前有一个延迟。
expireSeconds	number	如果任务被解锁但未在指定的秒数内完成，则会失败。
expireCountOffline	bool	如果任务有 expireSeconds 且 expireCountOffline 设置为 true，则玩家不在体验中时的时间将计入任务过期。

元数据

任务具有元数据，用于指定它们在任务用户界面中的显示方式。您可以使用以下可选字段来自定义其元数据。

名称	类型	描述
displayName	string	在用户界面中显示的任务名称，而不是 missionId。
description	string	提供关于该任务的额外信息或上下文的较长文本。
visibleAfterComplete	bool	如果设置为 true，任务将出现在任务列表中，即使标记为已完成。
visibleAfterFailed	bool	如果设置为 true，任务将出现在任务列表中，即使标记为已失败。
visibleBeforeUnlocked	bool	如果设置为 true，任务将在可完成之前在任务列表中显示，但处于锁定状态。
invisibleWhileActive	bool	如果设置为 true，任务在积极进行时将不可见。
rewards	table	奖励显示信息的列表。 assetID (number) - 显示在任务用户界面中任务奖励下的图像 ID。如果存在奖励，则这是必需的。 displayName (string) - 显示在任务用户界面中图标下的名称。

定义任务

每个任务可以有零个或多个任务。如果一个任务没有任务，则在解锁后可立即领取；如果一个任务有一个或多个任务，一旦任务完成，玩家可以收集与该任务相关的任何奖励。每个任务都有一个 taskId，这是与给定任务关联的任务的键。

任务分为两种类型：

计时任务 - 让您在不同时间点开始和停止任务。在任务计时器运行时，必须经过一定时间，然后任务即为完成。
计数任务 - 让您添加或设置任务的进度。当进度达到设定值时，任务完成。

两种任务类型都有以下字段：

名称	类型	描述
taskType	string	指定任务类型是计数任务还是计时任务。
counter	object	(可选) 此任务跟踪的计数器。计数器是玩家特定的持久存储，用于存储数字或计时器。多个任务可以共享同一个计数器；例如，如果多个任务跟踪玩家收集的硬币数，则它们都可以共享同一个“硬币”计数器。这些任务可以独立跟踪新收集的硬币，从零开始，或从计数器值（所有已收集硬币）继续计数。 counterId (string) - 要跟踪的计数器的 ID。使用此 ID 获取或设置计数器的值。 continueFromCounter (可选 bool) - 如果设置为 true，任务进度将直接与计数器的值匹配，而不是增加的数量。
metadata	object	(可选) 关于任务如何在用户界面中显示的信息。 displayName (string) - 任务的名称，在用户界面中显示时使用。 numericType (可选 string) - 任务中的进度数字应如何显示。分数，例如 5/10 或 5k/50k 百分比，例如 50% 或 10% 长分数，例如 5/10 或 5000/50000 布尔值，例如不完整
callToAction	object	(可选) 触发回调函数的按钮。 callback (function) - 由 callToAction 按钮触发的函数。 buttonText (string) - 在按钮用户界面中显示的文本。

计数任务字段

计数任务具有一个必需值。当任务进度达到这个数量时，任务完成。

名称	类型	描述
goalCount	number	(可选) 完成任务所需的进度。

时间任务字段

计时任务有一个目标耗时，并被启动和停止。当达到目标时间时，任务完成。

名称	类型	描述
goalSeconds	number	需要经过的秒数以完成任务。
startImmediately	bool	如果任务应该在解锁后立即开始计算时间，而不是仅在启动后开始。
includesOfflineTime	bool	如果任务应该包括玩家不在体验中时所花费的时间。

配置类别

类别不必明确定义即可使用，因为任务类别有默认值将被使用。但是，您可以在 ReplicatedStorage.Missions.Configs.Categories 中配置这些值，以添加对类别的额外效果。类别由唯一的 CategoryIds 标识，这些 ID 在任务配置中被引用。

名称	类型	描述
repeatDelaySeconds	number	(可选) 如果设置，类别中的所有任务将在指定时间经过后重置，并可以再次解锁、完成和领取奖励。这与在给定类别重复的可重复任务是分开的。

集成服务器逻辑

查看 ReplicatedStorage.Missions.Server.Examples.MissionsExample，展示了您的服务器如何与任务功能包交互。

将任务功能包拖入您的体验后，您主要需要连接四个方面：

在任务配置中定义任务。

向您的体验中添加逻辑，以更新任务进度或与进度相关的计数器。

README
-- 在任务“跳跃”中增加进度
Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

-- 启动任务“战斗时间”中的计时器
Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

-- 停止任务“战斗时间”中的计时器
Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

-- 增加所有与“跳跃”计数器相关的任务进度
CounterSystem.addCounter(player, "Jumps", 1)

-- 启动所有与“战斗时间”计时器计数器相关的计时任务
CounterSystem.startTimer(player, "TimeInBattle")

-- 停止所有与“战斗时间”计时器计数器相关的计时任务
CounterSystem.stopTimer(player, "TimeInBattle")

设置任务完成处理程序，并可选地解锁或失败处理程序。使用完成处理程序在您的体验中颁发任务奖励。

README
local function completeHandler(player: Player, missionId: Types.MissionId)
     print(`{player} 完成了任务 {missionId}`)
     -- 奖励玩家他们的奖励。
 end

Missions.setCompletionHandler(missionId, completeHandler)

解锁未自动解锁的任务。任务功能包逻辑确保在任务完成之前满足所有任务要求，并且其奖励是可以领取的。
```
README
Missions.unlockMission(player, "Manual")
```

配置常量

核心功能包的常量位于两个位置：

共享常量位于 ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants 中。
包特定常量，在本例中是任务功能包，位于 ReplicatedStorage.Missions.Configs.Constants 中。

此外，您可以在一个位置找到翻译字符串：ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings。

自定义 UI 组件

通过修改包对象，例如颜色、字体和透明度，您可以调整任务 UI 的视觉呈现。例如，在ReplicatedStorage.Missions.Configs.Constants 中，您可以启用 SingleTaskMode 以在仅有一个任务的任务上直接显示进度条。

如果您将任何对象在层次结构中移动，代码将无法找到它们，您需要在任务UI 中进行调整。

此外，如果您的体验已经有一个现有的 UI，您希望将其集成到任务功能包中，客户端 ModuleScript MissionsClient 包含获取来自服务器的玩家任务信息所需的所有函数。