Quests

Quests

The Quests module turns ordinary gameplay into rewarded goals. Players are assigned a rotating set of daily and weekly quests (plus any number of always-on permanent quests). Completing a quest lets the player claim its reward — and any Battle Pass XP — from the /quests menu.

Quests are tracked automatically by listening to what players already do across the plugin, so no other configuration is needed to make them work — just define the quests.

---

Overview

Feature	Details
Storage	Database
Categories	Daily, Weekly, Permanent
Quests	Unlimited — define as many as you like
Daily/Weekly size	Configurable random, weighted selection per player
Rotation	Daily and weekly, with configurable timezone & reset time
Rewards	Reward bundle (commands + messages + sound) per quest
Battle Pass XP	Configurable per quest
Reroll	/quests reroll (permission-gated)
Scaling	Optional per-quest goal/reward scaling by rank, prestige, rebirth or permission
Gating	Optional per-quest permission so only certain ranks receive a quest

---

Commands

/quests          Open the quests menu (alias: /missions)
/quests reroll   Reroll your daily quests (permission: xprison.quests.reroll)

---

Quest Types

Each quest has a type that decides what it tracks. An optional filter narrows a quest to a single currency or enchant (matched by name, case-insensitive).

Type	Tracks	filter
MINE_BLOCKS	Blocks mined	—
EARN_CURRENCY	Currency earned	Currency name (e.g. Tokens)
RANKUP	Rank-ups	—
PRESTIGE	Prestiges	—
REBIRTH	Rebirths	—
TRIGGER_ENCHANT	Pickaxe enchant procs	Enchant name (e.g. Explosive)
USE_BOMB	Bombs detonated	—
JOIN_GANG	Joining a gang	—
AUTOMINE	Auto-miner cycles	—

---

Categories & Rotation

Category	Behaviour
DAILY	Each player gets daily.count random quests, re-rolled automatically every day
WEEKLY	Each player gets weekly.count random quests, re-rolled automatically every week
PERMANENT	Every permanent quest is always active until completed

Daily and weekly selections are weighted by each quest's weight (higher = more likely to be picked). Rotation timing is controlled under rotation: in quests.yml (timezone, daily reset hour, weekly reset day & hour).

---

Creating Unlimited Quests

There is no cap on how many quests you can define — add as many entries under quests: as you want, across any of the types above. Each quest is self-contained:

daily:
  count: 3          # how many daily quests each player gets
weekly:
  count: 2

quests:
  daily_mine_blocks:
    type: MINE_BLOCKS
    category: DAILY
    display-name: "Daily Miner"
    target: 2500          # amount required
    weight: 10            # selection weight (DAILY/WEEKLY only)
    pass-xp: 150          # Battle Pass XP on claim
    display:
      material: IRON_PICKAXE
      name: "<yellow>Daily Miner"
      lore:
        - "<gray>Mine <white>%target% <gray>blocks."
        - "<gray>Progress: <white>%progress%<gray>/<white>%target% <gray>(<white>%percent%<gray>)"
        - "%bar%"
        - "%status%"
    rewards:
      commands:
        - "money give %player% 25000"
      messages:
        - "<green>+ $25,000"
      sound: ENTITY_PLAYER_LEVELUP

  earn_tokens:
    type: EARN_CURRENCY
    category: WEEKLY
    display-name: "Token Hoarder"
    target: 50000
    weight: 8
    filter: "Tokens"      # only counts Tokens
    pass-xp: 750
    display: { material: SUNFLOWER, name: "<gold>Token Hoarder", lore: ["<gray>Earn <white>%target% <gray>Tokens", "%bar%", "%status%"] }
    rewards:
      commands: ["tokens give %player% 5000"]
      messages: ["<aqua>+ 5,000 Tokens"]

Display placeholders usable in a quest's name/lore: %name%, %category%, %progress%, %target%, %percent%, %bar% (a live progress bar), %status% and %multiplier% (the player's scaling factor, see below).

