Create a quest

All you need to know about how to create quests.

Summary

How to create a quest

Quests are defined in YAML files, organized by category. For example, if you want to add a quest to the easy category, you must edit the easy.yml file. Each quest follows the same structure, regardless of the file it belongs to.

More information about the categories on this page.

Mandatory parameters

name The quest’s title, shown in menus and messages. Supports & color codes and HEX color codes.
description A short text displayed alongside the quest’s name. Formatting supports the same color options as above.
type The action the player must perform (e.g., KILL, BREAK, GET). The full list of quest types and their meaning is documented here.
required Specifies the item or entity concerned by the quest.
- Some types require this parameter (e.g., GET quests always need a required item). To make global quests (any item or entity), simply remove this line.
required_amount The number of actions required (items to collect, blocks to break, mobs to kill, etc.). The required amount can also be dynamic, more details here.
reward Defines what the player receives when completing the quest. A reward must have a type (e.g., MONEY, COMMAND, ITEM) and either an amount or associated actions. Full details are available on the Rewards page.

Important things to note

Indentation in YAML files is critical. Even a single misplaced space may cause errors.
Some types of quests have very specific parameters. Please refer to the associated page.

Placeholders

You can use placeholders in the quest name or description. They will be displayed automatically.

  1:
    name: "&f%player_name%"
    ...
    description:
      - "%player_name%"
    ...

Oraxen, ItemsAdder, Nexo, MMOItems

You can specify for the menu item an item from Oraxen, ItemsAdder, Nexo or MMOItems. It's really simple, you just need to add oraxen:, itemsadder:, nexo: or mmoitems: before the name of the item.

For Oraxen, you need to set use_oraxen to true in the configuration file.

For ItemsAdder, you need to specify the namespace before the name of the item, like the example below. You also need to set use_itemsadder to true in the configuration file.

For Nexo, you need to set use_nexo to true in the configuration file.

For MMOItems, you need to specify the category and the id of the item.

menu_item: "oraxen:my_item"
menu_item: "itemsadder:namespace:my_item"
menu_item: "nexo:my_item"
menu_item: "mmoitems:category:id"

Don't forget to enclose the item names in inverted commas ("..."), otherwise the file will be formatted incorrectly and the plugin will crash!

Custom head texture

You can also use custom head textures, from this website.

The value to put here is the Minecraft-URL at the bottom of the head page. Be sure to use the Minecraft-URL and NOT the Value that is just before!

// from https://minecraft-heads.com/custom-heads/decoration/60568-coin
menu_item: "customhead:ebda5f31937b2ff755271d97f01be84d52a407b36ca77451856162ac6cfbb34f"

Custom model data

You can specify for the menu item a custom model data. You need to add custommodeldata: before the type of the item, and then add the corresponding number just after, as the following example.

menu_item: "custommodeldata:paper:1234"

By default, the menu_item has an amount of 1 in the interface. If you want to change its amount, you can use the menu_item_amount parameter.

  ...
  menu_item: NETHER_QUARTZ_ORE
  menu_item_amount: 10
  required_amount: 10
  ...

The maximum amount is 64 (the maximum stack size), due to Minecraft limitations. You also have the option to set the value to 0, which will automatically apply the value of required_amount to the item.

  ...
  menu_item: NETHER_QUARTZ_ORE
  menu_item_amount: 0 # will be equal to 10 in the menu
  required_amount: 10
  ...

You may also want the item displayed in the menu to be different when a player completes a quest. To do this, you can use the achieved_menu_item parameter, which works exactly like the menu_item parameter.

  ...
  menu_item: NETHER_QUARTZ_ORE
  achieved_menu_item: "customhead:b5a3b49beec3ab23ae0b60dab56e9cc8fa16769a25830b5d8d6c46378f54430" # checkmark head
  ...

Optional parameters

Required worlds

For each quest, you can specify the worlds where the player have to be in order to complete the objective, with the required_worlds parameter. Here is an example:

1:
  name: "&aMiner of hell"
  menu_item: NETHER_QUARTZ_ORE
  description:
    - "&bMine 10 quartz ore in the Nether."
    - "&bWin &c500$&b."
  quest_type: BREAK
  required: NETHER_QUARTZ_ORE
  required_amount: 10
  reward:
    reward_type: MONEY
    amount: 500
  # simply add this section
  required_worlds:
    - world_nether

Required regions

You can also specify the regions in which a quest can progress with the required_regions parameter. Only compatible with WorldGuard.

