Quests

Each rank holds any number of quests, defined in ranks.yml under that rank's quests: section. A quest is a small block of keys:

quests:
  cobblestone:
    type: BREAK_BLOCK
    material: COBBLESTONE
    amount: 300

There is no limit on quests per rank. The quest menu shows them on the slots from gui.quest-slots and adds pages on its own when a rank has more quests than slots, with previous / next arrows (see Configuration).

Quest keys

Several materials, tags and custom items

Every material can be more than one thing, and any of them counts (OR logic). Four spellings, mix them as you like:

material: DIRT                          # one material
materials: [DIRT, GRASS_BLOCK]          # a list, any of them counts
material: "DIRT, GRASS_BLOCK"           # same thing on one line
material: "#minecraft:logs"             # a vanilla tag: every log type
material: itemsadder:myitems:ruby_ore   # an ItemsAdder custom block or item

Tags save a lot of typing. Handy ones: #minecraft:logs, #minecraft:coal_ores, #minecraft:iron_ores, #minecraft:diamond_ores, #minecraft:dirt, #minecraft:leaves, #minecraft:planks, #minecraft:fishes, #minecraft:wool. Any block or item tag the server knows works, the minecraft: part is optional.

ItemsAdder custom blocks and items are matched by their id, and only by their id: a custom "ruby ore" never counts as the note block it is built on, and a custom item never counts as the paper it is based on. The same itemsadder: spelling works in entity for ItemsAdder custom mobs.

Quest types

BREAK_BLOCK

Break blocks of the given material. Covers mining, chopping logs, breaking leaves, anything that breaks.

coal:
  type: BREAK_BLOCK
  material: COAL_ORE
  amount: 100

logs:
  type: BREAK_BLOCK
  material: "#minecraft:logs"
  amount: 200
  icon: OAK_LOG

PLACE_BLOCK

Place blocks of the given material. What counts is the block that ends up in the world, so cocoa beans placed on a jungle log count as COCOA, seeds as WHEAT, a bucket of water as WATER. Naming the item instead works just as well (COCOA_BEANS, WHEAT_SEEDS), both spellings match.

dirt:
  type: PLACE_BLOCK
  materials: [DIRT, GRASS_BLOCK]
  amount: 500

cocoa:
  type: PLACE_BLOCK
  material: COCOA
  amount: 256
  icon: COCOA_BEANS

HARVEST

Break fully-grown crops of the given material (wheat, carrots, potatoes, and so on). Baby crops do not count, so players cannot spam-break seedlings.

wheat:
  type: HARVEST
  material: WHEAT
  amount: 500

KILL_MOB

Kill mobs. entity: ANY counts every mob, or set one type like ZOMBIE or SKELETON. Several types at once with entities. Player kills never count here, those are KILL_PLAYER.

zombies:
  type: KILL_MOB
  entity: ZOMBIE
  amount: 150

undead:
  type: KILL_MOB
  entities: [ZOMBIE, HUSK, DROWNED, ZOMBIE_VILLAGER]
  amount: 300

MythicMobs mobs are named with mythicmobs: followed by the mob's internal name (the name of its file in plugins/MythicMobs/Mobs). Needs MythicMobs installed, 4.x or 5.x both work.

boss:
  type: KILL_MOB
  entity: mythicmobs:SkeletonKing
  amount: 1
  display-name: "&7Slay the &cSkeleton King"
  icon: WITHER_SKELETON_SKULL

Not sure of the exact internal name? Turn on general.debug: true and kill the mob once, the console prints MythicMobs mob <name> died, killed by <player> with the name to copy.

ItemsAdder custom mobs work the same way with entity: itemsadder:namespace:id.

Kill with a certain weapon

Add weapon to any kill quest (KILL_MOB or KILL_PLAYER) and only kills made with that item count. It takes the same formats as material: a material, several, a tag, or an ItemsAdder item. Writing material: instead of weapon: on a kill quest does the same thing.

sword-zombies:
  type: KILL_MOB
  entity: ZOMBIE
  weapon: DIAMOND_SWORD
  amount: 25

archer:
  type: KILL_MOB
  entities: [SKELETON, STRAY]
  weapon: BOW
  amount: 10

axe-anything:
  type: KILL_MOB
  entity: ANY
  weapons: [IRON_AXE, DIAMOND_AXE, NETHERITE_AXE]
  amount: 50

For a custom named weapon from another plugin, use weapon-name. The weapon's name has to contain that text, colors and caps don't matter. You can combine it with weapon to also lock the item type.

