For the complete documentation index, see llms.txt. This page is also available as Markdown.

Create a Quest

All quests are defined in quests.yml. Every quest is a section under the top-level quests: key, and the section name is the quest ID (used in commands, placeholders and storage — pick something short and lowercase, like beginner_miner).

You don't need to touch any code. Create the section, run /quests reload, and the quest is live.

A complete example

quests:
  beginner_miner:
    display:
      name: "&#B8FFF2&lBeginner Miner"
      material: AMETHYST_SHARD
      custom-model-data: 358

    level: 1
    daily: true

    objectives:
      stone:
        name: "&#D3DBE3&lStone Veins"
        description:
          - "&#C7D0D9Mine stone blocks to gather"
          - "&#C7D0D9your first resources."
          - ""
          - "&#8A8F98Progress: &#FFFFFF{progress}&#8A8F98/&#FFFFFF{required}"
        trigger: block_break
        target: STONE
        required: 64

      craft_pickaxe:
        name: "&#FFD86E&lFirst Upgrade"
        description:
          - "&#C7D0D9Craft a stone pickaxe."
        trigger: craft_item
        target: STONE_PICKAXE
        required: 1

    rewards:
      - type: message
        value: "&#B8FFF2You learned the basics of mining."
      - type: command
        value: give %player% iron_pickaxe 1

    accept-expire: -1
    active-expire: 1800

This quest asks the player to mine 64 stone and craft a stone pickaxe. Once both objectives are done, the rewards run automatically.

Quest options

Key
Description
Default

display

How the quest looks in the quest board GUI (see below).

level

The quest level. The daily board only offers quests within level-range (set in config.yml) of the player's own level.

1

daily

Whether the quest can appear on the daily quest board. Set to false for quests you only hand out manually (e.g. via admin commands).

true

objectives

The tasks the player has to complete. At least one is required.

conditions

Extra requirements checked when the player tries to accept the quest.

none

rewards

What the player gets when every objective is complete.

none

accept-expire

Seconds the player has to start the quest after accepting it. -1 means no limit.

-1

active-expire

Seconds the player has to finish the quest once it becomes active. -1 means no limit.

-1

Both expire values are in seconds. active-expire: 1800 gives the player 30 minutes to finish. Players get warnings as the timer runs down — configurable under quests.expire-warning in config.yml.

Display

The display section controls the item shown for the quest in the board GUI:

name supports legacy color codes (&a) and hex colors (&#FF6B6B). material is any Bukkit Material name.

Objectives

Each objective is a named section under objectives:. The section name (e.g. stone) is the objective ID — it's used to track progress, so don't rename it after players have started the quest.

Key
Description

trigger

What kind of action counts (see the trigger list below).

target

What exactly the action must involve — a block, item, entity, world, etc. Depends on the trigger. Some triggers accept any.

required

How many times the action must happen (or the total amount, for damage/distance/XP based triggers).

name

Objective name shown in GUIs and completion messages.

description

Lore lines shown in GUIs. {progress} and {required} are replaced with the player's live progress.

A quest is complete when all of its objectives are complete. Objectives progress in parallel — there's no fixed order.

Triggers

Vanilla triggers (no extra plugin needed):

Trigger

Counts when the player...

target

block_break

breaks a block

block material, e.g. STONE

place_block

places a block

block material

interact_block

right-clicks a block

block material, e.g. CHEST

kill_entity

kills a mob

entity type, e.g. ZOMBIE

deal_damage

deals damage (progress = damage dealt)

any

take_damage

takes damage (progress = damage taken)

any

move

walks (progress = blocks traveled)

any

move_while_sprinting

sprints

any

move_while_sneaking

sneaks while moving

any

move_while_flying

flies

any

move_while_swimming

swims

any

fish

catches something while fishing

any

craft_item

crafts an item

item material, e.g. STONE_PICKAXE

smelt_item

takes an item out of a furnace

item material or any

consume

eats or drinks an item

item material, e.g. COOKED_BEEF

change_world

switches world

world name or any

gain_exp

gains vanilla XP (progress = XP gained)

any

gain_quest_xp

gains quest XP

any

level_up

levels up in the quest leveling system

any

Rewards

Rewards run once, when the last objective is completed. They can be written as a list:

or as named sections, which lets you add a display-name (shown in GUIs instead of the raw value):

Available reward types:

Type

value

What it does

message

text (colors supported)

Sends a chat message to the player.

command

console command, %player% = player name

Runs the command from console.

item

MATERIAL:amount, e.g. DIAMOND:3

Puts the item in the player's inventory.

xp

number

Gives vanilla experience.

quest_xp

number

Gives quest XP (multiplied by the player's premium XP multiplier, if any).

The command type is the most flexible — anything a console command can do (economy, crates, permissions, custom items) can be a reward.

Conditions

Conditions are checked when a player tries to accept the quest. If any condition fails, the quest can't be accepted.

Type

value

Requirement

permission

permission node

The player must have this permission.

world

world name

The player must be in this world.

Applying your changes

After editing quests.yml, run:

Quests already accepted by players keep running with the definition they were started with; new accepts use the updated config.

You can hand out any quest directly with /quests force give <player> <quest> or /quests force start <player> <quest> (permission mcquests.admin.force), even quests with daily: false that never appear on the board — handy for testing a new quest before players see it.

Last updated