1:
  name: "&aCow Breeder"
  menu_item: WHEAT
  description:
    - "&bBreed &e5 &bcows inside the &6Cow Farm&b region."
    - "&bReward: &c$500&b."
  quest_type: BREED
  required: COW
  required_amount: 5
  reward:
    reward_type: MONEY
    amount: 500
  # simply add this section
  required_regions:
    - cow_farm

Required permissions

You can restrict quests to players who have specific permissions. This is useful for creating VIP-only quests or quests limited to certain groups.

The parameter is called required_permissions.
It accepts a single permission (string) or a list of permissions (array).
A quest will only be assigned to a player if they have all the listed permissions.

1:
  name: "&6&l[VIP] &aDiamonds"
  menu_item: DIAMOND
  description:
    - "&bGet 50 diamonds."
    - "&bWin &c5000$&b."
  quest_type: GET
  required: DIAMOND
  required_amount: 50
  reward:
    reward_type: MONEY
    amount: 5000
  # simply add this section
  required_permissions: 
    - "odailyquests.vip"

Protection bypass

By default, progress is only made in an authorized region if WorldGuard or Towny are present on the server, notably by checking the BLOCK_PLACE and BLOCK_BREAK flags. If for some reason you want the quest to progress even when the player doesn't have permission, you can add the protection_bypass parameter. This parameter can be combined with the required regions. For example :

1:
  name: "&aMine mine mine"
  menu_item: REDSTONE
  description:
    - "&bMine 500 blocks in the Spawn generator."
    - "&bWin &c500$&b."
  quest_type: BREAK
  required_amount: 10
  reward:
    reward_type: MONEY
    amount: 500
  protection_bypass: true
  required_regions:
    - cow_farm

Multiple requirements

It is possible to assign multiple items/entities to a same quest. Thus, all items/entities in the list will count towards the quest's progress. However, it is not possible to specify a required number for each attribute in the list.

To add multiple items/entities to a quest, the syntax is as follows:

required:
  - COAL_ORE
  - GOLD_ORE
  - ...

Dynamic required amount

The required_amount parameter can be written as a range (e.g., 10-50). When the quest is assigned, the plugin randomly selects a number within this range for that player.

1:
  name: "&aStone Collector"
  menu_item: STONE
  description:
    - "&bMine %required% stone blocks."
    - "&bReward: &c250$&b."
  quest_type: BREAK
  required: STONE
  required_amount: 10-50
  reward:
    reward_type: MONEY
    amount: 250

In this example, each player gets a quest with a random requirement between 10 and 50 stone blocks.

Random required

The random_required parameter allows you to create dynamic quests by letting the plugin randomly select one item (or entity) from a predefined list when the quest is assigned to a player. This makes it possible to generate many unique quests at once with a single configuration.

It can also be combined with a dynamic range for required_amount (e.g., 10-50) to increase variability.

Key points

Each entry in random_required has the format:
```
MATERIAL: "display name"
```
- The material/entity is what the quest tracks.
- The string value is used for display in menus and messages (%displayName% placeholder).
Works with both items and entities.
Only one item/entity from the list is chosen per player when the quest is assigned.
Do not use the required parameter in the same quest. If both are present, random_required will be ignored.

1:
  name: "&a%displayName"
  menu_item: STONE_PICKAXE
  description:
    - "&bMine %required% %displayName%."
    - "&bWin &c500$&b."
  quest_type: BREAK
  random_required:
    - STONE: "stone"
    - GRANITE: "granite"
    - DIORITE: "diorite"
    - COAL_ORE: "coal ore"
    - IRON_ORE: "iron ore"
  required_amount: 64
  reward:
    reward_type: MONEY
    amount: 500

In this example, when a player receives the quest, the plugin randomly picks one block type from the list.

%displayName% is replaced by the corresponding string (e.g., "coal ore"). %required% is replaced by the required amount.

Conditions

Similar to the required permissions, you can define conditions with placeholders that must be met in order to obtain quests. It works like the PLACEHOLDER quest type: same operators and similar configuration.

1:
  name: "&6&l[VIP] &aDiamonds"
  menu_item: DIAMOND
  description:
    - "&bGet 50 diamonds."
    - "&bWin &c5000$&b."
  quest_type: GET
  required: DIAMOND
  required_amount: 50
  conditions:
    vip_condition:
      placeholder: "%luckperms_in_group_vip%"
      operator: EQUALS
      expected: "yes"
      error_message: "&cYou must be VIP to get this quest!"
  reward:
    reward_type: MONEY
    amount: 5000

You can define as many conditions as you want.

PreviousCreate a category NextAvailable types

Last updated 14 days ago