Creating Quests

Quests live in plugins/SoapsQuest/quests.yml under the top-level quests: map. Each key is a unique quest ID.

After editing, run /sq reload. Premium users can also use /sq editor [questid].

---

Minimal quest

quests:
  lumberjack:
    display: "<#55FF55>Lumberjack"
    tier: common
    difficulty: easy
    objectives:
      - type: break
        target: OAK_LOG
        amount: 32
    reward:
      xp: 50
      money: 25

Every quest needs at least one objective and at least one reward.

---

Common fields

Field	Description
display	Name shown on the paper (MiniMessage or & codes)
material	Paper item material (default PAPER)
tier	Tier ID from tiers.yml
difficulty	Difficulty ID from difficulties.yml
sequential	true = objectives must finish in order
milestones	Progress percentages for milestone messages, e.g. [25, 50, 75]
lock-to-player	true = paper binds to the first player who progresses
lore	Custom lore lines (optional; default lore shows live progress)
permission	Root field: gates progress after pickup (not browser lock)
objectives	List of objective entries
reward	Reward block (see Rewards)
conditions	Start requirements (see Conditions)
timer	Optional deadline (see Rewards)
fail-reward	Payout when timed quest expires or finishes in overtime

---

Objectives

Each objective entry uses:

- type: kill
  target: ZOMBIE
  amount: 10

• type: Objective type (see Objectives)
• target: Entity, block, item, NPC id, region name, etc. depending on type
• amount: Required count (or distance, minutes, level, etc. per type)

Some types use extra keys instead of target:

Type	Extra fields
command	command: "help"
placeholder	placeholder: player_level
reachlevel	level: 30
chat	text: "hello"
vehicle	vehicle: MINECART

Multi-target lists use YAML lists on target for break, place, and collect.

---

Conditions

Flat keys under conditions: gate pickup in the browser or at /sq give:

conditions:
  min-level: 10
  sigil-cost: 5
  permission: "rank.vip"
  completed-quests:
    - lumberjack

See Conditions.

---

Timed quests

timer:
  minutes: 15
  start-on: activate    # receive | activate
  on-expire: overtime   # fail | consolation | overtime
fail-reward:
  xp: 25

Global timer HUD options are in config.yml under quest-timer-display. See Default Configs.

---

Citizens NPC links

Fixed quest givers can be stored in quests.yml:

citizens-npcs:
  "42":
    quest: lumberjack
    message: "<green>Take this job."

Or linked in-game: /sq npc link <npc> <quest-id> [message]

For random contracts use /sq npc broker instead (Premium). See Contract NPC Setup.

---

Showcase quests

Default quests.yml includes showcase_<type> entries for every objective type. They use permission: soapsquest.admin so only staff can pick them up in the browser.

/sq give <player> showcase_break

---

Version 1.0.5