Every reward is a reward bundle — an unlimited list of commands (with %player%), messages, and an optional sound.

---

Scaling & Permission Gating

Two optional, independent features keep quests fair across your whole rank ladder. Both are off by default — existing quest configs are unaffected.

Goal & reward scaling

A quest like "mine 2,500 blocks for $25,000" is a grind for a fresh player and trivial for an endgame one. Scaling lets a single quest grow with the player. Turn it on globally, then give any quest a formula:

scaling:
  enabled: true
  source: RANK          # RANK | PRESTIGE | REBIRTH | PERMISSION
  permission-weights:   # only used when source: PERMISSION
    "xprison.quests.scale.1": 1
    "xprison.quests.scale.2": 2

quests:
  daily_mine_blocks:
    type: MINE_BLOCKS
    target: 2500
    scaling:
      target-formula: "target * (1 + 0.25 * scale)"
      reward-multiplier-formula: "1 + 0.25 * scale"
    # ...rest of the quest...

• The chosen source is supplied to your formulas as the variable scale (rank index, prestige level, rebirth level, or a permission weight). The base target is available as target.
• target-formula sets the player's goal. With the example above, "mine 2,500 blocks" becomes 3,750 at scale 2 and 5,000 at scale 4.
• reward-multiplier-formula is exposed to the quest's reward commands/messages as the %multiplier% placeholder (and the scaled goal as %target%), so reward-aware commands and messages can pay out proportionally.
• The scale value is snapshotted when the quest is assigned, so ranking up mid-day never changes an in-progress quest.

Quests without a scaling: block are never scaled.

Permission-gated quests

Add a permission to any quest and only players holding that node will ever be assigned it — perfect for giving different ranks different quests (and different rewards):

quests:
  elite_excavation:
    type: MINE_BLOCKS
    permission: "xprison.quests.tier.elite"
    target: 15000
    # ...rest of the quest...

Players without the node simply never roll the quest — it stays out of their pool. Grant the node to the ranks/groups you want (e.g. via LuckPerms) to control who receives it.

---

The Quests Menu

/quests opens a paginated menu of the player's active quests, each showing a live progress bar and its state (in progress / completed / claimed). Completed quests are claimed by clicking. The progress bar characters and status labels are configurable under gui in quests.yml.

---

Titles & Sounds

Completing, claiming and hitting milestones fire configurable on-screen titles and sounds, set under effects: in quests.yml. Each block has an optional title (enabled, title, subtitle, fade-in/stay/fade-out in seconds) and an optional sound (enabled, sound, volume, pitch). The 25/50/75% milestone effects are off by default to avoid spam.

Event	Title	Sound	Default	Placeholders
quest-complete	✔	✔	on	%quest%
claim	–	✔	on	%quest%
milestone	✔	✔	off	%quest%

effects:
  quest-complete:
    title:
      enabled: true
      title: "<gradient:#f7971e:#ffd200><bold>QUEST COMPLETE</bold></gradient>"
      subtitle: "<white>%quest% <gray>- claim it in <yellow>/quests"
      fade-in: 1
      stay: 3
      fade-out: 1
    sound:
      enabled: true
      sound: ENTITY_PLAYER_LEVELUP
  claim:
    sound: { enabled: true, sound: ENTITY_EXPERIENCE_ORB_PICKUP }
  milestone:
    title: { enabled: false }
    sound: { enabled: false, sound: BLOCK_NOTE_BLOCK_PLING, volume: 0.5, pitch: 1.5 }

Sound names are standard Bukkit/XSound names.

---

Permissions

Permission	Description
xprison.quests.reroll	Use /quests reroll

---

PlaceholderAPI

Placeholder	Returns
%xprison_quests_active%	Number of active quests
%xprison_quests_completed%	Number of completed quests
%xprison_quests_unclaimed%	Completed quests not yet claimed

---

Related Pages

• quests.yml — Default Config
• Battle Pass
• Daily Rewards
• Commands & Permissions
• Placeholders
• Developer API