Rewards

Rewards are granted when a player claims a completed quest paper (right-click). Define them under the reward: key on each quest in quests.yml.

Optional fail-reward: uses the same keys and grant path as reward:. It is paid on timed-quest consolation (immediately) or overtime claim (if they finished after the deadline). Missing fail-reward never falls back to reward:.

---

Reward types

Key	Requires	Description
xp	Nothing	Minecraft experience points
money	Vault + economy	Currency via Vault
sigils	Nothing	SoapsQuest Sigils (stored in sigils.yml)
items	Nothing	List of item stacks with optional enchantments / chance / custom-model-data
commands	Nothing	Console commands run on claim (optional command-chance)
quest	Target quest exists	Gives another quest paper (quest.quest-id, optional quest.chance)
denizen	Denizen installed	Runs a Denizen script on claim (optional denizen-chance)

Optional chance keys: xp-chance, money-chance, sigils-chance (default 100).

---

XP

reward:
  xp: 250
  xp-chance: 100   # optional, default 100

---

Money

reward:
  money: 100.50
  money-chance: 100   # optional, default 100

Requires Vault and a registered economy provider. If Vault is missing, money is skipped and a warning may appear in console.

---

Sigils

reward:
  sigils: 50

Sigils work on Free and Premium. Balances persist in plugins/SoapsQuest/sigils.yml.

Optional chance (default 100):

reward:
  sigils: 25
  sigils-chance: 75

---

Items

reward:
  items:
    - material: DIAMOND_SWORD
      amount: 1
      name: "<#55FF55>Quest Blade"
      lore:
        - "<#AAAAAA>Awarded for bravery"
      enchantments:
        - "SHARPNESS:3"
        - "UNBREAKING:2"
      chance: 100
    - material: BREAD
      amount: 8
      chance: 100

Item field	Description
material	Bukkit material name (required)
amount	Stack size (default 1)
name	Display name (MiniMessage or & codes)
lore	Lore lines
enchantments	List of ENCHANT:level strings
chance	Drop chance 0-100 (default 100)
flags	Item flags such as HIDE_ENCHANTS
unbreakable	true / false
custom-model-data	Integer custom model data

MMOItems: when MMOItems is installed, set material (or the item string used by addreward chat input) to mmoitems:TYPE:ID (also accepts mmoitem:). Example: mmoitems:SWORD:DRAGON_SLAYER.

---

Commands

reward:
  commands:
    - "give {player} emerald 5"
    - "broadcast &a{player} completed a quest!"

Player placeholders: {player}, <player>, %player%.

Optional execution chance:

reward:
  commands:
    - "say Quest complete!"
  command-chance: 50

---

Denizen script

Requires Denizen and integrations.denizen enabled (or auto-detect).

reward:
  xp: 100
  denizen: quest_complete_fanfare

Optional denizen-chance (default 100). The script name is passed to Denizen on claim. See Integrations.

---

Quest chain reward

Give another quest paper when the player claims:

reward:
  xp: 100
  quest:
    quest-id: chapter_two
    chance: 100

String shorthand is also accepted:

reward:
  quest: chapter_two

The chained paper is created and given on claim. The target quest must exist in quests.yml or generated.yml.

---

Command-line reward editing

Staff can add rewards without editing YAML:

/sq addreward <questid> xp <amount>
/sq addreward <questid> money <amount>
/sq addreward <questid> sigils <amount>    # Premium only
/sq addreward <questid> command <cmd>
/sq addreward <questid> item               # Uses held item
/sq listreward <questid>
/sq removereward <questid> <index>

Permissions: soapsquest.addreward, soapsquest.listreward, soapsquest.removereward.

After command edits, run /sq reload to refresh existing papers.

---

Timed quests

Optional timer: on a quest starts one wall-clock deadline (not two clocks). start-on: receive arms when the paper instance is registered; start-on: activate waits for a right-click of the active held paper (queued copies do not start the clock). on-expire: fail voids with no payout; consolation grants fail-reward: then voids; overtime keeps the quest playable and uses fail-reward: on claim if they finished late. Completing before the deadline still pays full reward: even if they claim after. Dropping or storing the paper does not pause the timer.

Timer display (global)

Configure in config.yml under quest-timer-display: (see Default Config Files):

Option	Effect
paper-name	Append remaining time to the quest paper item name
action-bar	Live countdown in the action bar (default: on)
boss-bar	Boss bar for the most urgent active timed quest
chat-reminder-seconds	Periodic chat countdown (0 = off). The one-minute warning message is always sent separately.

Paper lore always shows the timer line when a deadline is armed. The HUD tracks only timed quests that are active in your queue (not queued copies waiting for activate-start).

Configure timer and fail rewards in the Premium quest editor (clock and fail-reward buttons flanking Edit Rewards).

---

Completion messages

messages.yml supports <quest_rewards> in completion text to list granted rewards on multiple lines.

---

Random generator rewards (Premium)

Generated quests pull rewards from random-generator.yml pools (reward-pool, tier ranges, item pools, and templates). The YAML format matches quests.yml reward blocks so you can copy templates between files.

When a generated quest rolls a timer, fail-reward-scale clones that same reward: block into fail-reward: with scaled amounts (XP, money, sigils, item counts). Commands, quest papers, and chances are copied as-is.

---

Version 1.0.5