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

此功能包处于测试阶段。

任务功能包提供开箱即用的功能，以创建玩家可以完成的任务，以获得奖励并在您的游戏中进展。所有任务必须具有 ID、类别和玩家必须完成的任务列表，以完成该任务。然而，任务列表可以为空，允许立即领取任务的奖励。

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

创建任务以引导新玩家进入您的游戏，并提高 D1 留存率。
通过添加中长期目标和进展感来针对 D7 和 D30 留存率。
通过展示您游戏中的各种系统并奖励玩家与之互动来增加参与度。

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

获取包

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

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

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

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

核心功能包
核心功能包为所有功能包提供共享数据存储逻辑。
任务功能包
任务功能包提供创建玩家可以完成以获得奖励和在您的游戏中进展的任务的功能。
从 Studio 的窗口菜单或主页选项卡工具栏中，打开工具箱。
在工具箱窗口中，单击库存选项卡。我的模型排序显示。
单击功能包核心图块，然后单击任务功能包图块。两个包文件夹在资源管理器窗口中显示。
将包文件夹拖入 ReplicatedStorage。

定义任务

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

必填字段

每个任务都需要以下字段。

名称	类型	描述
missionId	string	主要任务表的键。所有任务都通过其唯一字符串进行标识。
categoryId	string	任务必须属于一个类别，并在 UI 中按类别分组。
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) - 在任务 UI 中显示在任务奖励下的图像 ID。如果存在奖励，则这是必需的。 displayName (string) - 在任务 UI 中显示在图标下的名称。

定义任务

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

任务有两种类型：

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

这两种任务类型共享以下字段：

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

计数任务字段

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

名称	类型	描述
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，以便在仅有单个任务的任务上直接显示任务的进度条。

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

此外，如果您的游戏已经有现有的 UI，您希望与任务功能包集成，客户端 ModuleScript MissionsClient 包含获取从服务器发送的玩家任务信息所需的所有函数。