SoapsUniverse
SoapsQuest
SoapsQuest

Pages

Integrations

Getting Started

HomeIntroductionGetting Started

Quest Authoring

Creating QuestsObjectivesRewardsConditionsTiers and DifficultiesExamples

Premium

Daily and Weekly Quests (Premium)Random Quest Generator (Premium)Quest Loot System (Premium)

Reference

GUI SystemCommands and PermissionsPlaceholdersDefault Configs

Support

FAQChangelog

Changelog

Last updated Jul 6, 2026

Changelog

1.1.0

Release date: June 2026

Overview

SoapsQuest 1.1.0 adds six new vanilla objective types, optional integrations with five popular plugins (18 integration objective types), Citizens NPC quest givers, Denizen script rewards, multi-material target lists for break/place/collect, and a batch of reliability fixes around claiming, admin commands, and data saves.

Objective count: 43 vanilla types + 18 integration types (61 total when all integrations are enabled).

New vanilla objective types

Type Description
playtime Minutes while the quest is Active (ticks every 60s)
enter_world Enter a dimension/world (target: NETHER, THE_END, world name, or ANY)
kill_player Kill other players
advancement Earn a Minecraft advancement (target: advancement key, e.g. minecraft:story/mine_stone)
equip Wear or hold an item (target material; optional slot: CHEST, HAND, etc.)
smith Smith items at a smithing table (target result material or ANY)

Each type ships with a showcase_<type> quest gated by permission: soapsquest.admin.

Plugin integrations (optional)

Soft-dependencies via reflection — no hard Maven dependency on third-party plugins. Toggle per integration in config.yml under integrations:.

Plugin Objective types Other features
WorldGuard wg_enter_region, wg_leave_region, wg_time_in_region Region enter/leave + time tracking
Lands lands_enter_land, lands_visit_land, lands_claim_chunks, lands_land_level, lands_deposit, lands_member_count Land name/id targets
Citizens citizens_talk_npc, citizens_deliver_npc, citizens_kill_npc NPC quest givers via quests.yml → citizens-npcs: and /sq npc link
mcMMO mcmmo_skill_level, mcmmo_skill_gain, mcmmo_power_level, mcmmo_ability, mcmmo_xp_gain Skill and ability tracking
Denizen denizen_run reward.denizen runs a Denizen script on claim

See Integrations for YAML examples. Admin showcase quests exist for every integration type.

Objective improvements

  • Multi-target lists: break, place, and collect accept target as a YAML list (e.g. IRON_ORE and DEEPSLATE_IRON_ORE in one objective)
  • Projectile alias: projectile objectives accept target as an alias for the projectile field
  • Starter quests: iron_miner and diamond_rush use deepslate ore lists; shepherd grants wool in rewards
  • Invalid config logging: ItemRequirementCondition warns on bad material entries in console

Bug fixes and reliability

  • Claim transaction: QuestPaperListener checks giveRewards(); claim aborts on failure with reward-claim-failed in messages.yml
  • /sq complete: Sets progress on all objectives, marks claimable, then completes (multi-objective quests)
  • /sq reload: Flushes pending saves, reloads DataManager, refreshes online player quest queues
  • Craft objective: Null-recipe guard prevents NPE on invalid craft targets
  • Quest transfer: transferOrAdoptQuest preserves ownerUUID when moving papers between players
  • Gamemode condition: Fails closed when gamemode config is missing or invalid
  • Async saves: Stale-write guard via saveSequence in DataManager
  • Completion stats: Increment on claim, not when objectives first complete
  • Equip listener: Only scans armor/equipment slot clicks (not every inventory click); join check for already-worn gear
  • Playtime: Removed erroneous playtime tick on player join; only scans players with active playtime objectives
  • Citizens /sq npc link: Persists to quests.yml (citizens-npcs:) automatically
  • citizens_deliver_npc: Right-click NPC with items consumes inventory and progresses deliver objectives
  • denizen_run: /sq denizen signal <script> and Denizen script rewards fire objective progress

Free & Premium polish

  • Clear startup banners: edition=Free or edition=Premium in startup summary
  • Free JAR hides Premium commands from tab completion (generate, editor, sigils, drop)
  • /sq info shows edition-specific feature lines
  • Integrations auto-detect when optional plugins are installed (integrations.auto-detect)
  • Quest browser icons use quest materials reliably (fixes empty GUI slots on showcase quests)
  • <quest_type> placeholder shows SINGLE / MULTI / SEQUENCE in browser lore
  • WorldGuard: Single enter/leave path via move tracking (no duplicate boundary events); wg_time_in_region amount is minutes
  • Lands: Unique-land visit tracking; level/member scans only on API events
  • Integration validation: Quest load warns when integration objectives reference missing/disabled plugins
  • /sq reload: Reloads integration config flags and Citizens NPC links from quests.yml

Content and permissions

  • All showcase_* quests require permission: soapsquest.admin (staff-only objective demos)
  • New showcase quests for vanilla extension types and integration types

Config and files

File Change
config.yml integrations.lands, .citizens, .mcmmo, .worldguard, .denizen toggles
quests.yml Quest definitions; citizens-npcs: section for Citizens NPC links
messages.yml reward-claim-failed message
plugin.yml Soft-depend: Lands, Citizens, mcMMO, WorldGuard, Denizen; version 1.1.0

Documentation