demon-blade:
  type: KILL_MOB
  entity: ANY
  weapon-name: "Demon Blade"
  amount: 20

Bows, crossbows and tridents are tracked properly: an arrow kill counts for the bow it was shot from, even if the player switched to a sword before the arrow landed. The menu line gets a "with Diamond Sword" ending on its own (quest.objective.with-weapon in the language file).

KILL_PLAYER

Kill real players. NPCs from Citizens and similar plugins never count, and neither does dying on your own. Works with weapon and weapon-name just like mob kills.

pvp:
  type: KILL_PLAYER
  amount: 5
  unique-players: true

CRAFT_ITEM

Craft items of the given material. Shift-click crafting is counted correctly: a full batch counts as the whole batch, not as one craft.

bread:
  type: CRAFT_ITEM
  material: BREAD
  amount: 100

COOK_OR_SMELT, COOK and SMELT

Three cooking types, all tracked the same way in furnaces, blast furnaces, smokers and campfires. The only difference is what they accept:

Each one has its own line in the menu ("Cook or smelt", "Cook", "Smelt"), so players always know which one it is. output is what comes out, the optional input is what has to go in. Leave output out and anything of the right kind counts.

porkchops:
  type: COOK
  input: PORKCHOP
  output: COOKED_PORKCHOP
  amount: 256

any-food:
  type: COOK
  amount: 64

iron:
  type: SMELT
  output: IRON_INGOT
  inputs: [RAW_IRON]        # ingots from ore blocks would not count
  amount: 64

anything:
  type: COOK_OR_SMELT
  amount: 500

How it counts:

• Furnaces, blast furnaces and smokers count each item the moment it finishes cooking (since 1.4.3), for the player who put the raw item in by hand. Nobody has to collect it or even stay near the furnace, but the player has to be online when it finishes. Raw items fed in by a hopper count for nobody. Two players sharing one furnace each get credit for their own raw items, first in first cooked.
• Prefer the old way? Set progression.smelt-counts-when: collected in config.yml and progress counts when the player takes the result out instead (any click, shift-click or hotbar key, bit by bit counts every bit, whoever takes it gets the progress).
• Campfires count when the food finishes cooking, for the player who put it on.
• Only items cooked while the server was running count. Raw items loaded before a restart, or cooked stock left over from before one, give nothing.
• With an input set, the plugin remembers which raw item each result came from while the server runs.
• Leave input out and any raw item that gives the output counts.

DELIVER_ITEM

Bring items back to the quest menu. The player clicks the quest icon and the items are consumed from their inventory; progress is stored, so it can be turned in across several trips.

seeds:
  type: DELIVER_ITEM
  material: WHEAT_SEEDS
  amount: 256

ENCHANT

Enchant items at an enchanting table. Leave material out and any item counts. enchantment only counts it when that enchant is one of the ones added.

enchanter:
  type: ENCHANT
  amount: 10

sharp-swords:
  type: ENCHANT
  materials: [IRON_SWORD, DIAMOND_SWORD]
  enchantment: sharpness
  amount: 3

Enchantment names are the Minecraft ids: sharpness, efficiency, unbreaking, fortune, protection and so on. A list works too: enchantments: [mending, unbreaking].

When a quest asks for an enchantment, the quest menu names it, so players know what to aim for: "Enchant 1 Diamond Sword with Sharpness". With a list it shows all of them: "with Mending, Unbreaking". The wording comes from the lang file:

quest:
  objective:
    enchant: "&7Enchant &e{amount} {name}"
    enchant-any: "&7Enchant &e{amount} &7items"
    # added at the end when the quest wants a certain enchantment
    with-enchantment: " &7with &e{enchantment}"

By default the with-enchantment line is stuck on at the end. If you want the enchantment somewhere else in the sentence, put {enchantment} right inside enchant or enchant-any, and then the extra line is left out. For example "&7Put &e{enchantment} &7on &e{amount} {name}".

ANVIL

Use an anvil. It counts when the player actually takes the result out and pays the levels, so just putting items in and taking them back does nothing. action picks what kind of anvil job counts:

Leave action out and every anvil use counts. material limits it to that result item.

blacksmith:
  type: ANVIL
  action: REPAIR
  amount: 10

book-work:
  type: ANVIL
  actions: [COMBINE]
  material: DIAMOND_PICKAXE
  amount: 3

FISH

Catch things with a fishing rod. Without a material, every catch counts. With one, only that exact catch counts.

