Missions Package

The Missions feature package offers out-of-the-box functionality to create missions that players can complete to achieve rewards and progress in your experience. All missions must have an ID, category, and a list of tasks that players must complete to finish the mission. However, the tasks list can be empty, allowing the mission's rewards to be claimed immediately.

Using the package's customization options, you can personalize all missions to meet your unique gameplay requirements.

Get Package

The Creator Store is a tab of the Toolbox that you can use to find all assets that are made by Roblox and the Roblox community for use within your projects, including model, image, mesh, audio, plugin, video, and font assets. You can use the Creator Store to add one or more assets directly into an open experience, including feature packages!

Every feature package requires the Core feature package to function properly. Once the Core and Missions feature package assets are within your inventory, you can reuse them in any project on the platform.

To get the packages from your inventory into your experience:

1. Add the Core and Missions to your inventory within Studio by clicking the Add to Inventory link in the following set of components.

   Core Feature Package

   The Core Feature Package offers shared DataStore table logic for all feature packages.

   Ouvrir dans Studio

   Ajouter à l'inventaire

   Missions Feature Package

   The Missions Feature Package offers functionality to create missions that players can complete to achieve rewards and progress in your experience.

   Ouvrir dans Studio

   Ajouter à l'inventaire

2. In the menu bar, select the View tab.

3. In the Show section, click Toolbox. The Toolbox window displays.

   

4. In the Toolbox window, click the Inventory tab. The My Models sort displays.

   

5. Click the Feature Package Core tile, then the Missions Feature Package tile. Both package folders display in the Explorer window.

6. Drag the package folders into ReplicatedStorage.

Defining Missions

Each completeable mission includes a set of tasks that must be finished to complete the mission, configuration options, and optional display metadata, all of which can be defined within ReplicatedStorage.Missions.Configs.Missions, with types exported from the Types script in the same folder.

Required Fields

The following fields are required for each mission.

Unlock Conditions

By default, missions are unlocked for players automatically and can be completed exactly once. However, you can use the following optional configuration options to alter this behavior.

Metadata

Missions have metadata that specifies how they will be displayed in the Missions user interface. You can use the following optional fields to customize its metadata.

Defining Tasks

Each mission can have zero or more tasks. If a mission has zero tasks, it is claimable immediately after it's unlocked; if a mission has one or more tasks, once the tasks are complete, the player can collect any rewards associated with the mission. Each task has a taskId, which is the key associated with the task for a given mission.

Tasks come in two types:

• Timed Tasks - Lets you start and stop the task at different points in time. A certain amount of time must pass while the task's timer is running, then the task is complete.
• Count Tasks - Lets you add to or set the task's progress. When the progress reaches a set value, the task is complete.

Both task types share the following fields:

Count Tasks Fields

Count tasks have a required value. When the task progress meets this amount, the task is complete.

Time Tasks Fields

Time tasks have a target amount of time spent, and are started and stopped. When the target amount of time is met, the task is complete.

Configuring Categories

Categories do not have to be explicitly defined to be used, as the category for a mission has default values that will be used. However, you can configure these values in ReplicatedStorage.Missions.Configs.Categories to add additional effects to the category. Categories are identified by unique CategoryIds, the same ones referenced in the missions config.

Integrating Server Logic

Take a look at ReplicatedStorage.Missions.Server.Examples.MissionsExample, which shows how your server will interact with the Missions feature package.

You mainly need to hook up four things once dragging the Missions feature package into your experience:

1. Define missions in your missions config.

2. Add logic to your experience to update task progress or the counters the progress is tied to.

   README
   -- Increases progress on a mission Jumping with a Jumps task
   Missions.addProgressToTask(player, "Jumping", "Jumps", 1)
   
   -- Starts the timer on a mission BattlingTime with a TimeInBattle task
   Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")
   
   -- Stops the timer on a mission BattlingTime with a TimeInBattle task
   Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")
   
   -- Increases the progress on all tasks tied to the Jumps counter
   CounterSystem.addCounter(player, "Jumps", 1)
   
   -- Starts the timer on all timed tasks tied to the TimeInBattle timer counter
   CounterSystem.startTimer(player, "TimeInBattle")
   
   -- Stops the timer on all timed tasks tied to the TimeInBattle timer counter
   CounterSystem.stopTimer(player, "TimeInBattle")

3. Set mission completion handlers, and optionally unlock or fail handlers. Use the completion handler to award the rewards from the mission in your experience.

   README
   local function completeHandler(player: Player, missionId: Types.MissionId)
        print(`{player} completed mission {missionId}`)
        -- Award player their rewards.
    end
   
   Missions.setCompletionHandler(missionId, completeHandler)

4. Unlock missions that are not unlocked automatically. Missions feature package logic ensures that all mission requirements are met before the mission is complete, and its rewards are collectible.

   README
   Missions.unlockMission(player, "Manual")

Configuring Constants

Constants for the Core feature package live in two spots:

• Shared constants live in ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.

• Package-specific constants, in this case the Missions feature package, live in ReplicatedStorage.Missions.Configs.Constants.

Additionally, you can find strings for translation broken out into one location: ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

Customizing UI Components

By modifying the package objects, such as colors, font, and transparency, you can adjust the visual presentation of your missions UI. For example, in ReplicatedStorage.Missions.Configs.Constants, you can enable SingleTaskMode to display a progress bar for a task directly on the mission itself for missions that only have a single task.

In addition, if your experience already has an existing UI that you would like to integrate with the Missions feature package, the client ModuleScript MissionsClient contains all the functions necessary to get the information about a player's missions sent from the server.