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:

display:
  name: "&#FF6B6B&lMonster Hunter"
  material: MACE
  custom-model-data: 358   # optional, for resource pack icons

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.

objectives:
  zombies:
    name: "&#8DFFB3&lRotten Threat"
    description:
      - "&#C7D0D9Defeat zombies before they"
      - "&#C7D0D9overrun the area."
      - ""
      - "&#8A8F98Progress: &#FFFFFF{progress}&#8A8F98/&#FFFFFF{required}"
    trigger: kill_entity
    target: ZOMBIE
    required: 15

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

target values for vanilla triggers must be exact material/entity names (IRON_ORE, SKELETON, ...). A typo means the objective simply never progresses — no error is thrown.

Rewards

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

rewards:
  - type: message
    value: "&#B8FFF2Well done!"
  - type: command
    value: eco give %player% 500

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

rewards:
  money:
    type: command
    display-name: "&a$500"
    value: eco give %player% 500
  bonus_xp:
    type: quest_xp
    value: 250

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.

conditions:
  - type: permission
    value: quests.vip
  - type: world
    value: world_nether

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 reload

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.