任務包 | 文件 - 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) - 在任務用戶界面中顯示的圖像ID，用於顯示任務的獎勵。如果有獎勵，此項為必填。 displayName (string) - 在任務用戶界面下的圖標中顯示的名稱。

定義任務

每個任務可以有零個或多個任務。如果一個任務沒有任務，它在解鎖後可以立即被認領；如果一個任務有一個或多個任務，當這些任務完成後，玩家可以收集與該任務相關的任何獎勵。每個任務都有一個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
-- 在Jumping任務中增加進度
Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

-- 在BattlingTime任務中啟動計時器
Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

-- 停止BattlingTime任務中的計時器
Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

-- 增加與Jumps計數器相關的所有任務的進度
CounterSystem.addCounter(player, "Jumps", 1)

-- 在所有計時任務中啟動與TimeInBattle計時器計數器相關的計時器
CounterSystem.startTimer(player, "TimeInBattle")

-- 停止所有計時任務中與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包含獲取關於玩家任務的信息並從伺服器發送所需的所有函數。