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
commands	Nothing	Console commands run on claim
quest	Target quest exists	Gives another quest paper
denizen	Denizen installed	Runs a Denizen script on claim (1.1.0)

You can combine multiple types in one reward block.

---

XP

reward:
  xp: 250

---

Money

reward:
  money: 100.50

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

The plugin also supports MMOItems custom items when MMOItems is installed (same item format as other Soaps plugins).

---

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 (1.1.0)

Requires Denizen and integrations.denizen: true.

reward:
  xp: 100
  denizen: quest_complete_fanfare

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

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 Configs):

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