Polish (1.1.0 follow-up)

  • Reward claims: Mandatory rewards roll back XP/money on partial failure (prevents duplicate claims)
  • /sq reload: Sync-saves player data before reloading from disk
  • Conditions: Typed require-completed-quests / require-quest-completed work; invalid item: fails closed
  • Move objectives: Jump, elytra, biome, and in-block movement no longer blocked by hasChangedBlock() gate
  • Daily/weekly resets: Reschedule from config time after each reset (not hardcoded 24h/7d)
  • Editor: Six extension objective types in GUI picker; reachlevel saves level field; smelt ANY supported
  • Anti-cheat: Placed-block cache capped at 100k entries
  • MythicMobs: Vanilla kill no longer double-counts mythic mob deaths
  • Permissions: /sq abandon checks soapsquest.abandon; expanded tab completion
  • Quest load: Warns when a quest has no reward block
  • Messages: Admin command strings moved from hardcoded colors to messages.yml
  • /sq progress: Chat summary of active quest progress (soapsquest.progress, .progress.others)
  • MythicMobKillListener: Uses MythicMobQuestEvent + shared QuestListenerHelper scan path
  • Inventory scans: QuestListenerHelper deduplicates active-paper iteration; skips redundant inventory verify on event path
  • Showcase quests: Added WG leave/time, Lands visit/claim/level/deposit/members, Citizens deliver/kill, mcMMO gain/power/ability/xp
  • PlaceholderAPI: active_count, active_names, active_<questid>_progress placeholders
  • /sq give: Condition-locked papers stay locked unless soapsquest.give.bypass-conditions or soapsquest.admin
  • Sigil conditions: Dedicated SigilRequirementCondition type
  • Quest loot: Reorganized quest-loot.yml around pool.*; obey-plugin-restrictions enforced; chest papers tagged with loot marker
  • Legacy cleanup: Removed duplicate reward/condition/objective code paths; unified QuestReward hierarchy; objective aliases canonicalized at load; stripped CFR artifacts; corrected Citizens NPC docs

1.0.4

Release date: May 2026

Production readiness (2026-06-11)

  • Data safety: autosave/batch paths on main thread; YAML snapshot written async; stale async writes guarded
  • Quest queues persisted under players.<uuid>.quest-queues and restored on join
  • Per-player data shards (data.per-player-files, default on); /sq reload reloads DataManager
  • MoveListener skips sub-block moves; objective scans skip when no active quests
  • PlaceholderAPI scan fast-path; scan restarts on /sq reload
  • Premium: premium.edition: auto|free|premium config; quest paper instance UUID inventory check
  • Warns when SoapsCommon version is below required minimum
  • Custom YAML commands routed through SoapsCommandSandbox

Stability

  • Fixed shutdown task scheduling race on server stop
  • Safer autosave and batch save paths
  • Improved recurring task shutdown handling

Objectives

  • Fixed random/manual chat objectives in edge cases
  • Improved jump objective detection
  • Fixed craft objective alias handling (e.g. BANNER resolves correctly)
  • Smelt target validation prevents invalid/no-recipe targets

Rewards and completion

  • Multiline completion reward placeholder: <quest_rewards>
  • Unified completion messaging (no duplicate notifications)
  • Hardened quest list reward display with SIGILS support
  • Clearer workstation placement denial messages

Anti-cheat

  • Placed-block tracking for relevant objective types
  • Prevents place-then-break farming by default
  • Toggle: anti-cheat.enabled: true in config.yml

PlaceholderAPI

  • Improved expansion registration feedback
  • Safer placeholder request handling
  • External PlaceholderAPI pass-through in message processing

Loot and generator (Premium)

  • Loot-table source filtering via allowed-loot-tables
  • Batch generation path for random quest generator
  • Canonical mode: generated-quest-mode: persistent | temporary | session

1.0.3

Release date: 2026

Overview

Physical quest papers, 37 objective types, Free and Premium builds, full quests.yml showcase set.

Features

  • 37 objective types with showcase_<type> test quests
  • Active/Queued paper system for duplicate quest IDs
  • Sigils currency in rewards and conditions
  • Anti-cheat placed-block tracking
  • Smelt target validation and craft material alias resolution
  • PlaceholderAPI expansion for completions, tiers, difficulties, and sigils
  • Progress display modes: actionbar, chat, bossbar, none
  • Premium: random generator, daily/weekly quests, quest loot, in-game editor

1.0.2

Release date: May 2026

Quest queue and progress

  • Fixed multiple copies of the same quest completing from one action
  • Different quest IDs can be Active at once; duplicate IDs stay Queued until claim
  • Recurring daily/weekly papers register progress and join the queue
  • Active/Queued lore updates after queue refresh

Logging

  • Claim messages no longer spam console by default
  • log-quest-completions and log-admin-actions in config.yml (default false)

Conditions

  • active-limit counts Active quest types in the queue, not all papers in playerdata

1.0.1

Release date: May 2026

Objective fixes

  • command: commands matched without leading slash; subcommands supported
  • placeholder: polls PlaceholderAPI when installed
  • explore_biome: registry key matching on Paper 1.21+
  • Internal objectives no longer double-count on event path

Quest tracking

  • Direct objectives respect active queue, conditions, and sequential order
  • Queued papers do not gain progress until Active

Rewards and conditions

  • Command rewards support {player}, <player>, %player%
  • completed-quests accepts flat list in quest YAML

Configuration

  • quests.yml header documents all 37 objective types
  • /sq reload reports quest count
  • /sq info shows edition and objective count

Requirements (all versions)

  • Paper 1.21+, Java 21+, SoapsCommon
  • Optional: Vault, PlaceholderAPI, MythicMobs
  • Optional (1.1.0+): Lands, Citizens, mcMMO, WorldGuard, Denizen
Discord