Creating Quests

A quest is one YAML file. To add a quest you write the file, drop it in, and reload. No code, no restart.

Add a quest in three steps

1. Write the file

   Copy the template below into a new .yml file. Give it a unique id.

2. Put it in the quests folder

   In GLOBAL mode it goes flat in plugins/zDailyQuests/quests/. In RARITY mode it goes in the easy/, normal/, or hard/ subfolder. See Selection Modes.

3. Reload

   Run /dq reload. The pool is re-read and the console tells you how many quests are loaded.

Caution

Every quest id must be unique across all files. A duplicate id, or a file the loader cannot understand, is skipped with a warning in the console rather than crashing the pool.

The full template

# Unique id for this quest, must not repeat across files
id: kill_zombies_25

# Name shown in the menu. Used when use-single-display is true
display-name: "&aZombie Slayer"

# Text under the quest name. %progress% and %target% are filled in for you
description:
  - "&7Kill zombies to complete this quest"
  - "&7Progress: %progress%/%target%"

# Item shown as the quest in the menu. Used when use-single-display is true.
# Can be a material, or a player head: head-<name> or basehead-<base64>
icon: ZOMBIE_HEAD

# A quest goes through stages: not started, in progress, ready to claim, done.
# true  = show the same name, text and icon in every stage (the three keys above)
# false = show a different name, text and icon per stage (set in phase-display below)
use-single-display: true

# What this quest tracks, see the Objective Types page for the full list
objective: KILL

# Optional. Only some objectives need a type. Put one value or a list.
# Leave it out to mean "any" (any mob, any block, and so on)
target-type: ZOMBIE

# How many you need to finish the quest once
target-amount: 25

# How many times a player can do this quest in the same day.
# 1 = do it only once. Higher = it can be done again, up to this many times
max-completions: 1

# Difficulty label. Only shown in GLOBAL mode. In RARITY mode the folder sets it
difficulty: EASY

# Reward for finishing this one quest
reward:
  commands:
    - "eco give %player% 250"
  items:
    - material: EMERALD
      amount: 3

Head icons

The icon (and any per-phase icon) can be a player head instead of a material:

Spec	Result
head-<playername>	that player’s skin, e.g. icon: head-Notch
basehead-<base64>	a custom textured head, the base64 is the value you copy from a heads site

icon: "head-Notch"

A bad or missing texture falls back to a plain head rather than breaking the menu. The same specs work for menu decoration items, see The Menu.

Per-phase display

Set use-single-display: false to give a quest a distinct look in each phase, for example a “click to claim” chest icon when it is ready:

use-single-display: false
phase-display:
  not-started:
    icon: ZOMBIE_HEAD
    name: "&7Zombie Slayer"
    lore:
      - "&7Not started yet"
  in-progress:
    icon: ZOMBIE_HEAD
    name: "&aZombie Slayer"
    lore:
      - "&7Progress: %progress%/%target%"
  completed-unclaimed:
    icon: CHEST
    name: "&eZombie Slayer (click to claim!)"
    lore:
      - "&eYou did it, click to grab your reward"
  completed:
    icon: LIME_STAINED_GLASS_PANE
    name: "&aZombie Slayer (done)"
    lore:
      - "&7Completed"

The completed-unclaimed phase only ever shows in manual claim mode.

Caution

use-single-display: false does nothing on its own. You must also add the phase-display block. If it is missing, the plugin logs a warning in console and falls back to the single display, so the menu looks exactly the same as true. A phase with no block (or a name, icon or lore you left out) falls back to the shared display-name, icon and description, so only the stages you actually change will look different. To see the change, watch a quest as it moves from in-progress to completed, an already finished quest only shows its completed phase.

Advanced examples

Location

id: explore_spawn_ruins
display-name: "&aExplorer"
description:
  - "&7Go check out the ruins near spawn"
icon: MAP
objective: LOCATION
location:
  world: world
  x: -4
  y: 103
  z: 7
  radius: 3
max-completions: 1
difficulty: NORMAL
reward:
  commands:
    - "eco give %player% 150"

Checked when the player opens the menu while inside the radius.

Villager trade

id: farmer_cookies
display-name: "&aCookie Run"
description:
  - "&7Buy 32 cookies from a level 3 farmer villager"
icon: COOKIE
objective: VILLAGER_TRADE
target-type: COOKIE
villager-profession: FARMER
villager-level: 3
target-amount: 32
max-completions: 1
difficulty: NORMAL
reward:
  commands:
    - "eco give %player% 300"

Both villager-profession and villager-level are optional and independent. Level means “at least this level”.

Shear a colour

id: shear_white_sheep_10
display-name: "&aWool Gatherer"
description:
  - "&7Shear white sheep"
icon: WHITE_WOOL
objective: SHEAR
target-type: SHEEP
sheep-color: WHITE
target-amount: 10
max-completions: 1
difficulty: EASY
reward:
  items:
    - material: SHEARS
      amount: 1

The six starter quests

The plugin ships with a small pool so you have working examples to copy:

• Directoryquests/

  • kill_zombies_25.yml KILL
  • break_stone_64.yml BREAK
  • place_planks_32.yml PLACE
  • craft_bread_16.yml CRAFT
  • catch_fish_10.yml FISH
  • deal_damage_200.yml DEAL_DAMAGE

Objective Types Pick the right objective for your quest, and read its quirks.