Create a quest

All you need to know about how to create quests.

Quests must be created in dedicated files.

If you have selected mode 1, they must all be created in the "globalQuests.yml" file.

If you have selected mode 2, they must be created in the files "easyQuests.yml", "mediumQuests.yml" and "hardQuests.yml".

The name and description of a quest will be displayed in the menus and messages.

The type of the quest represents the action the player has to perform, for which an item is specified just below and an amount. You can see all the quest types and what they correspond to on this page.

For some types of quests, you don't need to specify an item or an entity. These quests will be "global" quests, which will take into account all items and entities. Note that for GET quests, you must indicate a required item. To create a global quest, simply delete the required_item or entity_type line in your quest configuration.

For each quest a reward is specified, with a type and amount or associated actions. You can see all the types of rewards and what they stand for on this page.

Whatever the file, the creation of a quest always follows the same pattern.

For colours, you can use the ampersand (&) followed by the colour code you want. Quests also supports HEX colour codes

Please pay attention to the indentation on all YAML files. The slightest mismatch may cause errors.

Placeholders

Quest name and description supports all placeholders with PlaceholderAPI. To enable placeholders, you just need to add the use_placeholders: true option in the quest configuration.

  1:
    name: "&f%player_name%"
    menu_item: PAPER
    use_placeholders: true
    description:
      - "%player_name%"
    quest_type: GET
    required_item: PAPER
    required_amount: 1
    reward:
      reward_type: COMMAND
      commands:
        - "broadcast done"

Oraxen, ItemsAdder, MMOItems items

You can specify for the menu item or in the required items an item from Oraxen or ItemsAdder. It's really simple, you just need to add oraxen:, itemsadder: 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 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: "mmoitems:category:id"

required_item: "oraxen:my_item"
required_item: "itemsadder:namespace:my_item"
required_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 textures

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

You just need to add a texture field in the item section. 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!

The syntax is the same as for Oraxen and ItemsAdder items.

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

Custom Model Data

You can specify for the menu item or in the required items 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"
required_item: "custommodeldata:paper:1234"

Custom items

For quests that require an item, you can specify a custom item.

You must then specify in required_item the type CUSTOM_ITEM. Then, below, you must specify the name of the item and its description.

required_item: CUSTOM_ITEM 
custom_item: 
  type: COBBLESTONE 
  name: "&c&lThe Saint Cobblestone" 
  lore: 
    - "&cWoaaaaaaaw..."

For a complete example, you can take a look at the quest number 4 just below.

Required worlds

For each quest, you can specify the worlds where the player have to be in order to complete the objective. 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_item: 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. Only compatible with WorldGuard.

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_item: NETHER_QUARTZ_ORE
  required_amount: 10
  reward:
    reward_type: MONEY
    amount: 500
  # simply add this section
  required_regions:
    - cow_farm

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

Since version 2.0, 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_item:
  - COAL_ORE
  - GOLD_ORE
  - ...

For example, a "collect 10 ores" quest would look like this:

1:
  name: "&aMiner"
  menu_item: COBBLESTONE
  description:
    - "&bMine 10 ores."
    - "&bWin &c500$&b."
  quest_type: BREAK
  required_item:
    - COAL_ORE
    - GOLD_ORE
    - IRON_ORE
    - DIAMOND_ORE
  required_amount: 10
  reward:
    reward_type: MONEY
    amount: 500

The syntax is the same for queries that require entities:

1:
  name: "Too many zombies"
  menu_item: ZOMBIE_HEAD
  description:
    - "&cKill &65 &czombies."
    - "&aWin &b500 &aTokens."
  quest_type: KILL
  required_entity: 
    - ZOMBIE
    - ZOMBIE_VILLAGER
  required_amount: 5
  reward:
    reward_type: POINTS
    amount: 500

NBT Tags

It's currently not possible to require an NBT tag. Otherwise, if your quest require items that can have differents NBT tags, such as fish seals, which store the life of the fish and a unique ID in an NBT tag, you can add the option ignore_nbt: true in your quest configuration.

This means that when you attempt to complete the quest, only the type of item will be checked and not the NBT tags. For example:

    quest_type: GET
    required_item: TROPICAL_FISH_BUCKET
    ignore_nbt: true
    required_amount: 1