任務包

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

任務功能包提供即時可用的功能，以創建玩家可以完成以獲得獎勵並在您的遊戲中進行進度的任務。所有任務必須具有 ID、類別和玩家必須完成的任務列表以完成該任務。然而，任務列表可以是空的，允許立即索取任務的獎勵。

使用該包的自定義選項，您可以個性化所有任務以滿足您獨特的遊戲需求，例如：

  • 創建任務以 引導 新玩家進入您的遊戲並改善 D1 留存率。
  • 通過添加中期到長期目標和進步感來針對 D7 和 D30 留存率。
  • 通過展示您遊戲中的各種系統並獎勵玩家與它們互動來增加 參與度。

獲取包

創作者商店是 工具箱 的一個選項卡，您可以使用它來查找所有由 Roblox 和 Roblox 社區製作的資產，以便在您的項目中使用，包括模型、圖像、網格、音頻、插件、視頻和字體資產。您可以使用創作者商店將一個或多個資產直接添加到打開的遊戲中，包括功能包！

每個功能包都需要 核心 功能包才能正常運行。一旦 核心 和 任務 功能包資產在您的庫中，您可以在平台上的任何項目中重用它們。

要將庫中的包添加到您的遊戲中：

  1. 通過單擊以下組件集中的 添加到庫 連結，將 核心 和 任務 添加到您在 Studio 中的庫。

    核心功能包

    核心功能包提供所有功能包的共享數據存儲邏輯。

    任務功能包

    任務功能包提供創建玩家可以完成以獲得獎勵並在您的遊戲中進行進度的任務的功能。

  2. 從 Studio 的 窗口 菜單或 首頁 標籤工具欄中，打開 工具箱。

  3. 在 工具箱 窗口中，單擊 庫 標籤。顯示 我的模型 排序。

    Studio 的工具箱窗口，庫標籤突出顯示。

  4. 單擊 功能包核心 瓷磚，然後單擊 任務功能包 瓷磚。兩個包文件夾在 資源管理器 窗口中顯示。

  5. 將包文件夾拖入 ReplicatedStorage。

定義任務

每個可完成的任務包括一組必須完成的任務、配置選項和可選的顯示元數據，所有這些都可以在 ReplicatedStorage.Missions.Configs.Missions 中定義，類型從同一文件夾中的 Types 腳本導出。

必填字段

每個任務需要以下字段。

名稱類型描述
missionIdstring主要任務表的鍵。所有任務都由其唯一字符串識別。
categoryIdstring任務必須屬於一個類別，並在 UI 中按類別分組。
taskstable玩家必須完成的任務列表以完成該任務。

解鎖條件

默認情況下，任務會自動為玩家解鎖，並且只能完成一次。然而，您可以使用以下 可選 配置選項來更改此行為。

名稱類型描述
prerequisitestable必須在任務解鎖之前完成的其他 missionIds 列表。
manualOnlybool禁用任務的自動解鎖。相反，必須調用一個函數來解鎖該任務。任何其他解鎖條件也必須滿足。
availableAfterUtcbool在指定的 UTC 時間之前無法解鎖該任務。
availableBeforeUtcbool在指定的 UTC 時間之後無法解鎖該任務。如果在此時間之前解鎖但未完成，則該任務將失敗。
repeatablebool該任務在完成後再次解鎖。
repeatLimitnumber如果該任務是可重複的，則不能重複超過此次數。
repeatCooldownSecondsnumber如果該任務是可重複的，則在其再次解鎖之前會有延遲。
expireSecondsnumber如果該任務已解鎖且在指定的秒數內未完成，則將失敗。
expireCountOfflinebool如果該任務具有 expireSeconds 且 expireCountOffline 設置為 true，則玩家不在遊戲中的時間將計入任務過期。

元數據

任務具有元數據，指定它們將如何在任務用戶界面中顯示。您可以使用以下 可選 字段來自定義其元數據。

名稱類型描述
displayNamestring在用戶界面中顯示的任務名稱，而不是 missionId。
descriptionstring提供有關該任務的額外信息或上下文的較長文本塊。
visibleAfterCompletebool如果設置為 true，該任務即使在完成後也會顯示在任務列表中，但標記為已完成。
visibleAfterFailedbool如果設置為 true，該任務即使在失敗後也會顯示在任務列表中，但標記為已失敗。
visibleBeforeUnlockedbool如果設置為 true，該任務在可完成之前將在任務列表中可見但被鎖定。
invisibleWhileActivebool如果設置為 true，該任務即使在積極進行中也將不可見。
rewardstable獎勵顯示信息的列表。
  • assetID (number) - 在任務 UI 中顯示的圖像 ID，顯示在任務的獎勵下。如果存在獎勵，則此項為必填。
  • displayName (string) - 在任務 UI 中圖標下顯示的名稱。

定義任務

