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
temporary	true = temporary definition (generator/contracts cleanup)
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 (or in addition to) target:

Type	Extra fields
command	command: (or target:)
placeholder	placeholder: (or target:)
reachlevel	level:
chat	text: (or target:)
vehicle	vehicle: (or target:)
equip	slot: (ANY, HAND, CHEST, …; default ANY)
enter_world	world: (or target:; e.g. NETHER, world name)
advancement	advancement: (or target:)
wg_*	region: (or target:); wg_time_in_region also accepts seconds:
lands_*	land: (or target:); level types also accept level:
citizens_*	npc: (or target:); citizens_deliver_npc needs item: MATERIAL:amount
mcmmo_*	skill: / ability: (or target:); level types accept level:
denizen_run	script: (or target:)

kill targets may be a specific EntityType, or filters ANY, HOSTILE, PASSIVE.

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

Per-objective milestones: integer lists are supported on registered types (in addition to quest-level milestones).

---

Conditions

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

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

For prior-quest gates use the typed form (type: require-quest-completed with a quests: list). See Conditions.

---

Temporary quests

temporary: true

Marks the quest as temporary (used by Premium generation / contracts so definitions can be cleaned up after claim). Manual quests may set this; default is false.

---

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 Config Files.

---

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