fishing:
  type: FISH
  amount: 50

salmon:
  type: FISH
  material: SALMON
  amount: 20

The menu icon defaults to a fishing rod.

FIND_HEAD

A treasure hunt built in. Hide player heads around your world and let a quest count the ones a player finds by right-clicking them. Every head spot counts once per player per quest, so clicking the same head twice, or breaking it and placing it back, does nothing.

The heads that may count live in heads.yml, one entry per head with a name of your choice and either the head's skin texture or a player name:

heads:
  egg-blue:
    texture: "eyJ0ZXh0dXJlcyI6ey..."   # the base64 "Value" from a head site
  egg-pink:
    texture: "http://textures.minecraft.net/texture/<hash>"   # or the URL, or just the hash
  notch:
    player: Notch

Then in ranks.yml:

easter:
  type: FIND_HEAD
  amount: 10
  heads: [egg-blue, egg-pink]   # only these two

treasure:
  type: FIND_HEAD
  amount: 5                     # no "heads" line = every head listed in heads.yml

any-head:
  type: FIND_HEAD
  amount: 5
  heads: ANY                    # every player head in the world, listed or not

heads.yml is yours, the plugin writes it once and never touches it again. Edits are picked up automatically a few seconds after saving, like ranks.yml.

Each quest can point at its own AdvancedHunt collection, and only treasures found in that collection count:

hunt-spawn:
  type: PLACEHOLDER
  placeholder: "%advancedhunt_found_treasures_7a849b47-e0cf-47f3-b5a5-78b9d71e1a26%"
  amount: 5
  display-name: "&eFind 5 treasures at spawn"

<collection> is the collection's UUID (safest) or its name. A wrong UUID makes AdvancedHunt answer 0, so the quest just stays at 0: check it with /rank admin placeholder <placeholder> <player>. The count is everything that player ever found in that collection, including before they reached the rank.

TOWER_FLOOR

Completes when the player has cleared a floor of a TowerTrials tower this season.

spire:
  type: TOWER_FLOOR
  tower: ashen-spire
  floor: 10
  icon: LADDER
  display-name: "&7Clear floor &e10 &7of the &6Ashen Spire"

tower is the tower id, which is the id: line in its file under plugins/TowerTrials/towers/, not its display name. Floors count from 1, the same numbers the portals carry.

The menu shows their highest cleared floor out of the target, so a player on floor 3 of a "clear floor 10" quest sees 3/10. Clearing a higher floor counts too, and a floor cleared before the quest ever existed counts as well, because the number is read straight from TowerTrials instead of being counted by us.

TOWER_CLEAR

Counts cleared floors as they happen, so it is the "keep climbing" kind of quest.

climber:
  type: TOWER_CLEAR
  tower: ashen-spire     # optional, leave it out and every tower counts
  amount: 25
  first-clear: true      # optional, only floors cleared for the first time this season

Add floor: 5 to count only clears of that one floor. With first-clear: true a player cannot farm the same easy floor over and over, because only the first clear of each floor this season counts.

TowerTrials quests

Both tower types need the TowerTrials plugin on the server. zQuestRank is built against TowerTrials 1.0.0-9 (API version 1) and talks to it without a hard dependency, so:

• No TowerTrials installed? Tower quests simply stay at 0 instead of erroring, exactly like a placeholder quest without PlaceholderAPI.
• A wrong tower id is reported in the console at startup, with a note to check the id in plugins/TowerTrials/towers/.
• towertrials.enabled: false in config.yml turns the whole link off, see Configuration.

Tower progress belongs to the tower's current season. When a season resets everyone goes back to floor 0, but quests already completed stay completed, they are never taken back.

You can also close tower floors until players reach a rank, see rank gates.

WALK

Travel a number of blocks. By default only on foot: walking, sprinting and swimming. Jumping on the spot, falling straight down and creative or /fly flying never count.

explorer:
  type: WALK
  amount: 5000

long-journey:
  type: WALK
  any-travel: true          # or just "type: TRAVEL"
  amount: 20000

With any-travel: true (or type: TRAVEL), boats, horses, pigs, striders, minecarts and elytra flying count too. The menu line changes from "Walk" to "Travel".

EXPLORE

Discover places. amount is how many different places, and each place counts once per player. Mix any of these:

forests:
  type: EXPLORE
  biome: "*FOREST*"         # * = any text, so every forest kind counts
  amount: 3

cold-places:
  type: EXPLORE
  biomes: [SNOWY_PLAINS, ICE_SPIKES, FROZEN_PEAKS]
  amount: 2