每個任務可以有零個或多個任務。如果一個任務沒有任務，則在解鎖後可以立即索取；如果一個任務有一個或多個任務，則一旦任務完成，玩家可以收集與該任務相關的任何獎勵。每個任務都有一個 taskId，這是與給定任務相關的任務的鍵。

任務有兩種類型：

  • 計時任務 - 允許您在不同的時間點開始和停止任務。必須在任務計時器運行時經過一定的時間，然後任務完成。
  • 計數任務 - 允許您增加或設置任務的進度。當進度達到設置的值時，任務完成。

兩種類型的任務共享以下字段：

名稱類型描述
taskTypestring指定任務類型是計數還是計時。
counterobject(可選) 此任務跟蹤的計數器。計數器是玩家特定的持久存儲，用於數字或計時器。多個任務可以跟蹤單個計數器；例如，如果多個任務跟蹤玩家收集的硬幣數量，則它們都可以共享相同的“硬幣”計數器。這些任務可以獨立跟蹤新收集的硬幣，從零開始，或從計數器值（所有已收集的硬幣）繼續計數。
  • counterId (string) - 要跟蹤的計數器的 ID。使用此 ID 獲取或設置計數器的值。
  • continueFromCounter (可選 bool) - 如果設置為 true，則任務進度將直接匹配計數器的值，而不是增加的數量。
metadataobject(可選) 有關任務在 UI 中顯示方式的信息。
  • displayName (string) - 任務的名稱，用於在 UI 中顯示。
  • numericType (可選 string) - 任務中進度數字的顯示方式。
    • 分數，例如 5/10 或 5k/50k
    • 百分比，例如 50% 或 10%
    • 長分數，例如 5/10 或 5000/50000
    • 布爾值，例如 未完成
callToActionobject(可選) 觸發回調函數的按鈕。
  • callback (function) - 由 callToAction 按鈕觸發的函數。
  • buttonText (string) - 在按鈕 UI 中顯示的文本。

計數任務字段

計數任務有一個必填值。當任務進度達到此數量時，任務完成。

名稱類型描述
goalCountnumber(可選) 完成任務所需的進度。

計時任務字段

計時任務有一個目標時間，並且可以開始和停止。當達到目標時間時，任務完成。

名稱類型描述
goalSecondsnumber必須經過的秒數以完成任務。
startImmediatelybool如果任務應在解鎖後立即開始計時，而不是僅在開始後。
includesOfflineTimebool如果任務應包括玩家不在遊戲中時所花費的時間。

配置類別

類別不必明確定義以供使用，因為任務的類別具有將使用的默認值。然而，您可以在 ReplicatedStorage.Missions.Configs.Categories 中配置這些值，以為類別添加額外效果。類別由唯一的 CategoryIds 識別，這些 ID 與任務配置中引用的 ID 相同。

名稱類型描述
repeatDelaySecondsnumber(可選) 如果設置，該類別中的所有任務在指定的時間間隔內重置，並且可以再次解鎖、完成和索取獎勵。這與可重複的任務不同，後者在給定的類別重複。

整合伺服器邏輯

查看 ReplicatedStorage.Missions.Server.Examples.MissionsExample，該示例顯示了您的伺服器將如何與 任務 功能包互動。

您主要需要在將 任務 功能包拖入遊戲後連接四件事：

  1. 在您的任務配置中定義任務。

  2. 向您的遊戲添加邏輯以更新任務進度或與進度相關的計數器。

    README
    -- 在任務 Jumping 中增加 Jumps 任務的進度

    Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

    

    -- 在任務 BattlingTime 中開始計時任務 TimeInBattle

    Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

    

    -- 停止任務 BattlingTime 中的計時任務 TimeInBattle

    Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

    

    -- 增加所有與 Jumps 計數器相關的任務的進度

    CounterSystem.addCounter(player, "Jumps", 1)

    

    -- 開始所有與 TimeInBattle 計時器計數器相關的計時任務

    CounterSystem.startTimer(player, "TimeInBattle")

    

    -- 停止所有與 TimeInBattle 計時器計數器相關的計時任務

    CounterSystem.stopTimer(player, "TimeInBattle")

  3. 設置任務完成處理程序，並可選擇設置解鎖或失敗處理程序。使用完成處理程序在您的遊戲中獎勵任務的獎勵。

    README
    local function completeHandler(player: Player, missionId: Types.MissionId)

         print(`{player} 完成了任務 {missionId}`)

         -- 獎勵玩家的獎勵。

     end

    

    Missions.setCompletionHandler(missionId, completeHandler)

  4. 解鎖未自動解鎖的任務。任務功能包邏輯確保在任務完成之前滿足所有任務要求，並且其獎勵可被收集。

    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，您希望與 任務 功能包集成，客戶端 ModuleScript MissionsClient 包含所有必要的函數，以從伺服器獲取有關玩家任務的信息。

©2026 Roblox Corporation、Roblox、Roblox 標誌及 Powering Imagination 是我們在美國及其他國家地區的部分註冊與未註冊商標。
條款·隱私權·無障礙功能·支援
中文(繁體)