Quest configuration

Guide to configure a single Quest inside a quest pool

This page is the full reference for a single quest file. Tasks are covered in detail in Task objective types, the per-task filters block has its own page at Task progression filters, and rewards are in Rewards. New here? Start with Getting started.

# Name of the quest, this will show up in messages and can be used as an internal
# placeholder in multiple places
name: "Daily Example"
# Difficulty. Required.
difficulty: easy

# How should it be displayed in the Quest pool menu?
# Same item config as everywhere: https://docs.auroramc.gg/aurora/item-config
menu-item:
  material: paper
  name: "&f{name}"
  lore:
    - "&7This is an example quest."
    - "&7You can edit this file to create your own quests."
    - ""
    - "&7Tasks:"
    # These placeholders are created from the task keys
    - "  &f{task_mine_block}"
    - "  &f{task_kill_mob}"
    - ""
    - "&7Rewards:"
    # These placeholders will be created from the reward keys
    - "  {reward_money}"
    - "  {reward_cmsg}"
    - ""
    - "&7Difficulty: &f{difficulty}"

# Optional: a different appearance once this quest is completed.
# Uses the same item config as menu-item. Any property you leave out
# is inherited from menu-item above, so you can override just the
# material, add a line to the lore, etc.
# This takes priority over the global completed-quest-item fallback
# defined in menu_common.yml.
completed-menu-item:
  material: LIME_STAINED_GLASS_PANE
  name: "&a{name} &2✔"

# These lines will be added to the item lore when a GLOBAL quest
# is locked but is set up to always show in the menu
locked-lore:
  - ""
  - "&cYou can't start this quest yet."

# These lines will be added to the item lore if the visible quest
# is already completed.
completed-lore:
  - ""
  - "&aYou have completed this quest."
  
# These lines will be added to the item lore if the visible quest
# isn't completed nor locked.
uncompleted-lore:
  - ""
  - "&7You haven't completed this quest yet."

# Tasks/objectives that need to be done in order to complete the quest.
tasks:
  # Task 1
  mine_block: # This line is the ID of the task. It must be unique in this file
    # Task/objective type, case sensitive
    # In this task the player has to break 10 stone blocks.
    task: BLOCK_BREAK
    # How should the task look like?
    # {status} is either an ✖️ or ✔️ if you are using the default config.
    # {current} is the current progress/count and {required} is the required
    # progress/count to complete the task.
    display: "{status} &fMine {required} stone &b{current}&f/&b{required}"
    # Arguments for the task. Mostly, only amount/types exist, but some task
    # types may require more arguments.
    args:
      # How many stone should the player break?
      amount: 10
      # Types can be material, entity type or anything. It depends on the task type.
      types:
        # What should the player break?
        - "minecraft:stone"
    # You can define conditions for progression
    # You can delete this filters individually if you don't need them
    # or you can delete the whole filters section. 
    filters:
      # Restrict progression to specific worlds
      worlds:
        type: whitelist # blacklist also works
        value: [ "world" ]
      # Restrict progression to specific WorldGuard regions
      regions:
        type: blacklist
        value: [ "spawn" ]
      # Restrict progression to specific biomes
      biomes:
        type: whitelist
        value: [ "minecraft:plains", "minecraft:forest" ]
      # Restrict progression based on Y coordinates.
      min-ylevel: 0
      max-ylevel: 64
      # What should a player hold in his/her hands when doing the task? 
      hand:
        # Material or other plugin items.
        # Only one needs to match.
        items:
          - "minecraft:diamond_pickaxe"
          - "oraxen:mythril_pickaxe"
  # Task 2
  kill_mob:
    task: KILL_MOB
    display: "{status} &fKill {required} zombies &b{current}&f/&b{required}"
    # You can run actions when the task progresses (2.0+)
    # See AuroraLib/CommandDispatcher for whats supported here
    on-progress:
      - "[message] Wow you progressed {percent}% {progress}/{target}!"
      - "[actionbar] Wow you progressed {percent}% {progress}/{target}!"
    # You can run actions when the task completes (2.0+)
    # See AuroraLib/CommandDispatcher for whats supported here
    on-complete:
      - "[console] say {player} finished an objective!"
    args:
      amount: 10
      types:
        - "minecraft:zombie"

# Rewards to give when player completes the quest
rewards:
  money:
    type: money
    amount: 10000
    display: "&8+&a{value_formatted}$"
  cmsg:
    type: command
    command: "[console] say Hi %player_name%"
    display: "&8+&f1 Console message"

# Requirements to start a quest. Quest will be locked until the requirements are met.
start-requirements:
  # If true, quest will always show in the active quest menu, even if it is locked.
  # Locked lore will be added to the menu item.
  # Only works for global type quests.
  always-show-in-menu: true
  # Required quests to be completed before this quest can be started
  quests:
    - "pool_id:quest_name"
  # Required permissions to start the quest
  # This requires LuckPerms to work properly
  permissions:
    - "example.permission"
    
# Optional overrides for completion sound and message (2.0+)
quest-complete-message:
  enabled: true
  message:
    - "My cool"
    - "multiline message"
    
quest-complete-sound:
  enabled: true
  sound: "sound key"
  volume: 1
  pitch: 1

How a completed quest looks

When the pool is set to keep completed quests visible (completed-quests.display: true, the default — see Quest pool configuration), the item shown for a completed quest is built by layering three things on top of each other, in this order:

menu-item of the quest — always the base.
completed-quest-item from menu_common.yml — an optional, server-wide fallback appearance for every completed quest. By default it is commented out, so nothing changes. Uncomment and edit it to give all completed quests a shared look (for example a green glass pane with a checkmark):

# menu_common.yml
completed-quest-item:
  material: LIME_STAINED_GLASS_PANE
  name: "&e{name} &a✔"

completed-menu-item of the quest (shown above) — the most specific, overrides both of the above for this one quest.

Each layer only overrides the properties it defines, so you can, for example, change just the material in completed-quest-item globally while leaving the lore from each quest's menu-item intact. The completed-lore lines are still appended on top of whichever appearance is used.