villages:
  type: EXPLORE
  structure: VILLAGE
  amount: 3

landmarks:
  type: EXPLORE
  areas:
    - "Old Castle;world;120;70;-340;40"
    - "Spawn Temple;world;0;80;0;25"
  amount: 2

• Biomes use the Minecraft names (FOREST, DARK_FOREST, DESERT, CHERRY_GROVE...). A * matches any text.
• Structures: village, stronghold, mineshaft, fortress, monument, mansion, desert_pyramid, jungle_pyramid, igloo, swamp_hut, pillager_outpost, shipwreck, ruined_portal, bastion_remnant, end_city, and on 1.19+ also ancient_city, trail_ruins, trial_chambers and anything else the server knows. village covers every village kind (plains, desert, snowy...). Every different village counts as a new one. How close a player has to get is progression.explore-structure-distance in config.yml (48 blocks by default).
• Areas are your own spots: name;world;x;y;z;radius. Good for builds, landmarks, or special places.

The player gets a chat line the moment something new counts, like "Discovered Village! (2/3)" (quest.explore-found in the language file).

PLACEHOLDER

Completes when a numeric PlaceholderAPI value reaches amount. This is the bridge to every other plugin: job levels, vote counts, island levels, quest counts, treasures found, anything that can be read as a number.

job-level:
  type: PLACEHOLDER
  placeholder: "%ecojobs_miner%"
  amount: 5
  display-name: "&7Reach Miner job level &e5"
  icon: IRON_PICKAXE

The value is read live, and once it reaches the target the completion is saved, so it stays completed even if the value later drops. See Placeholders for known-good placeholder names, and test any placeholder in game with /papi parse me <placeholder> first.

World filters

Any quest can be limited to certain worlds, for example a player's island world on a skyblock server. Progress made anywhere else is ignored.

island-dirt:
  type: PLACE_BLOCK
  materials: [DIRT, GRASS_BLOCK]
  amount: 500
  worlds: [island_world]

A worlds list on the rank itself applies to every quest of that rank that has no list of its own:

rank-3:
  display-name: "&dRank III"
  worlds: [island_world, island_world_nether]
  quests:
    ...

Quests with a world filter show an "Only counts in: ..." line in the menu (wording under quest.lore.worlds in the language file). Delivery quests use the world the player is standing in when they click.

Quest description

The quest icon's title is the objective (for example "Craft 20 Golden Apples"). By default the icon shows just that title, the progress line, and the status, nothing repeated. If you want to explain the quest in your own words, add a description: list and those lines show up right under the title.

golden_apples:
  type: CRAFT_ITEM
  material: GOLDEN_APPLE
  amount: 20
  description:
    - "&7Craft golden apples at a"
    - "&7crafting table to progress."

The same {objective}, {progress}, {target} and {status} placeholders (see the table below) work inside description lines too. To change the title itself, use display-name. For full control over the whole icon text, use lore instead (below), which replaces everything.

Custom lore per quest

By default a quest icon shows the objective, the progress line, and the status. To write your own text for one specific quest, give it a lore: list. It fully replaces the default text for that quest.

These placeholders work inside the lines:

seeds:
  type: DELIVER_ITEM
  material: WHEAT_SEEDS
  amount: 256
  lore:
    - "&7Bring the seeds back here and click!"
    - ""
    - "&7Progress: &e{progress}&7/&e{target}"
    - "{status}"

Color codes (&a style and &#rrggbb hex, see Colors) work everywhere, and with PlaceholderAPI any %...% placeholder or emoji works in names, lore and description too (see Placeholders). The icon's name stays the objective; use display-name to change that.

Per-quest rewards

A quest can pay out on its own, the moment it completes, separate from the rank rewards. Add a rewards: block with any of money, xp-levels, items, and commands:

seeds:
  type: DELIVER_ITEM
  material: WHEAT_SEEDS
  amount: 256
  rewards:
    money: 500
    items:
      - "BREAD:16"
    commands:
      - "crates give {player} vote 1"

The reward fires exactly once per completion and arrives together with the quest-completed chat message. The options are described in full on the Rewards page.

Progress rules worth knowing

• Progress always belongs to the player's current rank. Claiming a rank starts the next rank's quests from zero.
• Progress is saved per player and survives relogs and restarts. See Storage.
• The moment a quest reaches its target, the player gets a chat message (toggle with progression.notify-on-quest-complete in config.yml).